-
Notifications
You must be signed in to change notification settings - Fork 4
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #51 from TheThingsIndustries/docs/production-app
doc: Add production app documentation
- Loading branch information
Showing
5 changed files
with
247 additions
and
21 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,79 @@ | ||
| --- | ||
| title: "Sensor Edition: vanilla application" | ||
| description: "" | ||
| weight: -2 | ||
| distributions: null | ||
| --- | ||
|
|
||
| {{% gnse %}} comes pre-programmed with a vanilla application that showcases the device functionality and capabilities. | ||
|
|
||
| The application leverages a combination of the on-board components such as LEDs, button, buzzer, accelerometer, secure element, temperature and humidity sensor. | ||
|
|
||
| <!--more--> | ||
|
|
||
| ## Claiming your device | ||
|
|
||
| The vanilla application uses the on-board secure element to join the LoRaWAN network using over the air activation (OTAA) method. | ||
|
|
||
| You can claim your device on the The Things Stack cloud by following this [guide](https://www.thethingsindustries.com/docs/devices/device-claiming/claim-devices/). | ||
|
|
||
| ## Powering up your device | ||
|
|
||
| After claiming, you can power up the device using two standard AA batteries. | ||
|
|
||
| If the device powers up correctly, you will see the red, green and blue LEDs blinking thus indicating successful boot-up. | ||
|
|
||
| ## Joining the network | ||
|
|
||
| The device will attempt to join LoRaWAN network using OTAA indicated by the blinking red led. | ||
|
|
||
| When the device joins successfully, the buzzer will ring briefly the red LED will stop blinking. | ||
|
|
||
| ## Default uplinks and events | ||
|
|
||
| After a successful join, the device will periodically transmit two types of messages. | ||
|
|
||
| 1. A heartbeat message on FPort 1 every 25 seconds | ||
| 2. A Temperature and Humidity reading on FPort 2 every 1 minute | ||
|
|
||
| You can also press the button to transmit an uplink with the heartbeat message. | ||
|
|
||
| The device will blink the green LED with each successful uplink. | ||
|
|
||
| ## Heartbeat | ||
|
|
||
| The heartbeat uplink message sent by the device on FPort 1 contains the device battery voltage and the firmware version. | ||
|
|
||
| ## Temperature and Humidity | ||
|
|
||
| The temperature and humidity uplink message sent on FPort 2 contains the temperature in Celsius and the humidity in percentage. | ||
|
|
||
| ## Accelerometer | ||
|
|
||
| The accelerometer is disabled by default and can be enabled via a downlink on FPort 3 to detect shake and free-fall events. | ||
| When an accelerometer event occurs (shake or free-fall), the device will transmit an uplink with the temperature and humidity readings. | ||
|
|
||
| {{< note "The accelerometer should be disabled when it's not used to conserve energy" />}} | ||
|
|
||
| ## Button | ||
|
|
||
| The button is enabled by default and can be disabled or enabled via a downlink on FPort 4. | ||
| When the button is enabled, pressing the button will send a heartbeat uplink message. | ||
|
|
||
| ## Buzzer | ||
|
|
||
| The buzzer is disabled by default can be enabled via a downlink on FPort 5. | ||
| The buzzer can ring briefly in two tones, warning and danger. | ||
|
|
||
| ## Blue LED | ||
|
|
||
| The blue LED is disabled by default and can be enabled via a downlink on FPort 6. | ||
| This feature can be used to indicate that the device requires attention (battery change, reset, re-positioning, etc) | ||
|
|
||
| ## Adjusting the device behavior | ||
|
|
||
| The vanilla application attempts to be as generic as possible to facilitate exploring the device functionality. | ||
|
|
||
| Use the [uplinks guide]({{< ref "/applications/se-vanilla/uplinks" >}}) to decode the uplink messages. | ||
|
|
||
| Follow the [downlinks guide]({{< ref "/applications/se-vanilla/downlinks" >}}) to adjust the device functionality according to your needs. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,107 @@ | ||
| --- | ||
| title: "downlinks" | ||
| description: "" | ||
| weight: 2 | ||
| --- | ||
|
|
||
| The vanilla app can be configured using downlinks to control the device functionality and effectively unlock new features. | ||
|
|
||
| Each device component is controlled on a separate FPort, but please remember that LoRaWAN class A devices can only receive a downlink when they transmit and uplink. | ||
|
|
||
| So make sure you trigger an uplink via the button or wait for a periodic uplink message in order for the device to receive your downlink. | ||
|
|
||
| ## Heartbeat | ||
|
|
||
| - Disable periodic heartbeat uplink: | ||
|
|
||
| | FPort | Command (first byte) | | ||
| |-------|-----------------------------| | ||
| | 0x01 | 0x00 | | ||
|
|
||
| - Enable periodic heartbeat uplink every 10 minutes: | ||
|
|
||
| | FPort | Command (first byte) | | ||
| |-------|-----------------------------| | ||
| | 0x01 | 0x0A | | ||
|
|
||
| The periodicity can range from 0x01 (every 1 minute) to 0xC8 (every 200 minutes). | ||
|
|
||
|
|
||
| ## Temperature and Humidity | ||
|
|
||
| - Disable periodic temperature and humidity uplink: | ||
|
|
||
| | FPort | Command (first byte) | | ||
| |-------|-----------------------------| | ||
| | 0x02 | 0x00 | | ||
|
|
||
| - Enable periodic temperature and humidity uplink every 25 minutes: | ||
|
|
||
| | FPort | Command (first byte) | | ||
| |-------|-----------------------------| | ||
| | 0x02 | 0x19 | | ||
|
|
||
| The periodicity can range from 0x01 (every 1 minute) to 0xC8 (every 200 minutes). | ||
|
|
||
| ## Accelerometer | ||
|
|
||
| - Disable accelerometer events: | ||
|
|
||
| | FPort | Command (first byte) | | ||
| |-------|-----------------------------| | ||
| | 0x03 | 0x00 | | ||
|
|
||
| - Enable accelerometer shake event detection: | ||
|
|
||
| | FPort | Command (first byte) | | ||
| |-------|-----------------------------| | ||
| | 0x03 | 0x01 | | ||
|
|
||
| - Enable accelerometer free-fall event detection: | ||
|
|
||
| | FPort | Command (first byte) | | ||
| |-------|-----------------------------| | ||
| | 0x03 | 0x02 | | ||
|
|
||
| ## Button | ||
|
|
||
| - Disable button events: | ||
|
|
||
| | FPort | Command (first byte) | | ||
| |-------|-----------------------------| | ||
| | 0x04 | 0x00 | | ||
|
|
||
| - Enable button events: | ||
|
|
||
| | FPort | Command (first byte) | | ||
| |-------|-----------------------------| | ||
| | 0x04 | 0x01 | | ||
|
|
||
| ## Buzzer | ||
|
|
||
| - Briefly ring buzzer with warning tone: | ||
|
|
||
| | FPort | Command (first byte) | | ||
| |-------|-----------------------------| | ||
| | 0x05 | 0x01 | | ||
|
|
||
| - Briefly ring buzzer with danger tone: | ||
|
|
||
| | FPort | Command (first byte) | | ||
| |-------|-----------------------------| | ||
| | 0x05 | 0x02 | | ||
|
|
||
|
|
||
| ## Blue LED | ||
|
|
||
| - Disable the blue LED: | ||
|
|
||
| | FPort | Command (first byte) | | ||
| |-------|-----------------------------| | ||
| | 0x06 | 0x00 | | ||
|
|
||
| - Turn on the blue LED: | ||
|
|
||
| | FPort | Command (first byte) | | ||
| |-------|-----------------------------| | ||
| | 0x06 | 0x01 | |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,45 @@ | ||
| --- | ||
| title: "uplinks" | ||
| description: "" | ||
| weight: 1 | ||
| --- | ||
|
|
||
| The vanilla app uplinks are compromised of two simple messages (heartbeat and temperature/humidity) to reduce the complexity and show a simple example of the device functionality. | ||
|
|
||
| ## Payload formatters | ||
|
|
||
| Please see [The Things Stack Javascript payload formatter documentation](https://www.thethingsindustries.com/docs/integrations/payload-formatters/javascript/) for information on how to use payload formatters. | ||
|
|
||
| The javascript payload formatter below can be used to decode the vanilla app. | ||
|
|
||
| ```javascript | ||
| function decodeUplink(input) { | ||
| var data = {}; | ||
| if (input.fPort == 1) | ||
| { | ||
| data.BATTERY_VOLTAGE = (input.bytes[0]/10); | ||
| data.GNSE_FW_VERSION = input.bytes[1] + (input.bytes[2]/10); | ||
| } | ||
|
|
||
| if (input.fPort == 2) | ||
| { | ||
| data.TEMPERATURE = ((input.bytes[0] << 8) + input.bytes[1])/10; | ||
| data.HUMIDITY = ((input.bytes[2] << 8) + input.bytes[3])/10; | ||
| } | ||
| return { | ||
| data: data, | ||
| }; | ||
| } | ||
| ``` | ||
|
|
||
| ## Heartbeat | ||
|
|
||
| The heartbeat uplink message on FPort 1 contains: | ||
| - The device battery voltage (useful for replacing the batteries) | ||
| - The firmware version (useful for checking which commands to send) | ||
|
|
||
|
|
||
| ## Temperature and Humidity | ||
| The temperature and humidity uplink message on FPort 2 contains: | ||
| - The temperature in Celsius | ||
| - The humidity in percentage (between 0% to 100%) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters