chore: Update README for Installation, Usage and Development (#58)
This commit is contained in:
Dien-Nhung Nguyen
committed by
GitHub
GitHub
parent
bb33a6d82e
commit
321677cf9b
150
README.md
150
README.md
@@ -2,6 +2,156 @@
|
||||
|
||||
Hardware details and information to build an open firmware for Bluetooth LED badges, compatible with [Badge Magic app](https://github.com/fossasia/badgemagic-android)
|
||||
|
||||
## Installation
|
||||
|
||||
Install [wchisp](https://github.com/ch32-rs/wchisp?tab=readme-ov-file#installing).
|
||||
|
||||
Download prebuilt binaries from [release](https://github.com/fossasia/badgemagic-firmware/releases) or [the latest development builds](https://github.com/fossasia/badgemagic-firmware/tree/bin).
|
||||
|
||||
Make sure the battery is disconnected. Press and hold KEY2 (the button near the
|
||||
USB port) while plugging in the USB to enter the bootloader. Then run:
|
||||
|
||||
```sh
|
||||
wchisp flash badgemagic-ch582.bin
|
||||
```
|
||||
|
||||
Where badgemagic-ch582.bin is the binary downloaded above, the .elf file also
|
||||
works.
|
||||
|
||||
|
||||
## Usage
|
||||
|
||||
For usual usages, please refer to [badgemagic-android](https://github.com/fossasia/badgemagic-android) and [led-name-badge-ls32](https://github.com/fossasia/led-name-badge-ls32).
|
||||
|
||||
### Transferring Bitmap
|
||||
|
||||
#### over BLE
|
||||
|
||||
See [BadgeBLE.md](BadgeBLE.md).
|
||||
|
||||
#### over USB HID
|
||||
|
||||
From the device perspective, the data format is just the same as [the BLE Data
|
||||
Format](BadgeBLE.md#data-format). The only difference is the data width. It's 64 bytes, while BLE, is only 16.
|
||||
|
||||
Located at Interface 0x00 and Endpoint 0x01. Interface Number and Enpoint Address might not be always fixed, any app using this should check them before using.
|
||||
|
||||
For more detail about USB HID, please refer to [USB HID Device Class
|
||||
Definition](https://www.usb.org/hid).
|
||||
|
||||
#### over USB CDC ACM
|
||||
|
||||
Similar to USB HID, but more convenient. From the host's perspective, it appears as a serial device, which can be interacted directly without the additional library. e.g. A `bitmap.bin` file with a format just like [the BLE Data Format](BadgeBLE.md#data-format) can be transferred to the badge by:
|
||||
|
||||
```sh
|
||||
stty -F /dev/ttyACM0 raw && cat bitmap.bin > /dev/ttyACM0
|
||||
```
|
||||
|
||||
For more detail about USB CDC ACM, see [Class definitions for Communication Devices 1.2](https://www.usb.org/document-library/class-definitions-communication-devices-12).
|
||||
|
||||
### Read firmware version from the badge
|
||||
|
||||
#### over BLE
|
||||
|
||||
This firmware was implemented following [the BLE Device
|
||||
Information](https://www.bluetooth.com/specifications/specs/device-information-service-1-1/)
|
||||
standard. Any device with BLE-capable can easily get the version by reading the
|
||||
value of the Firmware Revision String Characteristic (0x2A26) in the Device
|
||||
Information Profile (0x18A).
|
||||
|
||||
#### over USB
|
||||
|
||||
The version can be read from USB by reading the [USB Serial Number
|
||||
String](https://www.usb.org/document-library/usb-20-specification).
|
||||
|
||||
#### from the screen
|
||||
|
||||
While the badge is in charging state, it display a animation followed by a
|
||||
version repeatedly.
|
||||
|
||||
|
||||
|
||||
## Development
|
||||
|
||||
### Tools
|
||||
|
||||
- [GNU make](https://www.gnu.org/software/make/)
|
||||
- [MounRiver Toolchain](http://file-oss.mounriver.com/tools/MRS_Toolchain_Linux_x64_V1.91.tar.xz)
|
||||
- [wchisp](https://github.com/ch32-rs/wchisp)
|
||||
|
||||
### Build
|
||||
|
||||
Set the toolchain location, e.g.:
|
||||
|
||||
```sh
|
||||
export PREFIX=../MRS_Toolchain_Linux_x64_V1.91/RISC-V_Embedded_GCC/bin/riscv-none-embed-
|
||||
```
|
||||
|
||||
Simply run `make` to build the firmware for the Micro USB version, with the output directed to the `build/` directory. To build for the USB-C version of the badge and specify a custom output directory:
|
||||
|
||||
```sh
|
||||
BUILD_DIR=custom-dir USBC_VERSION=1 make
|
||||
```
|
||||
|
||||
> [!NOTE]
|
||||
>
|
||||
> Switching `USBC_VERSION` will require a clean build to make sure the new build
|
||||
> does not contain the previous build blob. To rebuild:
|
||||
>
|
||||
> ```sh
|
||||
> make clean all
|
||||
> ```
|
||||
|
||||
To flash the firmware, enter the bootloader, then run:
|
||||
|
||||
```sh
|
||||
BUILD_DIR=custom-dir-if-needed make isp
|
||||
```
|
||||
|
||||
### Debugging
|
||||
|
||||
#### Logging over UART
|
||||
|
||||
Currently, only the UART1 with baudrate=921600 is used for debuging. To
|
||||
enable the log from UART, set the DEUBG=1 when build the project.
|
||||
|
||||
Any USB to UART dongle will work. Use your favorite terminal emulator to see the
|
||||
log, e.g.:
|
||||
|
||||
```sh
|
||||
picocom -b921600 /dev/ttyUSB0 --imap lfcrlf
|
||||
```
|
||||
|
||||
The [badgemagic-hardware](https://github.com/fossasia/badgemagic-hardware) have
|
||||
this UART wired over USB-C. So it can be used without opening the case, but
|
||||
required an [aditional hardware](https://oshwhub.com/mangogeek/typec) to split
|
||||
the serial lines from USB-C.
|
||||
|
||||
#### Logging over USB CDC-ACM
|
||||
|
||||
This is convenient as it doesn't require additional hardware, but it may not be
|
||||
useful for early logging when the USB is not yet initialized, and the user cannot open
|
||||
the serial port quickly enough.
|
||||
|
||||
Use `cdc_tx_poll()` to log to this serial channel.
|
||||
|
||||
#### On-chip Debugging
|
||||
|
||||
This is a mystery.
|
||||
|
||||
### Add a new BLE Profile
|
||||
|
||||
To create a new custom data exchange channel, add a new BLE profile to the firmware
|
||||
by duplicating `/src/ble/profile/legacy.c` and reconfig it. Rename
|
||||
`xxx_registerService()` function. Call this function after `peripheral_init()` to
|
||||
register your new profile.
|
||||
|
||||
For more detail of how to config a gatt service, see [BLE GATT](https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html).
|
||||
|
||||
### Add a new USB Composite Device
|
||||
|
||||
To add a new custom USB Composite Device (e.g., keyboard, mouse, speaker, etc.), duplicate `src/usb/composite/hiddev.c`. Rename and configure the file according to the Device Class you intend to implement, then call your device's `xxx_init()` function in `usb_start()` to initialize it. Each device class has specific specifications, so be sure to refer to them when implementing your new device.
|
||||
|
||||
## Hardware Information
|
||||
|
||||
BadgeMagic target hardware features a custom 11x44 LED matrix display,
|
||||
|
||||
Reference in New Issue
Block a user