Mostly readme fixes

CayenneLPP improvements

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=");

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.
+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.

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()

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 <CayenneLPP.h>`
+
+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.
+

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);

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.
+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.

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);

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.
+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.

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.
+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.

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.

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.
+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.

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.
+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.

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.