The seneye Local Data Exchange (LDE) enables a seneye USB device (SUD) to transmit data to a 3rd party URL, via a seneye Web Server (SWS) or the seneye Connect Application (SCA), with or without internet connection.
An HTTP POST request is issued by a SWS or SCA to a single URL. The content of the request is digitally signed and contains the device description, the result of the measurements, and warning states. The latest reading from the device will be posted. This allows you to view/log data locally, and/or remotely to your own server, for example.
The seneye LDE uses JSON Web Tokens (JWT) to transmit data.
This repository contains documentation explaining how to enable the LDE, as well as documented example code that demonstrates methods for handling LDE requests sent by your SWS or SCA.
Please note: no direct support is offered from seneye for development beyond the information in this repository. seneye provides examples as reference only and as such, warranties are not provided for their use and functionality. Please see Terms of Use.
A SWS or SCA must first be configured for LDE.
-
Navigate to the Settings panel of your SWS GUI or SCA.
You will need your SWS Pin to access the SWS GUI. Click here for help locating your pin. -
Under Developer settings tick the box for Enable Local Data Exchange.
-
Make note of the Secret Key. You will need this later for verification of the LDE HTTP request body.
-
Enter a URL for where the SWS/SCA will send data to.
Example:http://"IPaddress":7878/localexchange/endpoint
-
Click Ok/Save.
Readings will now be sent to the specified URL in addition to the seneye cloud whenever a reading is taken.
The LDE makes use of JSON Web Tokens (JWT) to digitally sign the transmitted data and help ensure validity and integrity.
You can learn more about JWT here.
This means LDE request bodies are comprised of three Base64Url encoded parts; the JWT header, payload, and signature, separated by dots.
For example:
xxxx.yyyy.zzzz
The header part contains the hashing algorithm being used: HS256 (HMAC with SHA-256).
{
"alg": "HS256"
}
SUD information and measurements data are contained in the payload part.
{
"ver":"1.0.0",
"SUD":{
"id":"F5001E4050F9D1B6AE0B84A60D002004",
"name":"SUD Device",
"type":3,
"TS":1486116880,
"data":{
"S":{
"W":1,
"T":0,
"P":0,
"N":0,
"S":0,
"K":0
},
"T":26.125,
"P":8.66,
"N":0.010,
"K":0,
"L":0,
"A":0
}
}
}
ver
- Version number
SUD
- Contains SUD description, and data object
Key | Description |
---|---|
id | SUD serial number |
name | SUD name |
type | SUD type [1 : Home] [2 : Pond] [3 : Reef ] |
TS | Time of reading as Unix time-stamp |
data | SUD data |
data
- Contains SUD status flags and experiment readings
Key | Description | Data Type |
---|---|---|
S | SUD Status | JSON object |
T | Temperature | Float |
P | pH - missing if slide error | Float |
N | NH3 - missing if slide error | Float |
K | Kelvin - Reef only | Integer |
L | Lux - Reef only | Integer |
A | PAR - Reef only | Integer |
K
- Numeric CCT value of the colour temperature in degrees Kelvin. 0 indicates the value is not a valid Kelvin. If this occurs the Kelvin status flag will be 1.
If the value is not a valid Kelvin this means the color of the light does not fit to the Kelvin line
on the CIE colourspace.
S
- SUD status flags
Key | Description | Value: 0 | Value: 1 |
---|---|---|---|
W | Water | Out of water | In water |
T | Temperature | Within limits | Outside limits |
P | pH | Within limits | Outside limits |
N | NH3 | Within limits | Outside limits |
S | Slide | Slide OK | Slide expired / not fitted |
K | Kelvin | Is a Kelvin | Not a kelvin |
As per the JWT standard, the signature part is created by taking the encoded header, the encoded payload, the secret key from your SWS/SCA GUI, the algorithm specified in the header, and signing it.
HMACSHA256(
base64UrlEncode(header) + "." +
base64UrlEncode(payload),
secret)
The signature is used to verify that the sender of the JWT is who it says it is and to ensure that the message wasn't changed along the way.
Source code for a Node.js application is provided as an example for handling LDE requests. VSCode project files are also provided to simplify running the example code.
The example Node.js application listens for incoming LDE requests and displays the data as simple formatted HTML for local clients. Communication between server and clients is achieved via HTML5 WebSockets.
Please note: the example code is for reference only and seneye does not offer support for further implementation. Please see Terms of Use.
After downloading the example code, you must make some changes specific to your SWS or SCA.
Since messages from devices are digitally signed, you will need to edit a config file - /config/default.json
- to include the source ID and secret key for each SWS or SCA that is configured for LDE.
Use these links for help locating your SWS or SCA ID:
Locate SWS ID.
Locate SCA ID.
Secret keys are located in the Settings panel of your SWS/SCA GUI.
If you cannot locate your ID or secret key please contact seneye support.
NOTE - a single seneye Connect Application (SCA) can operate with multiple SUDs and their data will be signed using the same ID and secret key.
Amend the config file with the gathered information like so:
{
"KnownSources": [
{"source": "SCA_rVYGiME5tYrf", "secret": "FGQEEESSA"},
{"source": "SWS_pLJfM7hEnrFP", "secret": "MDUELFPLL"},
...
]
}
The source ID string must be prepended with the source type, for example: "SCA_"
or "SWS_"
.
To run the example code type these commands into a shell from the VSCode project directory.
npm install
npm start
NOTE - Node.js needs to be installed on the machine.
THE SAMPLE CODE IS PROVIDED βAS ISβ AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL PAGERDUTY OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) SUSTAINED BY YOU OR A THIRD PARTY, HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT ARISING IN ANY WAY OUT OF THE USE OF THIS SAMPLE CODE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
The Code is not covered by any Seneye Service Level Agreements.