meta data for this page
  •  

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
doc_urecs:software_interface [2023/10/23 13:21] – [Components] vordoc_urecs:software_interface [2024/01/10 17:18] (current) – [LoRa Message] fun
Line 27: Line 27:
 ==== Access ==== ==== Access ====
  
-The u.RECS Management API is accessible via the IP-Address or the hostname of the u.RECS. The basic URL of the API has the format ''https://<ip-address>/REST/<system/baseboard/node>'' or ''http://<ip-address>/REST/<system/baseboard/node>''.+The u.RECS Management API is accessible via the IP-Address or the hostname of the u.RECS. The basic URL of the API has the format ''https://[ip-address]/REST/[system/baseboard/node]'' with ''http'' or ''https'', depending on your configuration. Therefore, please check the following URL as an example: 
 + 
 +https://192.168.0.50/REST/system
  
 Accessing the REST API requires HTTP Basic authentication. The password of the admin account can be changed in the Settings page. Accessing the REST API requires HTTP Basic authentication. The password of the admin account can be changed in the Settings page.
Line 74: Line 76:
 |''health'' |Health status of the node (OK, Warning, Critical)|-|String| |''health'' |Health status of the node (OK, Warning, Critical)|-|String|
 |''voltage'' |Supply voltage of the baseboard|V|Double| |''voltage'' |Supply voltage of the baseboard|V|Double|
-|''lastSensorUpdate'' |Timestamp of the last sensor update|ms|Long|+|''lastSensorUpdate'' |Unix-style epoche timestamp of the last sensor update|s|Long|
 |''present'' |Node is plugged in and detected|-|Boolean| |''present'' |Node is plugged in and detected|-|Boolean|
 |''mpciePresent'' |mPCIe card is plugged in and detected|-|Boolean| |''mpciePresent'' |mPCIe card is plugged in and detected|-|Boolean|
Line 189: Line 191:
  
 The LoRaWAN interface allows up and downlink connections to an application server. The LoRaWAN interface allows up and downlink connections to an application server.
-Packets can be scheduled and collected by interfacing the Management REST API+Payload can be scheduled and collected by interfacing the Management REST API.
  
 ^ Attribute ^ Description ^ HTTP method ^ ^ Attribute ^ Description ^ HTTP method ^
-|''/lorawan/queue'' |Responds with incoming LoRaWAN packets linked to the API key in the request body XML|POST| +|''/lorawan/uplink/{fport}'' |Schedules uplink packet to the application endpoint for the specified fport|POST| 
-|''/lorawan/queue'' |Schedules uplink packet to the application server defined in the management interface XML|GET| +|''/lorawan/downlink/{fport}'' |Responds with incoming downlink LoRaWAN messages for the specified fport|GET|
-|''/lorawan/manage'' |Manages LoRa PHY settings XML|GET|+
  
-Example XML queue GET / POST:+Example HTTP Body on GET request:
  
-<code xml><lorawan apikey="..."> +<code xml><lorawan> 
-<packetbody>lora packet content in base64</packetbody>+  <payload>{custom lorawan payload}</payload> 
 +  <time>{timestamp}</time>
 </lorawan></code> </lorawan></code>
  
-Example XML manage:+Example HTTP Body on POST request:
  
-<code xml><lorawan masterkey="..."> +<code xml><lorawan> 
-<band>eu</band> +  <payload>{custom lorawan payload}</payload>
-<txpwr>14</txpwr> +
-<txsf>7</txsf> +
-<rx2wsf>9</rx2wsf>+
 </lorawan></code> </lorawan></code>
  
-In order to remotely manage the RECS power status via LoRaWAN, the Application Server must send the downlink command payload in following format:+==== FPort ====
  
-<code xml> +The Frame Port (fport) separates different communication parties on the API, and functions as an identifyer for the message sender / reciever. 
-<l masterkey=""> +When using the REST API, you are free to choose a value between 2 - 223. 
-  <power>1</power> +FPort 1 is reserved for the management controller.
-<l> +
-</code> +
- +
-The master and API keys are managed in the RECS web interface.+
  
 === Errors === === Errors ===
Line 227: Line 222:
 ==== LoRa Message ==== ==== LoRa Message ====
  
-The u.RECS supports to upstream LoRa messages to [[https://www.thethingsnetwork.org/|The Things Network (TTN)]]. The following table gives the LoRa message meaning of version 0.+The u.RECS supports upstream and downstream LoRa messages to [[https://www.thethingsnetwork.org/|The Things Network (TTN)]]. The following table gives the LoRa message meaning of version 0. 
 + 
 +All system related management communication (excluding the REST API) uses **FPort 1**.  
 + 
 +Upstream message payload layout:
  
 ^ Byte(s) ^ Description ^ Unit ^ Data type ^ ^ Byte(s) ^ Description ^ Unit ^ Data type ^
Line 247: Line 246:
 |26    | PoE Status Port 1 | - (see below) | Byte | |26    | PoE Status Port 1 | - (see below) | Byte |
 |27    | PoE Status Port 2 | - (see below) | Byte | |27    | PoE Status Port 2 | - (see below) | Byte |
 +
 +The u.RECS supports basic control functions over LoRaWAN.
 +Downstream message payloads:
 +
 +**Change power state for node:**
 +^ Byte(s) ^ Description ^ Unit ^ Data type ^
 +|0   | Lora Message-Version | - | Byte |
 +|1   | Node ID | - | Byte |
 +|2   | LoRa Command (0x01 = ON, 0x02 = OFF, 0x03 = RESET) | - | Byte |
 +
 +
 +