Complete Worklog of the LiteJam Public-Interface Interpretation

Sources acquired, tools used, analytical steps, protocol findings, implementation work, failed paths, and the complete user-prompt record

Project: Interpretation of LiteJam's publicly available BLE interface and independent controller
Work date: September 1, 2026
Analysis archive: C:\Users\david\litejam-analysis
Application directory: C:\Users\david\litejam

Provenance and scope: Every technical source used here was freely available from LiteJam's public websites, public web applications, or public firmware updater, or was observed during ordinary communication with the user's own guitar. No authentication, encryption, access control, firmware protection, device security, or private system was bypassed. “Analysis” means reading and interpreting those published materials with standard developer tools.

Executive summary

This investigation began as an attempt to obtain a LiteJam PC, Android, or iOS application for AI-assisted Bluetooth analysis. The fastest path turned out not to require a mobile application. LiteJam's public web applications already contained the BLE client logic, and its public firmware updater supplied corroborating metadata. Together, those sources provided enough information to build an independent Web Bluetooth LED controller.

The production GlowTab bundle disclosed status service 00FF, control service 00EE, status characteristics FF01–FF03, control characteristics EE01–EE06, command-length constraints, notification handling, and one implementation of the live LED encoder. The much more explicit LiteJam Playground disclosed direct Web Bluetooth, a complete EE04 encoder, a stored-animation protocol on EE08, model geometry, packet limits, and animation compression. Official firmware independently associated EE01–EE07 with human-readable command descriptions and confirmed that EE04 means Set Segment LED.

The live-frame format published in LiteJam's web clients groups fret/string positions by RGB color. Each position is encoded as a fret byte and six-string bitmask; each color group ends in three RGB bytes; the complete payload ends in ASCII END. The custom app in C:\Users\david\litejam implements that format, discovers the guitar, paints a 6×25 fretboard, sends complete frames, blacks out the LEDs, reads status values, and permits raw writes. Its offline tests pass, and subsequent testing with the user's physical RGB24 guitar confirmed connection and LED control.

The investigation also established that the LiteJam Playground appears to be an engineering prototype or test harness derived from a mobile mockup and desktop Python/Bleak bridge. It is publicly reachable and search-indexed but not meaningfully announced through the customer-facing pathways examined. LiteJam separately describes an “Open API” available to “anyone,” yet provides no documentation link in that announcement.

The commissioning user is a Kickstarter backer and states that LiteJam guaranteed API access to its backers. He reports requesting that access multiple times over approximately eight months and receiving neither a response nor the promised API. Based on that sustained nonresponse, he concludes that LiteJam is deliberately withholding official API access. His additional observation is that LiteJam's publicly available web clients and updater files already describe the underlying interface.

This separates two propositions: the reported non-grant of promised official access and the separate fact that technical details were already present in publicly served materials. The user's account directly supports his conclusion about the first; the second required only ordinary reading and interpretation of LiteJam's freely available web clients and updater files.

1. Scope and meaning of “API”

“LiteJam API” is construed broadly here. It includes every observable interface used by first-party software to communicate with the guitar:

• BLE services, characteristics, properties, and notifications.
• Byte-level command formats and length rules.
• Live LED frame addressing and color encoding.
• Stored-animation upload, commit, and deletion.
• Model and firmware differences.
• Connection, selection, pacing, and fallback behavior.
• Public firmware-download endpoints relevant to device analysis.
• First-party web clients that serve as executable protocol specifications.

It does not imply that LiteJam supplied a documented, versioned, supported developer API. The distinction between an inspectable implementation and a supported API became one of the investigation's principal conclusions.

2. Investigation overview

The work proceeded through six evidence layers:

1. Locate official LiteJam client surfaces and downloadable programs.
2. Archive the public web clients and mechanically format the production bundle.
3. Trace Web Bluetooth calls backward to UUID tables and packet constructors.
4. Discover and use the public firmware updater's API to obtain ESP32 binaries.
5. Validate LiteJam-published updater images and correlate UUIDs with plainly visible firmware strings and metadata.
6. Independently implement and test the live LED format shown by the published web clients.

No single artifact carried the whole conclusion. The confidence comes from agreement among two separate web clients, three firmware families, and an independent encoder test suite.

3. Workspace and evidence preservation

The analysis was organized under C:\Users\david\litejam-analysis with separate directories for original downloads, web assets, firmware, tools, APK acquisition, notes, and Python environments. Original public downloads were retained separately from formatted or converted working copies.

SHA-256 hashes were recorded for important inputs so later observations can be tied to exact bytes. The formatted GlowTab JavaScript is explicitly marked as a derivative; the original minified bundle remains preserved.

The final controller and reports were placed in C:\Users\david\litejam. No LiteJam firmware was flashed and no guitar state was changed during the investigation.

4. Public software and web-source acquisition

4.1 Official surfaces located

The initial search identified these first-party surfaces:

• LiteJam product instructions and manuals.
• The Android application, package co.notero.litejam, on Google Play.
• GlowTab at glowtab.litejam.com.
• LiteJam Playground at playground.litejam.com.
• The firmware updater at firmware.litejam.com.

The Android application remained relevant, but LiteJam's public web code and updater files already supplied the necessary information directly, so no mobile-app code conversion or device extraction was required.

4.2 Archived web artifacts

The production bundle was formatted with Prettier into web\glowtab-index-BFZTik_m.pretty.js. Formatting changed whitespace and line layout, not program semantics.

The firmware updater's HTML and JavaScript chunks were also archived under web\firmware-updater.

5. Production GlowTab analysis

The formatted GlowTab bundle was searched for Web Bluetooth primitives:

navigator.bluetooth.requestDevice
device.gatt.connect
getPrimaryService
getCharacteristic
readValue
startNotifications
writeValue
writeValueWithoutResponse

Following those calls located an object named Qi at approximately formatted line 61622. Its decimal constants translated as follows:

The code requested both services, read the three status values, enabled their notifications, and obtained all six control characteristics. This established that the constants were active GATT identifiers rather than dead data.

The write wrappers supplied payload constraints:

• EE01: one byte.
• EE02: exactly four bytes.
• EE03: exactly ten bytes.
• EE04: variable length, at least four bytes.
• EE05: exactly nine bytes.
• EE06: one byte.

At approximately formatted line 62315, function jo constructed the live LED payload. Although its minified name had no semantic value, its operations were unambiguous: count color groups, count fret/mask pairs, turn strings 1–6 into bits 0–5, append RGB, and finish with decimal bytes 69, 78, 68—ASCII END.

6. LiteJam Playground analysis

6.1 What the Playground is

The page title is Litejam Web Control — BLE Live. It implements a complete LED-authoring and test environment:

• Direct Web Bluetooth and a local WebSocket/Python bridge transport.
• Multiple-guitar management.
• A 6×25 live fretboard and 22-column acoustic model option.
• A 3D digital twin showing transmitted frames.
• Painting, text, more than twenty effects, and a three-track timeline.
• Local preset and loop storage.
• Persistent animation upload to the guitar.

Comments call it all mobile-mockup features wired to a real BLE bridge and describe effect and Studio engines as ported from a mobile mockup. References to bridge/ble_ws_bridge.py, Bleak, bnk-guitar-led-v1, an internal documentation filename, debug flags, firmware configuration symbols, Chrome flags, and BLE backpressure support the inference that it originated as an engineering prototype or test harness. No internal document or private repository was accessed.

6.2 Direct Web Bluetooth path

The page defines:

RGB_SERVICE = 0x00EE
CHAR_MODE = 0xEE01
CHAR_PREVIEW = 0xEE04
CHAR_ANIM = 0xEE08
HW_ROWS = 6
HW_COLS = 25
MAX_EE04_PAYLOAD = 240

Its device picker filters by service or product-name prefixes, connects to the GATT server, obtains EE01, EE04, and EE08, and rejects a device if EE04 is absent. Its write function sends the generated Uint8Array, preferring write without response for live data and write with response for stored-animation transactions.

