diff --git a/Examples/Accelerometer/Accelerometer.ino b/Examples/Accelerometer/Accelerometer.ino index 8646466..ef481de 100644 --- a/Examples/Accelerometer/Accelerometer.ino +++ b/Examples/Accelerometer/Accelerometer.ino @@ -41,7 +41,8 @@ void setup() { setAccelerometerRange(ACC_RANGE); } -void loop() {float x,y,z; +void loop() { + float x,y,z; getAcceleration(&x, &y, &z); Serial.print("Acceleration:\tx="); diff --git a/Examples/Accelerometer/README.md b/Examples/Accelerometer/README.md index 284fb00..b441bb1 100644 --- a/Examples/Accelerometer/README.md +++ b/Examples/Accelerometer/README.md @@ -1,3 +1,9 @@ # Accelerometer -The KISS LoRa board has an FXLS8471Q accelerometer. See [FXLS8471Q.pdf](FXLS8471Q.pdf) for technical details on this sensor. \ No newline at end of file +The KISS LoRa board has an FXLS8471Q accelerometer. See [FXLS8471Q.pdf](FXLS8471Q.pdf) for technical details on this sensor. + +Communication with the accelerometer is also via the I2C bus, just like with the temperature and humidity sensor. The difference is that we do not have a library to handle setting up and reading values from the accelerometer. This makes this example more complex. + +I2C communication is handled by the Wire library. At startup we initialise the accelerometer by firstly checking if the device responds correctly via I2C. We then change a few configuration bits to allow constant measurements. We also configure it to read acceleration in the range -2g to +2g. + +At this stage it is important to remember that gravity causes a 1g acceleration toward the centre of the earth. This means that we can only measure an extra 1g downward acceleration, but a 3g upward acceleration. In all other axes we can measure 2g of acceleration. This range is good enough for most uses, but if you know that you need a greater range, but at a lower resolution, you can change the range configuration to either -4g to +4g or -8g to +8g. \ No newline at end of file diff --git a/Examples/CayenneLPP/CayenneLPP.ino b/Examples/CayenneLPP/CayenneLPP.ino index 9a998af..552adc0 100644 --- a/Examples/CayenneLPP/CayenneLPP.ino +++ b/Examples/CayenneLPP/CayenneLPP.ino @@ -60,7 +60,7 @@ void sendData(uint8_t port) getAcceleration(&x, &y, &z); lpp.addAccelerometer(6, x, y, z); - ttn.sendBytes(lpp.getBuffer(), lpp.getSize()); + ttn.sendBytes(lpp.getBuffer(), lpp.getSize(), 2, false, getSF()); } uint8_t getButtonPressed() diff --git a/Examples/CayenneLPP/README.md b/Examples/CayenneLPP/README.md index 9824fdb..b198d6d 100644 --- a/Examples/CayenneLPP/README.md +++ b/Examples/CayenneLPP/README.md @@ -1,5 +1,40 @@ # CayenneLPP example -See [this description](index.md) of what CayenneLPP is, and how you can use it via The Things Network. +See [this description](https://www.thethingsnetwork.org/docs/applications/Cayenne/) of what CayenneLPP is, and how you can use it via The Things Network. This example reads all the sensors on the KISS LoRa device and sends the values using CayenneLPP format, so that you can easily visualise the data on myDevices Cayenne. + +Because this example reads all the sensors, it contains all the code that you have previously seen. The only new part is the encoding of the payload using CayenneLPP format. + +## Description + +The lines in this sketch that you have not yet seen are as follow: + +`#include ` + +Include the CayenneLPP library to do the encoding of the data payload for us. + +`CayenneLPP lpp(51);` + +Create an instance of the LPP library, passing it the maximum size a payload can be that we can transmit. That is 51 bytes for LoRaWAN packets. + +``` +void sendData(uint8_t port) +{ + lpp.reset(); + lpp.addDigitalInput(1, getButtonPressed()); + lpp.addAnalogInput(2, getRotaryPosition()); + lpp.addRelativeHumidity(3, sensor.getRH()); + lpp.addTemperature(4, sensor.getTemp()); + lpp.addLuminosity(5, get_lux_value()); + + float x,y,z; + getAcceleration(&x, &y, &z); + lpp.addAccelerometer(6, x, y, z); + + ttn.sendBytes(lpp.getBuffer(), lpp.getSize(), 2, false, getSF()); +} +``` + +We reset the lpp instance and that will clear all old values from the buffer. Then we add the sensor values to the payload, giving it the "channel number" as first parameter, and the sensor value as second parameter. At the end we send the payload bytes we get from the LPP library, on port 2, not asking for an ack, and on a random spreading factor. + diff --git a/Examples/CayenneLPP/cayenne-add-device.png b/Examples/CayenneLPP/cayenne-add-device.png deleted file mode 100644 index c1969e9..0000000 Binary files a/Examples/CayenneLPP/cayenne-add-device.png and /dev/null differ diff --git a/Examples/CayenneLPP/index.md b/Examples/CayenneLPP/index.md deleted file mode 100644 index a865b98..0000000 --- a/Examples/CayenneLPP/index.md +++ /dev/null @@ -1,67 +0,0 @@ -# myDevices Cayenne - - -[myDevices Cayenne](https://mydevices.com/) allows you to quickly design, prototype, and visualize IoT solutions. You can use Cayenne as a tool to visualize real-time and historical data, sent over The Things Network. - - -## Change the payload to Cayenne LPP - -In order to display your content in the Cayenne dashboard, the payload has to be encoded with the Cayenne Low Power Payload (LPP) - -> We need to send extra data for Cayenne to understand what data comes into their dashboard. Before we send the sensor data, we need to define what type of data it is. The first byte is the so-called `Channel ID`. The second byte explains the `Data Type`. The latter bytes contain the actual sensor values. -Please have a look [**here**](https://mydevices.com/cayenne/docs/#lora-cayenne-low-power-payload) to find more information on the **Cayenne Low Power Payload (LPP)**. - -### CayenneLPP Class -Documentation about altering your Arduino Sketch to encode data with `CayenneLPP` can be found [here](https://www.thethingsnetwork.org/docs/devices/arduino/api/cayennelpp.html). - -*Example code:* - -```js -TheThingsNetwork ttn(loraSerial, debugSerial, freqPlan); -CayenneLPP lpp(51); // create a buffer of 51 bytes to store the payload - -lpp.reset(); // clear the buffer -lpp.addTemperature(1, 22.5); // on channel 1, add temperature, value 22.5°C -lpp.addBarometricPressure(2, 1073.21); // channel 2, pressure -lpp.addGPS(3, 52.37365, 4.88650, 2); // channel 3, coordinates - -ttn.sendBytes(lpp.getBuffer(), lpp.getSize()); -``` - -### Set the Payload Format in the Console - -After encoding data with CayenneLPP, have a look at the console to change the **Payload Formats** - -* Go to your Application in [**The Things Network Console**](https://console.thethingsnetwork.org/) and click **Payload Formats** -* In the dropdown menu select **Cayenne LPP** instead of **Custom** - - -## Set up your myDevices account - -1. Create an account on [myDevices](https://mydevices.com/) -2. Log-in and click on **LoRa** - - -3. Select **The Things Network** at the bottom of the left menu bar, click on **Cayenne LPP** and fill in your **DevEUI** of your device (which you can find in the [**Console**](https://console.thethingsnetwork.org/applications)) - ![add-device](cayenne-add-device.png) - - -## Add the myDevices Cayenne integration in the Console - -1. Go to your application in the [**Console**](https://console.thethingsnetwork.org/applications) and add the Cayenne integration via **Add Integration** - ![myDevices-dashboard](integrations.png) - -2. You can find your **Process ID** in the URL of the myDevices Cayenne dashboard, starting after `/lora/` -3. Add the integration - - - - -## Build your Cayenne dashboard -Click the device on the left side of your dashboard in Cayenne and your data is shown right away. After a bit of editing you can make quite some fancy stuff. - -![myDevices-dashboard](mydevices-data.png) - - -🎉 Now impress some folks with this amazing dashboard you built on Twitter, using *@thethingsntwrk @CayenneIoT* - diff --git a/Examples/CayenneLPP/integrations.png b/Examples/CayenneLPP/integrations.png deleted file mode 100644 index 07b552f..0000000 Binary files a/Examples/CayenneLPP/integrations.png and /dev/null differ diff --git a/Examples/CayenneLPP/logo-cayenne.png b/Examples/CayenneLPP/logo-cayenne.png deleted file mode 100644 index a02d734..0000000 Binary files a/Examples/CayenneLPP/logo-cayenne.png and /dev/null differ diff --git a/Examples/CayenneLPP/logo-mydevices.png b/Examples/CayenneLPP/logo-mydevices.png deleted file mode 100644 index da76967..0000000 Binary files a/Examples/CayenneLPP/logo-mydevices.png and /dev/null differ diff --git a/Examples/CayenneLPP/myDevices-lora.png b/Examples/CayenneLPP/myDevices-lora.png deleted file mode 100644 index 9fbe146..0000000 Binary files a/Examples/CayenneLPP/myDevices-lora.png and /dev/null differ diff --git a/Examples/CayenneLPP/mydevices-data.png b/Examples/CayenneLPP/mydevices-data.png deleted file mode 100644 index 6fa4700..0000000 Binary files a/Examples/CayenneLPP/mydevices-data.png and /dev/null differ diff --git a/Examples/LightSensor/LightSensor.ino b/Examples/LightSensor/LightSensor.ino index 6c13d51..a6ba7b7 100644 --- a/Examples/LightSensor/LightSensor.ino +++ b/Examples/LightSensor/LightSensor.ino @@ -36,7 +36,7 @@ void setup() { } void loop() { - Serial.print("Ambient ligh: "); + Serial.print("Ambient light: "); Serial.print(get_lux_value()); Serial.println("lux"); delay(1000); diff --git a/Examples/LightSensor/README.md b/Examples/LightSensor/README.md index 1ecc969..0015184 100644 --- a/Examples/LightSensor/README.md +++ b/Examples/LightSensor/README.md @@ -1,3 +1,5 @@ # Light Sensor -The KISS LoRa board has an APDS-9007 ambient light sensor. See [AV02-0512EN0.pdf](AV02-0512EN0.pdf) for technical details on this sensor. \ No newline at end of file +The KISS LoRa board has an APDS-9007 ambient light sensor. See [AV02-0512EN0.pdf](AV02-0512EN0.pdf) for technical details on this sensor. + +The ambient light sensor outputs the light intensity as an analog value that is logarithmically proportionate to the light intensity. This example reads the analog value and converts it to light intensity. \ No newline at end of file diff --git a/Examples/LoRa_TX_RX/LoRa_TX_RX.ino b/Examples/LoRa_TX_RX/LoRa_TX_RX.ino index 9cffbd3..ebc901d 100644 --- a/Examples/LoRa_TX_RX/LoRa_TX_RX.ino +++ b/Examples/LoRa_TX_RX/LoRa_TX_RX.ino @@ -48,7 +48,7 @@ void loop() byte payload[1]; payload[0] = getRotaryPosition(); - // Send it off on port 2 + // Send the payload, on port 2, not asking for an ack, using the random SF ttn.sendBytes(payload, sizeof(payload), 2, false, getSF()); delay(10000); diff --git a/Examples/LoRa_TX_RX/README.md b/Examples/LoRa_TX_RX/README.md index e7dbad2..a037e7f 100644 --- a/Examples/LoRa_TX_RX/README.md +++ b/Examples/LoRa_TX_RX/README.md @@ -27,8 +27,16 @@ const char *appEui = "0000000000000000"; const char *appKey = "00000000000000000000000000000000"; ``` +Also remove line 29, because we do not need this delay anymore, as it was only there to have time to copy the EUI: + +``` +delay(30000); //remove this after you registered your device +``` + + + When you use this firmware on your KISS device, it will poll the network for a downlink message, wait 10 seconds, send the position of the rotary switch and check for downlink messages, wait another 10 seconds, and continue doing the same in a loop. -On the TTN console you should see the push button status arriving on port 2, and the polling messages on port 1. You can send some downlink message using the "Downlink" form on the console. The data you type in the payload field should be HEX characters. When the KISS device receives a downlink message, it will toggle the red LED. +On the TTN console you should see the rotary switch position arriving on port 2, and the polling messages on port 1. You can send some downlink message using the "Downlink" form on the console. The data you type in the payload field should be HEX characters. When the KISS device receives a downlink message, it will toggle the red LED. -This firmware chooses a random Spreading Factor to transmit the LoRa message on, using a specific probability density function designed to optimise the capacity of the LoRaWAN network. \ No newline at end of file +This firmware chooses a random Spreading Factor to transmit the LoRa message on, using a specific probability density function designed to optimise the capacity of the LoRaWAN network. The biggest part of this example is made up of the code to compute this random SF. \ No newline at end of file diff --git a/Examples/PushButton/README.md b/Examples/PushButton/README.md index 4f8d4b2..fbac32c 100644 --- a/Examples/PushButton/README.md +++ b/Examples/PushButton/README.md @@ -1,3 +1,7 @@ # Push Button Switch -The KISS LoRa board has one push button switch. This example polls the switch every second and prints out the state. It also uses an interrupt to detect when the switch was pressed and toggles the red LED. \ No newline at end of file +The KISS LoRa board has one push button switch. This example polls the switch every second and prints out the state. It also uses an interrupt to detect when the switch was pressed and toggles the red LED. + +In the schematic we can see that the switch will connect the pin on the microcontroller to 0V when it is pressed, but connected via a resistor to 3V3 when it is not pressed. This means that we will read a 0 on the digital input pin on the microcontroller when the button is pressed. On the other hand we will read a 1 when the button is not pressed. + +The button is also connected to a pin that supports an interrupt. This means that a specific Interrupt Service Routine (ISR) can be executed when the state of the input pin changes. This is used to toggle the LED when the button is pressed. \ No newline at end of file diff --git a/Examples/README.md b/Examples/README.md index d72810a..44be7cc 100644 --- a/Examples/README.md +++ b/Examples/README.md @@ -1,3 +1,18 @@ # Examples -See the readme in every subdirectory for an explanation of what each example does, and how to use it. +This directory contains some basic examples on how to read the sensors, or control the actuators on the KISS LoRa gadget. + +We recommend programming every example onto the KISS device to see how to use all the sensors. + +Our recommended order is: + +1. [Blink](Blink) +2. [PushButton](PushButton) +3. [RotarySwitch](RotarySwitch) +4. [LightSensor](LightSensor) +5. [ReadTemperatureHumidity](ReadTemperatureHumidity) +6. [Accelerometer](Accelerometer) +7. [LoRa_TX_RX](LoRa_TX_RX) +8. [CayenneLPP](CayenneLPP) + +See the readme in every subdirectory for an explanation of what each example does, and how to use it. \ No newline at end of file diff --git a/Examples/ReadTemperatureHumidity/README.md b/Examples/ReadTemperatureHumidity/README.md index eb3c5a9..00255c6 100644 --- a/Examples/ReadTemperatureHumidity/README.md +++ b/Examples/ReadTemperatureHumidity/README.md @@ -1,3 +1,5 @@ # Temperature and Humidity -The KISS LoRa board has a Silicon Labs Si7021 Temperature and Humidity sensor. See [Si7021-A20.pdf](Si7021-A20.pdf) for technical details on this sensor. \ No newline at end of file +The KISS LoRa board has a Silicon Labs Si7021 Temperature and Humidity sensor. See [Si7021-A20.pdf](Si7021-A20.pdf) for technical details on this sensor. + +Communication with the sensor is done via I2C. This example makes use of a SparkFun library for the Si7021 to setup and read the sensor. \ No newline at end of file diff --git a/Examples/RotarySwitch/README.md b/Examples/RotarySwitch/README.md index ed057a6..452773c 100644 --- a/Examples/RotarySwitch/README.md +++ b/Examples/RotarySwitch/README.md @@ -1,3 +1,5 @@ # Rotary Switch -The KISS LoRa board has a rotary switch with 10 different positions, marked 0 to 9. This example constantly polls the switch and print out the position of the switch. \ No newline at end of file +The KISS LoRa board has a rotary switch with 10 different positions, marked 0 to 9. This example constantly polls the switch and prints out the position of the switch. + +The rotary switch outputs the value that is selected in binary format, using 4 digital lines. If these 4 digital lines are read and interpreted in the correct order, the value can be calculated. \ No newline at end of file diff --git a/README.md b/README.md index b8c35fd..1a98750 100644 --- a/README.md +++ b/README.md @@ -74,6 +74,8 @@ In the Bootloader directory you will find the hex file for the bootloader that r The Schematics directory contains the electronic design of the board. It specifically shows how everything is connected. This is useful to have when writing firmware for the KISS LoRa device, to know on which pins the sensors are connected. +The schematic uses the pin names and numbers from the [datasheet of the ATmega32u4](Schematics/Atmel-7766-8-bit-AVR-ATmega16U4-32U4_Datasheet.pdf). When programming this board from within Arduino IDE, we use the Arduino pin names and numbers. See the [PIN_MAPPING](Schematics/PIN_MAPPING.md) document for the translation between these pin numbers and names. + ## [Examples](Examples) In the Examples directory you will find example firmware files to read the sensors on the board. Have a look at the README in each subdirectory to see an explanation of each example. diff --git a/Schematics/Atmel-7766-8-bit-AVR-ATmega16U4-32U4_Datasheet.pdf b/Schematics/Atmel-7766-8-bit-AVR-ATmega16U4-32U4_Datasheet.pdf new file mode 100644 index 0000000..e9fd3d8 Binary files /dev/null and b/Schematics/Atmel-7766-8-bit-AVR-ATmega16U4-32U4_Datasheet.pdf differ