You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
- README: image paths switch to absolute raw.githubusercontent.com URLs
so they resolve on the ESP Component Registry; ESP Component Registry
badge added; Install sections refreshed to reflect that midi2cpp ships
on Arduino Library Manager, PlatformIO Registry, and ESP Component
Registry; v0.2.0 references bumped to v0.3.1; recipe path fix
(rp2040-promicro-ump-test-bench).
- CHANGELOG: drop reference to internal design heritage notes.
- examples/t-display-s3-shield-host-midi2: drop absolute path from
lib_extra_dirs; recipe now resolves midi2cpp from the parent only.
- CODE_OF_CONDUCT.md, CONTRIBUTING.md, SECURITY.md added, mirroring
the governance set already published with midi2.
-**C++17 strict** (`-Wall -Wextra -Wpedantic -Werror`, zero warnings on GCC and Clang)
37
+
-**Static-by-default** -- the hot path is allocation-free; init-time `new` is allowed only inside `m2bridge` for the per-slot tables. The C99 core (midi2) stays strictly zero-allocation
38
+
-**Caller-provided platform hooks** -- write fn, monotonic clock, RNG, USB mount/alt are caller-supplied; no `<Arduino.h>`, `pico/time.h`, `esp_timer.h` or USB stack header is included by the library
-**Every new public method needs a test** -- host-side unit tests under `tests/`
41
+
-**C++17 standard library only** -- `<cstdint>`, `<cstring>`, `<functional>`, `<array>`. No exceptions, no RTTI assumptions
42
+
-**Comments**: explain _why_, not _what_. Reference the spec section when handling a UMP or MIDI-CI message
43
+
44
+
## Adding a Hardware Recipe
45
+
46
+
Recipes live under `examples/<board-role>-midi2/` and follow a consistent layout:
47
+
48
+
-`README.md` (banner, USB identity, build, validation, spec coverage table)
49
+
-`idf/`, `pio/`, or top-level `CMakeLists.txt` depending on the build system
50
+
-`src/` (board glue, USB descriptors, showcase main)
51
+
-`board/` (banner image, schematic, datasheet)
52
+
-`monitor/` (screenshots from MIDI tooling that prove the recipe runs)
53
+
- A fresh USB PID from the project pool
54
+
55
+
The simplest way to add a new recipe is to copy the closest existing one under `examples/` and adapt the board glue, USB descriptors, and showcase main to the new target.
56
+
57
+
## Testing
58
+
59
+
```bash
60
+
cmake -B build -DMIDI2CPP_BUILD_TESTS=ON
61
+
cmake --build build --parallel
62
+
ctest --test-dir build --output-on-failure # all tests
CI runs host tests on Linux + macOS, strict warnings (gcc + clang), arduino-cli compile of `HelloMIDI2.ino`, and the Pico SDK build of `examples/rp2040-midi2`.
67
+
68
+
## Spec References
69
+
70
+
midi2cpp wraps the [midi2](https://github.com/sauloverissimo/midi2) C99 core, which implements:
71
+
72
+
-**UMP messages**: M2-104-UM v1.1.2
73
+
-**MIDI-CI messages**: M2-101-UM v1.2
74
+
-**Value scaling**: M2-115-U v1.0.2
75
+
76
+
When adding or modifying message handling, reference the spec section in code comments.
77
+
78
+
## License
79
+
80
+
By contributing, you agree that your contributions will be licensed under the MIT License.
@@ -197,9 +198,9 @@ By role: 10 device, 4 host, 4 bridge, 1 multi-transport (BLE + ESP-NOW, no USB P
197
198
198
199
### Arduino IDE
199
200
200
-
Once midi2cpp is published to the [Arduino Library Manager](https://github.com/arduino/library-registry), the IDE install becomes: search `midi2cpp`, click Install. The dependency on `midi2` (already on the Library Manager) is resolved automatically.
201
+
Listed on the [Arduino Library Manager](https://github.com/arduino/library-registry). The IDE install path: search the manager, click Install. The dependency on `midi2` is resolved automatically.
201
202
202
-
Until then, install manually:
203
+
Manual install (mirror, or while the manager index is propagating):
Either way, `midi2` is resolved transitively via the manifest declaration in `library.json`.
226
227
227
228
### ESP-IDF component
228
229
229
-
Two paths, depending on whether midi2cpp lives inside the project tree or alongside it:
230
+
Published on the [ESP Component Registry](https://components.espressif.com/components/sauloverissimo/midi2cpp). Two install paths, depending on whether midi2cpp comes from the registry or lives inside the project tree:
230
231
231
-
**As a local component** (current pattern in [`examples/`](examples/)):
232
+
**Via the Component Manager** (recommended):
233
+
234
+
```yaml
235
+
# main/idf_component.yml
236
+
dependencies:
237
+
idf: ">=5.0"
238
+
sauloverissimo/midi2cpp: ">=0.3.1"
239
+
```
240
+
241
+
`midi2` is pulled transitively through `midi2cpp`'s manifest. `idf.py reconfigure` drops both into `managed_components/`.
242
+
243
+
**As a local component** (vendoring pattern, useful when iterating on the wrapper):
Declare midi2 in `main/idf_component.yml` so the Component Manager pulls it next to `managed_components/`:
250
+
Then declare `midi2` in `main/idf_component.yml`:
239
251
240
252
```yaml
241
253
dependencies:
242
-
idf: ">=5.4"
243
-
midi2:
244
-
git: https://github.com/sauloverissimo/midi2.git
245
-
version: ">=0.3.4"
254
+
idf: ">=5.0"
255
+
sauloverissimo/midi2: ">=0.3.4"
246
256
```
247
257
248
-
`main/CMakeLists.txt` lists `midi2` (and any of `midi2cpp`'s wrapper sources you use) in its `idf_component_register(...)` block. The seven ESP-IDF recipes under [`examples/`](examples/) ship working templates for device, host and bridge roles.
258
+
`main/CMakeLists.txt`lists `midi2cpp`in its `idf_component_register(... REQUIRES midi2cpp ...)` block. The seven ESP-IDF recipes under [`examples/`](examples/) ship working templates for device, host and bridge roles.
If you discover a security vulnerability, please report it privately:
12
+
13
+
1.**Do not** open a public issue
14
+
2. Email: sauloverissimo@gmail.com
15
+
3. Include: description, steps to reproduce, potential impact
16
+
17
+
You will receive a response within 48 hours. Confirmed vulnerabilities will be patched and disclosed responsibly.
18
+
19
+
## Scope
20
+
21
+
midi2cpp is a C++17 wrapper over the [midi2](https://github.com/sauloverissimo/midi2) C99 core. It carries no network, file, or OS access of its own; the library reads UMP words from a caller-wired transport, dispatches them to typed callbacks, and writes UMP words back. Security concerns are limited to:
22
+
23
+
- Buffer overflows in SysEx7 / SysEx8 reassembly or MIDI-CI message parsing
24
+
- Integer overflows in value scaling, length calculations, or per-slot bridge windows
25
+
- Malformed UMP or MIDI-CI input causing unexpected behavior
26
+
- Out-of-bounds reads when parsing variable-length fields (Profiles, PE data)
27
+
- Use-after-free in the `m2bridge` slot table when the platform tears down a slot mid-feed
28
+
29
+
## Mitigations
30
+
31
+
- The host test suite (7 executables under `tests/`) runs under AddressSanitizer and UndefinedBehaviorSanitizer locally and in CI
32
+
- The `test_midi2_bridge` suite specifically exercises the heap allocations inside `m2bridge::begin()` (50x construct/begin/destruct cycles) under ASan
33
+
- Input length is validated before accessing message fields
34
+
- Multi-byte field access uses explicit bounds checks
35
+
- The C99 core (midi2) is strictly zero-allocation, eliminating use-after-free and double-free classes there
36
+
- midi2cpp's `new` allocations live only inside `m2bridge::begin()` and are released in the destructor
0 commit comments