<mmm-embed path="/0x33.board" facet="toc" nolink></mmm-embed>

# <mmm-embed facet="title" nolink></mmm-embed>

The 0x33.board firmware is built on CircuitPython and can easily
be modified while the board is connected to a computer.

<span id="install-fw" />
## updating/installing the firmware

These steps assume you already have the latest version of CircuitPython installed on the board.
If this is not the case, follow the steps in [the next section](#install-cpy) first.

1. If you don't see a `HEX33BOARD` or `CIRCUITPYTHON` drive when connecting the board to your computer,
   you need to enter dev mode first [(see below)](#dev-mode).
1. Download or clone the [firmware source code][firmware] source code.
1. Back up your `profiles` directory to make sure you don't lose your settings when updating.
1. Change <mmm-link path="/0x33.board/appendix/config.py">`config.py`</mmm-link> to reflect your hardware revision or any changes you made.
1. Copy all files from the repo to the drive.
1. Use `circup` to install the dependencies, or manually get them from the [Adafruit CircuitPython library bundle][cpy-lib-bundle]:

       $ cd $DRIVE
       $ circup --path . install -r requirements.txt

<span id="install-cpy" />
## updating/installing CircuitPython

1. Download the latest CircuitPython build (`.uf2` file) [for the Solderparty RP2040 Stamp][cpy].
2. Connect the 0x33.board to a computer.
3. Reset the board into bootloader mode by double-pressing the RESET button in the small hole on the bottom of the 0x33.board.
   A new removable drive with the UF2 bootloader should appear.
4. Copy the `.uf2` file to the removable drive.
   The drive should disappear and reappear with a different name.
5. Reinstall the hex33board firmware [(see above)](#install-fw).

## debugging & the serial console

The firmware can print debugging messages and errors to the Serial Console.
See [the Adafruit guide for connecting to the CircuitPython Serial Console][serial] for information on how to access it.

After connecting, you can enter CTRL+C to interrupt the firmeware and press any key to enter the [REPL][cpy-repl].
It can be useful to load the board config (with the hardware pin assignments) and/or instantiate Keyboard for debugging:

    from hex33board import Keyboard
    import config as board
    
    k = board.Keyboard(board)


<span id="dev-mode" />
## dev mode

When the board is in *dev mode*, it will show up on a computer as a flash storage in addition to MIDI and Serial connections.
This allows viewing or changing the stored profile data, firmware source code etc.

When the board turns on, it will enter *dev mode* when either:

- the <mmm-link path="/0x33.board/appendix/config.py">`config.py`</mmm-link> option `dev_mode` is set to `True`
  - setting this will keep the board in dev mode across restarts
- the `menu` key is held down while the board is plugged in or reset
  - this override is temporary

When the board is in *dev mode*, profiles can't be saved (so any settings changed will be lost).
When the board is set to `dev_mode=True` in `config.py`,
holding down the `menu` key while the board starts will temporarily bring the board *out of* dev mode.
This can be useful to test or debug issues with profile saving etc. during development.


<span id="simulator" />
## simulator
The firmware can be run without any hadrware using 'regular python' on a computer.
To do this, install the dependencies and run `simulator.py`:

    $ pip install -r requirements.sim.txt # you may want to do this in a venv
    $ python simulator.py

This will start the simulator server, which can now be accessed in a browser at [http://localhost:8000/](http://localhost:8000).
The simulator currently supports pressing keys, RGB lighting and display output via the web interface.
It also exposes MIDI ports via python rtmidi API.

### hardware input
A hardware keyboard configured with `sysex_key_sync = True` and connected via USB to the simulator's virtual
USB-MIDI input can be used as a hardware control surface for the simulator.

In this case the firmware will be running twice in parallel: once on the physical device, and once on the computer.
Only key press/release events are shared, so care must be taken to start with the devices in the same state in order to keep them in sync.

[firmware]: https://git.s-ol.nu/hw/0x33.board/firmware/-/
[cpy]: https://circuitpython.org/board/solderparty_rp2040_stamp/
[cpy-lib-bundle]: https://circuitpython.org/libraries
[cpy-repl]: https://learn.adafruit.com/welcome-to-circuitpython/the-repl
[serial]: https://learn.adafruit.com/welcome-to-circuitpython/kattni-connecting-to-the-serial-console#using-something-else-2978927