Application Programming Interface for the Radio Bridge Console for the Radio... · 2020. 3. 29. · Example: “Steves tilt sensor ” deviceType Description of the device. Example:

Application Programming Interface for the Radio Bridge Console

VERSION 1.3

MARCH 2020

API FOR THE RADIO BRIDGE CONSOLE

COPYRIGHT © 2019, RADIO BRIDGE INC. API FOR THE RADIO BRIDGE CONSOLE PAGE 1 OF 13

TABLE OF CONTENTS

1. OVERVIEW .......................................................................................................................... 2

1.1. Introduction ...............................................................................................................................2

1.2. Revision History .........................................................................................................................2

1.3. Document Conventions ..............................................................................................................2

2. OVERVIEW .......................................................................................................................... 3

2.1. Message Types ...........................................................................................................................3

2.2. API Types ...................................................................................................................................3

2.3. API Location ...............................................................................................................................3

3. UPLINK CONFIGURATION .................................................................................................... 3

4. DOWNLINK CONFIGURATION .............................................................................................. 9

5. TUTORIAL AND EXAMPLES .................................................................................................. 10

5.1. Setup ....................................................................................................................................... 10

5.2. Configure Uplink ...................................................................................................................... 10

5.3. Test Uplink ............................................................................................................................... 10

5.4. Test Downlink .......................................................................................................................... 11

6. CUSTOMER SUPPORT ......................................................................................................... 13

7. DISCLAIMERS ...................................................................................................................... 13

8. LEGAL NOTICES .................................................................................................................. 13

9. TRADEMARKS AND COPYRIGHT .......................................................................................... 13



1. OVERVIEW

1.1. Introduction

The wireless sensors designed and manufactured by Radio Bridge provide full sensor to cloud

solutions for Internet of Things (IoT) applications. The Radio Bridge Console is a web-based

device manager that handles the provisioning, monitoring, and configuration of Radio Bridge

sensors. The Console is not required in order to use Radio Bridge sensor hardware, but it

eliminates much of the work required to properly interface to the sensors and allows end

users to get to get up and running quickly. Third party applications can be developed “on top

of” the Console with basic APIs. This document provides instructions for third party

applications to communicate to the Radio Bridge Console via APIs.

For more information on the Console, visit https://console.radiobridge.com

1.2. Revision History Table 1 Revision History

Revision Date Description

1.0 December 2018 Initial release of the document

1.1 May 2019 Updated API format for decoded messages

1.2 December 2019 Added new fields to API

1.3 March 2020 Added examples and updated units

1.3. Document Conventions Table 2 Document Conventions

Font / Icon Meaning

Important notes

Warnings and cautions

https://console.radiobridge.com/



2. OVERVIEW

2.1. Message Types

There are two types of messages when communicating with Radio Bridge sensors or the

web-based console, uplink and downlink. Uplink messages originate from the sensor and are

received by the Console and/or third-party application. The uplink messages communicate

sensor events, alerts, heath, and status of the sensor.

Downlink messages originate from the Console and/or third-party application and are

received by the sensor. Downlink messages provide configuration information for the

sensor, and after receiving this information the sensor will behave accordingly.

2.2. API Types

The APIs used by the Console are RESTful APIs that utilize a simple POST request. These

POST requests apply to both the uplink and downlink messages.

2.3. API Location

To utilize the Console API, go to the Radio Bridge Console application at

https://console.radiobridge.com and click on the “API” tab along the left side. From there

you can use the uplink and downlink APIs as described in the following sections.

3. UPLINK CONFIGURATION

Within the API section of the Console, there are two input fields in the Uplink section as shown

in the following table.

Table 3 Uplink API Fields

Field Description

Uplink URL The URL of the third-party application as defined by the user

Header Authorization Code The user defined authorization code added to the header of the POST request

Both fields in the above table are required. Uplink messages will be sent to the user defined URL

with the user defined authorization code in the header.

The parameters that are passed with the uplink request are defined in the following table.

https://console.radiobridge.com/



Table 4 Uplink Parameters

Parameter Description

deviceId Unique Device ID of sensor. Example: 80000004012067

deviceName Device Name defined in the Console. Example: “Steves tilt sensor 1”

deviceType Description of the device. Example: “LoRa High Precision Tilt Sensor”

