Jetstream™ Developer Guide
What is Jetstream?
“Jetstream™ makes it easy for developers to create powerful new applications or quickly enhance
existing applications to use RFID by providing the complex infrastructure and management as a
simple cloud API service for globally distributed locations.”
A more basic description of what Jetstream™ is and what it does is this: Jetstream™ is the
infrastructure that facilitates communications between remotely deployed devices and the
applications that consume and parse data from them.
So what does this mean? Let’s pretend that we have an inventorying device deployed to a location
several hundred miles away. The device uses Jetstream™ to send messages to “headquarters”. An
application at headquarters picks up these messages and consolidates the information into a
meaningful format for human consumption.
Jetstream™ provides a very simple API allowing for the remotely deployed devices to be
configured and queried. Similarly, the devices automatically send messages to report inventory
plusses and minuses, general health and any problems.
The Jetstream™ API is based on the industry standard ReST protocol and leverages a global
infrastructure to provide redundant and responsive functionality. When combined with Terso
Solutions’ proven RFID Storage and Support Services…
“… Jetstream™ lets you focus your time on developing business value, not on the technologies or
capital investments.”
An example of Jetstream™ in action
A remotely deployed Jetstream™ enabled device will send a periodic ‘Heartbeat Event’ to
Jetstream. Jetstream™ will then pass the message to your in house Jetstream™ application.
Jetstream™
Enable
Device
Events
EE
In house Jetstream
Application
Jetstream
The in house Jetstream™ application can also send commands to the Jetstream™ enabled device.
An example of a command could be to query the device’s current network configuration.
Commands
and queries
Jetstream
Enable
Device
Jetstream
In house Jetstream
Application
Responses
When a request of this sort is made, the command is queued in Jetstream™ for the device to pick up
the next time it communicates. The device will process the command. A command completion will
be returned from Jetstream™ to the in house Jetstream™ application indicating the network
settings else indicate a failure condition.
Different devices behave differently. For example, Terso Solutions cabinets will post heartbeat
events on a regularly scheduled basis. Other Jetstream™ enabled devices might post heartbeats on
a different schedule.
Jetstream™ Website
Documentation
Access the Jetstream™ API documentation is available at https://www.jetstreamrfid.com. A
username and password are required to access the contents of the site.
Jetstream™ is currently on release v1.1. There are APIs for v1.0 and v1.1. Each version has a set of
commands broken down into the following sections:





Description
Authentication
Request Parameters
Errors
Response Schema
In addition, there are samples illustrating HTTP request/responses and code examples. An
example CommandComplettionEvent is also provided where appropriate.
In addition to the configuration commands and other commands, a list of events is also listed here.
Each event is listed with:



Description
Schema
Sample Event XML
Resources
The Jetstream™ documentation website also has a Resources section. The Jetstream™ SDKs are
available for download there. A device simulator is also provided to make insertion of messages
into Jetstream™ easier.
The device simulator impersonates a Jetstream™ enabled device to send events to Jetstream. After
submitting events via the simulator, the XML that was prepared and sent to Jetstream™ as well as
the response will be displayed.
Prerequisites to using Jetstream
Terso will need a valid email address to setup a Jetstream™ account. A new application and user
will be created using this information. The application is a logical boundary in Jetstream™ that
contains devices and users. Security is done at the application level for users.
An access key will be sent to the provided email address. The access key is required to make any
call to the Jetstream™ API. If the access key is lost or is compromised, Terso can generate a new
key as well. There are three important pieces of information in email.


Access Key - The access key is used as the authentication mechanism with Jetstream
Base Jetstream™ URL - The base Jetstream™ URL is the endpoint to issue API commands
against
At this point, Jetstream™ is ready to have devices added to it.
Adding a device to Jetstream
For the purposes of these examples, the access key has been replaced with <ACCESS_KEY>. If you
execute these commands, be sure to substitute in the appropriate access key.
The following parameters are needed when adding a device to Jetstream:




Device Serial Number – The physical device serial number
Logical Device ID – The logical device id to correlate to the device serial number
Device Definition ID – The id of the device definition currently available in Jetstream. Terso
can add device definitions for use if needed.
Region – The region that the device is being placed. Valid values are US, EU and ASIA.
The device definition ID is not known yet. A query into Jetstream™ can solve this problem.
Get Device Definitions
Since Jetstream™ is a ReST based system, the easiest way to query for information is simply by
entering the proper URL(s) into a web browser.
The “Get Device Definitions” command is a very simple call.
https://jetstream.tersosolutions.com/v1.0/application/?
Action=GetDeviceDefinitions
&AccessKey=<ACCESS_KEY>
Entering this into a web browser will return all of the available device definitions that Jetstream™
supports. A device definition is a unique collection of settings and key/values pairs for a specific
device. Other details included are definition name, hardware manufacturer, firmware version and
firmware download URL.
The output of "GetDeviceDefinitions" in Google Chrome
Add Device
Now that the device definition ID is known, the device can be added. Using the AddLogicalDevice
command, add a device to Jetstream™. A physical device is correlated to a logical identifier using
the serial number with the AddLogicalDevice command. This allows for the replacement of the
physical device without having to change any subscribers.
At this point, the device can be added to Jetstream™.
https://jetstream.tersosolutions.com/v1.0/application/?
Action=AddLogicalDevice
&AccessKey=<ACCESS_KEY>
&DeviceSerialNumber=123456
&LogicalDeviceId=DCDock12
&DeviceDefinitionId=d5ac4f89-7113-49e4-8509-29fe6b0fd5c7
&Region=US
The XML response from Jetstream™ is very minimal from executing the command.
<Jetstream™ xmlns="http://Jetstream.TersoSolutions.com/v1.0/ConfigureResponse">
<Header/>
<ConfigureResponse Id="b72061c0-6cbc-41b0-9819-0aae4f857afe"/>
</Jetstream>
The ConfigureResponse includes the AccessKey in the ‘ID’ field the device needs to use to
communicate with Jetstream™.
Get Configuration
Jetstream™ can be queried at any time to view the current configuration of the application. To do
so, use the GetConfiguration command.
https://jetstream.tersosolutions.com/v1.0/application/?
Action=GetConfiguration
&AccessKey=<ACCESS_KEY>
Again, Jetstream™ will respond with an XML message showing the current state of the application.
<Jetstream™ xmlns="http://Jetstream.TersoSolutions.com/v1.0/GetConfigurationResponse">
<Header/>
<GetConfigurationResponse>
<LogicalDeviceList>
<LogicalDevice Region="US" DeviceSerialNumber="123" LogicalDeviceId="USDC1Dock1"
DeviceDefinitionId="082e3b03-2cef-4f07-83d0-7de716f67028" Health="Active" />
<LogicalDevice Region="EU" DeviceSerialNumber="234" LogicalDeviceId="EUDC1Dock1"
DeviceDefinitionId="cd6e0dc8-cc3a-43fe-ba50-1598b80bc4f7" Health="Failed" />
<LogicalDevice Region="ASIA" DeviceSerialNumber="345"
LogicalDeviceId="ASIADC1Dock1"
DeviceDefinitionId="01b10c57-7497-4361-86c5-63d6a04f3ba4" Health="Restoring" />
</LogicalDeviceList>
</GetConfigurationResponse>
</Jetstream>
Device Simulator or Real Unit
Using the Device Simulator, available on the Jetstream™ Documentation website at
https://jetstreamrfid.com, users can emulate a number of different functions that Jetstream™
enabled devices can perform.
Before emulating any of the functions, the device’s serial number and access key are needed. If
necessary, Terso can reset the device’s access key. Please keep in mind that once reset, the device
using the old access key will no longer be able to communicate with Jetstream™.
Sending a heartbeat event
Navigate to the device simulator at https://jetstreamrfid.com/Simulator/HeartbeatEvent and
enter in the device’s serial number and access key. The current date and time are entered by
default; It can be overridden as desired. Click the Send button to emulate the device sending a
Heartbeat event.
Notice that the response is simply an ‘HTTP 200 (OK)’ code. This indicates that the event was
successfully posted to Jetstream. Had the serial number or access key been incorrect, an ‘HTTP
400 (Error)’ would have been displayed.
Querying a device
A more useful example of communications with a device is to ask a device for some information
about its current configuration using the GetConfigValuesCommand. Keep in mind that queued
messages will eventually time out if the end device does not acknowledge that the command was
received.
A number of parameters are needed to perform the command:



Access Key
Logical Device ID
An underscore delimited list of parameters to retrieve the current value on the device
https://jetstream.tersosolutions.com/v1.0/application/?
Action=GetConfigValuesCommand
&AccessKey=<ACCESS_KEY>
&LogicalDeviceId=DCDock12
&Parameters=IP_SubNet_Gateway
The response that comes back from the command request is very minimal.
<Jetstream™ xmlns="http://Jetstream.TersoSolutions.com/v1.0/CommandResponse">
<Header/>
<CommandResponse CommandId="b08f13bf-f5fc-4f2e-a49a-d8632f1415bf" />
</Jetstream>
Getting the results of communications
Messages from Device Simulator and live devices are sent to Jetstream™ and can be retrieved by
calling the GetEvents command.
Queued Command
Using the previous example of a GetConfigValuesCommand, an email is received from Jetstream™
of the command.
<Jetstream™ xmlns="http://Jetstream.TersoSolutions.com/v1.0/CommandQueuedEvent">
<Header EventId="8353c9eb-897b-4d7c-a988-10748b1b704c" EventTime="2012-04-13T19:49:33Z"
LogicalDeviceId="DCDock12" />
<CommandQueuedEvent CommandId="35144c40-e995-4d00-8db1-cfc9fd924664"
CommandName="GetConfigValuesCommand" UserName="Tsukasa">
<ParameterList>
<Parameter Name="Parameter0" Value="ip" />
<Parameter Name="Parameter1" Value="subnet" />
<Parameter Name="Parameter2" Value="gateway" />
</ParameterList>
</CommandQueuedEvent>
</Jetstream>
Device Response
The device picks up the request the next time it communicats with Jetstream™. In response, the
device generates a CommandCompletionEvent with the requested values for the indicated
parameters.
<Jetstream™ xmlns="http://Jetstream.TersoSolutions.com/v1.0/CommandCompletionEvent">
<Header EventId="77823460-5859-4124-aa89-b1130e861017" EventTime="2012-04-13T19:57:32Z"
ReceivedTime="2012-04-13T19:59:49Z" />
<CommandCompletionEvent CommandId="35144c40-e995-4d00-8db1-cfc9fd924664">
<OutputParameterList>
<OutputParameter Name="ip" Value="0.0.0.0" />
<OutputParameter Name="subnet" Value="0.0.0.0" />
<OutputParameter Name="gateway" Value="0.0.0.0" />
</OutputParameterList>
<ExceptionList />
<DeviceExtensionList />
</CommandCompletionEvent>
</Jetstream>
Device Simulator Response
To simulate a reply, navigate to the Device Simulator
https://jetstreamrfid.com/Simulator/CommandCompletionEvent
Each of the requested parameters should be entered in the Output Parameter Name field with an
appropriate value in the Message field. The CommandId must be the Command Response ID from
the GetConfigValuesCommand entered in the browser. This ties the two commands together in a
request/acknowledge mechanism.
Other Considerations
These are the basic concepts Jetstream™ provides. Terso encourages user’s to use the Device
Simulator while prototyping an application or until a real world device can be used in its place. All
commands and messages are fully documented on website. Please contact Terso if problems are
encountered or for suggestions on how Jetstream™ could be better.