From f43971e8be1ab51b142d9fcd9b87f47f84870742 Mon Sep 17 00:00:00 2001 From: Philip Schell Date: Wed, 25 Sep 2019 13:43:08 +0200 Subject: [PATCH] Update Communication Docu --- Communcation.yml | 161 ++++++-- Communication.md | 1029 +++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 1140 insertions(+), 50 deletions(-) diff --git a/Communcation.yml b/Communcation.yml index f4f2413..75c0eb9 100644 --- a/Communcation.yml +++ b/Communcation.yml @@ -29,25 +29,36 @@ defaultContentType: application/json channels: lora/data/{deviceID}: - description: The topic on whitch the devices are shown for Tracking data. + description: Topic witch contains the tracking data. parameters: deviceID: $ref: '#/components/parameters/deviceID' subscribe: - summary: Send informations over a Tracker on that topic with an id operationId: loradata message: $ref: '#/components/messages/loradata' + + + lora/panic/{deviceID}: + description: Topic witch contains the tracking data, when the panic buttons was pressed + parameters: + deviceID: + $ref: '#/components/parameters/deviceID' + subscribe: + operationId: lorapanic + message: + $ref: '#/components/messages/loradata' - smartylighting/streetlights/1/0/action/{streetlightId}/dim: + lora/status/{deviceID}: + description: Topic witch contains status of the devices parameters: - streetlightId: - $ref: '#/components/parameters/streetlightId' - publish: - operationId: dimLight - message: - $ref: '#/components/messages/dimLight' + deviceID: + $ref: '#/components/parameters/deviceID' + subscribe: + operationId: lorastatus + message: + $ref: '#/components/messages/lorastatus' components: messages: @@ -58,39 +69,117 @@ components: contentType: application/json payload: $ref: "#/components/schemas/loradataPayload" - dimLight: - name: dimLight - title: Dim light - summary: Command a particular streetlight to dim the lights. + lorastatus: + name: loraStatus + title: Statusdata + summary: Informs you about a Status of a Tracker payload: - $ref: "#/components/schemas/dimLightPayload" + $ref: "#/components/schemas/lorastausPayload" schemas: - loradataPayload1: - type: object - properties: - lumens: - type: integer - minimum: 0 - description: Light intensity measured in lumens. - sentAt: - $ref: "#/components/schemas/sentAt" loradataPayload: $ref: "#/components/schemas/loradataObject" - dimLightPayload: + + lorastausPayload: + $ref: "#/components/schemas/lorastatusObject" + + lorastatusObject: type: object properties: - percentage: + Bandwidth: type: integer - description: Percentage to which the light should be dimmed to. - minimum: 0 - maximum: 100 - sentAt: - $ref: "#/components/schemas/sentAt" - sentAt: - type: string - format: date-time - description: Date and time when the message was sent. + description: Bandwidth on witch the Signal was recieved + minimum: 7800 + maximum: 500000 + BatteryLevel: + type: number + description: Voltage of the battery from the device + minimum: 2.5 + maximum: 5 + Calculatedcrc: + type: integer + description: The calculated CRC + Codingrate: + type: integer + description: The Codingrate in witch the Signal was recieved + minimum: 5 + maximum: 8 + Crcstatus: + type: string + description: Shows the CRC-Status in a Field + enum: + - Ok + - Bad + - No + DeviceStatus: + type: string + description: Shows the internal state in a Field + enum: + - Startup + - Powersave + - Shutdown + Frequency: + type: integer + description: The Frequency on that the Message was arrived + FrequencyOffset: + type: integer + description: The internal offset to the base frequency, to compensate cheap china rf modules + Host: + type: string + description: Name of the Gateway that Recieves the Data + IpAddress: + type: string + description: IP-Address of the device, for debug + default: "0.0.0.0" + format: "[0-9]\\.[0-9]\\.[0-9]\\.[0-9]" + Name: + type: string + description: Name of the GPS-Tracker, must be unique between every Device + format: "/[a-z]{2}/i" + PacketRssi: + type: number + description: Recieve Signal Strength Index for the whole LORA-Messgae + Receivedtime: + type: string + description: Timestamp of the Gateway, when it recieves the LORA-Message + format: dd/mm/YYYY hh:MM:ss + default: 01/01/2019 12:00:00 + Recieverinterface: + type: integer + description: Internal virtual Radio of the Gateway, witch recieves the LORA-Messange + Recieverradio: + type: integer + description: Internal Radio of the Gateway, witch recieves the LORA-Messange + Rssi: + type: number + description: Recieve Signal Strength Index for the LORA-Message + Snr: + type: number + description: Signal to Noise Ratio of the LORA-Message + Snrmax: + type: number + description: Maximum Signal to Noise Ratio of the LORA-Message + Snrmin: + type: number + description: Minimum Signal to Noise Ratio of the LORA-Message + Spreadingfactor: + type: integer + description: The Spreadingfactor of the LORA-Message + minimum: 7 + maximum: 12 + Time: + type: integer + description: Internal Timecounter of the LORA-Reciever + Version: + type: integer + description: Software-Versionsnumber of the Device + WifiActive: + type: boolean + description: Status if the Device successufly connect to a wifi + WifiSsid: + type: string + description: SSID of the WIFI witch the device connects to. + loradataObject: type: object required: @@ -228,10 +317,6 @@ components: description: Using Username and Password to connect to online broker parameters: - streetlightId: - description: The ID of the streetlight. - schema: - type: string deviceID: description: The ID of the streetlight. schema: diff --git a/Communication.md b/Communication.md index b5b5c99..a4aade2 100644 --- a/Communication.md +++ b/Communication.md @@ -109,7 +109,7 @@ Internal Communication for: -The topic on whitch the devices are shown for Tracking data. +Topic witch contains the tracking data. @@ -713,9 +713,11 @@ Informs you about a Position and Status of a Tracker - + +Topic witch contains the tracking data, when the panic buttons was pressed + @@ -723,7 +725,7 @@ Informs you about a Position and Status of a Tracker -##### streetlightId +##### deviceID The ID of the streetlight. @@ -743,7 +745,7 @@ The ID of the streetlight. - streetlightId + deviceID string @@ -764,13 +766,13 @@ The ID of the streetlight. -### `publish` smartylighting/streetlights/1/0/action/{streetlightId}/dim +### `subscribe` lora/panic/{deviceID} #### Message -Command a particular streetlight to dim the lights. +Informs you about a Position and Status of a Tracker @@ -796,11 +798,11 @@ Command a particular streetlight to dim the lights. - percentage + Bandwidth integer -

