improved DFP setup and support:

- `./make dfp` downloads and installs Atmel DFPs for each supported MCU
- build.sh detects and uses attiny or avrdd, and others are simple to add
- updated setup info in /README.md

... also some other small documentation updates.

6 files changed, 118 insertions, 30 deletions

diff --git a/.gitignore b/.gitignore
index 9c7486d..3063e65 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,4 @@
+arch/dfp/
 env/
 hex/
 ignore/
@@ -11,5 +12,6 @@ old/
 *.html
 *.o
 *.old
+*.otl
 .*.swo
 .*.swp
diff --git a/README.md b/README.md
index 315395f..d7ba329 100644
--- a/README.md
+++ b/README.md
@@ -21,6 +21,10 @@ for full details.
 
 If you want to know what changed recently, check the [ChangeLog](ChangeLog.md).
 
+For info about hardware-specific features, like what the channel modes are on
+multi-channel lights, browse into the [hw/](hw/) directories to find the
+hardware model and any hardware-specific documentation.
+
 ## Flashing Firmware
 
 Get the latest updates by flashing new firmware!
@@ -50,6 +54,9 @@ A few things are needed to flash firmware:
 
 One particularly useful guide is at https://anduril.click/ .
 
+More info about installing flashing programs is below, in
+[Flashing Programs](#flashing-programs).
+
 ## Compiling
 
 The firmware can be deeply customized by modifying it and compiling your own
@@ -63,30 +70,54 @@ convenient.
 
 ### Prerequisites:
 
-  - AVR toolchain packages:  
-    `sudo apt install gcc-avr avr-libc binutils-avr avrdude`
-
-  - One or more Atmel DFPs (Device Family Pack) may be needed, to add support
-    for recent AVR MCUs.
-
-    - Download the Atmel ATtiny Series Device Support pack:
-      http://packs.download.atmel.com/
+- AVR toolchain packages:  
+  `sudo apt install gcc-avr avr-libc binutils-avr`
 
-    - Unzip the pack somewhere on your build computer
+- Other misc packages:  
+  `sudo apt install git wget unzip bash`
 
-    - Set ATTINY_DFP=/path/to/where/you/unzipped/the/pack
-      (either in your shell, or in this repo's bin/build.sh script)
-
-      `export ATTINY_DFP=$HOME/src/torches/atmel/attiny-dfp`
+- Atmel DFPs (Device Family Packs).  A small script is included to
+  download and install these for you:  
+  `./make dfp`
 
 ### Building
 
 Use the `make` script included in this repo.  Run `./make --help` for details
 about how to use it.  In most cases though, you should be able to just run
 `./make` by itself to compile all available build targets.  Or give it a search
-term to limit builds to only a few, like `./make d4v2` to build all Emisar D4v2
-firmwares.
+term to limit builds to only a few, like `./make hank boost` to build all
+firmwares for Hanklights with optional boost drivers.
 
 The compiled firmware goes into the `hex/` directory, ready to be used by any
 firmware flashing program.
 
+## Customizing Settings Per User
+
+The build can be [customized per user](docs/per-user-config.md) by placing
+overrides into the `users/myname/` directory and letting the build script know
+your username.  That way, your favorite settings can be applied automatically
+without having to modify the original source files.
+
+## Flashing Programs
+
+### AVRdude
+
+Usually avrdude installs in a single command:
+
+`sudo apt install avrdude`
+
+### PyMCUprog
+
+If you use `pymcuprog` to flash firmware, a few extras are needed:
+
+```sh
+sudo apt install python3 python3-pip python3-venv
+python3 -m venv env
+source env/bin/activate
+pip install pymcuprog
+```
+
+You'll need to `source env/bin/activate` every time you start a fresh shell,
+if you want to use pymcuprog.  The activation lasts until the shell is
+closed or until you run `deactivate`.
+
diff --git a/bin/build.sh b/bin/build.sh
index 8743260..50f93b7 100755
--- a/bin/build.sh
+++ b/bin/build.sh
@@ -13,6 +13,9 @@ if [ -z "$1" ]; then
   exit
 fi
 
+# repo root dir
+BASEDIR=$(dirname $(dirname "$0"))
+
 TARGET=$1 ; shift
 UI=$(basename $TARGET .h)
 MODEL=$(dirname $TARGET)
@@ -24,24 +27,26 @@ MODEL_NUMBER=$(head -1 $MODEL/model)
 # figure out the MCU type and set some vars
 eval $( bin/detect-mcu.sh "$TARGET" )
 
-# TODO: add support for AVR DD
-# give a more useful error message when AVR DFP is needed but not installed
-# (Atmel ATtiny device family pack, for attiny1616 support)
-# http://packs.download.atmel.com/
-#if [ -z "$ATTINY_DFP" ]; then export ATTINY_DFP=~/avr/attiny_dfp ; fi
-SERIES1=' 416 417 816 817 1616 1617 3216 3217 '
-if [[ $SERIES1 =~ " $ATTINY " ]]; then
-  if [ -z "$ATTINY_DFP" ]; then
-    echo "ATtiny$ATTINY support requires Atmel attiny device family pack."
-    echo "More info is in /README under tiny1616 support."
-    exit 1
-  fi
+# detect and enable a relevant Atmel DFP
+if [[ $MCUNAME =~ "attiny" ]]; then
+  DFPPATH=$BASEDIR/arch/dfp/attiny
+elif [[ $MCUNAME =~ "avr" && $MCUNAME =~ "dd" ]]; then
+  DFPPATH=$BASEDIR/arch/dfp/avrdd
+else
+  echo "Unrecognized MCU type: '$MCUNAME'"
+  exit 1
+fi
+# ensure the DFP files exist
+if [ ! -d "$DFPPATH" ]; then
+  echo "Atmel DFP files not found: '$DFPPATH'"
+  echo "Install DFP files with './make dfp'"
+  exit 1
 fi
 
 export CC=avr-gcc
 export CPP=avr-cpp
 export OBJCOPY=avr-objcopy
-export DFPFLAGS="-B $ATTINY_DFP/gcc/dev/$MCUNAME/ -I $ATTINY_DFP/include/"
+export DFPFLAGS="-B $DFPPATH/gcc/dev/$MCUNAME/ -I $DFPPATH/include/"
 # TODO: include $user/ first so it can override other stuff
 INCLUDES="-I ui -I hw -I. -I.. -I../.. -I../../.."
 export CFLAGS="  -Wall -g -Os -mmcu=$MCUNAME -c -std=gnu99 -fgnu89-inline -fwhole-program $MCUFLAGS $INCLUDES -fshort-enums $DFPFLAGS"
diff --git a/bin/dfp-install.sh b/bin/dfp-install.sh
new file mode 100755
index 0000000..a73c4d5
--- /dev/null
+++ b/bin/dfp-install.sh
@@ -0,0 +1,36 @@
+#!/bin/sh
+# Atmel DFP download/install/setup script
+# Copyright (C) 2023 Selene ToyKeeper
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+set -e
+
+V_ATTINY='2.0.368'
+V_AVRDD='2.2.253'
+F_ATTINY="Atmel.ATtiny_DFP.${V_ATTINY}.atpack"
+F_AVRDD="Atmel.AVR-Dx_DFP.${V_AVRDD}.atpack"
+
+cd arch
+
+# make the base DFP dir
+mkdir -p dfp
+cd dfp
+
+# download the zipped pack files if they don't exist yet
+mkdir -p zip
+cd zip
+[ ! -f "${F_ATTINY}" ] && wget "http://packs.download.atmel.com/${F_ATTINY}"
+[ ! -f "${F_AVRDD}"  ] && wget "http://packs.download.atmel.com/${F_AVRDD}"
+
+# extract the packs
+# attiny
+cd ..
+mkdir -p attiny
+cd attiny
+unzip "../zip/${F_ATTINY}"
+# avrdd
+cd ..
+mkdir -p avrdd
+cd avrdd
+unzip "../zip/${F_AVRDD}"
+
diff --git a/docs/per-user-config.md b/docs/per-user-config.md
new file mode 100644
index 0000000..cbb7c29
--- /dev/null
+++ b/docs/per-user-config.md
@@ -0,0 +1,4 @@
+# Per-User Configuration
+
+(write me)
+
diff --git a/make b/make
index 40fc398..d0d1a5d 100755
--- a/make
+++ b/make
@@ -23,10 +23,11 @@ Usage: ./make TASK
   (nothing)       Compile all build targets
   flash FILE      Flash firmare FILE to a hardware device
   clean           Delete generated files
-  todo            Show tasks noted in source code files
+  dfp             Download and install Atmel DFPs
+  docs            Convert all .md files to .html
   models          Generate the MODELS file
   release         Zip up all .hex files to prep for publishing a release
-  docs            Convert all .md files to .html
+  todo            Show tasks noted in source code files
 
 ... or TASK can be the partial name of a build target.
 
@@ -56,6 +57,10 @@ function main() {
       echo 'rm -vf **/*.hex **/*~ **/*.elf **/*.o **/*.cpp'
       rm -vf **/*.hex **/*~ **/*.elf **/*.o **/*.cpp
       ;;
+    dfp)
+      shift
+      ./bin/dfp-install.sh "$@"
+      ;;
     docs)
       make-docs
       ;;
@@ -87,5 +92,10 @@ function make-docs () {
   done
 }
 
+# go to the repo root
+BASEDIR=$(dirname $0)
+cd "$BASEDIR"
+
+# do whatever the user requested
 main "$@"