Serve one room from several nodes

A shared room is a MeshCore room that any Aspen ESP32 with WiFi can serve. The room's key lives on a shared-room Worker on Cloudflare, and each node forwards its RF traffic to it. Companion apps see an ordinary room.

Choose a starting point

Send every cloudroom command from the companion app's Management console (see Open the Management console over RF). The commands need encrypted Management RF, and the node needs WiFi and a trusted clock. Shared rooms stay off until you join, create or convert one. A node serves up to two rooms.

What you want to do
You are	Send on your node	Result
Joining a room someone else runs	`cloudroom join CODE@HOST`	The node serves that room. The owner gives you the code.
Creating a room across your own nodes	`cloudroom create CODE@HOST NAME`	The server generates the key and this node becomes an owner.
Converting a room your node already hosts	`cloudroom convert CODE@HOST`, then the same line with `yes`	The room keeps its identity. The server now holds its key.

Each command replies at once and works in the background. Send cloudroom result for the outcome. A successful link restarts the node 10 seconds later.

Join a room with an invite code

An owner node sends cloudroom invite and reads you the reply:

Code ABCD-EFGH-JKMN-PQRS (10 min, once). Run: cloudroom join [email protected]

On your node:

cloudroom join [email protected]
cloudroom result

Expected: Linked. Restarts in 10 s. Ask the room owner for the password. Ask the owner for the room password and add the room in your app. If it does not appear, send cloudroom advertise 1.

Create a room for your fleet

cloudroom create [email protected] Backyard Room
cloudroom result

After the restart the node sends one room advert. Add the room in your app, then read its password with cloudroom password. Owner nodes can also send cloudroom password open to remove the password, cloudroom password new to generate one, or cloudroom password PW to set one of up to 15 printable characters. For each further node, send cloudroom invite and have its operator send cloudroom join.

Convert a local room

Conversion moves the room your node's Room role serves to a server, so more nodes can serve it. Members keep the room password and their existing contact. Without yes, the command changes nothing and tells you what will happen:

cloudroom convert [email protected]

Key goes to aspen-rooms.example.workers.dev; it can speak as the room. Admin logins stay. Add "yes aspen-rooms.example.workers.dev".

cloudroom convert [email protected] yes aspen-rooms.example.workers.dev
cloudroom result

For the hosted service, add just yes; for any other host, retype the host after yes.

The room's private key leaves your node. The node sends the key, name and guest password to the server over its own TLS connection, once. No reply, log or later command returns it. The server's operator can read the room and send as it. The local administrator logins, read-only guest logins, in-room command line and the last 32 posts held in RAM stay on the node. Administer the room with cloudroom commands afterwards, and its Room role stays off while the room is shared.

Choose a server

Hosted service or your own Worker
	Hosted (`aspen.ve6slp.ca`)	Your own Worker
Setup	Request a create code, then run `cloudroom create CODE NAME`	`npm run setup`, then mint your own codes
Who can read the room and speak as it	The hosted service operator	You
Cost and limits	No cost; operator quotas	Your Cloudflare plan; your own limits
Node commands	Leave off `@HOST`	Add `@HOST` with your Worker's name

Hosted service. New rooms are by invitation. Open a Hosted room request issue on slepp/meshcore-aspen, and the operator replies with a one-time create code, typically within a few days. Joining an existing room needs no request: the room's owner sends you an invite code.

Your own Worker. Run the service on your Cloudflare account and keep every room key. Setup takes one command and about ten minutes. Back up .deploy/room-kek.json to a password manager at once; without it the rooms on that Worker cannot be opened. The self-hosting guide covers deployment, minting codes, sign-up modes, Cloudflare plan limits and recovery.

A node accepts a host of up to 36 bytes in a direct message, so choose a short Worker name or domain. A longer name, or a server behind a private certificate authority, goes in a profile uploaded with admin.py cloudroom configure.

Commands on the Management channel

CODE is 16 letters and digits, with dashes optional. HOST is a lowercase DNS name; without it the node uses the hosted service. ALIAS is a room id or its position in cloudroom list (1 or 2), and you can leave it off when one room is linked.

