Programming a lampOS lamp
A lampOS lamp is a desk lamp with a body (head and arm), a light ring, a
voice, eyes and touch. A computer the owner paired with it can ask it to
move, light, speak and look, and hear what it notices, over one protocol
(lamp-control, WebSocket over TLS on port 7731). Three ways in, the same
protocol underneath:
| you write |
use |
install |
| Python |
lampos |
pip install "git+https://github.com/autonomous-ai/lampOS@lamp-voice#subdirectory=lampOS/sdk/python" |
| JavaScript (Node 20.11+) |
lampos |
git clone --branch lamp-voice https://github.com/autonomous-ai/lampOS.git, then in your project npm install --install-links <the clone>/lampOS/sdk/js (a copy, so Node finds its ws) |
| an AI agent's tools |
lamp-mcp |
both in one command: pip install "lampos @ git+https://github.com/autonomous-ai/lampOS@lamp-voice#subdirectory=lampOS/sdk/python" "lamp-mcp @ git+https://github.com/autonomous-ai/lampOS@lamp-voice#subdirectory=lampOS/sdk/mcp", then claude mcp add lamp -- lamp-mcp (or any MCP client) |
The packages aren't on PyPI or npm yet (pip install lampos and
npm install lampos fail); install from the repository as above.
lamp-mcp needs lampos in the same pip command, or pip looks for it on
PyPI and fails.
An MCP client usually starts lamp-mcp without your shell's environment, so
LAMPOS_HOME is lost, the pairing isn't found, and the client shows only
"Connection closed". Give the folder lamp pair used: --home PATH in the
client's config (claude mcp add lamp -- lamp-mcp --home ~/.config/lampos), or
python -m lamp_mcp from the venv's python when the client can't find lamp-mcp
on its PATH. An unpaired start says in one stderr line which folder it looked in.
On a customer lamp (stable 11450) five things are missing: play and a
look at a face or name, a motion's end (wait=True returns when the lamp takes
it), limp and pose, mDNS (pair with --host), and local event times (at is
UTC). Skill push, joints for roll, shoulder and elbow (while the lamp
stands) and a head tap as a touch event are in 11450. Read
references/gotchas.md
before promising any of them.
Start without a lamp
Always build and test against the fake lamp first: it speaks the real
protocol and answers as lamp-control does.
lamp fake --everything # a fake lamp, paired with this computer; leave it running
python my_program.py # in another terminal, same LAMPOS_HOME
--everything answers every op; without it the fake answers as a customer
lamp does: look and joints at yaw and pitch taken, play and joints
at roll, shoulder or elbow refused in lamp-control's words. It takes a skill
push, which a customer lamp refuses. In tests, use lampos.testing.FakeLamp (JS:
FakeLamp from lampos/testing): see references/testing.md.
Pair with a real lamp
The owner makes a code in the lamp's app: an 8-digit code, the
certificate's pin (64 hex), and the grants this computer gets. Ask the
owner for the grants your program needs, by what it does:
| your program |
grants |
| lights the ring |
light |
| speaks or plays sounds |
speak |
| moves (gestures, feelings, looks, moves) |
body (a feeling needs light too) |
| knows who's there, follows a hand |
look |
| hears a phrase or its name |
hear |
| hears music, laughter, the door, footsteps |
sound |
| puts skills of its own on the lamp |
skills |
| reads the room's air, the lamp's own computer |
air, device |
| sees pictures |
camera |
| hears the room's sound (20 ms blocks of samples) |
microphone |
A grant added later needs a new pairing code: the owner can't widen a pairing. Then, on the computer:
lamp pair CODE --pin PIN --host lamp-xxxx.local --name my-laptop
lamp hello # connects, says this computer's grants
python scripts/check_pairing.py # this skill's check: grants, limits, what each refusal means
The pairing (a key and the lamp's pin) is kept in ~/.config/lampos, or
LAMPOS_HOME.
A pairing holding a grant a lamp's build doesn't know stops an older
lamp-control at its start (fixed from #4525 on). If you pair with a new
grant on a lamp that tries a newer build, revoke that pairing before the
lamp goes back to an older build.
Reaching the lamp from off its network
By default the lamp answers only computers on its own network. Two ways from
elsewhere:
- The lamp's remote opt-in, on a lamp whose lamp-control has it (
--remote, or
LAMP_CONTROL_REMOTE=on): off by default, and the owner must switch it
on on the lamp. Then any address that reaches port 7731 is admitted
(still only paired computers). Camera and microphone never leave the
lamp's own network, whatever this says.
- An ssh tunnel to the lamp, which needs the lamp's ssh: the owner's to
give, and nothing else to switch on.
ssh -N -L 7731:127.0.0.1:7731 orangepi@lamp-xxxx.local, then --host 127.0.0.1 for lamp pair and
Lamp.connect(host="127.0.0.1"). Through a tunnel the lamp sees
127.0.0.1, which is its own network (lamp-control counts loopback as
local), so a tunnel carries every grant, the camera and microphone
included. Never use or suggest a tunnel to get the camera or microphone
off the lamp's network: that is the owner's decision when they give ssh,
not a way around item 1.
The mental model (read before writing code)
- Grants: the owner ticks what this computer may do:
body (move),
light, speak, look (presence, hands, face/hand targets), hear
(phrases, the name), sound (sound classes), skills (push skills),
air (the air sensor), device (the lamp's own computer), camera
(pictures), microphone (the room's sound).
A call without its grant is refused no_grant. Grants are read at hello.
- Leases: moving the body (
look, move, play, joints) needs a
body lease. Hold one with async with lamp.lease("body"): (JS
lamp.withLease(['body'], async (lease) => …)). The lamp can take it back
(a conversation, a hand on the head, private): you get a lease event
with state: lost and the why. gesture and express need no lease.
- Who wins: the person always. A conversation, a touch, the app, private
or paused mode come first, and the lamp tells you (
lease, lamp.changed).
Behind the person, one computer at a time holds the body.
- Limits: by default the rates are off: hello's
limits says
"rates": "off", and only refused actions (20 a second, then the
connection closes) and phrase changes (6 a minute) are bounded. A lamp run
with --rates default sends a window for each kind. The body bounds every
move whatever the rate. Read lamp.limits with .get(): an older lamp or
fake leaves keys out.
- Closing ends what you asked for: when your program's last connection
closes, the lamp gives back its light and stops its waiting lines at once.
A script that lights the ring and exits shows it for a moment only: stay
connected for as long as it should show.
- A new motion cuts the one playing short: a gesture, move or
feeling's move asked while another plays replaces it, eased out from where
the body is. While the person is using the lamp, the body drops the new
one ("the person is using the lamp"). Stable 10824 and older refused it
busy with retry_ms instead: wait and ask again.
- Quiet hours: a lamp setting (
limits.quiet_hours, off by default,
or a {from, to} window the lamp sets). say and sound are refused quiet_hours then; the
light still works.
- Be a living thing, not a machine: react to something that happened, let
a move finish, don't loop gestures. A lamp switching feelings every 3 s
reads as twitchy.
The calls
Every call, side by side in Python, JavaScript and MCP:
references/api.md. The shape, in Python:
import asyncio
from lampos import Lamp
from lampos.errors import LampError
async def main():
async with await Lamp.connect() as lamp: # the paired lamp
await lamp.light("green", 3, 10_000, pattern="breathe")
try:
await lamp.say("The build passed.")
except LampError as refused: # quiet_hours, private, busy...
print(refused.code, refused.why)
await lamp.on("person.arrived", lambda event: print("someone came", event))
await lamp.wait_closed()
asyncio.run(main())
Every refusal is a LampError with code and why, the lamp's own words;
references/errors.md has what to do about each code.
Reading the lamp
- Events come by edge, when something changes:
person.arrived,
person.left, person.facing, person.stood_up, hand, phrase.heard,
name.heard, sound.heard, touch, button, lamp.changed, time;
lease and done come unasked. Subscribe with lamp.on(event, handler).
- State with
lamp.get("presence", "light", "mood", "lamp"); the
body's joints, bounds and caps with lamp.body_info() (JS
lamp.bodyInfo(), the body grant).
- What each carries, and its grant: references/api.md.
- Never readable, by any grant but
camera and microphone: pictures,
audio. By any grant: transcripts, face prints, names. A hand's or face's
place is a share of the picture.
- The camera (the
camera grant): a snapshot, or a stream of
frames; never while private, never off the lamp's own network:
references/camera.md.
- The microphone (the
microphone grant): Python
await lamp.microphone_stream(True), JS lamp.microphoneStream(true),
sends microphone.audio events, each a 20 ms block (16 kHz mono S16LE,
640 bytes in data), until microphone_stream(False) /
microphoneStream(false), stop, or microphone.ended; off unless the
owner switched it on, never while private or with someone else in view,
never off the lamp's own network:
references/api.md. body.state and
routed joints come next; this skill gains them as they land.
Patterns
Ready to adapt, each in Python and JS: react to presence, a CI light, a
pomodoro, an agent's progress shown on the lamp, a chat alert, a program
that runs for days, and a web app on the SDK:
references/patterns.md.
Gotchas we hit
Read references/gotchas.md before your first real
run: what a customer lamp lacks today, breathe and pulse levels, one pulse a
minute, busy while a motion plays, the light's shows, the restart mute.
Debugging
LAMPOS_LOG=debug prints every frame to and from the lamp on stderr, secrets
redacted. The lamp's side and the journal recipe:
references/debugging.md.
1---2name: lampos-sdk3description: Program a lampOS lamp from a developer's own computer with the lampos SDK (Python or JavaScript) or the lamp-mcp server. Use when someone asks to program the lamp, control a lampOS lamp, make the lamp react to something (presence, a build, a timer, an agent's progress, a message), write a lamp script or skill, pair a computer with a lamp, or test lamp code against the fake lamp.4metadata:5 source: https://skillmd.com/skills/autonomous-ai/lampos-sdk6---78# Programming a lampOS lamp910A lampOS lamp is a desk lamp with a body (head and arm), a light ring, a11voice, eyes and touch. A computer the owner paired with it can ask it to12move, light, speak and look, and hear what it notices, over one protocol13(`lamp-control`, WebSocket over TLS on port 7731). Three ways in, the same14protocol underneath:1516| you write | use | install |17|---|---|---|18| Python | `lampos` | `pip install "git+https://github.com/autonomous-ai/lampOS@lamp-voice#subdirectory=lampOS/sdk/python"` |19| JavaScript (Node 20.11+) | `lampos` | `git clone --branch lamp-voice https://github.com/autonomous-ai/lampOS.git`, then in your project `npm install --install-links <the clone>/lampOS/sdk/js` (a copy, so Node finds its `ws`) |20| an AI agent's tools | `lamp-mcp` | both in one command: `pip install "lampos @ git+https://github.com/autonomous-ai/lampOS@lamp-voice#subdirectory=lampOS/sdk/python" "lamp-mcp @ git+https://github.com/autonomous-ai/lampOS@lamp-voice#subdirectory=lampOS/sdk/mcp"`, then `claude mcp add lamp -- lamp-mcp` (or any MCP client) |2122The packages aren't on PyPI or npm yet (`pip install lampos` and23`npm install lampos` fail); install from the repository as above.24`lamp-mcp` needs `lampos` in the same `pip` command, or pip looks for it on25PyPI and fails.2627**An MCP client usually starts `lamp-mcp` without your shell's environment**, so28`LAMPOS_HOME` is lost, the pairing isn't found, and the client shows only29"Connection closed". Give the folder `lamp pair` used: `--home PATH` in the30client's config (`claude mcp add lamp -- lamp-mcp --home ~/.config/lampos`), or31`python -m lamp_mcp` from the venv's python when the client can't find `lamp-mcp`32on its PATH. An unpaired start says in one stderr line which folder it looked in.3334**On a customer lamp (stable 11450)** five things are missing: `play` and a35look at a face or name, a motion's end (`wait=True` returns when the lamp takes36it), limp and pose, mDNS (pair with `--host`), and local event times (`at` is37UTC). Skill push, `joints` for `roll`, `shoulder` and `elbow` (while the lamp38stands) and a head tap as a `touch` event are in 11450. Read39[references/gotchas.md](references/gotchas.md#on-a-customer-lamp-today-stable-11450)40before promising any of them.4142## Start without a lamp4344Always build and test against the **fake lamp** first: it speaks the real45protocol and answers as lamp-control does.4647```sh48lamp fake --everything # a fake lamp, paired with this computer; leave it running49python my_program.py # in another terminal, same LAMPOS_HOME50```5152`--everything` answers every op; without it the fake answers as a customer53lamp does: `look` and `joints` at yaw and pitch taken, `play` and `joints`54at roll, shoulder or elbow refused in lamp-control's words. It takes a skill55push, which a customer lamp refuses. In tests, use `lampos.testing.FakeLamp` (JS:56`FakeLamp` from `lampos/testing`): see [references/testing.md](references/testing.md).5758## Pair with a real lamp5960The owner makes a code in the lamp's app: an 8-digit code, the61certificate's pin (64 hex), and the grants this computer gets. Ask the62owner for the grants your program needs, by what it does:6364| your program | grants |65|---|---|66| lights the ring | `light` |67| speaks or plays sounds | `speak` |68| moves (gestures, feelings, looks, moves) | `body` (a feeling needs `light` too) |69| knows who's there, follows a hand | `look` |70| hears a phrase or its name | `hear` |71| hears music, laughter, the door, footsteps | `sound` |72| puts skills of its own on the lamp | `skills` |73| reads the room's air, the lamp's own computer | `air`, `device` |74| sees pictures | `camera` |75| hears the room's sound (20 ms blocks of samples) | `microphone` |7677**A grant added later needs a new pairing code:** the owner can't widen a pairing. Then, on the computer:7879```sh80lamp pair CODE --pin PIN --host lamp-xxxx.local --name my-laptop81lamp hello # connects, says this computer's grants82python scripts/check_pairing.py # this skill's check: grants, limits, what each refusal means83```8485The pairing (a key and the lamp's pin) is kept in `~/.config/lampos`, or86`LAMPOS_HOME`.8788**A pairing holding a grant a lamp's build doesn't know** stops an older89lamp-control at its start (fixed from #4525 on). If you pair with a new90grant on a lamp that tries a newer build, revoke that pairing before the91lamp goes back to an older build.9293## Reaching the lamp from off its network9495By default the lamp answers only computers on its own network. Two ways from96elsewhere:97981. **The lamp's remote opt-in**, on a lamp whose lamp-control has it (`--remote`, or99 `LAMP_CONTROL_REMOTE=on`): off by default, and **the owner must switch it100 on** on the lamp. Then any address that reaches port 7731 is admitted101 (still only paired computers). Camera and microphone never leave the102 lamp's own network, whatever this says.1032. **An ssh tunnel to the lamp**, which needs the lamp's ssh: the owner's to104 give, and nothing else to switch on. `ssh -N -L 7731:127.0.0.1:7731105 orangepi@lamp-xxxx.local`, then `--host 127.0.0.1` for `lamp pair` and106 `Lamp.connect(host="127.0.0.1")`. Through a tunnel the lamp sees107 `127.0.0.1`, which is its own network (lamp-control counts loopback as108 local), so **a tunnel carries every grant, the camera and microphone109 included.** Never use or suggest a tunnel to get the camera or microphone110 off the lamp's network: that is the owner's decision when they give ssh,111 not a way around item 1.112113## The mental model (read before writing code)114115- **Grants:** the owner ticks what this computer may do: `body` (move),116 `light`, `speak`, `look` (presence, hands, face/hand targets), `hear`117 (phrases, the name), `sound` (sound classes), `skills` (push skills),118 `air` (the air sensor), `device` (the lamp's own computer), `camera`119 (pictures), `microphone` (the room's sound).120 A call without its grant is refused `no_grant`. Grants are read at hello.121- **Leases:** moving the body (`look`, `move`, `play`, `joints`) needs a122 `body` lease. Hold one with `async with lamp.lease("body"):` (JS123 `lamp.withLease(['body'], async (lease) => …)`). The lamp can take it back124 (a conversation, a hand on the head, private): you get a `lease` event125 with `state: lost` and the why. `gesture` and `express` need no lease.126- **Who wins:** the person always. A conversation, a touch, the app, private127 or paused mode come first, and the lamp tells you (`lease`, `lamp.changed`).128 Behind the person, one computer at a time holds the body.129- **Limits:** by default the rates are off: hello's `limits` says130 `"rates": "off"`, and only refused actions (20 a second, then the131 connection closes) and phrase changes (6 a minute) are bounded. A lamp run132 with `--rates default` sends a window for each kind. The body bounds every133 move whatever the rate. Read `lamp.limits` with `.get()`: an older lamp or134 fake leaves keys out.135- **Closing ends what you asked for:** when your program's last connection136 closes, the lamp gives back its light and stops its waiting lines at once.137 A script that lights the ring and exits shows it for a moment only: stay138 connected for as long as it should show.139- **A new motion cuts the one playing short:** a gesture, move or140 feeling's move asked while another plays replaces it, eased out from where141 the body is. While the person is using the lamp, the body drops the new142 one ("the person is using the lamp"). Stable 10824 and older refused it143 `busy` with `retry_ms` instead: wait and ask again.144- **Quiet hours:** a lamp setting (`limits.quiet_hours`, `off` by default,145 or a `{from, to}` window the lamp sets). `say` and `sound` are refused `quiet_hours` then; the146 light still works.147- **Be a living thing, not a machine:** react to something that happened, let148 a move finish, don't loop gestures. A lamp switching feelings every 3 s149 reads as twitchy.150151## The calls152153Every call, side by side in Python, JavaScript and MCP:154[references/api.md](references/api.md). The shape, in Python:155156```python157import asyncio158from lampos import Lamp159from lampos.errors import LampError160161async def main():162 async with await Lamp.connect() as lamp: # the paired lamp163 await lamp.light("green", 3, 10_000, pattern="breathe")164 try:165 await lamp.say("The build passed.")166 except LampError as refused: # quiet_hours, private, busy...167 print(refused.code, refused.why)168 await lamp.on("person.arrived", lambda event: print("someone came", event))169 await lamp.wait_closed()170171asyncio.run(main())172```173174Every refusal is a `LampError` with `code` and `why`, the lamp's own words;175[references/errors.md](references/errors.md) has what to do about each code.176177## Reading the lamp178179- **Events** come by edge, when something changes: `person.arrived`,180 `person.left`, `person.facing`, `person.stood_up`, `hand`, `phrase.heard`,181 `name.heard`, `sound.heard`, `touch`, `button`, `lamp.changed`, `time`;182 `lease` and `done` come unasked. Subscribe with `lamp.on(event, handler)`.183- **State** with `lamp.get("presence", "light", "mood", "lamp")`; the184 body's joints, bounds and caps with `lamp.body_info()` (JS185 `lamp.bodyInfo()`, the `body` grant).186- What each carries, and its grant: [references/api.md](references/api.md#events-and-state).187- Never readable, by any grant but `camera` and `microphone`: pictures,188 audio. By any grant: transcripts, face prints, names. A hand's or face's189 place is a share of the picture.190- **The camera** (the `camera` grant): a snapshot, or a stream of191 frames; never while private, never off the lamp's own network:192 [references/camera.md](references/camera.md).193- **The microphone** (the `microphone` grant): Python194 `await lamp.microphone_stream(True)`, JS `lamp.microphoneStream(true)`,195 sends `microphone.audio` events, each a 20 ms block (16 kHz mono S16LE,196 640 bytes in `data`), until `microphone_stream(False)` /197 `microphoneStream(false)`, `stop`, or `microphone.ended`; off unless the198 owner switched it on, never while private or with someone else in view,199 never off the lamp's own network:200 [references/api.md](references/api.md#the-microphone). `body.state` and201 routed `joints` come next; this skill gains them as they land.202203## Patterns204205Ready to adapt, each in Python and JS: react to presence, a CI light, a206pomodoro, an agent's progress shown on the lamp, a chat alert, a program207that runs for days, and a web app on the SDK:208[references/patterns.md](references/patterns.md).209210## Gotchas we hit211212Read [references/gotchas.md](references/gotchas.md) before your first real213run: what a customer lamp lacks today, breathe and pulse levels, one pulse a214minute, `busy` while a motion plays, the light's `shows`, the restart mute.215216## Debugging217218`LAMPOS_LOG=debug` prints every frame to and from the lamp on stderr, secrets219redacted. The lamp's side and the journal recipe:220[references/debugging.md](references/debugging.md).