partNumber The Radio Bridge part number. Example: “RBS306-TILT-HP”

seqNumber Message Sequence Number. 0x00 to 0x0F and then wraps back to 0x00.

eventType The type of uplink message. Example: “RESET”

eventDescription Description of the event, used with eventType Example: “Button 1 and 2 released together”

eventTime Time stamp of the event in UTC Example: “2019-05-06Z21:01:38”

rawBytes Raw hex data received from the sensor Example: “150f005e40”

snr Signal to Noise Ratio

Example: “10.3”

rssi Receive Signal Strength Indicator

Example: “-93”

hardwareVersion Hardware version from reset message

Example: “2.0”

firmwareVersion Firmware version from reset message

Example: “1.6”

sensorState Current state of the sensor from the supervisory message

Example: “Door Closed”



battery Battery voltage reported by the supervisory message

Example: “3.0 V”

network LoRaWAN network server

Example: “Senet”

measurement See measurement table

gateway The gateway defined in the console if it is being used

Example: “my gateway 1”

The measurement field is dependent on the sensor type, and is defined in the following table.

Table 5 Measurement Field Definitions

Sensor Measurement Field

Water Sensor Relative measurement

Example: “228”

Temperature Sensor Current Temperature

Example: “22 C”

Tilt Sensor Tilt angle from vertical axis

Example: “91.3 Degrees”

Tank Level Sensor Relative measurement

Ambient Light Sensor Current ambient light measurement

Air Temperature Humidity Sensor

Current temperature in degrees Celsius

Example: “21.6 C, 34.3 %”

Vibration Sensor Vibration Sensor

Example: “High-frequency vibration peak g-force: 0”

Acceleration Movement Sensor Current sensor state

Example: “Acceleration stopped”

Ultrasonic Level Sensor Current distance

Example: “668 mm”



420mA Current Loop Sensor Current measurement

Example: “8.5 mA”

Voltage Sensor Voltage measurement

Example: “0.03 V”

Thermocouple Temp Sensor Current temperature in degrees Celsius

Example: “10.81 C”

Low Freq Vibration Sensor Current temperature in Celsius


Table 6 GPS Specific Fields


latitude This is available for GPS devices

Example: “39.7567144000”

longitude This param is available for GPS devices only

Example: “105.00442380000”

location This param is available for GPS devices only

Example: Contains HTML markup with google maps link.

<a target="_blank" href="http://maps.google.com/?q=39.7567144000,-105.00442380000">View on Google Maps</a>

Table 7 Honeywell 5800 Bridge Specific Fields


eventIdentifier Event identifier

Example: “Status Code”

hexId Contains hex id

Example: “0x000341”

decimalId Hex id is converted into decimal values



Example: “833”

sensorPayload Sensor payload in decimal

Example: “2444”

sensorPayloadHex Sensor payload in hex (Example: “0x00098c”)

Table 8 High Bandwidth Vibration Sensor Specific Fields


vibrationVelocity High-frequency vibration peak g-force

Example: “0”

acceleratorTemp Temperature


sensor Shows the vibration event

Example: “High Frequency Periodic Report”

Table 9 Low Bandwidth Vibration Sensor Specific Fields


xaxis Low-frequency vibration peak velocity in inches/sec in the x-axis

Example: “0”

yaxis Low-frequency vibration peak velocity in inches/sec in the y-axis

Example: “1”

zaxis Low-frequency vibration peak velocity in inches/sec in the z-axis

Example: “4”

sensor Shows the vibration event

Example: “Low Frequency Periodic Report”



Table 10 Weather Station Bridge Specific Fields


errorEvent Error details

Example: “Some data is marked as invalid”

windDirection Contains sub-array

Example: {"min":"36 Degrees","max":"90 Degrees ","avg":"68 Degrees"}

windSpeed Contains sub-array

Example: {"min":"0 m/s","max":"0.001 m/s", "avg":"0.001 m/s "}

pressureTempHumidity Contains sub-array with following element

Example: {"temperature":"26.2 C","pressure":"83,020 Pa","humidity":"24.2 %"}

rain Contains sub-array with element

Example: {"duration ":"0 Seconds","accumulation ":"0 mm","intensity ":"0 mm/h"}

hail Contains sub-array with element

