Soilstate frontend

Tutorial objectives

At the end of the tutorial on the frontend you should be able to:

Understand how the frontend authenticates with the backend
Understand how to receive device meta data
Understand how to receive device observations

Frontend API usage

There are three types of API available:

authentication - permits the user to login
end device events - sensor meta data including position, naming, removal and more
observations - actual sensor readings

As we don’t prescribe the use of a particular frontend technology–there are so many to choose from!–the following sections show the APIs that a frontend will need. Authentication is required when an “HTTP Unauthorized” response (a 403) is replied to the /api endpoints of end device events and observations.

Server Sent Events

Server Sent Events (SSE) are used for receiving meta data and observations so that data is pushed to your front-end application almost as fast as it is produced i.e. there is no polling required for data. This makes your front-end application highly responsive and keeps network usage down.

SSE is baked into your browser and so connection management is also taken care of entirely.

To TLS or not to TLS…

When running your application from within your IDE i.e. using the java command, Streambed applications will default to http and port 9000. When running in Docker, https and an external port that you bind to 9000 will be used. This document assumes that you are not running your app via Docker.

Proxying

When developing your front end application you will need to proxy its requests to the backend in order to conform with the same origin policy. Here is an example using the npm based http-server which will serve up files from your current working directory, and proxy any /api requests to a running backend process:

http-server --proxy http://localhost:9000

Authenticate

curl \
  -v \
  -d'{"username":"admin","password":"password"}' \
  -H"Content-Type: application/json" \
  http://localhost:9000/api/login

Note the token that is replied. Let’s assume it is c527c50b678dece80cbc1c7d for the following commands.

Subscribe to end device events

curl \
  -v \
  -H"Authorization: Bearer c527c50b678dece80cbc1c7d" \
  http://localhost:9000/api/end-devices

A front end is typically interested in the following end device events:

SSE type: `PositionUpdated`

{
  "nwkAddr": 1,
  "time": "1970-01-01T00:00:00Z",
  "position": {
    "lat": 1,
    "lng": 2,
    "alt": 3
  },
  "type": "PositionUpdated"
}

and

SSE type: `NwkAddrRemoved`

{"nwkAddr":1,"type":"NwkAddrRemoved"}

Subscribe to observations

curl \
  -v \
  -H"Authorization: Bearer c527c50b678dece80cbc1c7d" \
  http://localhost:9000/api/$deviceType;format="norm"$

The format of the data will depend on your sensor.

Next: Reference