Skip to content

Commit c4b0f10

Browse files
timhodsontimhodson
committed
Add an OSC server to write to the badge
1 parent 366258c commit c4b0f10

File tree

6 files changed

+938
-1
lines changed

6 files changed

+938
-1
lines changed

‎font-editor/similey.json‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
{
2+
"width": 48,
3+
"height": 12,
4+
"segments": 8,
5+
"bytes": [
6+
0,
7+
0,
8+
0,
9+
0,
10+
0,
11+
0,
12+
0,
13+
0,
14+
0,
15+
0,
16+
0,
17+
0,
18+
0,
19+
0,
20+
0,
21+
0,
22+
0,
23+
15,
24+
31,
25+
140,
26+
63,
27+
62,
28+
206,
29+
126,
30+
119,
31+
103,
32+
231,
33+
231,
34+
187,
35+
255,
36+
255,
37+
187,
38+
255,
39+
255,
40+
187,
41+
255,
42+
231,
43+
187,
44+
231,
45+
247,
46+
118,
47+
126,
48+
126,
49+
236,
50+
63,
51+
63,
52+
200,
53+
31,
54+
15,
55+
0,
56+
0,
57+
0,
58+
0,
59+
0,
60+
0,
61+
0,
62+
0,
63+
0,
64+
0,
65+
0,
66+
0,
67+
0,
68+
0,
69+
0,
70+
0,
71+
0,
72+
0,
73+
0,
74+
0,
75+
0,
76+
0,
77+
0
78+
]
79+
}

