From a2e98b5f01814900493b99cba79312e8dcb4825b Mon Sep 17 00:00:00 2001
From: spirkelmann <simon.pirkelmann@gmail.com>
Date: Sat, 30 Nov 2019 21:18:49 +0100
Subject: [PATCH] added readme

---
 README.md | 111 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 111 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..2f5f96d
--- /dev/null
+++ b/README.md
@@ -0,0 +1,111 @@
+# imaginaerraum LoRa Workshop
+
+This workshop assumes you are familiar with the basics of MicroPython (see [apos'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 send 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(list(map(lambda x: "{0:02x}".format(x), devAddr))).upper()
+nwkSKey_hex = " ".join(list(map(lambda x: "{0:02x}".format(x), nwkSKey))).upper()
+appSKey_hex = " ".join(list(map(lambda x: "{0:02x}".format(x), appSKey))).upper()
+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.