Percentage to which the light should be dimmed to.

+

Bandwidth on witch the Signal was recieved

Any @@ -813,11 +815,453 @@ Command a particular streetlight to dim the lights. - sentAt + BatteryLevel + + + number +

Voltage of the battery from the device

+ + Any + + + + + + + + + + + Calculatedcrc + + + integer +

The calculated CRC

+ + Any + + + + + + + + + + + Codingrate + + + integer +

The Codingrate in witch the Signal was recieved

+ + Any + + + + + + + + + + + Crcstatus string -

Date and time when the message was sent.

+

Shows the CRC-Status in a Field

+ + Ok, Bad, No + + + + + + + + + + + Frequency + + + integer +

The Frequency on that the Message was arrived

+ + Any + + + + + + + + + + + Gps + + + object +

Gps-Data of a Message

+ + Any + + + + + + + Gps.Fix + + + boolean +

Status of the Tracker, true if it has GPS-Signal

+ + Any + + + + + + + + + + + Gps.Hdop + + + number +

Dislocation from GPS-Reciever

+ + Any + + + + + + + + + + + Gps.Height + + + number +

Height of the GPS-Reciever

+ + Any + + + + + + + + + + + Gps.LastGPSPos + + + string +

Timestamp when the GPS-Reciever has its last position

+ + Any + + + + + + + + + + + Gps.LastLatitude + + + number +

Last Latitude of the GPS-Reciever

+ + Any + + + + + + + + + + + Gps.LastLongitude + + + number +

Last Longitude of the GPS-Reciever

+ + Any + + + + + + + + + + + Gps.Latitude + + + number +

Latitude of the GPS-Reciever

+ + Any + + + + + + + + + + + Gps.Longitude + + + number +

Longitude of the GPS-Reciever

+ + Any + + + + + + + + + + + Gps.Time + + + string +

Timestamp of the GPS-Reciever, that it gets from the Satelites

+ + Any + + + + + + + + + + + + + + + Host + + + string +

Name of the Gateway that Recieves the Data

+ + Any + + + + + + + + + + + Name + + + string +

Name of the GPS-Tracker, must be unique between every Device

+ + Any + + + + + + + + + + + PacketRssi + + + number +

Recieve Signal Strength Index for the whole LORA-Messgae

+ + Any + + + + + + + + + + + Receivedtime + + + string +

Timestamp of the Gateway, when it recieves the LORA-Message

+ + Any + + + + + + + + + + + Recieverinterface + + + integer +

Internal virtual Radio of the Gateway, witch recieves the LORA-Messange

+ + Any + + + + + + + + + + + Recieverradio + + + integer +

Internal Radio of the Gateway, witch recieves the LORA-Messange

+ + Any + + + + + + + + + + + Rssi + + + number +

Recieve Signal Strength Index for the LORA-Message

+ + Any + + + + + + + + + + + Snr + + + number +

Signal to Noise Ratio of the LORA-Message

+ + Any + + + + + + + + + + + Snrmax + + + number +

Maximum Signal to Noise Ratio of the LORA-Message

+ + Any + + + + + + + + + + + Snrmin + + + number +

Minimum Signal to Noise Ratio of the LORA-Message

+ + Any + + + + + + + + + + + Spreadingfactor + + + integer +

The Spreadingfactor of the LORA-Message

+ + Any + + + + + + + + + + + Time + + + integer +

Internal Timecounter of the LORA-Reciever

Any @@ -837,8 +1281,569 @@ Command a particular streetlight to dim the lights. ```json { - "percentage": 0, - "sentAt": "2019-09-24T12:10:43Z" + "Bandwidth": 7800, + "BatteryLevel": 2.5, + "Calculatedcrc": 0, + "Codingrate": 5, + "Crcstatus": "Ok", + "Frequency": 0, + "Gps": { + "Fix": true, + "Hdop": 0.8, + "Height": 0, + "LastGPSPos": "01/01/2019 12:00:00", + "LastLatitude": 50.7, + "LastLongitude": 7.2, + "Latitude": 50.7, + "Longitude": 7.2, + "Time": "01/01/2019 12:00:00" + }, + "Host": "string", + "Name": "string", + "PacketRssi": 0, + "Receivedtime": "01/01/2019 12:00:00", + "Recieverinterface": 0, + "Recieverradio": 0, + "Rssi": 0, + "Snr": 0, + "Snrmax": 0, + "Snrmin": 0, + "Spreadingfactor": 7, + "Time": 0 +} +``` + + + + + + + + + + + +Topic witch contains status of the devices + + + + +#### Channel Parameters + + + +##### deviceID + + +The ID of the streetlight. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionAccepted values
deviceID + + stringAny
+ + + + + +### `subscribe` lora/status/{deviceID} + +#### Message + + + +Informs you about a Status of a Tracker + + + + + + + +##### Payload + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDescriptionAccepted values
Bandwidth + + integer

Bandwidth on witch the Signal was recieved

+		Any
BatteryLevel + + number

Voltage of the battery from the device

+		Any
Calculatedcrc + + integer

The calculated CRC

+		Any
Codingrate + + integer

The Codingrate in witch the Signal was recieved

+		Any
Crcstatus + + string

Shows the CRC-Status in a Field

+		Ok, Bad, No
DeviceStatus + + string

Shows the internal state in a Field

+		Startup, Powersave, Shutdown
Frequency + + integer

The Frequency on that the Message was arrived

+		Any
FrequencyOffset + + integer

The internal offset to the base frequency, to compensate cheap china rf modules

+		Any
Host + + string

Name of the Gateway that Recieves the Data

+		Any
IpAddress + + string

IP-Address of the device, for debug

+		Any
Name + + string

Name of the GPS-Tracker, must be unique between every Device

+		Any
PacketRssi + + number

Recieve Signal Strength Index for the whole LORA-Messgae

+		Any
Receivedtime + + string

Timestamp of the Gateway, when it recieves the LORA-Message

+		Any
Recieverinterface + + integer

Internal virtual Radio of the Gateway, witch recieves the LORA-Messange

+		Any
Recieverradio + + integer

Internal Radio of the Gateway, witch recieves the LORA-Messange

+		Any
Rssi + + number

Recieve Signal Strength Index for the LORA-Message

+		Any
Snr + + number

Signal to Noise Ratio of the LORA-Message

+		Any
Snrmax + + number

Maximum Signal to Noise Ratio of the LORA-Message

+		Any
Snrmin + + number

Minimum Signal to Noise Ratio of the LORA-Message

+		Any
Spreadingfactor + + integer

The Spreadingfactor of the LORA-Message

+		Any
Time + + integer

Internal Timecounter of the LORA-Reciever

+		Any
Version + + integer

Software-Versionsnumber of the Device

+		Any
WifiActive + + boolean

Status if the Device successufly connect to a wifi

+		Any
WifiSsid + + string

SSID of the WIFI witch the device connects to.

+		Any
+ + + +###### Example of payload _(generated)_ + +```json +{ + "Bandwidth": 7800, + "BatteryLevel": 2.5, + "Calculatedcrc": 0, + "Codingrate": 5, + "Crcstatus": "Ok", + "DeviceStatus": "Startup", + "Frequency": 0, + "FrequencyOffset": 0, + "Host": "string", + "IpAddress": "0.0.0.0", + "Name": "string", + "PacketRssi": 0, + "Receivedtime": "01/01/2019 12:00:00", + "Recieverinterface": 0, + "Recieverradio": 0, + "Rssi": 0, + "Snr": 0, + "Snrmax": 0, + "Snrmin": 0, + "Spreadingfactor": 7, + "Time": 0, + "Version": 0, + "WifiActive": true, + "WifiSsid": "string" } ```