Supervisor REPL support for ports/nrf/boards/feather52

Author: Kevin Townsend

.gitmodules

@@ -40,3 +40,6 @@
 [submodule "tools/usb_descriptor"]
 	path = tools/usb_descriptor
 	url = https://github.com/adafruit/usb_descriptor.git
+[submodule "lib/nrfutil"]
+	path = lib/nrfutil
+	url = [email protected]:adafruit/nRF52_nrfutil.git

lib/nrfutil

@@ -1,6 +1,6 @@
 # Select the board to build for: if not given on the command line,
-# then default to pca10040.
-BOARD ?= pca10040
+# then default to feather52.
+BOARD ?= feather52
 ifeq ($(wildcard boards/$(BOARD)/.),)
 $(error Invalid BOARD specified)
 endif
@@ -11,17 +11,18 @@ SD_LOWER = $(shell echo $(SD) | tr '[:upper:]' '[:lower:]')
 
 # TODO: Verify that it is a valid target.
 
-
 ifeq ($(SD), )
 	# If the build directory is not given, make it reflect the board name.
 	BUILD ?= build-$(BOARD)
 	include ../../py/mkenv.mk
 	include boards/$(BOARD)/mpconfigboard.mk
+	-include mpconfigport.mk
 else
 	# If the build directory is not given, make it reflect the board name.
 	BUILD ?= build-$(BOARD)-$(SD_LOWER)
 	include ../../py/mkenv.mk
 	include boards/$(BOARD)/mpconfigboard_$(SD_LOWER).mk
+	-include mpconfigport.mk
 
 	include drivers/bluetooth/bluetooth_common.mk
 endif
@@ -34,10 +35,9 @@ FROZEN_MPY_DIR = freeze
 # include py core make definitions
 include ../../py/py.mk
 
+include $(TOP)/supervisor/supervisor.mk
 
 FATFS_DIR = lib/oofatfs
-MPY_CROSS = ../../mpy-cross/mpy-cross
-MPY_TOOL = ../../tools/mpy-tool.py
 
 CROSS_COMPILE = arm-none-eabi-
 