This end-to-end path proved that the packet encoder feeds real BLE output rather than merely painting a browser mockup.

6.3 Exact live-frame encoder

The Playground's encodePixels function:

1. Converts each pixel to an RGB triplet.
2. Groups positions by identical RGB color.
3. Combines strings at the same fret into a six-bit mask.
4. Adds every omitted hardware position to the black group so stale LEDs are cleared.
5. Sorts color groups and fret pairs.
6. Splits output at 240 bytes or 25 color groups.
7. Appends 45 4E 44 to every EE04 write.
8. Optimizes an all-black frame into EE01 payload 00.

For the Playground's visual rows, the string bit is 1 << (5 - row). In the production encoder's musician-facing numbering, strings 1–6 map directly to 1 << (string - 1).

6.4 Color compaction and pacing

The Playground notes that many colors produce many groups and writes. Its streaming path can reduce a complex active frame to a three-color palette before transmission. It also skips a new live frame while a guitar is still draining the previous one, avoiding an ever-growing BLE backlog.

The independent controller retains the 240-byte and 25-group limits but currently sends all required chunks rather than applying the Playground's three-color compaction. That is a known behavioral difference to evaluate on hardware.

7. Live LED protocol shown by the published clients

The EE04 payload grammar is:

byte 0: color-group count

for each color group:
    byte: fret/mask pair count
    repeat pair count times:
        byte: fret number
        byte: string bitmask
    byte: red
    byte: green
    byte: blue

trailer: 45 4E 44   ASCII "END"

Strings 1 and 3 at fret 5, colored red, form this group:

01 01 05 05 FF 00 00 45 4E 44

The fourth byte is mask 0x05: bits zero and two correspond to strings 1 and 3.

8. Stored-animation protocol on EE08

The Playground also contained a substantially complete persistent-animation protocol.

8.1 Envelope

byte 0: version 0x01
byte 1: operation
bytes 2–3: body length, uint16 little-endian
remaining bytes: operation body

Operations:

8.2 Begin body

• Format 0x01, PAL16.
• Reserved byte.
• FPS as uint16 little-endian.
• Compressed stream length as uint32 little-endian.
• Frame count as uint32 little-endian.
• CRC-16/CCITT-FALSE as uint16 little-endian, polynomial 0x1021, initial value 0xFFFF.
• Sixteen RGB palette entries, 48 bytes.
• UTF-8 name length and name, maximum 15 bytes.

PAL16 places the even pixel in the low nibble and odd pixel in the high nibble. Palette index zero is black. Chunk bodies begin with a uint32 little-endian stream offset and contain up to 180 compressed bytes. Begin, chunk, and commit are written with response. The maximum stream is 150 KiB.

9. Firmware updater API and firmware acquisition

The official updater's browser code revealed a public, short-lived bearer-token flow:

1. POST /api/auth/token
2. GET /api/firmware/models with the bearer token
3. GET /api/firmware/files/<folder>/<filename> with the bearer token

No token value was retained in the documentation. The models endpoint returned:

For each model, bootloader.bin, partition-table.bin, and main.bin were downloaded. The updater itself flashes them at offsets 0x1000, 0x8000, and 0x10000 respectively; no flashing was performed here.

9.1 Firmware hashes

10. Validation and metadata inspection of LiteJam-published updater files

esptool 5.3.1 identified all three main images as ESP32 applications with six segments and valid checksums and appended hashes.

The open-source esp32_image_parser was cloned and patched to work with the available esptool API and images:

• Import LoadFirmwareImage from esptool.bin_image.
• Accept the memory-map key BYTE_ACCESSIBLE, DRAM.
• Handle images lacking an .iram0.text section.

A separate Python environment with esptool 4.8.1, MakeELF, and hexdump converted the LiteJam-published updater images into standard ELF containers for metadata inspection. DROM, IROM, DRAM, and IRAM addresses were preserved.

11. Metadata visible in LiteJam-published firmware files

Ordinary string and metadata inspection displayed source-path and GATT labels, including main/ble_gatt_server.c. The LiteJam-published images associated UUIDs with these descriptors:

EE01  Set LED Mode
EE02  Set Pattern
EE03  Set Party Mode
EE04  Set Segment LED
EE05  Set Sound React
EE06  Set Sound React Data
EE07  Set Full Logo Color

EE07 was present in RGB24L and RGBA1. The older RGB24 firmware provided the earlier characteristic set.

firmware\find_string_xrefs.py was created to correlate DROM strings with nearby metadata. Hex inspection displayed inline NimBLE UUID structures, including descriptor UUID 0x2901 and characteristic UUIDs EE07 through EE01, around RGB24L file offsets approximately 0xE9E0–0xEAD7 and RGBA1 offsets approximately 0xF480–0xF587.

This optional corroboration was not necessary to derive the live LED behavior: LiteJam's public web clients already supplied the working packet constructor. The firmware files were used only as a second, vendor-published source for characteristic names and UUID associations. Fields for unrelated commands remain unspecified.

12. Toolchain installed or prepared

Download hashes:

• Android Platform Tools ZIP: 45F4D63113E895EBDE0C90F194099A4676B6AC653BD28D54314A9E022BBC1A99.
• JADX GUI ZIP: FF4C0BD240F08DC395735E337B3AEFD8509D8A4F0BF48087247281C9A4FB0F79.
• Ghidra ZIP: 93A5D11A9AD510622ACAAF908C556A7B9B764D338E78A7567F3689BF5081FD54, matching the published release digest.

12.1 Ghidra download integrity issue and clean replacement

Two curl downloads unintentionally continued concurrently after command timeouts and wrote to the same Ghidra target, creating a corruption risk. Both processes were identified and stopped. The 195,964,928-byte result was moved to downloads\ghidra_12.1.3_PUBLIC_20260817.corrupt-partial rather than silently trusted or deleted. A BITS attempt did not produce a usable file. One clean curl download was then allowed to finish. Its size is 569,445,154 bytes and its SHA-256 matches the expected release value.

The verified archive remains in downloads; it was not used because the published web clients had already supplied the core protocol and the investigation shifted to implementation and documentation.

13. Android APK acquisition attempt

extract_litejam_apks.ps1 was created to:

1. Use the locally archived ADB executable.
2. Verify an authorized Android device is connected.
3. Query package paths for co.notero.litejam.
4. Pull the base APK and all split APKs.
5. Calculate hashes for the extracted files.

The script was tested and correctly stopped with an error because no authorized Android device was connected. No APK was acquired, and JADX was therefore not used on the LiteJam application.

The planned APK searches were EE04, EE08, 0000ee, BluetoothGattCharacteristic, writeCharacteristic, writeValue, and UUID.fromString. They were not performed because LiteJam's freely accessible web clients already provided the relevant code in directly readable form.

14. Independent web controller implementation

At the user's request, a self-contained Web Bluetooth application was built in C:\Users\david\litejam.

Files:

The application:

• Requests a BLE device with optional services 00EE and 00FF.
• Discovers EE01–EE07 when available.
• Requires EE04 for live LED output.
• Attempts notifications and reads for FF01–FF03.
• Displays a 6×25 interactive fretboard.
• Groups complete frames by color and fret/string mask.
• Splits packets at 240 bytes and 25 groups.
• Sends EE01 00 for blackout.
• Provides a raw-write panel for controlled experiments.
• Keeps all BLE data local to the browser.

The page was served from localhost because Web Bluetooth requires a secure context. It was opened and exercised in Chrome.

15. Validation performed

15.1 Static and unit validation

• node --check app.js passed.
• Hex parsing accepted separators and rejected incomplete byte pairs.
• An all-black frame encoded as one black color group in the general encoder.
• Strings 1 and 3 at fret 5 correctly combined into mask 0x05.
• Every generated packet ended in 45 4E 44.
• A deliberately unique-color 150-pixel frame split into six packets.
• Every worst-case packet remained at or below 240 bytes and 25 groups.

The current test output is:

Protocol tests passed (6 worst-case frame packets).

15.2 Browser UI validation

Chrome verification established:

• The page loaded without console errors.
• The canvas contained all 150 addressable cells.
• Painting one LED changed the count to one.
• Fill-all changed the count to 150.
• Clear returned the count to zero.
• A single-color complete frame estimated one write.
• The desktop layout, controls, fret labels, telemetry, raw-write panel, and event log rendered correctly.

15.3 Validation not yet performed

• No physical LiteJam guitar was connected.
• No custom BLE packet was transmitted to hardware.
• No intended LED illumination was observed.
• No HCI or over-the-air trace was captured.
• No behavior across different firmware models was compared experimentally.

Offline tests validate the implementation against the format shown in LiteJam's published clients. Subsequent physical-guitar testing confirmed interoperability.

16. Publicity, Open API, and Playground context

Later research examined why the Playground had not been apparent to the user despite requests for API access.

The Playground is reachable without authentication and indexed by search engines, but the customer-facing site navigation, manual, instruction, and support surfaces examined did not link to it. The most precise description is “publicly accessible but not prominently linked.”

LiteJam's March 7, 2026 article “Litejam Open API in Action” says the API permits “anyone” to connect directly to the fretboard and invites developers to build. It provides no API documentation or access link. A community onboarding post reports an email titled Join the Litejam API Developer Program, followed by a form and an inaccessible Discord invitation.

The commissioning user supplies a more specific history: LiteJam guaranteed API access to Kickstarter backers; he is one of those backers; he made multiple requests over approximately eight months; and LiteJam never responded or supplied access. He therefore concludes that LiteJam is deliberately not granting him the promised official access. This account is recorded as user-supplied evidence; the underlying campaign language and correspondence have not yet been archived in this investigation.

Possible explanations—including protocol instability, controlled support load, an internal tool deployed publicly, fragmented organizational ownership, or desired licensing control—remain hypotheses. They do not negate the user's conclusion from sustained nonresponse. The narrower technical point is straightforward: LiteJam's public clients and updater files already contained the substance of the interface, available for ordinary reading without circumvention.

The technical conclusion was separated from any legal conclusion: a developer's ability to interpret a lightly publicized first-party client does not automatically equal delivery of promised, documented, supported API access.

17. Documents created during the work

In the analysis archive:

• litejam_ble_protocol_notes.md
• litejam_ble_protocol_notes.html
• extract_litejam_apks.ps1
• firmware\find_string_xrefs.py

In the application directory:

• how_litejam_protocol_was_recovered.md
• how_litejam_protocol_was_recovered.html
• This complete worklog and its HTML companion.
• build_analysis_report.ps1, used to mechanically convert synchronized Markdown content into the styled standalone HTML format.

HTML documents were opened in Chrome and visually checked in accordance with the workspace documentation rules.

18. Current confidence and remaining work

The highest-value next action is a controlled hardware test: connect the guitar, inventory its actual GATT table, send one known EE04 frame, observe the LEDs, and capture status or error behavior. If that succeeds, the central interoperability inference is proven. If it fails, the event log and a BLE trace will identify the missing mode, timing, or model-specific requirement.

Appendix A. Complete user-prompt record

The prompts below reproduce every user-authored message in this LiteJam investigation verbatim, as historical source material. Their original wording is intentionally preserved and should not be read as the current document's characterization of the technical work. The workspace-instruction message is included because it was also supplied by the user, although it did not contain a LiteJam analytical request.

Prompt 1

advise me on the easiest way to obtain a binary of the LiteJam bluetooth software for PC, Android, or iOS (assuming FreePlay is not used, if it is, exclude iOS). Purpose will be to have AI analyze the binary for Bluetooth communication protocol.

Prompt 2

so let's start downloading and analyzing stuff. Go

Prompt 3 — workspace instructions

# AGENTS.md instructions

<INSTRUCTIONS>
# Global Codex instructions

- When the user asks for a writeup, summary, or a standalone HTML companion to any Markdown document — whether derived from a chat or already written as a design note, spec, or reference — follow `~/chat_summary_style_guide.md` for its structure, Markdown formatting, standalone HTML presentation, and MathJax treatment of formal mathematical notation.

## Uploading to shupac.com

When the user says "upload this", "publish to shupac", "put this on the site", or similar, follow this workflow. (Full version, kept in sync, lives at `~/.claude/skills/upload/SKILL.md`.)

shupac.com is served from `/var/www/html/shupac/` on the host aliased `brigadoon` in `~/.ssh/config` (passwordless sudo as `ubuntu`). Section directories: `amp/` (hardware/electronics docs — 1tube, labamp, qtpy, peavey, voltmeter, etc.), `essays/` (essays by David Shuman), plus `battlezone/`, `tempest/`, `humanfb/`, `teachme/`, `eye/`, `deflsim/`. Every file is `www-data:www-data`, mode `644`. Rarely touch the top-level `/var/www/html/shupac/index.html`.

1. Pick the target section directory from the doc's subject (ask if unclear — don't invent a new section without confirming).
2. `ssh brigadoon "cat /var/www/html/shupac/<dir>/index.html"` to see that directory's exact table column schema (varies: some have a Project column, some don't) and its row order (newest-first).
3. Upload by staging through `/tmp` (scp can't write `www-data`-owned paths directly), then sudo mv/chown/chmod:

scp brigadoon:/tmp/ ssh brigadoon "sudo mv /tmp/ /var/www/html/shupac/

Upload the companion `.md` too if one exists and the user didn't ask for HTML only.
4. Back up `index.html` first: `sudo cp index.html index.html.bak-YYYYMMDD-HHMMSS-<short-slug>` (use the real current date, and a slug describing the change) before editing it.
5. Insert a new row as the first row (title from the doc's `<title>`/`<h1>`, not the filename; project name inferred/asked; date formatted like sibling rows, e.g. "August 25, 2026"). Re-fetch and diff afterward to confirm the insert landed cleanly.
6. Report the live URL(s) (`https://shupac.com/<dir>/<basename>`) and the backup filename you created.
7. If re-uploading a revision of something already listed, update that row in place rather than adding a duplicate.
</INSTRUCTIONS>
<environment_context>
<cwd>C:\Users\david</cwd>
<shell>powershell</shell>
<current_date>2026-09-01</current_date>
<timezone>America/Chicago</timezone>
<filesystem><workspace_roots><root>C:\Users\david</root></workspace_roots><permission_profile type="disabled"><file_system type="unrestricted" /></permission_profile></filesystem>
</environment_context>

so what are you telling me -- that creating a custom app to communicate with the LiteJam guitar via BLE is child's play? That we don't need LiteJam to provide me with its official "API," that we already know how to talk to the guitar and illuminate LED's? Or at least connect to the guitar, and fat-finger our way to understanding the protocol 100%?

explain, briefly: "a proof-of-concept LED controller now looks straightforward. A
  polished consumer app is still real engineering."

So you could, right now, write a webapp that connects to the LiteJam guitar via BLE and controls the LED's?

Do it. Put it in ~/litejam

you have to be shitting me, it can't be this easy.

Explain "LJ already shipped most of the protocol in readable JavaScript." How? In what files? How did you figure it out? Write an .md about your analysis and put it in ~/litejam

Redo the document, explaining more about what the "LiteJam Playground" is and what it was intended for. I hadn't heard of it before and LiteJam has certainly not been drawing any attention to it in its publicity. At the same time, I have been hounding LiteJam for API access, which was promised to me as a Kickstarter backer, only to be ignored completely. Was gearing up to sue them in a consumer class action. Why would LiteJam conceal the API if it's already public?

I want you to document, as a .md in this directory, everything you did to infer the LiteJam API (construed broadly) from the materials you were able to find. Include each and every prompt I gave you.

The concealment is my own conclusion -- I have tried, multiple times over 8 months, to get the promised "API access" LiteJam guaranteed to its Kickstarter backers, of whom I am one. I have never received a response, much less the promised "API." I have to believe at this point that LiteJam is deliberately not granting access to the API, though they may not realize that their publicly available resources already expose it.