chore: Update README for Installation, Usage and Development (#58)

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.
+
+![Badge Magic LED charging animation](assets/charging-animation.gif)
+
+## 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,