iotagent-sigfox¶

IoT agents are responsible for receiving messages from physical devices (directly or through a gateway) and sending them commands in order to configure them. This iotagent-sigfox, in particular, receives messages via Sigfox’s network server, processes them and update all the attributes from the associated device.

Operation¶

Configuration¶

iotagent-sigfox configuration is pretty simple. It is mainly configured by environment variables, which are (with default values):

# Where Kafka is located
export KAFKA_ADDRESS=kafka:9092
# Where data-broker is located
export DATA_BROKER_ADDRESS=data-broker:80
# Where auth service can be reached
export AUTH_ADDRESS=auth:5000
# Where device-manager is located
export DEVM_ADDRESS=device-manager:5000
# Where sigfox backend server is
export SIGFOX_BACKEND_SERVER=localhost:8008
# Where a Redis instance is (to store device-related data)
export IOTAGENT_SIGFOX_CACHE_HOST=iotagent-sigfox-redis
# Which port will be used by this IoT agent to receive messages from backend
export IOTAGENT_SIGFOX_PORT=80

Receiving messages from DeviceManager via Kafka¶

Messages containing device operations should be in this format:

{
  "event": "create",
  "meta": {
    "service": "admin"
  },
  "data": {
    "id": "efac",
    "attrs" : {
      "1": [
        {
          "template_id": "1",
          "label": "device",
          "value_type": "string",
          "type": "static",
          "id": 1
        }
      ]
    }
  }
}

These messages are related to device creation, update, removal and actuation events. For creation and update operations, it contains the device data model to be added or updated. For removal operation, it will contain only the device ID being removed. The actuation operation will contain all attributes previously created with their respective values.

The documentation related to this message can be found in DeviceManager Messages.

Registering SigFox users in iotagent-sigfox¶

Before creating any device, a SigFox user must be registered in iotagent-sigfox so it can create devices. This is done by sending a POST request to it:

This will be stored internally by iotagent-sigfox and it won’t be retrievable nor removable, but it is rewritable. If one must invalidate a particular user, then its password must be updated to an invalid one.

Device configuration for iotagent-sigfox¶

The following device attributes are considered by iotagent-sigfox. All these attributes are of static_value type.

Device attributes for iotagent-sigfox¶
Attribute	Attribute type	Description	Example
device	static	SigFox device ID	“3DE15A”
pac_number	static	Porting Authorization Code for this device	“6A757C859B23471B”
product_certificate	static	Product certificate key to associate to each device (optional)	“P_0004_D356_03”
sigfox_user	static	SigFox user to be associated to this device. The registration will be performed on behalf of this user.	“897987231”
device_type_id	static	SigFox device type ID	“875928d”
device_coordinates	static	Device coordinates	“-22.8742,-47.0505”
avg_snr	dynamic	Average received SNR	64.04
rssi	dynamic	Received RSSI	-75.6
seq_number	dynamic	Message sequence number	1356
snr	dynamic	Last received SNR	65.2
station	dynamic	Station associated to this device	“6C47”
station_coordinates	dynamic	Station geolocation	“-22.8742,-47.0505”

Example¶

The following message serves as an example of a device with all attributes used by iotagent-sigfox.

{
  "label": "Sigfox Device",
  "attrs": [
    {
      "label": "device",
      "type": "static",
      "value_type": "string",
      "static_value": "device_id_1"
    },
    {
      "label": "pac_number",
      "type": "static",
      "value_type": "string",
      "static_value": "6A757C859B23471B"
    },
    {
      "label": "product_certificate",
      "type": "static",
      "value_type": "string",
      "static_value": "P_0004_D356_03"
    },
    {
      "label": "sigfox_user",
      "type": "static",
      "value_type": "string",
      "static_value": "98792872"
    },
    {
      "label": "device_type_id",
      "type": "static",
      "value_type": "string",
      "static_value": "8498761"
    },
    {
      "label": "device_coordinates",
      "type": "static",
      "value_type": "geo:point",
      "static_value": "-22.8742,-47.0505"
    },
    {
      "label": "avg_snr",
      "type": "dynamic",
      "value_type": "float"
    },
    {
      "label": "rssi",
      "type": "dynamic",
      "value_type": "float"
    },
    {
      "label": "seq_number",
      "type": "dynamic",
      "value_type": "integer"
    },
    {
      "label": "snr",
      "type": "dynamic",
      "value_type": "float"
    },
    {
      "label": "station",
      "type": "dynamic",
      "value_type": "string"
    },
    {
      "label": "station_coordinates",
      "type": "dynamic",
      "value_type": "geo:point"
    }
  ]
}

With these parameters, iotagent-sigfox will register a new device. iotagent-sigfox assumes that device type is already created and all callback registration is already configured in SigFox backend.

Deployment¶

This document will show how to properly deploy an IoT agent SigFox in your current dojot deployment. This page assume that the deployment used the docker-compose scheme from repository dojot/docker-compose.

Build docker image¶

The first step to be executed is to build a Docker image. This can be done by executing the following command:

docker build -t iotagent-sigfox .

After building it, you can add it to docker-compose.yml (assuming you are using docker-compose. Other tools, such as Kubernetes, have their particular mechanism to add new services into the deployment). The following services should be added to docker-compose.yml file:

iotagent-sigfox-redis:
  image: redis:alpine
  restart: always
  logging:
    driver: json-file
    options:
      max-size: 100m

iotagent-sigfox:
  image: iotagent-sigfox
  depends_on:
    - iotagent-sigfox-redis
    - kafka
    - data-broker
    - auth
  restart: always
  logging:
    driver: json-file
    options:
      max-size: 100m

Also, kong.config.sh script should also be changed. This modification will configure Kong to forward all requests received for /sigfox endpoint to iotagent-sigfox. You can add the following lines to the end of this script:

(curl -o /dev/null ${kong}/apis -sS -X PUT \
    --header "Content-Type: application/json" \
    -d @- ) <<PAYLOAD
{
    "name": "iotagent-sigfox",
    "uris": ["/sigfox", "/sigfox_user"],
    "strip_uri": false,
    "upstream_url": "http://iotagent-sigfox:80"
}
PAYLOAD

After this, you’ll need to rerun kong-config service (to apply this new configuration to Kong):

docker-compose up kong-config

At last, the IoT agent can be started:

docker-compose up -d iotagent-sigfox

To use this IoT agent, you must add Sigfox user, used to register new devices in sigfox backend servers and, sigfox template using this user and add a few Sigfox devices. There a sample template to be used in Operation section and a simple exemple of how to add users. To test whether everything is working, you could send some dummy messages, like these:

curl -X POST ${DOJOT_HOST}/sigfox -H "Content-Type:application/json" -d '
  {
    "timestamp": '$(date +%s)',
    "station_lat": 0,
    "station_lng": 0,
    "data": "sample-data",
    "device" : "device_id_1"
  }'

This will send the “sample-data” message payload to a particular device (sigfox ID is `device_id_1`).

How to build/update/translate documentation¶

If you have a local clone of this repository and you want to change the documentation, then you should follow this simple guide.

Build¶

The readable version of this documentation can be generated by means of sphinx. In order to do so, please follow the steps below. Those are actually based off ReadTheDocs documentation.

pip install sphinx sphinx-autobuild sphinx_rtd_theme sphinx-intl
make html

For that to work, you must have pip installed on the machine used to build the documentation. To install pip on an Ubuntu machine:

sudo apt-get install python-pip

To build the documentation in Brazilian Portuguese language, run the following extra commands:

sphinx-intl -c conf.py build -d locale
make html BUILDDIR=build/html-pt_BR O='-d build/doctrees/ -D language=pt_BR'

Update workflow¶

To update the documentation, follow the steps below:

Update the source files for the english version
Extract translatable messages from the english version

make gettext

Update the message catalog (PO Files) for pt_BR language

sphinx-intl -c conf.py update -p build/gettext -l pt_BR

Translate the messages in the pt_BR language PO files

This workflow is based on the Sphinx i18n guide.

How does it work¶

iotagent-sigfox depends on two things: a Kafka broker, so that it can receive messages informing it about new devices (and, in extension, about their updates and removals), and access to a Sigfox network server, so that it can receive messages from the devices. When a new device is added to dojot, this IoT agent receives a notification indicating this. Thus, it communicates with the configured network server, creating a new device type, registering the new device and properly configuring a callback endpoint so that it will receive any update related to devices of the same type.

How to build¶

As this is a npm-based project, building it is as simple as

npm install
npm run build

If everything runs fine, the generated code should be in ./build folder.

How to run¶

As simple as:

npm start ./config.json

Remember that you should already have a Kafka node (with a zookeeper instance) and access to a Sigfox network server.

How do I know if it is working properly?¶

Simply put: you won’t. In fact you can implement a simple Kafka publisher to emulate the behaviour of a device manager instance and a listener to check what messages it is generating. But it seems easier to get the real components - they are not that hard to start and to use (given that you use dojot’s docker-compose). Check also DeviceManager documentation for further information about how to create a new device.