diff --git a/README.md b/README.md
new file mode 100644
index 0000000..5b6495e
--- /dev/null
+++ b/README.md
@@ -0,0 +1,67 @@
+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.  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 propietary components.  This ment 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 to
+cross-compile with clang as well, but that requires finding a libc like
+the nano libc that `nano.specs` in the above toolchain provides.
+
+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 pressent.
+
+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"
+```