‎osc_server/README.md‎

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
# OSC Server for BLE LED Badge
2+
3+
An OSC (Open Sound Control) server that provides a network interface for controlling BLE LED badges. This enables integration with creative tools like TouchDesigner, Max/MSP, Processing, Pure Data, and more.
4+
5+
## Installation
6+
7+
The OSC server is part of the main project. Install dependencies using Poetry:
8+
9+
```bash
10+
cd /path/to/ble-led-badge
11+
poetry install
12+
```
13+
14+
## Usage
15+
16+
### Starting the Server
17+
18+
```bash
19+
# Using poetry run
20+
poetry run badge-osc-server
21+
22+
# Or with custom ports
23+
poetry run badge-osc-server --port 9000 --reply-port 9001
24+
25+
# All options
26+
poetry run badge-osc-server --host 0.0.0.0 --port 9000 --reply-host 127.0.0.1 --reply-port 9001 --verbose
27+
```
28+
29+
### Command Line Options
30+
31+
| Option | Default | Description |
32+
|--------|---------|-------------|
33+
| `--host`, `-H` | `0.0.0.0` | Host to listen on for OSC messages |
34+
| `--port`, `-p` | `9000` | Port to listen on for OSC messages |
35+
| `--reply-host`, `-r` | `127.0.0.1` | Host to send reply messages to |
36+
| `--reply-port`, `-R` | `9001` | Port to send reply messages to |
37+
| `--verbose`, `-v` | - | Enable verbose logging |
38+
39+
## OSC Commands
40+
41+
### Connection Management
42+
43+
| Address | Arguments | Description |
44+
|---------|-----------|-------------|
45+
| `/badge/connect` | `<address>` | Connect to a badge by BLE address (e.g., `AA:BB:CC:DD:EE:FF`) |
46+
| `/badge/disconnect` | - | Disconnect from current badge |
47+
| `/badge/status` | - | Request connection status |
48+
49+
### Content Commands
50+
51+
| Address | Arguments | Description |
52+
|---------|-----------|-------------|
53+
| `/badge/text` | `<string>` | Send text to the badge display |
54+
| `/badge/image` | `<byte0> <byte1> ...` | Upload raw image bytes (9 bytes per segment) |
55+
| `/badge/image/json` | `<json_string>` | Upload image from JSON (font-editor export format) |
56+
57+
### Display Settings
58+
59+
| Address | Arguments | Description |
60+
|---------|-----------|-------------|
61+
| `/badge/brightness` | `<0-255>` | Set brightness level |
62+
| `/badge/speed` | `<0-255>` | Set scroll speed |
63+
| `/badge/scroll` | `<mode>` | Set scroll mode: `static`, `left`, `right`, `up`, `down`, `snow` |
64+
65+
### Power and Animation
66+
67+
| Address | Arguments | Description |
68+
|---------|-----------|-------------|
69+
| `/badge/on` | - | Turn display on |
70+
| `/badge/off` | - | Turn display off |
71+
| `/badge/animation` | `<1-8>` | Play built-in animation |
72+
73+
## Reply Messages
74+
75+
The server sends reply messages to the configured reply host/port:
76+
77+
| Address | Arguments | Description |
78+
|---------|-----------|-------------|
79+
| `/badge/connected` | `<address>` | Successfully connected to badge |
80+
| `/badge/disconnected` | `"OK"` | Successfully disconnected |
81+
| `/badge/status` | `<status>` `[address]` | Connection status |
82+
| `/badge/error` | `<message>` | Error message |
83+
| `/badge/notification` | `<text>` | Notification from badge |
84+
| `/badge/text/ok` | `<text>` | Text sent successfully |
85+
| `/badge/image/ok` | `<bytes>` | Image uploaded successfully |
86+
| `/badge/brightness/ok` | `<value>` | Brightness set successfully |
87+
| `/badge/speed/ok` | `<value>` | Speed set successfully |
88+
| `/badge/scroll/ok` | `<mode>` | Scroll mode set successfully |
89+
| `/badge/on/ok` | `"OK"` | Display turned on |
90+
| `/badge/off/ok` | `"OK"` | Display turned off |
91+
| `/badge/animation/ok` | `<id>` | Animation started |
92+
93+
## Examples
94+
95+
### Python (python-osc)
96+
97+
```python
98+
from pythonosc import udp_client
99+
100+
client = udp_client.SimpleUDPClient("127.0.0.1", 9000)
101+
102+
# Connect to badge
103+
client.send_message("/badge/connect", "AA:BB:CC:DD:EE:FF")
104+
105+
# Send text
106+
client.send_message("/badge/text", "Hello World!")
107+
108+
# Set brightness
109+
client.send_message("/badge/brightness", 200)
110+
111+
# Set scroll mode
112+
client.send_message("/badge/scroll", "left")
113+
```
114+
115+
### TouchDesigner
116+
117+
Use a `OSC Out` CHOP or DAT to send messages:
118+
119+
```
120+
Address: /badge/text
121+
Arguments: "Hello from TD!"
122+
```
123+
124+
### Max/MSP
125+
126+
```
127+
[udpsend 127.0.0.1 9000]
128+
|
129+
[prepend /badge/text]
130+
|
131+
[message "Hello from Max!"]
132+
```
133+
134+
### Processing
135+
136+
```java
137+
import oscP5.*;
138+
import netP5.*;
139+
140+
OscP5 oscP5;
141+
NetAddress badgeServer;
142+
143+
void setup() {
144+
oscP5 = new OscP5(this, 9001); // Listen for replies
145+
badgeServer = new NetAddress("127.0.0.1", 9000);
146+
}
147+
148+
void sendText(String text) {
149+
OscMessage msg = new OscMessage("/badge/text");
150+
msg.add(text);
151+
oscP5.send(msg, badgeServer);
152+
}
153+
```
154+
155+
## Image Data Format
156+
157+
The `/badge/image/json` command accepts JSON in the format exported by the font-editor:
158+
159+
```json
160+
{
161+
"width": 48,
162+
"height": 12,
163+
"segments": 8,
164+
"bytes": [0, 1, 2, 3, ...]
165+
}
166+
```
167+
168+
Each segment is 9 bytes, encoding a 6x12 pixel block. See the main project documentation for details on the byte encoding format.
169+
170+
## Architecture
171+
172+
The OSC server maintains a persistent Bluetooth connection to the badge, allowing rapid command execution without reconnection overhead. This makes it suitable for real-time applications.
173+
174+
```
175+
┌─────────────────┐ OSC ┌─────────────────┐ BLE ┌─────────┐
176+
│ Creative Tool │ ──────────▶ │ OSC Server │ ─────────▶ │ Badge │
177+
│ (TD, Max, etc) │ ◀────────── │ (this script) │ ◀───────── │ │
178+
└─────────────────┘ Replies └─────────────────┘ Notify └─────────┘
179+
```
180+
181+
## Future Enhancements
182+
183+
- Multi-badge support (connect to multiple badges simultaneously)
184+
- HTTP/WebSocket interface
185+
- MIDI input support
186+
- Auto-reconnection on disconnect

‎osc_server/__init__.py‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
"""
2+
OSC Server for BLE LED Badge control.
3+
4+
Provides an OSC interface for controlling LED badges over Bluetooth,
5+
enabling integration with various creative tools like TouchDesigner,
6+
Max/MSP, Processing, and more.
7+
"""
8+
9+
from .server import BadgeOSCServer
10+
11+
__all__ = ["BadgeOSCServer"]

0 commit comments

Comments
 (0)