.github/workflows/ports_esp8266.yml

+name: esp8266 port
+
+on:
+  push:
+  pull_request:
+    paths:
+      - '.github/workflows/*.yml'
+      - 'tools/**'
+      - 'py/**'
+      - 'extmod/**'
+      - 'shared/**'
+      - 'lib/**'
+      - 'drivers/**'
+      - 'ports/esp8266/**'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - name: Install packages
+      run: source tools/ci.sh && ci_esp8266_setup && ci_esp8266_path >> $GITHUB_PATH
+    - name: Build
+      run: source tools/ci.sh && ci_esp8266_build

.github/workflows/ports_mimxrt.yml

+name: mimxrt port
+
+on:
+  push:
+  pull_request:
+    paths:
+      - '.github/workflows/*.yml'
+      - 'tools/**'
+      - 'py/**'
+      - 'extmod/**'
+      - 'shared/**'
+      - 'lib/**'
+      - 'drivers/**'
+      - 'ports/mimxrt/**'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-20.04
+    steps:
+    - uses: actions/checkout@v3
+    - name: Install packages
+      run: source tools/ci.sh && ci_mimxrt_setup
+    - name: Build
+      run: source tools/ci.sh && ci_mimxrt_build

.github/workflows/ports_nrf.yml

+name: nrf port
+
+on:
+  push:
+  pull_request:
+    paths:
+      - '.github/workflows/*.yml'
+      - 'tools/**'
+      - 'py/**'
+      - 'extmod/**'
+      - 'shared/**'
+      - 'lib/**'
+      - 'drivers/**'
+      - 'ports/nrf/**'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-20.04
+    steps:
+    - uses: actions/checkout@v3
+    - name: Install packages
+      run: source tools/ci.sh && ci_nrf_setup
+    - name: Build
+      run: source tools/ci.sh && ci_nrf_build

.github/workflows/ports_powerpc.yml

+name: powerpc port
+
+on:
+  push:
+  pull_request:
+    paths:
+      - '.github/workflows/*.yml'
+      - 'tools/**'
+      - 'py/**'
+      - 'extmod/**'
+      - 'shared/**'
+      - 'lib/**'
+      - 'drivers/**'
+      - 'ports/powerpc/**'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - name: Install packages
+      run: source tools/ci.sh && ci_powerpc_setup
+    - name: Build
+      run: source tools/ci.sh && ci_powerpc_build

.github/workflows/ports_qemu-arm.yml

+name: qemu-arm port
+
+on:
+  push:
+  pull_request:
+    paths:
+      - '.github/workflows/*.yml'
+      - 'tools/**'
+      - 'py/**'
+      - 'extmod/**'
+      - 'shared/**'
+      - 'lib/**'
+      - 'drivers/**'
+      - 'ports/qemu-arm/**'
+      - 'tests/**'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build_and_test:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - name: Install packages
+      run: source tools/ci.sh && ci_qemu_arm_setup
+    - name: Build and run test suite
+      run: source tools/ci.sh && ci_qemu_arm_build
+    - name: Print failures
+      if: failure()
+      run: grep --before-context=100 --text "FAIL" ports/qemu-arm/build/console.out

.github/workflows/ports_renesas-ra.yml

+name: renesas-ra port
+
+on:
+  push:
+  pull_request:
+    paths:
+      - '.github/workflows/*.yml'
+      - 'tools/**'
+      - 'py/**'
+      - 'extmod/**'
+      - 'shared/**'
+      - 'lib/**'
+      - 'drivers/**'
+      - 'ports/renesas-ra/**'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build_renesas_ra_board:
+    runs-on: ubuntu-20.04
+    steps:
+    - uses: actions/checkout@v3
+    - name: Install packages
+      run: source tools/ci.sh && ci_renesas_ra_setup
+    - name: Build
+      run: source tools/ci.sh && ci_renesas_ra_board_build
+

.github/workflows/ports_rp2.yml

