ttn-osem-integration

Integration for openSenseMap with TheThingsNetwork, that provides simple measurement upload from LoRa-WAN devices.

It decodes measurements from an uplink payload from the TTN HTTP Integrations API for a configured senseBox, and adds the decoded measurements to the database.

There are multiple decoding options provided via profiles, which may be easily extended to support other sensor configurations or value transformations.

configuring a box

To associate a device on the TTN network with a box on the openSenseMap, there is some configuration required on the openSenseMap. The box has to contain a field box.integrations.ttn with the following structure:

ttn: {
  // the app_id & dev_id you recieved when registering on TTN
  app_id: 'abcd',
  dev_id: '1234',
  // decode the messages according to this profile format, see below
  profile: 'lora-serialization',
  // optional. some profiles require additional configuration
  decodeOptions: [],
  // optional. if specified, only messages recieved on this LoRa-port are stored
  port: 3,
}

decoding profiles

`sensebox/home`

Decodes messages which contain 5 measurements of all sensors of the senseBox:home. The correct sensorIds are matched via their titles. Decoding fits the dragino senseBox:home sketch.

`lora-serialization`

Allows decoding of messages that were encoded with the lora-serialization library. The sub-profiles temperature, humidity, uint8, uint16 and unixtime are supported. Each encoded value is matched to a sensor via it's _id, sensorType, unit, or title properties. There may be one or more property defined for each value via sensor_id, sensor_title, sensor_type, sensor_unit. If one property matches a sensor, the other properties are discarded.

The following example config allows decoding of measurements of 3 sensors:

"ttn": {
  "profile": "lora-serialization",
  "decodeOptions": [
    { "sensor_unit": "°C", "decoder": "temperature" },
    { "sensor_id": "588876b67dd004f79259bd8b", "decoder": "humidity" },
    { "sensor_type": "TSL45315", "sensor_title": "Beleuchtungsstärke", "decoder": "uint16" }
  ]
}

When decodeOptions contains an element { "decoder": "unixtime" }, the value will be used as timestamp for all other measurements.

`debug`

Simple decoder, which decodes a given number of bytes to integer values. Requires a config like the following, where the measurements are applied to the sensors in the order of box.sensors.

ttn: {
  profile: 'lora-serialization',
  decodeOptions: [3, 1, 2] // specifies the number of bytes to consume for each measurement
}

`json`

It's also possible to add measurements which already have been decoded by a TTN payload function. The property payload_fields has to contain JSON in the format accepted by the openSenseMap-API. This is the case, if the TTN application has a Payload Function defined.

deployment

There is a Dockerfile, as well as an docker-compose.yml which includes a mongodb instance. If you want to run the application directly, you need to have the dependencies listed below installed. For configuration, see below. Once configured, run

yarn install
npm start

dependencies

node.js >= 6.x
yarn
mongodb >= 3.x

configuration

See config.js. All options may be overridden by environment variables. Currently, the connection string to mongodb must be configured through the environment variables of the openSenseMap-API config:

OSEM_dbuser=user
OSEM_dbuserpass=pass
# ...or just:
OSEM_dbconnectionstring=mongodb://localhost/OSeM-api

development

JSDoc documentation can be found under ./docs/ or sensebox.github.io/ttn-osem-integration. To update it, run npm run docs.
To run the test suite, either run export OSEM_dbconnectionstring=....; npm run test while the application is running, or ./run_tests.sh (requires bash & docker).
Please follow the existing code style. Double check by running npm run lint.

license

MIT, see LICENSE

Home