acid/firmware2/README.md

# ACID firmware

## Building

### Compiling libxkbcommon

This needs to be done on Linux or in WSL.
meson.build needs to be changed such that `pkgconfig.generate` is called with the `variables` field embedded directly, for some reason:

```meson
    variables: [
        f'xkb_root=@XKB_CONFIG_ROOT@',
        f'xkb_extra_path=@XKB_CONFIG_EXTRA_PATH@',
    ],
```

Then, the tests, fuzzes and benches need to be commented out.
Afterwards, the following command should succeed in building the static library in debug mode:

```sh
meson setup build-debug -Denable-x11=false -Dxkb-config-root=/usr/share/X11/xkb -Dx-locale-root=/usr/share/X11/locale -Denable-wayland=false --cross-file cross-esp32s3.txt -Denable-xkbregistry=false -Denable-docs=false -Denable-tools=false --wipe --buildtype=debug
meson compile -C build-debug
```

Afterwards, a static library with redefined externally-linked symbols needs to be generated:

```
path/to/root/libxkbcommon-redefine-syms.sh build-debug/libxkbcommon{,_redefined_syms}.a
```

### Creating keymaps

To generate an English (US) keymap, the following command may be used:

`xkbcli compile-keymap --include [path-to-xkb-directory] --layout us >my_compose.txt`

Substitute `us` for any other 2-letter country code.

Where the `[path-to-xkb-directory]` is one of the following:
  * the `/usr/share/X11/xkb` directory on X11-based Linux distributions;
  * the [`xkeyboard-config` git repository](https://gitlab.freedesktop.org/xkeyboard-config/xkeyboard-config). There's an button to download it as a ZIP archive.

The most relevant part of the keymap is likely found in the `symbols` directory,
where variants of keymaps are defined for many languages.

### Compiling Compose files

Use libxkbcommon's `xkbcli` to compile a standalone compose file:

`xkbcli compile-compose [path-to-Compose-file] >my_compose.txt`

Compose files to replace `[path-to-Compose-file]` with may be found in:
  * the `/usr/share/X11/locale` directory on X11-based Linux distributions;
  * the [`libx11` git repository](https://gitlab.freedesktop.org/xorg/lib/libx11/-/tree/master). There's an button to download it as a ZIP archive.

# esp32s3 BLE example

To run this example, you should have latest Rust in **esp** channel installed. The full instruction of installing esp Rust toolchain can be found [here](https://docs.esp-rs.org/book/installation/index.html).

[`espflash`](https://github.com/esp-rs/espflash) should also be installed:

```
cargo install cargo-espflash espflash
```

After having everything installed, use the following command to run the example:

```
cd examples/use_rust/esp32s3_ble
cargo +esp run --release
```

If everything is good, you'll see the log as the following:

```shell
cargo run --release
    Compiling ...
    ...
    ...
    Finished `release` profile [optimized + debuginfo] target(s) in 11.70s
     Running `espflash flash --monitor --port /dev/cu.usbmodem211401 target/xtensa-esp32s3-none-elf/release/rmk-esp32s3`
[2025-04-10T10:01:23Z INFO ] Serial port: '/dev/cu.usbmodem211401'
[2025-04-10T10:01:23Z INFO ] Connecting...
[2025-04-10T10:01:23Z INFO ] Using flash stub
Chip type:         esp32s3 (revision v0.1)
Crystal frequency: 40 MHz
Flash size:        4MB
Features:          WiFi 6, BT 5
MAC address:       40:4c:ca:5b:c7:dc
App/part. size:    768,944/4,128,768 bytes, 18.62%
[2025-04-10T10:01:23Z INFO ] Segment at address '0x0' has not changed, skipping write
[2025-04-10T10:01:23Z INFO ] Segment at address '0x8000' has not changed, skipping write
[00:00:06] [========================================]     411/411     0x10000                                                                                             [2025-04-10T10:01:31Z INFO ] Flashing has completed!
```

If espflash reports the following error:

```
Error: espflash::connection_failed

  × Error while connecting to device
  ╰─▶ Serial port not found
```

You should to identify which serial port are connected to your esp board, and use `--port` to specify the used serial port:

```
# Suppose that the esp board are connected to /dev/cu.usbmodem211401
cargo run --release -- --port /dev/cu.usbmodem211401
```

If you want to get some insight of segments of your binary, [`espsegs`](https://github.com/bjoernQ/espsegs) would help:

```
# Install it first
cargo install --git https://github.com/bjoernQ/espsegs

# Check all segments
espsegs target/xtensa-esp32s3-none-elf/release/rmk-esp32s3 --chip esp32s3
```