cloudroom commands
Command	Who	What it does
`cloudroom list [N]`	Any node	Shows room N (default 1): id, name, role, state and host. State is `live`, `down`, `off` or `revoked`.
`cloudroom probe [HOST]`	Any node	Checks that a server answers and reports its version, sign-up mode and clock difference.
`cloudroom join CODE[@HOST]`	Any node	Joins a room.
`cloudroom create CODE[@HOST] NAME`	Any node	Creates a room named NAME.
`cloudroom convert CODE[@HOST] [yes [HOST]]`	Node with a local Room	Previews, then converts the local room.
`cloudroom invite [owner]`	Owner	Issues a join code, or an owner code with `owner`.
`cloudroom nodes [N]`	Owner	Lists the room's nodes five at a time, with role and last contact.
`cloudroom revoke ID`	Owner	Removes a node by the 8-character id from `nodes`.
`cloudroom password [PW\|open\|new]`	Owner	Shows, sets, removes or generates the room password.
`cloudroom unlink [ALIAS] [delete\|local] [force]`	Any node	Leaves a room. See Return a room to local.
`cloudroom share on\|off [force]`	Any node	Turns all shared rooms on or off and restarts. Settings stay saved.
`cloudroom advertise ALIAS`	Any node	Queues one room advert.
`cloudroom result`	Any node	Reports the outcome of the last background command.
`cloudroom apply`	Any node	Saves state and restarts.

Replies and requests stay within 145 bytes. One command runs at a time; a second one gets Error: link busy; send "cloudroom result". From a computer with a gateway, admin.py cloudroom join - reads the code from standard input, so it stays out of shell history, and polls cloudroom result for up to 40 seconds. The web /admin page and the !admin bot command never carry codes, passwords or membership changes; /admin shows cloudroom list and status and has a Share switch.

Management guide for shared rooms · Node guide

Return a room to local

Send cloudroom unlink on a converted node. After the restart that follows, its local Room role runs again with the password it had before conversion. If you removed the server copy with cloudroom unlink ALIAS delete, the local room takes the server's last password instead.

Other nodes still serve the room. Plain unlink refuses, and so do share off and unlink ALIAS local without force. This prevents one node from splitting a room that the others still use as the server's copy. Either delete the room for everyone, or add force to leave a copy running on the server.
Last owner. The last owner cannot leave while other nodes remain. Invite another owner first, or add delete to remove the room.
Server unreachable. cloudroom unlink ALIAS local removes the room on this node without contacting the server. Ask an owner to revoke the node.
Revoked node. A revoked node stops reconnecting. Send cloudroom unlink ALIAS local.
Pause without leaving. cloudroom share off stops serving every room and keeps the settings; cloudroom share on resumes.

Rooms linked with cloudroom save a settings record that Aspen 0.1.19 and 0.1.20 cannot read. To go back to either version, unlink each room and upload your earlier profile with admin.py cloudroom configure before installing the older firmware.

Limits and protections

Codes. A code works once and is stored as a hash. A join code lasts 10 minutes by default, up to 24 hours. An owner code lasts 2 minutes and never more than 15. Five wrong tries on one code delete it. Read a code out and use it at once.
Attempts. The server limits redeem requests, and wrong or unknown codes, per client address. After five failed link attempts in one boot, the node refuses further link commands until it restarts.
Quotas. A node can create 2 rooms a day and have 4 live. A room holds up to 16 nodes and 4 live invite codes. Operators of your own Worker can change the room and write limits.
Revocation. An owner removes a node with cloudroom nodes and cloudroom revoke ID, which closes its connections at once. Anyone who learns an unexpired join code can register a node until you revoke it, so share codes privately. An owner added in the last 24 hours cannot revoke another owner.
Backups. A backup restored onto new hardware carries the node key. Retire the old node first.
What the service operator sees. Whoever runs the Worker can read each room on it and send as it. The Worker logs no request body, code, token, key, password or address, and audit entries hold node ids. The operator's reach stops at the rooms on that Worker.
What the node needs. WiFi, a trusted clock and one network connection slot for each room it serves. A node serves up to two rooms, and both share its one radio.

Room keys and trust · Server limits

Troubleshooting

The room does not connect: Send cloudroom status. It reports the alias count, reserved sockets and wss-mask, which marks connected rooms, followed by link=idle|working|ok|failed room=local|cloud|off node=ab12cd34. If wss-mask stays zero, send cloudroom error for the last failed connection. HTTP 401 means the server rejected the node's token.
You need to know what the node saved: Send cloudroom config status for the saved enable state, aliases and upload state. Configuration and enable changes apply after a restart.
Clock not set. Wait for SNTP: The node needs the time to verify TLS. Send get sntp.server and confirm the node reaches an NTP server over WiFi.
TLS verify failed or server unavailable: The host in the command must be the host the certificate names. Send cloudroom probe HOST to see whether DNS, TLS or HTTP fails.
Link failed: code expired, code already used or code not valid: Ask the owner for a new code with cloudroom invite, and check the @HOST.
Link failed: rate limited: Wait the number of seconds the reply names, then try again.
The room is missing from your app: Send cloudroom advertise 1 (or 2), then add the room with its password.
No reply to a command: Send cloudroom result before sending the command again; the first request may have completed.

Recover a Management node · Operate a node