Example: {"duration ":"0 Seconds","accumulation ":"0 mm","intensity ":"0 mm/h"}

stationStatus Contains sub-array with element

Example: {"temperature":"27.8 C", "voltage":"0 V", "supply":"12.2 V","reference":"3.612 V"}



4. DOWNLINK CONFIGURATION

Within the API section of the Console, there is a single read-only field which specifies the URL to

which a third-party application can post downlink parameters to the Console. The downlink URL

contains a unique key that is used to authenticate downlink messages posted to this user

account.

The parameters that are passed with the downlink request are defined in the following table.

Table 11 Downlink Parameters


deviceId Unique Device ID of the sensor

downlink The 8-byte downlink message. See the corresponding sensor user manual for more detail.

To verify a successful queueing of a downlink message, there is a JSON response with the

following format:

{"status":"true|false","message":"<Success> or <Error> message"}

The two parameters are defined in the following table.

Table 12 Downlink API Response Parameters


status “true” indicates a successful queueing of a new downlink message. “false” indicates a failure to queue downlink message.

message A message following the status of the API call indicating either a success or an error message.



5. TUTORIAL AND EXAMPLES

This section will step you through a simple method of testing the API and provide example

values to the various parameters.

5.1. Setup

Go to the website https://webhook.site. This is a free webhook tester that provides

visualization for the uplink and downlink messages. Click on the “New URL” button and then

“Create”. This creates a unique URL that can be used to post uplink messages. An example

URL might look something like this:

5.2. Configure Uplink

Go back to the Radio Bridge Console and click on the API tab. In the Uplink URL field, enter

the URL generated in the last section. In the authorization field, enter any value your

application will use for authorization. In this case, simply enter “1234” and click Update.

5.3. Test Uplink

Send a message from a Radio Bridge sensor and observe the data arriving at the webhook

tester as shown below:

The sample data received in this example is shown in the following table.

https://webhook.site/



Table 13 Uplink Example Parameters


deviceId 3E5FBB

deviceName Steve’s dual push button

deviceType Wireless Dual Push Button - RBS104-2

sensorSeqNumber 1

eventType PUSH_BUTTON

eventDescription Button 2 Pressed

eventTime {“date”:”2018-12-06 18:20:07.000000”, “timezone_type”:”3”,”timezone”:”UTC”}

snr 6

rssi -113

rawBytes 11060200

5.4. Test Downlink

We will send a downlink message: 0600040000000000 which indicates it is a dual push

button device (06) with a hold time of 1 second (04) on button 1. Note that there must

always be 8 bytes in a downlink message so we add zeros to the end of the message if no

parameters are defined for those bytes.

Go to https://apitester.com, select POST, and enter the request string with the device ID

and downlink payload as shown in the example below:

https://apitester.com/



Scroll down to Response Body and you should see the following JSON response:

{"status":true,"message":"Event has been added in queue, device will be configured when

that wakes up."}

Back in the Radio Bridge Console, navigate to the device ID and the following will be shown

under the configuration section:

The downlink payload is queued and will be sent to the sensor.



6. CUSTOMER SUPPORT

Radio Bridge offers free technical support at:

https://support.radiobridge.com

Radio Bridge also offers technical support plans and service packages to help our customers get

the most out of their Radio Bridge products.

7. DISCLAIMERS

Information in this document is subject to change without notice and does not represent a

commitment on the part of Radio Bridge. Radio Bridge provides this document “as is,” without

warranty of any kind, expressed or implied, including, but not limited to, the implied warranties

of fitness or merchantability for a particular purpose. Radio Bridge may make improvements

and/or changes in this manual or in the product(s) and/or the software described in this manual

at any time.

8. LEGAL NOTICES

See the Legal Notices section of the website for up to date information on Radio Bridge’s

warranty, returns policy, privacy statement, terms of sale, and terms of service.

9. TRADEMARKS AND COPYRIGHT

Radio Bridge™, SubGig®, Armored Sensor™ and BridgeBee® are trademarks of Radio Bridge Inc in

the United States.

© 2019 Radio Bridge Inc. All rights reserved

Documents

Application Programming Interface for the Radio Bridge Console for the Radio... · 2020. 3. 29. · Example: “Steves tilt sensor ” deviceType Description of the device. Example: