The RS232 Protocol Library teaches Axion Displays Radar how to talk to a specific brand/model of hardware over a serial connection – what to send, how to read the reply, and which dashboard field each value belongs in. Build a protocol once and any device assigned to it starts polling immediately, with no code changes and no redeploying anything to the Axion Displays Radar Node itself.
You only need this if your device is controlled over RS232. If it’s a PJLink-capable projector, skip this entirely – just fill in the projector’s PJLink Host (IP address) on its Edit Device page. PJLink is a fixed standard with no per-protocol setup; see Managing Your Hardware for that field.
Step 1 – Create the Draft
- Go to the page and click New Protocol.
- Fill in:
- Name – e.g. “Acme AV-2000 Series”.
- Brand / Model Family – used for search/filtering, and shown on the public “is my display supported?” listing if you later publish it.
- Command Format Template – see Step 2.
- Response Format – see Step 2.
- Click Create Draft. You land on the protocol’s detail page, still editable, in
Draftstatus.
Step 2 – Configure the Wire Protocol
Serial Port
Match whatever the manufacturer’s RS232 documentation specifies: Baud, Byte Size, Parity, Stop Bits, Timeout. Get these wrong and nothing will ever respond.
Command Format Template
The template every polled command gets substituted into before being sent over serial. Use {cmd} as the placeholder for each command row’s own code.
- Classic ASCII protocols (Digital Projection, Christie, and similar) typically look like:
({cmd} ?)\ror({cmd}?)\r– check the exact spacing in the manufacturer’s docs; some use a space before?, some don’t. - A protocol with its own fixed wrapper (e.g.
V00G{cmd}\r) works the same way –{cmd}just needs to sit wherever the real command code goes. - JSON-RPC protocols (see below) wrap the whole request in JSON, e.g.:
{"jsonrpc":"2.0","method":"property.get","params":{"property":"{cmd}"},"id":1}\n
Type \r, \n, or \t literally as backslash+letter – they’re converted to real line-ending bytes automatically.
Response Format
- Plain text (default) – the reply is read as-is, then Response Strip Chars (individual characters removed anywhere, e.g.
()) and Response Strip Prefix (a fixed prefix removed from the start) clean it up before it’s stored. If the device echoes its own command code back in the reply (e.g. Christie’s(SHU!0)for a shutter query), Axion Displays Radar strips that automatically per-command, so you don’t need to configure anything extra for it. - JSON-RPC – the whole reply line is parsed as JSON and its
resultfield is used as the value. Response Strip Chars/Prefix are ignored in this mode since there’s no fixed wrapper text to strip, only JSON syntax. Use this for Barco Pulse/Pulse Lite-based projectors and anything else exposing a JSON-RPC 2.0 API.
Error Responses / Poll Interval
Error Responses is a comma-separated list of reply prefixes that mean “no value” (default NAK,ERR,?) – a command whose reply starts with one of these is treated as unanswered rather than stored as garbage. Poll Interval is how often (in seconds) every non-button command in the list gets queried.
Step 3 – Build the Command List
Two ways to add rows, both usable at any time:
Upload Command List (CSV)
Replaces the entire command list in one go, the fastest way to load a large command set. Required header row:
cmd,label,canonical_field,type,optional,essential,is_button,generic_action,unit,value_map| Column | Meaning |
|---|---|
cmd | The raw command code. For a polled row, this is what gets substituted into {cmd} (e.g. PWR, BDR+PRTA, image.brightness). For a button row (is_button = TRUE), this is the entire literal string sent as-is, with no substitution – e.g. (PWR 1)\r or a full JSON-RPC request. Letters, digits, and _ . - \ " : , { } ( ) + and spaces are allowed, up to 200 characters. |
label | Human-readable name shown in the dashboard (e.g. “Power State”). |
canonical_field | Which dashboard field this value gets stored in, shown in the UI as Database Field (e.g. power_state, brightness_pct). Must be one of the active fields on the page. Leave blank for a button row. |
type | string, int, or float – how the cleaned value gets cast before storage. |
optional | TRUE/FALSE. An optional command that gets no response is silently skipped each poll; a required one that fails logs a warning. |
essential | TRUE/FALSE. Marks this field as one of the important few shown in the Diagnostics page’s compact “Essential” view, instead of only appearing under “Complete”. Purely a display-priority flag, it doesn’t affect polling. |
is_button | TRUE/FALSE. TRUE means this is a momentary action (a remote-control button) sent on demand, not a value polled and stored on every cycle. |
generic_action | Only meaningful when is_button is TRUE: power_on, power_off, mute, or unmute. Makes this button the real implementation behind the dashboard’s fixed generic commands (used by Automation Schedules, the Remote Command modal, and anything else that just wants to “power off this device” without knowing its protocol). Leave blank for buttons with no generic equivalent (e.g. an input-select or reset button). |
unit | Optional display unit (e.g. %, h, °C). |
value_map | Optional key=value;key=value mapping applied to the cleaned reply before type-casting – e.g. 0=Standby;1=On;2=Cooling;3=Warming. |
Up to 500 rows per upload; uploading replaces the whole list, so re-upload a corrected CSV rather than trying to patch one row via CSV.
Already have a protocol close to what you need? Open it and use Export CSV to download its command list in this exact format, then edit and re-upload as a new protocol.
Add Command / Field Mapping table
For smaller edits, use Add Command to add one row without disturbing the rest, or edit cmd/label/type/etc. directly inline in the table and click Save Mapping.
Two Worked Examples
Plain ASCII (Digital Projection / Christie-style):
- Command Format Template:
({cmd} ?)\r - Response Format: Plain text
- Response Strip Chars:
() - A row:
cmd=PWR, label=Power State, canonical_field=power_state, type=string, value_map=0=Standby;1=On;2=Cooling;3=Warming
JSON-RPC (Barco Pulse / Pulse Lite):
- Command Format Template:
{"jsonrpc":"2.0","method":"property.get","params":{"property":"{cmd}"},"id":1}\n - Response Format: JSON-RPC
- A row:
cmd=system.state, label=Power State, canonical_field=power_state, type=string - A button row:
cmd={"jsonrpc":"2.0","method":"system.poweron","id":1}\n, label=Power On, is_button=TRUE, generic_action=power_on
Publishing and Sharing
- A new protocol starts as Draft – usable immediately by your own org’s devices, editable freely.
- Submit for Review sends it to a super admin once every non-button command has a Database Field mapped. It moves to Pending Review, then Approved or Rejected (with a reason).
- An approved protocol can be made Publicly Listed (super admin only) – visible to every organization, and shown on the public “is my display supported?” page.
- Use the panel to share an unpublished protocol with specific client organizations without making it fully public – everyone shared with can also edit it.
- Clone starts a fresh editable draft from any protocol you can view, public or otherwise – the fastest way to base a new product on an existing one.
Maturity (Alpha / Beta)
Independent of the Draft/Pending/Approved status, a protocol can carry a Maturity tag – set it on the protocol’s detail page, next to Version. Use Alpha or Beta for a protocol whose command list was built from a manufacturer’s reference document rather than fully verified against real hardware (unconfirmed property names, service-mode-only commands, etc.). It shows as a small badge next to the status everywhere the protocol appears, including the public listing, so an approved-and-public protocol can still visibly flag “verify before you rely on this.”
Assigning a Protocol to a Device
Once a protocol exists, assign it from that device’s Edit page – see Managing Your Hardware.