LoRa-Workshop/README.md

# imaginaerraum LoRa Workshop

This workshop assumes you are familiar with the basics of MicroPython (see [apo's MicroPython Workshop][micropython-workshop] for an introduction).

[micropython-workshop]: https://imaginaerraum.de/git/apo/micropython-workshop

## Hardware
We use the [Wemos® TTGO LORA32 868/915Mhz board][wemos].

[wemos]: https://www.banggood.com/2Pcs-LILYGO-TTGO-LORA32-915Mhz-ESP32-LoRa-OLED-0_96-Inch-Blue-Display-p-1239769.html

## Software
We make use of the two MicroPython libraries [uPyLora by lemariva][lemariva] and [uLoRaWAN by mallagant][mallagant]. uPyLora is a driver for the SX1276 LoRa module which is connected to the ESP32. 
uLoRaWAN is a library which creates LoRaWAN packages, which you can then transfer via LoRa to send data to [TheThingsNetwork][ttn].

I added a wrapper class [LoRaTransceiver](micropython/lora_transceiver.py) which makes them a bit easier to use.

[lemariva]: https://github.com/lemariva/uPyLora
[mallagant]: https://github.com/mallagant/uLoRaWAN
[ttn]: https://www.thethingsnetwork.org/

## Setup
The files you will need are all located in the `micropython/` subfolder. To get started, you can either upload the file 
 * `lora_transceiver.py`

and the folders 
* `uPyLora/`
* `uLoRaWAN/`
* `uPySensors/`

to the ESP, or just flash [this image](micropython/esp32-image/image.bin).

Here are some examples how to use the LoRa module:

__1. LoRa sending:__
```
from lora_transceiver import LoRaTransceiver

from uPySensors.ssd1306_i2c import Display

d = Display()

# create transceiver
lora = LoRaTransceiver(display=d)

# send data
lora.send_string('imaginaerraum')

```

__2. LoRa receiving:__
```
from lora_transceiver import LoRaTransceiver

from uPySensors.ssd1306_i2c import Display

d = Display()

# create transceiver 
lora = LoRaTransceiver(display=d)

# start receiving data
#lora.recv()
```

__3. LoRaWAN sending:__
```
from lora_transceiver import LoRaTransceiver

from uPySensors.ssd1306_i2c import Display

import uLoRaWAN
from uLoRaWAN.MHDR import MHDR

d = Display()

# create transceiver for LoRaWAN frequency (channel 0 = 868.1 Mhz)
lora = LoRaTransceiver(frequency=868.1E6, syncword=0x34, display=d)

# change the spreading factor
lora.setSpreadingFactor(9)

# TODO: set address and keys for LoRaWAN
devAddr = [0x00, 0x00, 0x00, 0x00] 
nwkSKey = [0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00]
appSKey = [0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00]

devAddr_hex = " ".join(["%02X" % (x,) for x in devAddr])
nwkSKey_hex = " ".join(["%02X" % (x,) for x in nwkSKey])
appSKey_hex = " ".join(["%02X" % (x,) for x in appSKey])
print("devAddr: ", devAddr_hex)
print("nwkSKey: ", nwkSKey_hex)
print("appSKey: ", appSKey_hex)

# lorawan object for conversion of data in LoRaWAN message format
lorawan = uLoRaWAN.new(nwkSKey, appSKey)

def send_lorawan(message, frame_cnt=0):
    lorawan.create(MHDR.UNCONF_DATA_UP, {'devaddr': devAddr, 'fcnt': frame_cnt, 'data': list(map(ord, message)) })
    payload = lorawan.to_raw()

    lora.send(payload)

    print("lorawan message sent")

send_lorawan("Hello world!")

```
(you can also find these in the `examples/` subdirectory)

For more information, have a look at the documentation of the [LoRaTransceiver](micropython/lora_transceiver.py) class.