Cisco RoomOS (xAPI)

Control Cisco collaboration endpoints directly on the LAN — Room Kit and Room Bar families, Board series, Desk series, and legacy CE-software SX / MX / DX units — using the device's own xAPI over HTTP interface (the "putxml" API).

One codec becomes one GEM device. From there you can wake and sleep the room, set speaker volume, mute microphones, place and end calls, start presentation sharing, and read the codec's people-presence sensor to drive lighting and HVAC.

Driver name

cisco_roomos — set this as the device driver when adding the codec in Devices.

This is the device API, not the Webex cloud API

The driver talks to the codec over your LAN. It does not use Webex Control Hub. A cloud-registered device still answers on the LAN, but you must create a local user on it first — see Prerequisites. Your Control Hub login will not authenticate here.

Prerequisites

• The codec reachable from the GEM controller on the LAN.
• A local user on the codec holding the Admin or Integrator role.
  • On a locally-registered device, add it from the device web UI under Users.
  • On a Webex-registered device, enable Local Device Controls in Control Hub first, then create the user on the device.
• Nothing else. HTTPS is on by default and the API needs no separate enable step.

Use HTTPS

Codecs ship with HTTPS enabled and a self-signed certificate, which GEM accepts. Plain HTTP is off unless someone sets xConfiguration NetworkServices HTTP Mode to HTTP+HTTPS on the device — prefer leaving this driver on https.

Setup steps

1. Go to Devices and click Add Device.
2. Choose driver Cisco RoomOS (xAPI).
3. Fill in:
   • Codec IP / Hostname — the codec's LAN address.
   • Username — the local user you created (defaults to admin).
   • Password — that user's password.
4. Save. Within a few seconds the device shows connected, and the codec's product id, platform, serial number, and software version are written back as device attributes.
5. Optionally add zones. Each zone mirrors one facet of the codec — see Zone address format.

Attribute reference

Device attributes

Attribute	Required	Default	Purpose
ip	yes	—	Codec LAN address or hostname.
password	yes	—	Password for the local device user. Stored encrypted.
username	no	admin	Local device user with the Admin or Integrator role.
port	no	443	API port.
protocol	no	https	https or http. http only works if the codec's HTTP Mode allows it.
dial_protocol	no	(blank)	Sent as the Protocol parameter on dial — Sip, H323, or Spark. Blank lets the codec decide.
status_interval	no	15000	Milliseconds between status polls.
request_timeout	no	8000	Per-request timeout in milliseconds.

The driver also writes these back as read-only device attributes once connected: product_id, product_platform, software_version, serial_number.

Zone attributes written by the driver

Which attributes appear depends on the zone's facet.

Facet	state	Other attributes
system	on / off	standby_state (Off, Standby, Halfwake, EnteringStandby)
volume	on / off (off = muted)	level (0-100), mute_state
microphones	on / off (off = muted)	mute_state
presence	present / absent	people_count
call	in_call / idle	call_status, call_remote, call_duration

Zone address format

A codec is one box with several independently interesting states, so zone.address selects which facet the zone mirrors and controls:

zone.address	What the zone does
(blank) or system	Wake / sleep the room. on wakes, off puts the codec in standby.
volume	Speaker volume. on unmutes, off mutes, level control sets 0-100.
microphones	Microphone mute. on means mics are live, off means muted.
presence	Read-only room occupancy from the codec's people sensor.
call	Call state. off hangs up.

An unrecognised address falls back to system, so a zone created without an address still drives wake/sleep.

A typical conference room uses two zones: a system zone in the AV subsystem for wake/sleep, and a presence zone that lighting and HVAC automations subscribe to.

Commands

Command	Arguments	Notes
on / off	address	Facet-aware — see the table above.
wake, standby, halfwake	—	Explicit standby control regardless of facet.
set_volume / set_level	level	0-100. The codec's own scale is 0-100, so there is no scaling.
volume_up / volume_down	steps	Defaults to one step.
mute_on, mute_off, mute_toggle	—	Speaker volume mute. mute_toggle is native.
mic_mute_on, mic_mute_off, mic_mute_toggle	—	Microphone mute. mic_mute_toggle is native.
dial	number, protocol, call_type	number is a SIP URI, H.323 alias, or phone number.
hangup	call_id	Omit call_id to disconnect everything.
accept_call	call_id	Answer an incoming call.
presentation_start	connector_id	Share a local input — connector 1 or 2 on most models.
presentation_stop	—	Stop sharing.
send_message	text, title, duration	On-screen alert. duration in seconds; 0 stays until dismissed.
reboot / shutdown	—	reboot takes roughly 2 minutes. shutdown needs a physical power-on afterwards.
get_status	—	Reads every facet and updates zone attributes.
get_info / get_devices	—	Product id, platform, serial, software version.
get_calls	—	The current call table.
raw_status	path	Read any xAPI path, e.g. /Status/Video/Input.
raw_command	xml	POST a raw <Command> or <Configuration> body.

The two raw_* commands are the escape hatch for anything this driver does not wrap. The full path tree is published at roomos.cisco.com.

How it talks to the codec

Reads use GET /getxml?location=<path>; writes use POST /putxml with a text/xml body. Authentication is HTTP basic on every request.

Known limitations

• Polling, not events. RoomOS can push feedback over a WebSocket, but this driver polls. status_interval (default 15 s) is therefore the reaction-time floor for occupancy and call state. Lower it for presence-driven lighting; raise it if you have many codecs.
• Room analytics must be enabled on the codec. People presence and count are only reported when xConfiguration RoomAnalytics PeoplePresenceDetector is On, and counts outside a call additionally need PeopleCountOutOfCall set to On. Models with no people sensor never report them, and the driver simply leaves those attributes unset rather than writing zeros.
• Presentation sharing is input-based. connector_id picks a physical HDMI input. Which source that is depends on room wiring, not on RoomOS.
• No call roster or directory. get_calls returns the live call table only. Phone book search, call history, and roster management are not wrapped — reach them through raw_command if you need them.
• No macro or UI-extension management. Saving panels and macros to the codec is deliberately out of scope; those belong in the device's own editor.
• One codec per device row. There is no controller/child model here — add each codec separately.

Troubleshooting

Symptom	What to check
HTTP 401 — check the local device user and password	The local user is missing or has the wrong role. Create one on the codec under Users with Admin or Integrator. A Control Hub account will not work.
ECONNREFUSED on port 80	Plain HTTP is disabled. Set protocol to https (recommended), or set xConfiguration NetworkServices HTTP Mode to HTTP+HTTPS on the codec.
command rejected by codec: <reason>	The codec parsed the command and refused it. The reason comes straight from RoomOS — most often a command the model does not implement, or a parameter out of range.
Presence zone never changes	Turn on RoomAnalytics PeoplePresenceDetector, plus PeopleCountOutOfCall for counts while idle. Confirm with raw_status on /Status/RoomAnalytics/PeoplePresence.
Device flaps between connected and disconnected	Usually request_timeout is too tight for a busy codec, or the poll is too aggressive. Raise status_interval and request_timeout.
Mute toggles land the wrong way	The speaker and mic toggles are native RoomOS toggles, but zone state only refreshes on the next poll — a toggle issued right after someone used the touch panel reflects on the following poll.

Related

• AV Zones — grouping codecs with the rest of the room's AV.
• Barco ClickShare — wireless presentation in the same rooms.