docs: add next-gen profile (#71)

2025-02-19 14:52:49 +07:00 · 2025-02-19 14:52:49 +07:00 · 68148af209
commit 68148af209
parent 4e556ab11f
2 changed files with 391 additions and 5 deletions
--- a/BadgeBLE.md
+++ b/BadgeBLE.md
@ -2,14 +2,33 @@

 ### Connection Information

-The pixel data is transferred to the badge via BLE. The badge advertizes the name "LSLED" and uses a vendor specific service/characteristic:
+#### OEM Firmware

- Service-UUID: 0000fee0-0000-1000-8000-00805f9b34fb
- Characteristic: 0000fee1-0000-1000-8000-00805f9b34fb
+The pixel data is transferred to the badge via BLE. The OEM firmware advertises
+the name 'LSLED' and a 16-bit vendor-specific service/characteristic pair:

-The characteristic accepts 16 byte long data packets.
+- Service-UUID: 0xFEE0 (128-bit equivalent:
+  0000fee0-0000-1000-8000-00805f9b34fb)
+- Characteristic: 0xFEE1 (128-bit equivalent:
+  0000fee1-0000-1000-8000-00805f9b34fb)

-### Data Format
+The characteristic of the OEM firmware has Read/Write/Notify properties. It
+accepts 16 byte long data packets on writing. Its Read/Notify behavior is
+currently unknown and needs to be investigated.
+
+#### Open Firmware
+
+This open firmware advertises the service/characteristic pair 0xFEE0/0xFEE1 in
+the same way as the OEM firmware and uses the name "LED Badge Magic" which can
+be renamed via the [next-gen profile](#next-gen-profile). The characteristic
+0xFEE1, marked as the legacy profile, is write-only. Read/Notify functionality
+will be supported once its behavior is fully understood.
+
+An additional custom profile has been implemented, enabling more remote features
+and configuration over the BLE connection, see the [next-gen
+profile](#next-gen-profile) for details.
+
+### Data Format (Legacy)

 The badge supports up to 8 bitmaps which can have various features enabled.

@ -50,3 +69,147 @@ The "mode" bytes are a combination of two 4 bit values. The high nibble describe
 | 0x07 | "picture"         |
 | 0x08 | "laser"           |

+### Next-Gen profile
+
+ 16-bit Service/characteristic:
+
+- Service-UUID: 0xF055 (128-bit equivalent:
+  0000f055-0000-1000-8000-00805f9b34fb)
+- Characteristic: 0xF056 (128-bit equivalent:
+  0000f056-0000-1000-8000-00805f9b34fb)
+  - Write property: to receive controls and configs
+  - Notify property: to return error codes
+  - Read property: to be implemented
+
+#### Protocol
+
+The next-gen characteristic accepts messages of varying lengths (0 to 512
+bytes). The first byte represents the function/command code, while the remaining
+bytes contain parameters for the corresponding function/command.
+
+![next-gen message format](/assets/ng-protocol.svg)
+
+Supported functions/commands:
+
+- power_setting
+- streaming_setting
+- stream_bitmap
+- ble_setting
+- flash_splash_screen
+- save_cfg
+- load_fallback_cfg
+
+The client app should enable notifications for the characteristic to receive the
+returned error code (e.g., by using setCharacteristicNotification() on Android).
+
+##### power_setting
+
+Function/Command code: `0x01`.
+
+Parameters:
+
+- Power off: `0x00`.
+- Enable resetting after uploading is done: `[0x01, 0x00]`. Note: call
+  the [save_cfg](#save_cfg) command to save this config.
+- Disable resetting after uploading is done: `[0x01, 0x01]`. Note: call
+  the [save_cfg](#save_cfg) command to save this config.
+- Power off: `0x02`.
+
+Returns:
+
+- Parameters out of range: `0xff`.
+- Success: `0x00`.
+
+##### streaming_setting
+
+Function/Command code: `0x02`.
+
+Parameters:
+
+- Enter streaming mode `0x00`. This command stops all animations, clears the
+  screen, and switches the device to streaming mode.
+- Leave streaming mode `0x01`. This command resumes all normal operations.
+
+Returns:
+
+- Parameters out of range: `0xff`.
+- Success: `0x00`.
+
+##### stream_bitmap
+
+Function/Command code: `0x03`.
+
+Parameters:
+
+- Array of bitmap in word (16-bit). Each word represents a column. The
+  least-significant bit of each word represents the top pixel of each column.
+  The length of the word array must be less than the number of columns on the
+  screen; otherwise, any overflow pixels will be ignored.
+
+Returns:
+
+- Parameters out of range or streaming not enabled: `0xff`.
+- Success: `0x00`.
+
+##### ble_setting
+
+Function/Command code: `0x04`.
+
+Parameters:
+
+- Disable always-on BLE: `[0x00, 0x00]`. Note: Call the save_cfg command to save
+  this configuration.
+- Enable always-on BLE: `[0x00, 0x01]`. Note: Call the save_cfg command to save
+  this configuration.
+- Change BLE device name: `[0x01, "This is name"]`. The name must be less than
+  or equal to 20 characters. Note: Call the save_cfg command to save this
+  configuration.
+
+Returns:
+
+- Parameters out of range: `0xff`.
+- Success: `0x00`.
+
+##### flash_splash_screen
+
+Function/Command code: `0x05`.
+
+Parameters:
+
+- The first byte describes the width of the image.
+- The second byte describes the height of the image.
+- The third byte describes the frame height that will be displayed on the
+  screen.
+- The rest are pixel content in `xbm` format.
+
+Returns:
+
+- Parameters out of range: `0xff`.
+- The width is larger than the maximum allowed (currently 48 pixels): `0xff`.
+- The height is larger than the maximum allowed (currently 44 pixels): `0xfe`.
+- Message length is not matched (currently 44 pixels): `0xfd`.
+- Missing pixel contents: `0xfc`.
+- Success: `0x00`.
+
+##### save_cfg
+
+Save configs to flash.
+
+Command code: `0x06`.
+
+Returns:
+
+- Parameters out of range: `0xff`.
+- Flash writing error: `0x01`.
+- Success: `0x00`.
+
+##### load_fallback_cfg
+
+Load firmware default configuration. Note: call the [save_cfg](#save_cfg)
+command to save this config.
+
+Function/Command code: `0x07`.
+
+Returns:
+
+- Success: `0x00`.
--- a/assets/ng-protocol.svg
+++ b/assets/ng-protocol.svg
@ -0,0 +1,223 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   width="93.96756mm"
+   height="37.041668mm"
+   viewBox="0 0 93.967559 37.041667"
+   version="1.1"
+   id="svg1"
+   inkscape:version="1.4 (e7c3feb100, 2024-10-09)"
+   sodipodi:docname="ng-protocol.svg"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:svg="http://www.w3.org/2000/svg">
+  <sodipodi:namedview
+     id="namedview1"
+     pagecolor="#ffffff"
+     bordercolor="#000000"
+     borderopacity="0.25"
+     inkscape:showpageshadow="2"
+     inkscape:pageopacity="0.0"
+     inkscape:pagecheckerboard="0"
+     inkscape:deskcolor="#d1d1d1"
+     inkscape:document-units="mm"
+     inkscape:zoom="1.9276399"
+     inkscape:cx="197.91041"
+     inkscape:cy="18.675688"
+     inkscape:window-width="1920"
+     inkscape:window-height="1060"
+     inkscape:window-x="0"
+     inkscape:window-y="0"
+     inkscape:window-maximized="1"
+     inkscape:current-layer="layer1" />
+  <defs
+     id="defs1">
+    <marker
+       style="overflow:visible"
+       id="marker12"
+       refX="0"
+       refY="0"
+       orient="auto-start-reverse"
+       inkscape:stockid="Wide arrow"
+       markerWidth="1"
+       markerHeight="1"
+       viewBox="0 0 1 1"
+       inkscape:isstock="true"
+       inkscape:collect="always"
+       preserveAspectRatio="xMidYMid">
+      <path
+         style="fill:none;stroke:context-stroke;stroke-width:1;stroke-linecap:butt"
+         d="M 3,-3 0,0 3,3"
+         transform="rotate(180,0.125,0)"
+         sodipodi:nodetypes="ccc"
+         id="path12" />
+    </marker>
+    <marker
+       style="overflow:visible"
+       id="ArrowWide"
+       refX="0"
+       refY="0"
+       orient="auto-start-reverse"
+       inkscape:stockid="Wide arrow"
+       markerWidth="1"
+       markerHeight="1"
+       viewBox="0 0 1 1"
+       inkscape:isstock="true"
+       inkscape:collect="always"
+       preserveAspectRatio="xMidYMid">
+      <path
+         style="fill:none;stroke:context-stroke;stroke-width:1;stroke-linecap:butt"
+         d="M 3,-3 0,0 3,3"
+         transform="rotate(180,0.125,0)"
+         sodipodi:nodetypes="ccc"
+         id="path1" />
+    </marker>
+  </defs>
+  <g
+     inkscape:label="Layer 1"
+     inkscape:groupmode="layer"
+     id="layer1"
+     transform="translate(-4.0441577,-4.1136454)">
+    <rect
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.264582;stroke-opacity:1"
+       id="rect1"
+       width="18.955954"
+       height="18.955954"
+       x="6.7991281"
+       y="4.2459364" />
+    <text
+       xml:space="preserve"
+       style="font-size:4.80828px;line-height:1;font-family:'Noto Sans';-inkscape-font-specification:'Noto Sans';text-align:start;text-decoration-color:#000000;writing-mode:lr-tb;direction:ltr;text-anchor:start;fill:#0000ff;fill-opacity:1;stroke:none;stroke-width:0.1;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:5;stroke-opacity:1;paint-order:stroke markers fill"
+       x="9.8561001"
+       y="13.041375"
+       id="text1"><tspan
+         sodipodi:role="line"
+         id="tspan1"
+         style="font-size:4.80828px;fill:#0000ff;fill-opacity:1;stroke:none;stroke-width:0.1"
+         x="9.8561001"
+         y="13.041375" /></text>
+    <text
+       xml:space="preserve"
+       style="font-size:4.80828px;line-height:1;font-family:'Noto Sans';-inkscape-font-specification:'Noto Sans';text-align:start;text-decoration-color:#000000;writing-mode:lr-tb;direction:ltr;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.1;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:5;stroke-opacity:1;paint-order:stroke markers fill"
+       x="8.3145914"
+       y="15.152661"
+       id="text2"><tspan
+         sodipodi:role="line"
+         id="tspan2"
+         style="font-size:4.80828px;fill:#000000;fill-opacity:1;stroke-width:0.1"
+         x="8.3145914"
+         y="15.152661">byte 0</tspan></text>
+    <rect
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.264582;stroke-opacity:1"
+       id="rect2"
+       width="18.955954"
+       height="18.955954"
+       x="26.375713"
+       y="4.2459364" />
+    <rect
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.264582;stroke-opacity:1"
+       id="rect3"
+       width="18.955954"
+       height="18.955954"
+       x="59.346848"
+       y="4.2459364" />
+    <rect
+       style="fill:none;fill-rule:evenodd;stroke:#000000;stroke-width:0.264582;stroke-opacity:1"
+       id="rect4"
+       width="18.955954"
+       height="18.955954"
+       x="78.92347"
+       y="4.2459364" />
+    <text
+       xml:space="preserve"
+       style="font-size:4.80828px;line-height:1;font-family:'Noto Sans';-inkscape-font-specification:'Noto Sans';text-align:start;text-decoration-color:#000000;writing-mode:lr-tb;direction:ltr;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.1;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:5;stroke-opacity:1;paint-order:stroke markers fill"
+       x="50.130188"
+       y="14.017906"
+       id="text4"><tspan
+         sodipodi:role="line"
+         id="tspan4"
+         style="font-size:4.80828px;stroke-width:0.1"
+         x="50.130188"
+         y="14.017906">...</tspan></text>
+    <text
+       xml:space="preserve"
+       style="font-size:4.80828px;line-height:1;font-family:'Noto Sans';-inkscape-font-specification:'Noto Sans';text-align:start;text-decoration-color:#000000;writing-mode:lr-tb;direction:ltr;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.1;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:5;stroke-opacity:1;paint-order:stroke markers fill"
+       x="27.891172"
+       y="15.152661"
+       id="text5"><tspan
+         sodipodi:role="line"
+         id="tspan5"
+         style="font-size:4.80828px;fill:#000000;fill-opacity:1;stroke-width:0.1"
+         x="27.891172"
+         y="15.152661">byte 1</tspan></text>
+    <text
+       xml:space="preserve"
+       style="font-size:4.80828px;line-height:1;font-family:'Noto Sans';-inkscape-font-specification:'Noto Sans';text-align:start;text-decoration-color:#000000;writing-mode:lr-tb;direction:ltr;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.1;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:5;stroke-opacity:1;paint-order:stroke markers fill"
+       x="69.297417"
+       y="13.091969"
+       id="text6"><tspan
+         sodipodi:role="line"
+         id="tspan6"
+         style="font-size:4.80828px;text-align:center;text-anchor:middle;fill:#000000;fill-opacity:1;stroke-width:0.1"
+         x="69.297417"
+         y="13.091969">byte </tspan><tspan
+         sodipodi:role="line"
+         style="font-size:4.80828px;text-align:center;text-anchor:middle;fill:#000000;fill-opacity:1;stroke-width:0.1"
+         x="69.297417"
+         y="17.900249"
+         id="tspan7">n-2</tspan></text>
+    <text
+       xml:space="preserve"
+       style="font-size:4.80828px;line-height:1;font-family:'Noto Sans';-inkscape-font-specification:'Noto Sans';text-align:start;text-decoration-color:#000000;writing-mode:lr-tb;direction:ltr;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.1;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:5;stroke-opacity:1;paint-order:stroke markers fill"
+       x="89.904373"
+       y="13.091969"
+       id="text9"><tspan
+         sodipodi:role="line"
+         id="tspan8"
+         style="font-size:4.80828px;text-align:center;text-anchor:middle;fill:#000000;fill-opacity:1;stroke-width:0.1"
+         x="89.904373"
+         y="13.091969">byte </tspan><tspan
+         sodipodi:role="line"
+         style="font-size:4.80828px;text-align:center;text-anchor:middle;fill:#000000;fill-opacity:1;stroke-width:0.1"
+         x="89.904373"
+         y="17.900249"
+         id="tspan9">n-1</tspan></text>
+    <text
+       xml:space="preserve"
+       style="font-size:4.80828px;line-height:1;font-family:'Noto Sans';-inkscape-font-specification:'Noto Sans';text-align:center;text-decoration-color:#000000;writing-mode:lr-tb;direction:ltr;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.1;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:5;stroke-opacity:1;paint-order:stroke markers fill"
+       x="16.348543"
+       y="36.29895"
+       id="text10"><tspan
+         sodipodi:role="line"
+         style="font-size:4.80828px;stroke-width:0.1"
+         x="16.348543"
+         y="36.29895"
+         id="tspan13">functions/</tspan><tspan
+         sodipodi:role="line"
+         style="font-size:4.80828px;stroke-width:0.1"
+         x="16.348543"
+         y="41.107231"
+         id="tspan14">commands</tspan></text>
+    <text
+       xml:space="preserve"
+       style="font-size:4.80828px;line-height:1;font-family:'Noto Sans';-inkscape-font-specification:'Noto Sans';text-align:center;text-decoration-color:#000000;writing-mode:lr-tb;direction:ltr;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.1;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:5;stroke-opacity:1;paint-order:stroke markers fill"
+       x="62.139526"
+       y="36.29895"
+       id="text11"><tspan
+         sodipodi:role="line"
+         id="tspan11"
+         style="font-size:4.80828px;stroke-width:0.1"
+         x="62.139526"
+         y="36.29895">parameters</tspan></text>
+    <path
+       style="fill:none;stroke:#000000;stroke-width:0.264999;stroke-linecap:butt;stroke-linejoin:miter;stroke-dasharray:none;stroke-opacity:1;marker-start:url(#ArrowWide);marker-end:url(#marker12)"
+       d="M 6.5415415,28.501193 H 26.012669"
+       id="path11" />
+    <path
+       style="fill:none;stroke:#000000;stroke-width:0.264999;stroke-linecap:butt;stroke-linejoin:miter;stroke-dasharray:none;stroke-opacity:1;marker-start:url(#ArrowWide);marker-end:url(#marker12)"
+       d="M 27.020996,28.501193 H 97.632395"
+       id="path13" />
+  </g>
+</svg>