enable development on macOS (#73)

Author: Brandon Paiz

.gitignore

@@ -1 +1,4 @@
-.vscode
+.vscode
+src/build
+src/scripts/arduino-cli
+src/.arduino15

README.md

@@ -50,26 +50,3 @@ To access the web interface, connect to the `RubberNugget` AP with the password
     - Custom graphics
     - Live command preview
     - Reactive RGB NeoPixel
-
-## Building / flashing from source
-Dependencies: docker, make.
-Docker is used to produce a replicable build environment and ensure library/tool dependensies are met.
-```
-# Clone the repo
-git clone https://github.com/HakCat-Tech/RubberNugget.git
-
-# Navigate to src
-cd RubberNugget/src
-
-# Build
-sudo make build
-
-# Build and flash the ESP32-S2 (may need sudo)
-sudo make flash
-#optionally specify port: sudo make flash PORT=<port>
-#optionally install default scripts: sudo make flash RESET_SCRIPTS_DURING_FLASH=true
-
-# Produce .img for release
-sudo make generate_img
-```
-

src/Dockerfile

@@ -35,4 +35,5 @@ COPY scripts ./scripts
 RUN ./scripts/build_web_ui.sh
 RUN ./arduino-cli compile -b esp32:esp32:esp32s2 RubberNugget \
     --build-property build.partitions=noota_3gffat \
-    --build-property build.cdc_on_boot=1
+    --build-property build.cdc_on_boot=1 \
+    --output-dir=./build

src/README.md

@@ -0,0 +1,75 @@
+## Building / flashing from source
+
+If want to flash the latest version of the USB-Nugget project, [the method
+documented
+here](https://github.com/HakCat-Tech/USB-Nugget#how-to-update-your-nugget) is
+easiest.
+
+Docker is used to produce a replicable build environment to ensure
+library and tool dependencies are met. Linux is recommended when developing,
+building, and flashing from source.
+
+### Linux
+
+Dependencies: docker, make.
+```
+# Clone the repo
+git clone https://github.com/HakCat-Tech/USB-Nugget.git
+
+# Navigate to src
+cd USB-Nugget/src
+
+# Build
+sudo make build
+
+# Build and flash the ESP32-S2 (may need sudo)
+sudo make flash
+#optionally specify port: sudo make flash PORT=<port>
+#optionally install default scripts: sudo make flash RESET_SCRIPTS_DURING_FLASH=true
+
+# Produce .img for release
+sudo make generate_img
+```
+
+### macOS
+
+Docker on mac has issues connecting to usb devices and complicates the flashing
+process. A workaround is in place -- USB-Nugget will be built within docker but
+then flashed outside of the container.  Some additional steps are also
+necessary to prepare your development environment:
+
+1. Install docker and ensure the daemon is running. The daemon is running if the
+   command `docker info` is successful.
+2. Install python3 and pip3, then `pip3 install esptool`
+
+```bash
+# Clone the repo
+git clone https://github.com/HakCat-Tech/USB-Nugget.git
+
+# Navigate to src
+cd USB-Nugget/src
+
+# Verify everything is installed and configured correctly
+make check-mac-deps
+
+# To build only, run
+make build
+
+# Plug in your USB-Nugget dev kit in flashing mode by holding down the '0'
+# button while plugging it in.
+
+# Find the port of your arduino. It's likely something like
+# "/dev/cu.usbmodem01".
+ls /dev/cu*
+
+# To build and flash, run
+make flash-on-mac PORT=<port>
+
+# If you want to overwrite the FAT partition to include default payloads, set
+# RESET_SCRIPTS_DURING_FLASH=true:
+make flash PORT=<port> RESET_SCRIPTS_DURING_FLASH=true
+```
+
+### Windows
+
+Not currently supported

src/arduino-cli-mac.yaml

@@ -0,0 +1,24 @@
+board_manager:
+  additional_urls: ["https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_dev_index.json"]
+daemon:
+  port: "50051"
+directories:
+  data: .arduino15
+  downloads: .arduino15/staging
+  user: /root/Arduino
+library:
+  enable_unsafe_install: true
+logging:
+  file: ""
+  format: text
+  level: info
+metrics:
+  addr: :9090
+  enabled: true
+output:
+  no_color: false
+sketch:
+  always_export_binaries: false
+updater:
+  enable_notification: true
+

src/makefile

@@ -2,15 +2,16 @@ PORT ?= /dev/ttyACM0
 RESET_SCRIPTS_DURING_FLASH ?= false
 IMAGE_NAME = rubber-nugget
 CONTAINER_NAME := $(IMAGE_NAME)-$(shell date +%s)
+ARDUINO_CLI_VERSION = 0.22.0
 
 submodules:
 	git submodule init
 	git submodule update
 
 build: submodules
-	docker build . --file Dockerfile --tag rubber-nugget
+	docker build . --file Dockerfile --build-arg ARDUINO_CLI_VERSION=$(ARDUINO_CLI_VERSION) --tag rubber-nugget
 
-flash: check_port build
+flash: check-port build
 	docker create --name $(CONTAINER_NAME) --device=$(PORT) -t rubber-nugget:latest
 	docker start $(CONTAINER_NAME)
 	docker exec $(CONTAINER_NAME) bash -c \
@@ -21,16 +22,54 @@ ifeq ($(RESET_SCRIPTS_DURING_FLASH), true)
 endif
 	docker rm --force $(CONTAINER_NAME)
 
-generate_img: check_port build
+generate_img: check-port build
 	docker create --name $(CONTAINER_NAME) --device=$(PORT) -t rubber-nugget:latest
 	docker start $(CONTAINER_NAME)
 	docker exec $(CONTAINER_NAME) bash -c \
 		'python3 -m esptool --after no_reset erase_flash && sleep 2 && \
 		./arduino-cli upload -b esp32:esp32:esp32s2 --port $(PORT) RubberNugget/ && sleep 2 && \
 		python3 -m esptool --after no_reset write_flash 0x110000 default.img && sleep 2 && \
 		python3 -m esptool --after no_reset read_flash 0x0 0x400000 /rubber_nugget.bin'
-	docker cp $(CONTAINER_NAME):/rubber_nugget.bin /tmp/meow.bin
+	docker cp $(CONTAINER_NAME):/rubber_nugget.bin .
 	docker rm --force $(CONTAINER_NAME)
 
-check_port:
-	@ls $(PORT) || { echo "Device not found at $(PORT). Run with 'make flash PORT=<port>'" && exit 1; }
+check-port:
+	@ls $(PORT) || { echo "Device not found at $(PORT)" && exit 1; }
+
+#-------------------------------------------------------------------------------
+# macOS development
+
+MAC_PORT = /dev/cu.usbmodem01
+MAC_ARDUINO_CLI_TAR = arduino-cli_$(ARDUINO_CLI_VERSION)_macOS_64bit.tar.gz
+
+arduino-cli: scripts/arduino-cli arduino-cli-esp32-install
+
+arduino-cli-esp32-install:
+	sudo ./scripts/arduino-cli core install esp32:esp32 --config-file arduino-cli-mac.yaml
+
+scripts/arduino-cli:
+	curl -L --output scripts/$(MAC_ARDUINO_CLI_TAR) https://github.com/arduino/arduino-cli/releases/download/$(ARDUINO_CLI_VERSION)/$(MAC_ARDUINO_CLI_TAR)
+	tar -xf scripts/$(MAC_ARDUINO_CLI_TAR) --directory=scripts
+	rm scripts/$(MAC_ARDUINO_CLI_TAR)
+	rm scripts/LICENSE.txt
+
+check-mac-deps:
+	docker info
+	which python3
+	python3 -E -m esptool version
+
+check-mac-port:
+	@ls $(MAC_PORT) || { echo "Device not found at $(MAC_PORT)" && exit 1; }
+
+mac-build: submodules
+	sudo docker build . --file Dockerfile --build-arg ARDUINO_CLI_VERSION=$(ARDUINO_CLI_VERSION) --tag rubber-nugget
+
+flash-on-mac: check-mac-port check-mac-deps arduino-cli mac-build
+	sudo docker create --name $(CONTAINER_NAME) -t rubber-nugget:latest
+	sudo docker cp $(CONTAINER_NAME):/app/build .
+	sudo docker rm --force $(CONTAINER_NAME)
+ifeq ($(RESET_SCRIPTS_DURING_FLASH), true)
+	python3 -m esptool --after no_reset write_flash 0x110000 fatfs/default.img
+endif
+	{ sudo ./scripts/arduino-cli upload -b esp32:esp32:esp32s2 --port $(MAC_PORT) --config-file arduino-cli-mac.yaml --input-dir build; } || echo \
+		'If you get the error: "esptool.py can not exit the download mode over USB..." this is a bug in arduino-cli and can be ignored'