From ea23bfa976905e6149ec28dbd5d9c4232227f34c Mon Sep 17 00:00:00 2001 From: my Date: Thu, 10 Sep 2026 16:10:14 +0200 Subject: [PATCH] add readme --- README.md | 96 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 96 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..8172494 --- /dev/null +++ b/README.md @@ -0,0 +1,96 @@ +# Cyberdeck Chat + +The Meshberry is a mesh chat app for the CYD + M5Stack CardKB v1.1, built for The Hmm cyberdeck workshop. +Devices in range talk to each other over ESP-NOW, and forward messages for other users. When not in range of other users, the device can be used for Note taking and as a Bluetooth keybaord. + +All the mesh chat functionality was directly ported from https://github.com/7h30th3r0n3/Evil-M5Project/wiki/EvilChatMesh + +## Hardware + +- **Board**: We used a non-standard CYD variant; [1005008564907457] from Aliexpress, mostly for the price and USB-C connector. The peripheral +connectors are placed a little differently from the commonly documented ESP32-2432S028R. The pin configuration in this project is specific to this board and may not work on other CYD revisions without changes to the GPIO assignments. + +ESP32-32E/ESP32-D0WD-V3, no PSRAM, 320×240 ST7789 display, resistive touch. +- **Keyboard**: M5Stack CardKB v1.1, wired to the board's 1.25 mm + peripheral headers (GPIO23/19) over I2C. 3.3V and GND are available on the other header, so a custom cable is needed. + See `include/config.h` for pin assignments. The keyboard uses pins IO19 and IO23 for I2C, which are also wired to the SD card SPI pins. So no SD card support regrettably. + +## Build & flash + +I've used PIOArduino for building, but regular PIO should work fine. +The source can be found in `/src`. +`src/meshberry` hold the source for the chat / notes applciuation +`src/chat-relay` is a slightly modified version of https://github.com/7h30th3r0n3/Evil-M5Project/blob/main/slave/EvilChatMesh-Relay.ino with the callback functions modified for the new signatures. Upload this to a 'regular' ESP32 module/devkit to extend your mesh chat network. + + +``` +pio run --target upload +``` + +Upload LittleFS `data/config.txt`. This deletes whats already there, so existing notes etc are lost. + +``` +pio run --target uploadfs +``` + +## config.txt reference + +All values have hardcoded defaults, so any key can be left out entirely. + +| Key | Meaning | +|---|---| +| `nick` | Set nickname. Max 15 characters, no spaces. `/nick ` in the app also updates this. | +| `brightness` | Backlight, 0 (off) - 255 (max). Default 200 | +| `snd_msg_freq`, `snd_msg_ms` | Frequency and duration (ms) of the incoming-message beep. | +| `snd_sys_freq`, `snd_sys_ms` | Frequency and duration (ms) of the join/leave beep. | +| `touch_threshold` | Threshold for touch to wake on Touch7 pin. Higher = easier to trigger. Not recommended for now. | +| `color_*` | 6-digit hex RGB (no `#`), same format as CSS, e.g. `ff0000` is red. See the table below for which UI element each one controls. | + +| Color key | Controls | +|---|---| +| `color_bg` | Screen background | +| `color_header_bg` | Header and Footer bar background | +| `color_msg` | Message body text | +| `color_nick_other` | Nickname color for other people's messages | +| `color_nick_own` | Nickname color for your own messages | +| `color_system` | System messages (joins, nick changes, errors) | +| `color_input_prompt` | The `>` prompt on the input line | + +Colors can also be changed from the device itself with `/set ` +(e.g. `/set color_bg ff0000`), see below. + +## Chat commands + +Typed into the input line, same as any chat message: + +| Command | Effect | +|---|---| +| `/nick ` | Change your nickname (saved to `config.txt`) | +| `/me ` | Roleplay-style action message | +| `/people` | List currently connected peers | +| `/clear` | Clear the chat window | +| `/clearnotes` | Erase all saved notes | +| `/set ` | Change a color setting; saved to `config.txt`, visible after sleep/restart | +| `/bt` | Toggle BT send mode (see below) | +| `/sleep` | Put the device to deep sleep (wake via BOOT button or touch7) | +| `/help` | List commands on-device | + +## Notes mode + +Press **Tab** to switch between chat and the notepad. What you type in notes mode is saved to a file on the device instead of broadcast on the chat. + +## BT mode +Your cyberdeck can also act as a Bluetooth keyboard. +To activate BT mode, Type `/bt` on your deck. The device is visible as Bluetooth HID device with your nickname as the device name. + +This has two functions: +1. Use it as a keyboard to remote control your computer / phone / tv etc. +2. It can type out the notes you stored in Notes-mode automatically into whatever text area you have open on your device. +To activate this press the `FN` key, then press `ESC`. + +**MAKE SURE YOU HAVE A TEXT EDITOR (NOTES, AN EMAIL) OPEN BEFORE YOU ACTIVATE THIS.** + +Press `TAB` exits BT mode and brings you back to the chat. + +Notes are *not* cleared automatically after sending, use `/clearnotes` +when you're done with them.