+name: rp2 port
+
+on:
+  push:
+  pull_request:
+    paths:
+      - '.github/workflows/*.yml'
+      - 'tools/**'
+      - 'py/**'
+      - 'extmod/**'
+      - 'shared/**'
+      - 'lib/**'
+      - 'drivers/**'
+      - 'ports/rp2/**'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - name: Install packages
+      run: source tools/ci.sh && ci_rp2_setup
+    - name: Build
+      run: source tools/ci.sh && ci_rp2_build

.github/workflows/ports_samd.yml

+name: samd port
+
+on:
+  push:
+  pull_request:
+    paths:
+      - '.github/workflows/*.yml'
+      - 'tools/**'
+      - 'py/**'
+      - 'extmod/**'
+      - 'shared/**'
+      - 'lib/**'
+      - 'drivers/**'
+      - 'ports/samd/**'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - name: Install packages
+      run: source tools/ci.sh && ci_samd_setup
+    - name: Build
+      run: source tools/ci.sh && ci_samd_build

.github/workflows/ports_stm32.yml

+name: stm32 port
+
+on:
+  push:
+  pull_request:
+    paths:
+      - '.github/workflows/*.yml'
+      - 'tools/**'
+      - 'py/**'
+      - 'extmod/**'
+      - 'shared/**'
+      - 'lib/**'
+      - 'drivers/**'
+      - 'ports/stm32/**'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build_pyb:
+    runs-on: ubuntu-20.04
+    steps:
+    - uses: actions/checkout@v3
+    - name: Install packages
+      run: source tools/ci.sh && ci_stm32_setup
+    - name: Build
+      run: source tools/ci.sh && ci_stm32_pyb_build
+
+  build_nucleo:
+    runs-on: ubuntu-20.04
+    steps:
+    - uses: actions/checkout@v3
+    - name: Install packages
+      run: source tools/ci.sh && ci_stm32_setup
+    - name: Build
+      run: source tools/ci.sh && ci_stm32_nucleo_build

.github/workflows/ports_teensy.yml

+name: teensy port
+
+on:
+  push:
+  pull_request:
+    paths:
+      - '.github/workflows/*.yml'
+      - 'tools/**'
+      - 'py/**'
+      - 'extmod/**'
+      - 'shared/**'
+      - 'lib/**'
+      - 'drivers/**'
+      - 'ports/teensy/**'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - name: Install packages
+      run: source tools/ci.sh && ci_teensy_setup
+    - name: Build
+      run: source tools/ci.sh && ci_teensy_build

.github/workflows/ports_unix.yml

