git.s-ol.nu hw/hw.s-ol.nu / e647c04
0x33.board: update dev/simulator docs s-ol 4 months ago
2 changed file(s) with 48 addition(s) and 17 deletion(s). Raw diff Collapse all Expand all
+27
-16
0x33.board/appendix/config.py/text$markdown.md less more
11
22 # <mmm-embed facet="title" nolink></mmm-embed>
33
4 When the board is in <mmm-link path="/0x33.board/hacking">dev mode</mmm-link>,
4 When the board is in <mmm-link path="/0x33.board/hacking" facet="#dev-mode">dev mode</mmm-link>,
55 the `config.py` file can be changed to set advanced settings that are not available from the interface.
66
77 ## dev mode
88
9 <mmm-link path="/0x33.board/hacking">dev mode</mmm-link> can be enabled permanently by setting the `dev_mode` variable to `True`.
9 <mmm-link path="/0x33.board/hacking" facet="#dev-mode">dev mode</mmm-link> can be enabled permanently by setting the `dev_mode` variable to `True`.
1010 Whatever the setting is, it can be overriden for a single boot by holding the menu key down while starting, which will invert the setting.
11
12 ## SysEx key sync
13
14 SysEx key-press synchronization can be enabled by setting the `sysex_key_sync` variable to `True`.
15 See the <mmm-link path="/0x33.board/hacking" facet="#simulator">simulator section</mmm-link> on the firmware hacking page for more information.
1116
1217 ## board parameters
1318
1924
2025 The board parameters are:
2126
22 - `Matrix`:
23 a class to instantiate for reading the key matrix. Will be constructed as `Matrix(*matrix_pins)` and
24 should implement a `scan_for_changes()` generator method that yields `(int, bool)` tuples of the
25 pressed key indices and the value they changed to when the state changes.
26 - `matrix_pins`:
27 a tuple of arguments to pass when initializing `Matrix`
28 - `pixels_pin`:
29 a CircuitPython GPIO Pin for driving the RGB lighting
30 - `display_pins` (optional):
31 a dictionary with `sda` and `scl` keys pointing to CircuitPython GPIO Pins connecting to the OLED module
32 - `midi_pins` (optional):
33 a dictionary with `tx` and `rx` keys pointing to CircuitPython GPIO Pins for UART MIDI
34 - `i2c_pins` (optional):
35 a dictionary with `sda` and `scl` keys pointing to CircuitPython GPIO Pins for external I2C I/O
27 - `Keyboard`:
28 a class to instantiate to start firmware execution.
29 The constructor will be passed the config module as the only argument.
30 After instantiation, `keyboard.run()` will be invoked.
31
32 This should usually simply be `hex33board.Keyboard`.
33 - `create_matrix(board)`:
34 a function to instantiate a key matrix object.
35 The returned object should implement a `scan_for_changes()` generator method that yields `(int, bool)`
36 tuples of the pressed key indices and the value they changed to when the state changes.
37 - `create_pixels(board, **kwargs)`:
38 a function to instantiate a `neopixel.NeoPixel`-like object for RGB lighting
39 - `create_display(board, **kwargs)`:
40 a function to instantiate a `displayio.Display`-like object for the main display
41 - `create_midi_usb(board)`, `create_midi_trs(board)`:
42 functions to instantiate `adafruit_midi.MIDI` ports
43 - `create_audio_out(board)`:
44 a function to instantiate a `audiopwmio.PWMAudioOut`-like object
45 - `create_i2c(board, **kwargs)`, `create_i2ctarget(board, **kwargs)`:
46 functions to instantiate `busio.I2C` and `i2ctarget.I2CTarget` instances
+21
-1
0x33.board/hacking/text$markdown.md less more
4343 from hex33board import Keyboard
4444 import config as board
4545
46 k = Keyboard(board)
46 k = board.Keyboard(board)
4747
4848
4949 <span id="dev-mode" />
6464 holding down the `menu` key while the board starts will temporarily bring the board *out of* dev mode.
6565 This can be useful to test or debug issues with profile saving etc. during development.
6666
67
68 <span id="simulator" />
69 ## simulator
70 The firmware can be run without any hadrware using 'regular python' on a computer.
71 To do this, install the dependencies and run `simulator.py`:
72
73 $ pip install -r requirements.sim.txt # you may want to do this in a venv
74 $ python simulator.py
75
76 This will start the simulator server, which can now be accessed in a browser at [http://localhost:8000/](http://localhost:8000).
77 The simulator currently supports pressing keys, RGB lighting and display output via the web interface.
78 It also exposes MIDI ports via python rtmidi API.
79
80 ### hardware input
81 A hardware keyboard configured with `sysex_key_sync = True` and connected via USB to the simulator's virtual
82 USB-MIDI input can be used as a hardware control surface for the simulator.
83
84 In this case the firmware will be running twice in parallel: once on the physical device, and once on the computer.
85 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.
86
6787 [firmware]: https://git.s-ol.nu/hw/0x33.board/firmware/-/
6888 [cpy]: https://circuitpython.org/board/solderparty_rp2040_stamp/
6989 [cpy-lib-bundle]: https://circuitpython.org/libraries