add some usage to README, also doc and improve shared key use/gen...

Makefile

@@ -58,6 +58,7 @@ SRCS+= rng_save.c
 CFLAGS+= -I$(.CURDIR)
 CFLAGS+= -g
 #CFLAGS+= -DNDEBUG
+CFLAGS+= -I$(.OBJDIR)	# for shared_key.h
 
 # Strobe
 .PATH: $(.CURDIR)/strobe
@@ -185,6 +186,26 @@ runbuild: $(SRCS)
 runtests: Makefile lora_comms.py lora.py loraserv.py multicast.py $(LIBLORA_TEST) $(LIBLORA_TEST_SRCS)
 	ls $(.ALLSRC) | entr sh -c '(cd $(.CURDIR) && $(MAKE) $(.MAKEFLAGS) $(LIBLORA_TEST)) && ((PYTHONPATH="$(.CURDIR)" python -m coverage run -m unittest lora multicast loraserv && coverage report --omit=$(.CURDIR)/p/\* -m -i) 2>&1 | head -n 30)'
 
+.if empty(IRR_KEY) && exists($(.CURDIR)/.irr_key)
+IRR_KEY!= cat $(.CURDIR)/.irr_key
+.endif
+
+.PHONY: irrigation_key
+irrigation_key:
+	@LANG=C tr -c -d a-zA-Z0-9 < /dev/urandom | dd bs=1 of=$(.CURDIR)/.irr_key count=32 2>/dev/null
+	@echo 'Irrgation key created and put into .irr_key.'
+
+# make this a phony target so it's always run
+# dependancies will only be made when it's updated
+.PHONY: $(.OBJDIR)/shared_key.h
+$(.OBJDIR)/shared_key.h:
+	@if [ "$(IRR_KEY)" = "" ]; then echo 'Must provide IRR_KEY make variable or have a non-empty file ".irr_key".'; false; fi
+
+	@echo 'static uint8_t shared_key[] = {' $$(python -c 'import sys; print(", ".join(str(x) for x in sys.argv[1].encode("utf-8")))' $(IRR_KEY) ) "};" > shared_key.h.tmp
+	@echo 'static struct pktbuf shared_key_buf = (struct pktbuf){ .pkt = shared_key, .pktlen = sizeof shared_key, };' >> shared_key.h.tmp
+
+	(cmp shared_key.h.tmp shared_key.h >/dev/null 2>&1 && rm shared_key.h.tmp) || mv shared_key.h.tmp shared_key.h
+
 # native objects
 .SUFFIXES: .no
 .c.no:
@@ -225,4 +246,7 @@ update-$($(module)_NAME):
 
 DIAG?=diag
 test-diag:
-	ls $(.CURDIR)/box.sh $(.CURDIR)/$(DIAG).getxt $(.CURDIR)/Makefile | entr sh -c 'cd $(.CURDIR) && $(MAKE) $(.MAKEFLAGS) $(DIAG).diag && cat $(MAKEOBJDIR)/$(DIAG).diag'
+	ls $(.CURDIR)/box.sh $(.CURDIR)/$(DIAG).getxt $(.CURDIR)/Makefile | entr sh -c 'cd $(.CURDIR) && $(MAKE) $(.MAKEFLAGS) $(DIAG).diag && cat $(.OBJDIR)/$(DIAG).diag'
+
+# hard coded dependancy for when "make depend" has not been run.
+irr_main.o: $(.OBJDIR)/shared_key.h

README.md

@@ -74,14 +74,28 @@ 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.
 
+One of the required parameters of the build is the shared key used for
+authentication.  A random key can be made using the command:
+`make irrigation_key`, or it can be provided via the make command by
+setting the variable IRR_KEY.
+
+Note: Both IRR_KEY and the argument to `lora.py` will encode the
+provided key to UTF-8.
+
 Once ARM's toolchain is in your path, the following should work:
 ```
 export MAKEOBJDIR=build
 mkdir $MAKEOBJDIR
-bsdmake all
+bsdmake all IRR_KEY=<sharedkey>
 ```
 
-And in the directory `build`, a file `lora.irr.elf` should be present.
+And in the directory `build`, two files, `lora.irr.elf` and
+`lora.gw.elf` should be present.  The file `lora.irr.elf` should be
+flashed on the Node151 device that is used for interfacing to the
+irrigation system as described in [Deploying](#deploying).  The file
+`lora.gw.elf` should be used on another Node151 that will be attached
+to a computer used as the gateway which runs the `loraserv.py` software
+as described in [Using](#using).
 
 Flashing
 --------
@@ -165,4 +179,40 @@ GND and JD-VCC should be connected to the 5V power supply, while VCC
 is connected to VDD on the Node151, and INx pins to the respective
 GPIO pins.
 
+Using
+-----
+
+The `lora.py` requires at least Python 3.8.  It also using the
+strobe library that in distributed with this program.  In general a
+[virtualenv](https://virtualenv.pypa.io/en/latest/) is recommended for
+all installed Python software to prevent version conflicts, but is not
+always necessary.  The `requirements.txt` file contains the necessary
+modules to be installed, but simply addeding the directory
+`strobe/python` to PYTHONPATH is also sufficient.
+
+The program `loraserv.py` takes a single argument, which is the device
+file for the VCP that runs on the gateway.  In my case, the device
+name is `/dev/cu.usbmodem1451` as I am on my MacBook Pro, so the comand
+to launch the gateway is simply:
+```
+python loraserv.py /dev/cu.usbmodem1451
+```
+
+Once that is running, then the `lora.py` program's multicast packets
+will be forwarded out via the LoRa radio.
+
+To test it, a simple `ping` command can be used, or turning on or off
+the on board LED via channel 4 using the `setunset` command.  The ping
+command:
+```
+python lora.py -s <sharedkey> ping
+```
+
+To turn off the LED (which defaults to on):
+```
+python lora.py -s <sharedkey> setunset 4 0
+```
+
+Either of these commands should exit w/o message or error.
+
 <!-- Markdeep: --><style class="fallback">body{visibility:hidden;white-space:pre;font-family:monospace}</style><script src="markdeep.min.js" charset="utf-8"></script><script src="https://casual-effects.com/markdeep/latest/markdeep.min.js" charset="utf-8"></script><script>window.alreadyProcessedMarkdeep||(document.body.style.visibility="visible")</script>

irr_main.c

@@ -58,11 +58,7 @@ static uint8_t rxpkt[128];
 static struct pktbuf rxpktbuf;
 static volatile bool rxpktavail;
 
-static uint8_t shared_key[] = "foobar";
-static struct pktbuf shared_key_buf = (struct pktbuf){
-	.pkt = shared_key,
-	.pktlen = sizeof shared_key - 1,
-};
+#include <shared_key.h>
 
 static struct comms_state cs;