LoRa Irrigation System
======================

This project is to build an irrigation system from LoRa capable
microcontrollers.  The [Heltec Node151](https://heltec.org/project/lora-node-151/)
was chosen due to it's small size and inexpensive cost.

Design Decisions
----------------

While investigating this, the LoraWAN protocol was investigated, but
after looking at the code complexity and other operational requirements,
if was decided that for this project, it was safer to target a direct
Node to Node style communication system.  This would allow the
implementation to be more simple, and security to be built in (LoRaWAN
does have a crypto layer, BUT, trusting/auditing it and any library that
implements it would be a larger task than I want to undertake).  It
could also be used for other projects that need security.

One of the other requirements is that the code be 100% open sourced,
not GPL licensed, and no proprietary components.  This meant that using
IDE's like ST's STM32CubeIDE which is only available in binary form
was not a choice, as that would preclude building on an operating
system other than Windows/MaxOS/Linux.

Building
--------

The build system uses the BSD flavor of make.  This is the default
make on the BSDs, originally called pmake, but also available as bsdmake
for MacOSX, and likely other operating systems as well.

It also depends upon ARM's [GNU Arm Embedded
Toolchain](https://developer.arm.com/tools-and-software/open-source-software/developer-tools/gnu-toolchain/gnu-rm),
which uses gcc as the compiler.  It would be good to get it
cross-compile with clang as well, but that requires finding a libc like
the nano libc that is provided by the toolchain.

Once ARM's toolchain is in your path, the following should work:
```
export MAKEOBJDIR=build
mkdir $MAKEOBJDIR
bsdmake all
```

And in the directory `build`, a file `lora.irr.elf` should be present.

Flashing
--------

Flashing can be done via the open source tool
[OpenOCD](https://sourceforge.net/projects/openocd/).  For this, I use
a Digilent HS1 JTAG programmer utilizing the [resistor
hack](https://github.com/ntfreak/openocd/blob/master/tcl/interface/ftdi/swd-resistor-hack.cfg)
to allow an FTDI JTAG programmer to control the bi-directional `SWIO`
pin.

One caveat w/ MacOSX, is that it may be necessary to unload the kext
`com.apple.driver.AppleUSBFTDI` via the command:
```
sudo kextunload -b com.apple.driver.AppleUSBFTDI
```
as OpenOCD wants direct access to the FTDI driver.

Once that happens, the device can be programmed using the following
command:
```
sudo openocd -f interface/ftdi/digilent-hs1.cfg -f interface/ftdi/swd-resistor-hack.cfg -f target/stm32l1.cfg -c "init" -c "reset init" -c "program build/lora.irr.elf verify reset exit"
```

Pins
----

The [pinout guide for the Node151](http://resource.heltec.cn/download/LoRa_Node_151/LoRa_Node_151_Pinout_Diagram.pdf).

The pins PB5-7,9 are used as active low controls for the relays.

The pin PB15 is used as an analog input for an RNG source.  This pin
should be grounded.