@@ -120,7 +120,6 @@ SRC_HAL = $(addprefix hal/,\
 	hal_spi.c \
 	hal_spie.c \
 	hal_time.c \
-	hal_rtc.c \
 	hal_timer.c \
 	hal_twi.c \
 	hal_adc.c \
@@ -136,17 +135,19 @@ SRC_HAL += $(addprefix hal/,\
 	)
 endif
 
+
 SRC_C += \
-	main.c \
 	mphalport.c \
 	help.c \
-	gccollect.c \
 	pin_named_pins.c \
 	fatfs_port.c \
 	drivers/softpwm.c \
 	drivers/ticker.c \
 	drivers/bluetooth/ble_drv.c \
 	drivers/bluetooth/ble_uart.c \
+  boards/$(BOARD)/board.c \
+  lib/utils/context_manager_helpers.c \
+  fifo.c \
 
 DRIVERS_SRC_C += $(addprefix modules/,\
 	machine/modmachine.c \
@@ -156,7 +157,6 @@ DRIVERS_SRC_C += $(addprefix modules/,\
 	machine/adc.c \
 	machine/pin.c \
 	machine/timer.c \
-	machine/rtc.c \
 	machine/pwm.c \
 	machine/led.c \
 	machine/temp.c \
@@ -183,13 +183,38 @@ SRC_C += \
 	device/$(MCU_VARIANT)/system_$(MCU_SUB_VARIANT).c \
 	device/$(MCU_VARIANT)/startup_$(MCU_SUB_VARIANT).c \
 
+
+SRC_COMMON_HAL += \
+  board/__init__.c \
+	digitalio/__init__.c \
+	digitalio/DigitalInOut.c \
+	microcontroller/__init__.c \
+	microcontroller/Pin.c \
+	microcontroller/Processor.c \
+  time/__init__.c \
+
+# These don't have corresponding files in each port but are still located in
+# shared-bindings to make it clear what the contents of the modules are.
+SRC_BINDINGS_ENUMS = \
+	digitalio/Direction.c \
+	digitalio/DriveMode.c \
+	digitalio/Pull.c \
+	help.c \
+	math/__init__.c \
+	util.c
+
+SRC_COMMON_HAL_EXPANDED = $(addprefix shared-bindings/, $(SRC_COMMON_HAL)) \
+                          $(addprefix shared-bindings/, $(SRC_BINDINGS_ENUMS)) \
+                          $(addprefix common-hal/, $(SRC_COMMON_HAL))
+
 FROZEN_MPY_PY_FILES := $(shell find -L $(FROZEN_MPY_DIR) -type f -name '*.py')
 FROZEN_MPY_MPY_FILES := $(addprefix $(BUILD)/,$(FROZEN_MPY_PY_FILES:.py=.mpy))
 
-OBJ += $(PY_O) $(addprefix $(BUILD)/, $(SRC_C:.c=.o))
+OBJ += $(PY_O) $(SUPERVISOR_O) $(addprefix $(BUILD)/, $(SRC_C:.c=.o))
 OBJ += $(addprefix $(BUILD)/, $(SRC_LIB:.c=.o))
 OBJ += $(addprefix $(BUILD)/, $(SRC_HAL:.c=.o))
 OBJ += $(addprefix $(BUILD)/, $(DRIVERS_SRC_C:.c=.o))
+OBJ += $(addprefix $(BUILD)/, $(SRC_COMMON_HAL_EXPANDED:.c=.o))
 OBJ += $(BUILD)/pins_gen.o
 
 $(BUILD)/$(FATFS_DIR)/ff.o: COPT += -Os
@@ -245,7 +270,7 @@ $(BUILD)/$(OUTPUT_FILENAME).elf: $(OBJ)
 	$(Q)$(SIZE) $@
 
 # List of sources for qstr extraction
-SRC_QSTR += $(SRC_C) $(SRC_MOD) $(SRC_LIB) $(DRIVERS_SRC_C)
+SRC_QSTR += $(SRC_C) $(SRC_SUPERVISOR) $(SRC_MOD) $(SRC_LIB) $(DRIVERS_SRC_C) $(SRC_COMMON_HAL_EXPANDED)
 
 # Append any auto-generated sources that are needed by sources listed in
 # SRC_QSTR

ports/nrf/Makefile

@@ -0,0 +1,47 @@
+/*
+ * This file is part of the MicroPython project, http://micropython.org/
+ *
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2017 Scott Shawcroft for Adafruit Industries
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+
+// This file defines board specific functions.
+
+#ifndef MICROPY_INCLUDED_NRF_BOARDS_BOARD_H
+#define MICROPY_INCLUDED_NRF_BOARDS_BOARD_H
+
+#include <stdbool.h>
+
+extern volatile uint32_t ticks_ms;
+
+// Initializes board related state once on start up.
+void board_init(void);
+
+// Returns true if the user initiates safe mode in a board specific way.
+// Also add BOARD_USER_SAFE_MODE in mpconfigboard.h to explain the board specific
+// way.
+bool board_requests_safe_mode(void);
+
+// Reset the state of off MCU components such as neopixels.
+void reset_board(void);
+
+#endif  // MICROPY_INCLUDED_NRF_BOARDS_BOARD_H

ports/nrf/boards/board.h

@@ -1,14 +1,18 @@
 # Setup
 
-Before you can build, you will need to run the following commands once:
+## Installing CircuitPython submodules
+
+Before you can build, you will need to run the following commands once, which
+will install the submodules that are part of the CircuitPython ecosystem, and
+build the `mpy-cross` tool:
 
 ```
 $ cd circuitpython
 $ git submodule update --init
 $ make -C mpy-cross
 ```
 
-You then need to download the SD and Nordic SDK files:
+You then need to download the SD and Nordic SDK files via:
 
 > This script relies on `wget`, which must be available from the command line.
 
@@ -17,47 +21,50 @@ $ cd ports/nrf
 $ ./drivers/bluetooth/download_ble_stack.sh
 ```
 
+## Installing `nrfutil`
+
+The Adafruit Bluefruit nRF52 Feather ships with a serial and OTA BLE bootloader
+that can be used to flash firmware images over a simple serial connection,
+using the on-board USB serial converter.
+
+If you haven't installed this command-line tool yet, go to the `/libs/nrfutil`
+folder (where nrfutil 0.5.2 is installed as a sub-module) and run the following
+commands:
+
+> If you get a 'sudo: pip: command not found' error running 'sudo pip install',
+you can install pip via 'sudo easy_install pip'
+
+```
+$ cd libs/nrfutil
+$ sudo pip install -r requirements.txt
+$ sudo python setup.py install
+```
+
 # Building and flashing firmware images
 
-## Building CircuitPython
+## Building CircuitPython binaries
 
 #### REPL over UART (default settings)
 
 To build a CircuitPython binary with default settings for the
 `feather52` target enter:
 
+> **NOTE:** `BOARD=feather52` is the default option and isn't stricly required.
+
 ```
 $ make BOARD=feather52 V=1
 ```
 
-#### REPL over BLE UART (AKA `NUS`)
+#### REPL over BLE support
 
-To build a CircuitPython binary with REPL over BLE UART, edit
-`bluetooth_conf.h` with the following values (under
-`#elif (BLUETOOTH_SD == 132)`):
-
-```
-#define MICROPY_PY_BLE                  (1)
-#define MICROPY_PY_BLE_NUS              (1)
-#define BLUETOOTH_WEBBLUETOOTH_REPL     (1)
-```
-
-Then build the CircuitPython binary, including `SD=s132`
-to enable BLE support in the build process:
+To build a CircuitPython binary with BLE support (S132) include `SD=s132`
+as part of the build process:
 
 ```
 $ make BOARD=feather52 V=1 SD=s132
 ```
 
-## Flashing with `nrfutil`
-
-The Adafruit Bluefruit nRF52 Feather ships with a serial and OTA BLE bootloader
-that can be used to flash firmware images over a simple serial connection,
-using the on-board USB serial converter.
-
-These commands assume that you have already installed `nrfutil`, as described
-in the [learning guide](https://learn.adafruit.com/bluefruit-nrf52-feather-learning-guide/arduino-bsp-setup)
-for the Arduino variant of the board.
+## Flashing binaries with `nrfutil`
 
 ### 1. **Update bootloader** to single-bank version
 
@@ -88,7 +95,7 @@ To enable BLE5 support and the latest S132 release, flash the v5.0.0 bootloader
 $ make BOARD=feather52 SERIAL=/dev/tty.SLAB_USBtoUART SOFTDEV_VERSION=5.0.0 boot-flash
 ```
 
-### 2. Generate a CircuitPython DFU .zip package and flash it over serial
+### 2. Generate and flash a CircuitPython DFU .zip package over serial
 
 The following command will package and flash the CircuitPython binary using the
 appropriate bootloader mentionned above.
@@ -102,9 +109,49 @@ image, as described earlier in this readme.
 $ make BOARD=feather52 SERIAL=/dev/tty.SLAB_USBtoUART dfu-gen dfu-flash
 ```
 
-If you built your CircuitPython binary with **BLE UART** support you will
-need to add the `SD=s132` flag as shown below:
+If you built your CircuitPython binary with **BLE** support you will need to
+add the `SD=s132` flag as shown below:
 
 ```
 $ make BOARD=feather52 SERIAL=/dev/tty.SLAB_USBtoUART SD=s132 dfu-gen dfu-flash
 ```
+
+## Working with CircuitPython
+
+### Running local files with `ampy`
+
+[ampy](https://learn.adafruit.com/micropython-basics-load-files-and-run-code/install-ampy)
+is a command-line tool that can be used with the nRF52 Feather to transfer
+local python files to the nRF52 for execution, rather than having to enter
+the REPL manually, enter paste mode, and paste the code yourself.
+
+> **IMPORTANT**: You must have `ampy` version **1.0.3** or higher to use `ampy`
+  with the nRF52. The bootloader on the nRF52 requires a delay between the
+  HW reset, and the moment when the command sequance is sent to enter raw
+  mode. This required `-d/--delay` flag was added in release 1.0.3.
+
+
+Save the following file as `test.py`:
+
+```
+import board
+import digitalio
+import time
+
+led = digitalio.DigitalInOut(board.LED2)
+led.direction = digitalio.Direction.OUTPUT
+
+while True:
+    led.value = True
+    time.sleep(0.5)
+    led.value = False
+    time.sleep(0.5)
+```
+
+Then run the saved file via ampy, updating the serial port as required:
+
+```
+$ ampy -p /dev/tty.SLAB_USBtoUART -d 1.5 run test.py
+```
+
+This should give you blinky at 1 Hz on LED2 (the blue LED on the nRF52 Feather).