+name: unix port
+
+on:
+  push:
+  pull_request:
+    paths:
+      - '.github/workflows/*.yml'
+      - 'tools/**'
+      - 'py/**'
+      - 'extmod/**'
+      - 'shared/**'
+      - 'lib/**'
+      - 'examples/**'
+      - 'mpy-cross/**'
+      - 'ports/unix/**'
+      - 'tests/**'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  minimal:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - name: Build
+      run: source tools/ci.sh && ci_unix_minimal_build
+    - name: Run main test suite
+      run: source tools/ci.sh && ci_unix_minimal_run_tests
+    - name: Print failures
+      if: failure()
+      run: tests/run-tests.py --print-failures
+
+  reproducible:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - name: Build with reproducible date
+      run: source tools/ci.sh && ci_unix_minimal_build
+      env:
+        SOURCE_DATE_EPOCH: 1234567890
+    - name: Check reproducible build date
+      run: echo | ports/unix/build-minimal/micropython -i | grep 'on 2009-02-13;'
+
+  standard:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - name: Build
+      run: source tools/ci.sh && ci_unix_standard_build
+    - name: Run main test suite
+      run: source tools/ci.sh && ci_unix_standard_run_tests
+    - name: Print failures
+      if: failure()
+      run: tests/run-tests.py --print-failures
+
+  coverage:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - name: Install packages
+      run: source tools/ci.sh && ci_unix_coverage_setup
+    - name: Build
+      run: source tools/ci.sh && ci_unix_coverage_build
+    - name: Run main test suite
+      run: source tools/ci.sh && ci_unix_coverage_run_tests
+    - name: Test merging .mpy files
+      run: source tools/ci.sh && ci_unix_coverage_run_mpy_merge_tests
+    - name: Build native mpy modules
+      run: source tools/ci.sh && ci_native_mpy_modules_build
+    - name: Test importing .mpy generated by mpy_ld.py
+      run: source tools/ci.sh && ci_unix_coverage_run_native_mpy_tests
+    - name: Run gcov coverage analysis
+      run: |
+        (cd ports/unix && gcov -o build-coverage/py ../../py/*.c || true)
+        (cd ports/unix && gcov -o build-coverage/extmod ../../extmod/*.c || true)
+    - name: Upload coverage to Codecov
+      uses: codecov/codecov-action@v3
+      with:
+        fail_ci_if_error: true
+        verbose: true
+    - name: Print failures
+      if: failure()
+      run: tests/run-tests.py --print-failures
+
+  coverage_32bit:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - name: Install packages
+      run: source tools/ci.sh && ci_unix_32bit_setup
+    - name: Build
+      run: source tools/ci.sh && ci_unix_coverage_32bit_build
+    - name: Run main test suite
+      run: source tools/ci.sh && ci_unix_coverage_32bit_run_tests
+    - name: Build native mpy modules
+      run: source tools/ci.sh && ci_native_mpy_modules_32bit_build
+    - name: Test importing .mpy generated by mpy_ld.py
+      run: source tools/ci.sh && ci_unix_coverage_32bit_run_native_mpy_tests
+    - name: Print failures
+      if: failure()
+      run: tests/run-tests.py --print-failures
+
+  nanbox:
+    runs-on: ubuntu-20.04 # use 20.04 to get python2
+    steps:
+    - uses: actions/checkout@v3
+    - name: Install packages
+      run: source tools/ci.sh && ci_unix_32bit_setup
+    - name: Build
+      run: source tools/ci.sh && ci_unix_nanbox_build
+    - name: Run main test suite
+      run: source tools/ci.sh && ci_unix_nanbox_run_tests
+    - name: Print failures
+      if: failure()
+      run: tests/run-tests.py --print-failures
+
+  float:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - name: Build
+      run: source tools/ci.sh && ci_unix_float_build
+    - name: Run main test suite
+      run: source tools/ci.sh && ci_unix_float_run_tests
+    - name: Print failures
+      if: failure()
+      run: tests/run-tests.py --print-failures
+
+  stackless_clang:
+    runs-on: ubuntu-20.04
+    steps:
+    - uses: actions/checkout@v3
+    - name: Install packages
+      run: source tools/ci.sh && ci_unix_clang_setup
+    - name: Build
+      run: source tools/ci.sh && ci_unix_stackless_clang_build
+    - name: Run main test suite
+      run: source tools/ci.sh && ci_unix_stackless_clang_run_tests
+    - name: Print failures
+      if: failure()
+      run: tests/run-tests.py --print-failures
+
+  float_clang:
+    runs-on: ubuntu-20.04
+    steps:
+    - uses: actions/checkout@v3
+    - name: Install packages
+      run: source tools/ci.sh && ci_unix_clang_setup
+    - name: Build
+      run: source tools/ci.sh && ci_unix_float_clang_build
+    - name: Run main test suite
+      run: source tools/ci.sh && ci_unix_float_clang_run_tests
+    - name: Print failures
+      if: failure()
+      run: tests/run-tests.py --print-failures
+
+  settrace:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - name: Build
+      run: source tools/ci.sh && ci_unix_settrace_build
+    - name: Run main test suite
+      run: source tools/ci.sh && ci_unix_settrace_run_tests
+    - name: Print failures
+      if: failure()
+      run: tests/run-tests.py --print-failures
+
+  settrace_stackless:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - name: Build
+      run: source tools/ci.sh && ci_unix_settrace_stackless_build
+    - name: Run main test suite
+      run: source tools/ci.sh && ci_unix_settrace_stackless_run_tests
+    - name: Print failures
+      if: failure()
+      run: tests/run-tests.py --print-failures
+
+  macos:
+    runs-on: macos-11.0
+    steps:
+    - uses: actions/checkout@v3
+    - uses: actions/setup-python@v4
+      with:
+        python-version: '3.8'
+    - name: Build
+      run: source tools/ci.sh && ci_unix_macos_build
+    - name: Run tests
+      run: source tools/ci.sh && ci_unix_macos_run_tests
+    - name: Print failures
+      if: failure()
+      run: tests/run-tests.py --print-failures
+
+  qemu_mips:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - name: Install packages
+      run: source tools/ci.sh && ci_unix_qemu_mips_setup
+    - name: Build
+      run: source tools/ci.sh && ci_unix_qemu_mips_build
+    - name: Run main test suite
+      run: source tools/ci.sh && ci_unix_qemu_mips_run_tests
+    - name: Print failures
+      if: failure()
+      run: tests/run-tests.py --print-failures
+
+  qemu_arm:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - name: Install packages
+      run: source tools/ci.sh && ci_unix_qemu_arm_setup
+    - name: Build
+      run: source tools/ci.sh && ci_unix_qemu_arm_build
+    - name: Run main test suite
+      run: source tools/ci.sh && ci_unix_qemu_arm_run_tests
+    - name: Print failures
+      if: failure()
+      run: tests/run-tests.py --print-failures

.github/workflows/ports_webassembly.yml

+name: webassembly port
+
+on:
+  push:
+  pull_request:
+    paths:
+      - '.github/workflows/*.yml'
+      - 'tools/**'
+      - 'py/**'
+      - 'extmod/**'
+      - 'shared/**'
+      - 'lib/**'
+      - 'ports/webassembly/**'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - name: Install packages
+      run: source tools/ci.sh && ci_webassembly_setup
+    - name: Build
+      run: source tools/ci.sh && ci_webassembly_build
+    - name: Run tests
+      run: source tools/ci.sh && ci_webassembly_run_tests
+    - name: Print failures
+      if: failure()
+      run: tests/run-tests.py --print-failures

.github/workflows/ports_windows.yml

+name: windows port
+
+on:
+  push:
+  pull_request:
+    paths:
+      - '.github/workflows/*.yml'
+      - 'tools/**'
+      - 'py/**'
+      - 'extmod/**'
+      - 'shared/**'
+      - 'lib/**'
+      - 'ports/unix/**'
+      - 'ports/windows/**'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - name: Install packages
+      run: source tools/ci.sh && ci_windows_setup
+    - name: Build
+      run: source tools/ci.sh && ci_windows_build

.github/workflows/ports_zephyr.yml

+name: zephyr port
+
+on:
+  push:
+  pull_request:
+    paths:
+      - '.github/workflows/ports_zephyr.yml'
+      - 'tools/**'
+      - 'py/**'
+      - 'extmod/**'
+      - 'shared/**'
+      - 'lib/**'
+      - 'ports/zephyr/**'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - name: Install packages
+      run: source tools/ci.sh && ci_zephyr_setup
+    - name: Install Zephyr
+      run: source tools/ci.sh && ci_zephyr_install
+    - name: Build
+      run: source tools/ci.sh && ci_zephyr_build

.gitignore

+# This .gitignore file is intended to be minimal.
+#
+# If you find that you need additional rules, such as IDE temporary
+# files, please do so either via a global .gitignore file (registered
+# with core.excludesFile), or by adding private repository-specific
+# rules to .git/info/exclude.  See https://git-scm.com/docs/gitignore
+# for more information.
+
+# Build directories
+build/
+build-*/
+docs/genrst/
+
+# Test failure outputs
+tests/results/*
+
+# Python cache files
+__pycache__/
+
+# Customized Makefile/project overrides
+GNUmakefile
+user.props
+
+# MacOS desktop metadata files
+.DS_Store
+
+#ctags
+tags
+
+sdkconfig.old
+sdkconfig

.gitlab-ci.yml

+variables:
+  GIT_SUBMODULE_STRATEGY: recursive
+  GIT_SUBMODULE_PATHS: micropython/lib/berkeley-db-1.xx micropython/lib/micropython-lib
+
+
+stages:
+  - build
+
+build-p1:
+  stage: build
+  tags:
+    - nixos
+  script:
+    - nix-shell nix/shell.nix --command "idf.py -g p1 build"
+  artifacts:
+    expose_as: 'Proto 1 ELF'
+    paths: ['build/badge23.elf']
+
+build-p3:
+  stage: build
+  tags:
+    - nixos
+  script:
+    - nix-shell nix/shell.nix --command "idf.py -g p3 build"
+  artifacts:
+    expose_as: 'Proto 3 ELF'
+    paths: ['build/badge23.elf']
+
+build-p4:
+  stage: build
+  tags:
+    - nixos
+  script:
+    - nix-shell nix/shell.nix --command "idf.py -g p4 build"
+  artifacts:
+    expose_as: 'Proto 4 ELF'
+    paths: ['build/badge23.elf']

.gitmodules

+[submodule "lib/axtls"]
+	path = micropython/lib/axtls
+	url = https://github.com/micropython/axtls.git
+[submodule "lib/libffi"]
+	path = micropython/lib/libffi
+	url = https://github.com/atgreen/libffi
+[submodule "lib/lwip"]
+	path = micropython/lib/lwip
+	url = https://github.com/lwip-tcpip/lwip.git
+[submodule "lib/berkeley-db-1.xx"]
+	path = micropython/lib/berkeley-db-1.xx
+	url = https://github.com/pfalcon/berkeley-db-1.xx
+[submodule "lib/stm32lib"]
+	path = micropython/lib/stm32lib
+	url = https://github.com/micropython/stm32lib
+	branch = work-F0-1.9.0+F4-1.16.0+F7-1.7.0+G0-1.5.1+G4-1.3.0+H7-1.6.0+L0-1.11.2+L1-1.10.3+L4-1.17.0+WB-1.10.0+WL-1.1.0
+[submodule "lib/nrfx"]
+	path = micropython/lib/nrfx
+	url = https://github.com/NordicSemiconductor/nrfx.git
+[submodule "lib/mbedtls"]
+	path = micropython/lib/mbedtls
+	url = https://github.com/ARMmbed/mbedtls.git
+[submodule "lib/asf4"]
+	path = micropython/lib/asf4
+	url = https://github.com/adafruit/asf4
+	branch = circuitpython
+[submodule "lib/tinyusb"]
+	path = micropython/lib/tinyusb
+	url = https://github.com/hathach/tinyusb
+[submodule "lib/mynewt-nimble"]
+	path = micropython/lib/mynewt-nimble
+	url = https://github.com/micropython/mynewt-nimble.git
+[submodule "lib/btstack"]
+	path = micropython/lib/btstack
+	url = https://github.com/bluekitchen/btstack.git
+[submodule "lib/nxp_driver"]
+	path = micropython/lib/nxp_driver
+	url = https://github.com/hathach/nxp_driver.git
+[submodule "lib/libhydrogen"]
+	path = micropython/lib/libhydrogen
+	url = https://github.com/jedisct1/libhydrogen.git
+[submodule "lib/pico-sdk"]
+	path = micropython/lib/pico-sdk
+	url = https://github.com/raspberrypi/pico-sdk.git
+[submodule "lib/fsp"]
+	path = micropython/lib/fsp
+	url = https://github.com/renesas/fsp.git
+[submodule "lib/wiznet"]
+	path = micropython/lib/wiznet5k
+	url = https://github.com/andrewleech/wiznet_ioLibrary_Driver.git
+	# Requires https://github.com/Wiznet/ioLibrary_Driver/pull/120
+	# url = https://github.com/Wiznet/ioLibrary_Driver.git
+[submodule "lib/cyw43-driver"]
+	path = micropython/lib/cyw43-driver
+	url = https://github.com/georgerobotics/cyw43-driver.git
+[submodule "lib/micropython-lib"]
+	path = micropython/lib/micropython-lib
+	url = https://github.com/micropython/micropython-lib.git

.pre-commit-config.yaml

+repos:
+  - repo: local
+    hooks:
+      - id: codeformat
+        name: MicroPython codeformat.py for changed files
+        entry: tools/codeformat.py -v -f
+        language: python
+      - id: verifygitlog
+        name: MicroPython git commit message format checker
+        entry: tools/verifygitlog.py --check-file --ignore-rebase
+        language: python
+        verbose: true
+        stages: [commit-msg]

CMakeLists.txt

+cmake_minimum_required(VERSION 3.12)
+
+set(IDF_TARGET esp32s3)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+
+project(badge23)

README.md

+## Demo Payload
+
+See python_payload/README.md for a demo application.
+
+Files can be transferred with mpremote, such as:
+
+```
+mpremote fs cp python_payload/boot.py :boot.py
+```
+
+Alternatively, adafruit-ampy may work more reliably sometimes:
+
+```
+ampy -p /dev/ttyACM0 -d3 put boot.py
+```
+
+Please transfer all .py files in python_payload/ for using the demo payload.
+
+## How to install dependencies
+
+### Generic
+
+1. install esp-idf v4.4:
+(copied from https://www.wemos.cc/en/latest/tutorials/others/build\_micropython\_esp32.html)
+```
+$ cd ~
+$ git clone https://github.com/espressif/esp-idf.git
+$ cd esp-idf
+$ git checkout v4.4
+$ git submodule update --init --recursive
+
+$ cd esp-idf
+$ ./install.sh
+$ source export.sh
+```
+best put something like "alias espidf='source ~/esp-idf/export.sh'" in your .bashrc etc,
+you need to run it in every new terminal and adding it to autostart did bother us
+
+### Nix(OS)
+
+```
+$ nix-shell nix/shell.nix
+```
+
+## How to build and flash
+
+Standard ESP-IDF project machinery present and working. You can run `idf.py` from the git checkout and things should just work.
+
+### Building
+
+Prepare submodules:
+
+```
+$ make -C micropython/ports/esp32 submodules
+```
+
+Build normally with idf.py:
+
+```
+$ idf.py build
+```
+
+By default, code for the fourth generation prototype will be built. To select a different generation, either set `-g`/`--generation` during an `idf.py build` (which will get cached for subsequent builds) or set the BADGE_GENERATION environment variable to one of the following values:
+
+^ `-g` / `BADGE_GENERATION` value ^ Badge Generation                   ^ 
+| `p1` or `proto1`                | Prototype 1                        |
+| `p3` or `proto3`                | Prototype 3 (B3xx)                 |
+| `p4` or `proto4`                | Prototype 4 (B4xx)                 |
+
+**Important**: when switching generations, do a full clean by running `rm -rf sdkconfig build`. Otherwise you will get _weird_ errors and likely will end up building for the wrong architecture.
+
+### Flashing
+
+Put badge into bootloader mode by holding left should button down during boot.
+
+```
+$ idf.py -p /dev/ttyACM0 flash
+```
+
+You can skip `-p /dev/ttyACM0` if you set the environment variable `ESPPORT=/dev/ttyACM0`. This environment variable is also set by default when using Nix.
+
+After flashing, remember to powercycle your badge to get it into the user application.
+
+
+### Cleaning
+
+For a full clean, do **not** trust `idf.py clean` or `idf.py fullclean`. Instead, do:
+
+```
+$ rm -rf build sdkconfig
+```
+
+### Accessing MicroPython REPL:
+
+```
+$ picocom -b 115200 /dev/ttyACM0
+$ # or
+$ screen /dev/ttyACM0
+$ # or (will eat newlines in REPL, though)
+$ idf.py -p /dev/ttyACM0 monitor
+```
+
+### Use CMake
+
+`idf.py` calls cmake under the hood for most operations. If you dislike using wrappers you can do the same work yourself:
+
+```
+mkdir build
+cd build
+cmake .. -G Ninja
+ninja
+```
+
+There's `flash/monitor` targets, too (but no openocd/gdb...). To pick what port to flash to/monitor, set the ESPPORT environment variable.
+
+## How to modify
+
+### Structure
+
+```
+main/               - main module, starts micropython on core1 and continues
+                      executing components/badge23/.
+usermodule/         - `hardware`, `synth`, ... C modules exposed to micropython.
+components/badge23/ - main ESP-IDF `app_main`, runs on core 0 after micropython
+                      gets started on core1.
+components/gc9a01/  - low-level LCD driver.
+```
+
+### General info
+
+Global + micropython entry point: `app_main()` in `micropython/ports/esp32/main.c`, compiled into `main/` component.
+
+C entry point, called by^: `os_app_main()` in components/badge23/espan.c
+
+Register new C files for compilation: add to components/badge23/CMakelists.txt
+
+Change output volume in the `set_global_vol_dB(int8_t)` call; -90 for mute
+
+### Debugging
+
+The badge is currently configured to run in HW USB UART/JTAG mode (vs. using TinyUSB and 'software' CDC/whatever using the generic OTG peripheral).
+
+What this means:
+
+1. You can use the MicroPython REPL over a USB console,
+2. The MicroPython REPL will also print ESP-IDF logs, including panics,
+3. You can use OpenOCD/GDB.
+
+#### printf() debugging and logging in C-land
+
+Given the above, you can do the following to get a log. This is part of ESP-IDF's standard logging functionality.
+
+```
+static const char *TAG = "misery";
+// ...
+ESP_LOGI(TAG, "i love C");
+```
+
+However, this will **only work** if you first set `CONFIG_LOG_DEFAULT_LEVEL_INFO=y` (which will likely break programs interacting with micropython REPL as many components of the ESP-IDF will suddenly become very chatty). But that's fine for troubleshooting some C-land bugs.
+
+If you want to only log errors or just add temporary logs, use `ESP_LOGE` instead, which will always print to the USB console.
+
+`printf()` also just works. But it should only be used for development debugging, for long-term logging statements please use `ESP_LOG*` instead.
+
+#### Running OpenOCD+GDB
+
+First, make sure your badge is running in application mode (not bootloader mode! that will stay in bootloader mode).
+
+Then, start OpenOCD:
+
+```
+$ OPENOCD_COMMANDS="-f board/esp32s3-builtin.cfg" idf.py openocd
+```
+
+(you can skip setting `OPENOCD_COMMANDS` if you're using Nix)
+
+Then, in another terminal:
+
+```
+$ idf.py gdb
+```
+
+Good luck. The idf.py gdb/openocd scripts seem somewhat buggy.
+
+### ESP-IDF functionality
+
+#### sdkconfig / menuconfig
+
+We have an sdkconfig.default file per badge generation. See the build
+instructions above to see how to select the generation to build against.
+
+The build system will generate an sdkconfig, but it should not be committed into
+version control. Instead, treat it like an ephemeral artifact that you can also
+modify for your own needs during development.
+
+To run menuconfig, do the usual::
+
+```
+$ idf.py  menuconfig
+```
+
+(Specify -g or BADGE_GENERATION if you haven't built the firmware yet)
+
+Then, either save into the temporary sdkconfig by using 'S', or save into a
+defconfig by using 'D'. The resulting `build/defconfig` file can then be copied
+into `sdkconfig.$generation` to change the defaults for a given generation.