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
API FOR THE RADIO BRIDGE CONSOLE
COPYRIGHT © 2019, RADIO BRIDGE INC. API FOR THE RADIO BRIDGE CONSOLE PAGE 2 OF 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
API FOR THE RADIO BRIDGE CONSOLE
COPYRIGHT © 2019, RADIO BRIDGE INC. API FOR THE RADIO BRIDGE CONSOLE PAGE 3 OF 13
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.
API FOR THE RADIO BRIDGE CONSOLE
COPYRIGHT © 2019, RADIO BRIDGE INC. API FOR THE RADIO BRIDGE CONSOLE PAGE 4 OF 13
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”
API FOR THE RADIO BRIDGE CONSOLE
COPYRIGHT © 2019, RADIO BRIDGE INC. API FOR THE RADIO BRIDGE CONSOLE PAGE 5 OF 13
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”
API FOR THE RADIO BRIDGE CONSOLE
COPYRIGHT © 2019, RADIO BRIDGE INC. API FOR THE RADIO BRIDGE CONSOLE PAGE 6 OF 13
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
Example: “10.81 C”
Table 6 GPS Specific Fields
Parameter Description
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
Parameter Description
eventIdentifier Event identifier
Example: “Status Code”
hexId Contains hex id
Example: “0x000341”
decimalId Hex id is converted into decimal values
API FOR THE RADIO BRIDGE CONSOLE
COPYRIGHT © 2019, RADIO BRIDGE INC. API FOR THE RADIO BRIDGE CONSOLE PAGE 7 OF 13
Example: “833”
sensorPayload Sensor payload in decimal
Example: “2444”
sensorPayloadHex Sensor payload in hex (Example: “0x00098c”)
Table 8 High Bandwidth Vibration Sensor Specific Fields
Parameter Description
vibrationVelocity High-frequency vibration peak g-force
Example: “0”
acceleratorTemp Temperature
Example: “10.81 C”
sensor Shows the vibration event
Example: “High Frequency Periodic Report”
Table 9 Low Bandwidth Vibration Sensor Specific Fields
Parameter Description
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”
API FOR THE RADIO BRIDGE CONSOLE
COPYRIGHT © 2019, RADIO BRIDGE INC. API FOR THE RADIO BRIDGE CONSOLE PAGE 8 OF 13
Table 10 Weather Station Bridge Specific Fields
Parameter Description
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"}
API FOR THE RADIO BRIDGE CONSOLE
COPYRIGHT © 2019, RADIO BRIDGE INC. API FOR THE RADIO BRIDGE CONSOLE PAGE 9 OF 13
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
Parameter Description
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
Parameter Description
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.
API FOR THE RADIO BRIDGE CONSOLE
COPYRIGHT © 2019, RADIO BRIDGE INC. API FOR THE RADIO BRIDGE CONSOLE PAGE 10 OF 13
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.
API FOR THE RADIO BRIDGE CONSOLE
COPYRIGHT © 2019, RADIO BRIDGE INC. API FOR THE RADIO BRIDGE CONSOLE PAGE 11 OF 13
Table 13 Uplink Example Parameters
Parameter Description
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:
API FOR THE RADIO BRIDGE CONSOLE
COPYRIGHT © 2019, RADIO BRIDGE INC. API FOR THE RADIO BRIDGE CONSOLE PAGE 12 OF 13
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.
API FOR THE RADIO BRIDGE CONSOLE
COPYRIGHT © 2019, RADIO BRIDGE INC. API FOR THE RADIO BRIDGE CONSOLE PAGE 13 OF 13
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