Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: Add production app documentation #51

Merged
merged 1 commit into from
Feb 23, 2022
Merged

Conversation

elsalahy
Copy link
Contributor

Summary

This adds documentation for the production app.

Screenshots

...

Changes

  • Add production application documentation

Notes for Reviewers

...

Checklist

  • Scope: The referenced issue is addressed, there are no unrelated changes.
  • Run Locally: Verified that the docs build using make server, posted screenshots, verified external links.
  • New Features Marked: Documentation for new features is marked using the new-in-version shortcode, according to the guidelines in CONTRIBUTING.
  • Style Guidelines: Documentation obeys style guidelines in CONTRIBUTING.
  • Commits: Commit messages follow guidelines in CONTRIBUTING, there are no fixup commits left.

@elsalahy
Copy link
Contributor Author

@johanstokking, no need to go into the details, just wanted to alert you on this!


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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A payload downlink formatter may be added later for this, but the commands are small enough to be doable using binary/hex.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes indeed, I leave this up to you guys to play with and add to this documentation in the future

The javascript payload formatter below can be used to decode the vanilla app.

```javascript
function decodeUplink(input) {

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can be formatted to:

function decodeUplink(input) {
    var data = {};
    if (input.fPort == 1) {
        data.batteryVoltage = (input.bytes[0] / 10);
        data.fwVersion = 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,
    };
}

Maybe worth adding to the Device Repository instead ? For the old Uno/Nodes, we allow people to select one of the default sketches as a firmware version, so maybe we could have the production app as one of the available firmwares, and it could use this formatter.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

With the current design of our GNSE repo, I don't recommend having a production app as standalone app.

The reason for this is that the applications were designed to allow for flexibility and versatility.
Adding a production app there will actively diminish the other applications purpose.

With sensors_lorawan and secure_element_lorawan I think users have all the foundation they need to build something similar to the production app.

I would like to also highlight that this this device addresses a different segment of developers than the ones using UNOs and The Things Node.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe worth adding to the Device Repository instead ?

I think it should be in both


## Temperature and Humidity
The temperature and humidity uplink message on FPort 2 contains:
- The temperature in Celsius.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Try to be consistent with the ending dots.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed this one, can't find others

@elsalahy elsalahy force-pushed the docs/production-app branch from 77812d7 to 374cb4c Compare November 29, 2021 21:22
Copy link
Contributor

@nejraselimovic nejraselimovic left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just improving readability a bit


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/).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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/).
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/).


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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
If the device powers up correctly, you will see the red, green and blue LEDs blinking thus indicating successful boot-up.
If the device powers up correctly, you will see the red, green and blue LEDs blinking thus indicating a successful boot-up.


## Joining the network

The device will attempt to join LoRaWAN network using OTAA indicated by the blinking red led.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The device will attempt to join LoRaWAN network using OTAA indicated by the blinking red led.
The device will attempt to join the LoRaWAN network using OTAA indicated by the blinking red LED.


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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
When the device joins successfully, the buzzer will ring briefly the red LED will stop blinking.
When the device successfully joins, the buzzer will briefly ring and the red LED will stop blinking.


## Default uplinks and events

After a successful join, the device will periodically transmit two types of messages.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
After a successful join, the device will periodically transmit two types of messages.
After a successful join, the device will periodically transmit two types of messages:

|-------|-----------------------------|
| 0x06 | 0x00 |

- Turn on the blue LED:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- Turn on the blue LED:
To turn on the blue LED:

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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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.
The vanilla app uplinks are composed of two simple messages, a heartbeat and a temperature/humidity uplink, to reduce the complexity and show a simple example of the device functionality.


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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The javascript payload formatter below can be used to decode the vanilla app.
The Javascript payload formatter below can be used to decode the vanilla app.

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)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change

## 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%)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- The humidity in percentage (between 0% to 100%)
- The relative humidity percentage (between 0% to 100%)

@nejraselimovic nejraselimovic merged commit 376a332 into master Feb 23, 2022
@adriansmares adriansmares deleted the docs/production-app branch August 12, 2022 12:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants