Skip to content

Commit a11e06b

Browse files
authored
Merge pull request #166 from ericdahl-dev/lc6000-display-tools
tools/lc6000-display: jog-display research tools (#165)
2 parents 77e34cf + 126b10d commit a11e06b

7 files changed

Lines changed: 692 additions & 0 deletions

File tree

‎tools/lc6000-display/README.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# LC6000 jog display tools
2+
3+
Research tools for the LC6000 PRIME's jog-wheel display, which is driven over its "WD" MIDI port (#121). They're
4+
the groundwork for showing the active deck on the jog (#165). They're not part of the app, and none of them run in
5+
CI.
6+
7+
The protocol, with what each message does and what the unit answers, is written up on #121 (see its recipe comment).
8+
In short:
9+
10+
1. **Host hello** to the Controller port: `F0 00 02 0B 7F 10 60 00 04 04 01 01 00 F7`, then `F0 00 20 7F 01 F7`.
11+
Without it, the unit refuses uploads (ack `06`).
12+
2. **Upload** to WD:
13+
- `90 01 00`
14+
- `0A 01 00 06 0D`
15+
- `0C`: the PNG's size
16+
- `0D`: chunks of a 21-bit offset plus the data as an MSB-first 7-bit bitstream
17+
- `0E`: slot `01`, then the PNG's 32-bit byte-sum as 8 nibbles
18+
3. **Commit:** wait for the `01 10 0F 00 01 00` acks, then send `7E 00 06 01` and `10`.
19+
4. **Show:** `0A 01 00 01 0D`, which displays image index 01.
20+
21+
The display shows uploads **rotated 180°**, so images are sent pre-rotated. Uploads move about 3.1 KB/s, so they're
22+
for what changes rarely, not real-time readouts.
23+
24+
## Files
25+
26+
| File | What it does |
27+
|---|---|
28+
| `jogbuild.py` | PNG in, upload out. `png` re-encodes a 198×198 PNG for the unit (rotated 180°, in the layout the unit has accepted). `plan` writes a `jogseq` plan. `selftest` runs round trips with no device. |
29+
| `jogseq.swift` | Sends a plan to the unit once, listening on both ports. `dry` checks a plan and prints it. |
30+
| `sysex_decode.py` | Reads a MIDI Monitor capture (`.mmon`, text export or `.syx`), groups the SysEx, and rebuilds image uploads as PNG files (`--dump DIR`). |
31+
| `mmon_list.py` | Lists every message in a `.mmon`, with timing and "To"/"From" endpoints. |
32+
| `images/deck-ring.png` | Our app icon at 198×198, as a source image, not rotated. |
33+
| `images/f-test.png` | An upright F with a red square top-right. The orientation test: the unit shows it upside down with the square lower-left. |
34+
35+
## Use
36+
37+
```sh
38+
cd tools/lc6000-display
39+
python3 -I jogbuild.py selftest
40+
python3 -I jogbuild.py plan images/deck-ring.png /tmp/deck-ring.plan
41+
swiftc -O -swift-version 5 jogseq.swift -o /tmp/jogseq
42+
/tmp/jogseq dry /tmp/deck-ring.plan # checks and prints; sends nothing
43+
/tmp/jogseq send /tmp/deck-ring.plan # sends once: see the rules below
44+
```
45+
46+
A plan is one message per line: `<delay ms> WD|CTL <hex bytes>`, or `<delay ms> ACKS <count> <timeout ms>`, which
47+
waits for that many accepted acks and stops the run on a refusal. Lines starting with `#` are comments.
48+
49+
`jogseq` sends only what the protocol needs:
50+
- **WD:** the `00 02 0B 7F 10` messages, the identity request, and `90 01 00`.
51+
- **Controller:** Serato SysEx, the `cmd 60` host message, LED note-ons, and the identity request.
52+
53+
It also refuses to send if the port names are ambiguous.
54+
55+
## Rules
56+
57+
- **Get an OK before sending to the hardware.** A stray note on WD resets the display (#143), and the host hello
58+
changes the unit's mode.
59+
- **No third-party data in this folder:** no other app's images, and no capture files. Test images are our own.
60+
- **What was verified, and what's still a guess:**
61+
- Verified: these exact images were uploaded and shown on hardware. Uploads were accepted (acks `00`), with the
62+
hello first.
63+
- Not yet tested: `plan` writes the protocol's minimal sequence. The verified runs also replayed a DJ app's LED
64+
paint and identity requests on the Controller port, and four `0A` messages before the last.
65+
- Trimming those is the bisect planned in #165.
17.5 KB
Loading
2.09 KB
Loading

‎tools/lc6000-display/jogbuild.py‎

Lines changed: 194 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,194 @@
1+
#!/usr/bin/env python3
2+
"""Builds the LC6000 jog-display upload (#121, #165): a 198x198 PNG in, a jogseq plan out.
3+
4+
python3 -I jogbuild.py png <in.png> <out.png> re-encode for the unit: rotated 180°, the PNG layout it accepts
5+
python3 -I jogbuild.py plan <in.png> <out.plan> the full host + upload + commit + show plan for jogseq
6+
python3 -I jogbuild.py selftest encoder round trips, no device
7+
8+
The recipe, as verified on hardware (see #121's recipe comment):
9+
CTL F0 00 02 0B 7F 10 60 00 04 04 01 01 00 F7, then F0 00 20 7F 01 F7 host hello (without it: ack 06)
10+
WD 90 01 00, 0A 01 00 06 0D, 0C <size>, 0D <offset + 7-bit data>…, 0E <slot + byte-sum>
11+
WD wait for the 01 10 0F 00 01 00 acks (06 = refused), then 7E 00 06 01, 10 (commit; unit answers 01 10 10)
12+
WD 0A … 01 00 01 0D show image index 01
13+
Frame: F0 00 02 0B <target 7F> 10 <cmd> <len, 14-bit> <payload> F7.
14+
"""
15+
import struct
16+
import sys
17+
import zlib
18+
19+
HEAD = [0x00, 0x02, 0x0B, 0x7F, 0x10]
20+
SIZE = 198
21+
CHUNK = 14332 # the most image bytes whose 7-bit form (n*8//7 + 1) plus a 3-byte offset fits a 14-bit length
22+
23+
HOST_HELLO = [
24+
[0xF0, 0x00, 0x02, 0x0B, 0x7F, 0x10, 0x60, 0x00, 0x04, 0x04, 0x01, 0x01, 0x00, 0xF7],
25+
[0xF0, 0x00, 0x20, 0x7F, 0x01, 0xF7],
26+
]
27+
HOST_GOODBYE = [0xF0, 0x00, 0x20, 0x7F, 0x02, 0xF7]
28+
SHOW_BLANK = [0x01, 0x00, 0x06, 0x0D] # 0A before an upload: image index 06
29+
SHOW_INDEX_1 = [0x01, 0x00, 0x01, 0x0D] # 0A after the commit: image index 01, the upload
30+
31+
32+
def frame(cmd, payload):
33+
n = len(payload)
34+
return [0xF0, *HEAD, cmd, n >> 7, n & 0x7F, *payload, 0xF7]
35+
36+
37+
def u21(value):
38+
return [(value >> 14) & 0x7F, (value >> 7) & 0x7F, value & 0x7F]
39+
40+
41+
def bits7(data):
42+
"""MSB-first bitstream into 7-bit bytes, zero-padded: len(data)*8//7 + 1 bytes."""
43+
out, acc, nbits = [], 0, 0
44+
for byte in data:
45+
acc, nbits = (acc << 8) | byte, nbits + 8
46+
while nbits >= 7:
47+
nbits -= 7
48+
out.append((acc >> nbits) & 0x7F)
49+
out.append((acc << (7 - nbits)) & 0x7F if nbits else 0)
50+
return out
51+
52+
53+
def commit_0e(png, slot=1):
54+
"""0E: the slot, then the PNG's 32-bit byte-sum as 8 nibbles, most significant first."""
55+
total = sum(png) & 0xFFFFFFFF
56+
return [slot] + [(total >> shift) & 0x0F for shift in range(28, -4, -4)]
57+
58+
59+
def upload(png, slot=1):
60+
"""0A (index 06), 0C size, 0D chunks, 0E checksum, 10 commit."""
61+
msgs = [frame(0x0A, SHOW_BLANK), frame(0x0C, u21(len(png)))]
62+
for offset in range(0, len(png), CHUNK):
63+
msgs.append(frame(0x0D, u21(offset) + bits7(png[offset:offset + CHUNK])))
64+
msgs += [frame(0x0E, commit_0e(png, slot)), frame(0x10, [])]
65+
return msgs
66+
67+
68+
# PNG in and out. Only 8-bit RGB and RGBA, not interlaced: what this tool makes and reads.
69+
70+
def chunks(png):
71+
pos = 8
72+
while pos < len(png):
73+
n, kind = struct.unpack('>I4s', png[pos:pos + 8])
74+
yield kind, png[pos + 8:pos + 8 + n]
75+
pos += 12 + n
76+
77+
78+
def decode_rgba(png):
79+
"""Rows of RGBA bytes from an 8-bit RGB or RGBA PNG."""
80+
header = dict(chunks(png))[b'IHDR']
81+
width, height, depth, kind, _, _, interlace = struct.unpack('>IIBBBBB', header)
82+
if depth != 8 or kind not in (2, 6) or interlace:
83+
raise SystemExit(f"need an 8-bit RGB or RGBA PNG, not interlaced (got depth {depth}, type {kind})")
84+
bpp = 4 if kind == 6 else 3
85+
raw = zlib.decompress(b''.join(body for k, body in chunks(png) if k == b'IDAT'))
86+
stride, rows, prev = width * bpp, [], bytearray(width * bpp)
87+
for y in range(height):
88+
kind_ = raw[y * (stride + 1)]
89+
line = bytearray(raw[y * (stride + 1) + 1:(y + 1) * (stride + 1)])
90+
for i in range(stride):
91+
a = line[i - bpp] if i >= bpp else 0
92+
b = prev[i]
93+
c = prev[i - bpp] if i >= bpp else 0
94+
if kind_ == 1:
95+
line[i] = (line[i] + a) & 255
96+
elif kind_ == 2:
97+
line[i] = (line[i] + b) & 255
98+
elif kind_ == 3:
99+
line[i] = (line[i] + ((a + b) >> 1)) & 255
100+
elif kind_ == 4:
101+
p = a + b - c
102+
pa, pb, pc = abs(p - a), abs(p - b), abs(p - c)
103+
line[i] = (line[i] + (a if pa <= pb and pa <= pc else b if pb <= pc else c)) & 255
104+
prev = line
105+
rows.append(bytes(line) if bpp == 4 else b''.join(bytes(line[i:i + 3]) + b'\xff' for i in range(0, stride, 3)))
106+
return width, height, rows
107+
108+
109+
def rotate180(rows):
110+
"""The unit shows uploads rotated 180° (#121's F test), so they're sent pre-rotated."""
111+
return [b''.join(row[i:i + 4] for i in range(len(row) - 4, -4, -4)) for row in reversed(rows)]
112+
113+
114+
def _chunk(kind, body):
115+
return struct.pack('>I', len(body)) + kind + body + struct.pack('>I', zlib.crc32(kind + body))
116+
117+
118+
def exif_dimensions(width, height):
119+
"""A minimal eXIf: a big-endian TIFF header, an Exif IFD pointer, and PixelX/YDimension (as on the tested files)."""
120+
tiff = b'MM\x00\x2a' + struct.pack('>I', 8)
121+
ifd0 = struct.pack('>H', 1) + struct.pack('>HHII', 0x8769, 4, 1, 26) + struct.pack('>I', 0)
122+
exif = struct.pack('>H', 2) + struct.pack('>HHII', 0xA002, 4, 1, width) + struct.pack('>HHII', 0xA003, 4, 1, height)
123+
return tiff + ifd0 + exif + struct.pack('>I', 0)
124+
125+
126+
def encode(width, height, rows):
127+
"""RGBA PNG laid out as the unit has accepted: IHDR, sRGB, eXIf, IDAT in 16384-byte pieces of a
128+
several-block zlib stream (level 1), IEND. Row filter 0."""
129+
raw = b''.join(b'\x00' + row for row in rows)
130+
compressor = zlib.compressobj(1, zlib.DEFLATED, 15, 1)
131+
data = compressor.compress(raw) + compressor.flush()
132+
png = b'\x89PNG\r\n\x1a\n' + _chunk(b'IHDR', struct.pack('>IIBBBBB', width, height, 8, 6, 0, 0, 0))
133+
png += _chunk(b'sRGB', b'\x00') + _chunk(b'eXIf', exif_dimensions(width, height))
134+
for i in range(0, len(data), 16384):
135+
png += _chunk(b'IDAT', data[i:i + 16384])
136+
return png + _chunk(b'IEND', b'')
137+
138+
139+
def for_unit(png):
140+
width, height, rows = decode_rgba(png)
141+
if (width, height) != (SIZE, SIZE):
142+
raise SystemExit(f"the jog display takes {SIZE}x{SIZE}, not {width}x{height}")
143+
return encode(width, height, rotate180(rows))
144+
145+
146+
def hexs(msg):
147+
return ' '.join(f'{b:02X}' for b in msg)
148+
149+
150+
def plan(png):
151+
"""A jogseq plan: hello, upload, wait for the acks, commit, show index 01."""
152+
msgs = upload(png)
153+
body, commit = msgs[:-1], msgs[-1]
154+
lines = ["# LC6000 jog upload (#121): host hello, upload, acks, commit, show index 01"]
155+
lines += [f"0 CTL {hexs(m)}" for m in HOST_HELLO]
156+
lines.append("0 WD 90 01 00")
157+
lines += [f"{8 if i == 1 else 0} WD {hexs(m)}" for i, m in enumerate(body)]
158+
# Each upload message but one is acked: the count seen on hardware.
159+
lines.append(f"0 ACKS {len(body) - 1} 20000")
160+
lines.append(f"0 WD {hexs([0xF0, 0x7E, 0x00, 0x06, 0x01, 0xF7])}")
161+
lines.append(f"10 WD {hexs(commit)}")
162+
lines.append(f"500 WD {hexs(frame(0x0A, SHOW_INDEX_1))}")
163+
return '\n'.join(lines) + '\n'
164+
165+
166+
def selftest():
167+
import os
168+
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
169+
import sysex_decode
170+
rows = [b''.join(bytes([x, y, (x * y) & 255, 255]) for x in range(SIZE)) for y in range(SIZE)]
171+
png = encode(SIZE, SIZE, rows)
172+
assert decode_rgba(png)[2] == rows, "PNG round trip"
173+
assert rotate180(rotate180(rows)) == rows, "two half turns are none"
174+
assert rotate180(rows)[0][:4] == rows[-1][-4:], "the last pixel comes first"
175+
assert sysex_decode.unbits(bits7(png))[:len(png)] == png, "7-bit bitstream round trip"
176+
messages = [("?", m) for m in upload(png)]
177+
assert sysex_decode.lc6000_images(messages) == [png], "upload rebuilds to the same PNG"
178+
assert commit_0e(bytes([1, 2, 3])) == [1, 0, 0, 0, 0, 0, 0, 0, 6], "byte-sum as nibbles"
179+
assert commit_0e(bytes([0xFF] * 0x3AEE))[1:] == [(0x3AEE * 0xFF >> s) & 0xF for s in range(28, -4, -4)]
180+
print("selftest ok:", len(png), "byte PNG,", len(messages), "messages")
181+
182+
183+
if __name__ == '__main__':
184+
if len(sys.argv) == 2 and sys.argv[1] == 'selftest':
185+
selftest()
186+
elif len(sys.argv) == 4 and sys.argv[1] in ('png', 'plan'):
187+
source = open(sys.argv[2], 'rb').read()
188+
if sys.argv[1] == 'png':
189+
open(sys.argv[3], 'wb').write(for_unit(source))
190+
else:
191+
open(sys.argv[3], 'w').write(plan(for_unit(source)))
192+
else:
193+
print(__doc__)
194+
sys.exit(2)

0 commit comments

Comments
 (0)