Skip to content

Low Level Command

Overview

The Low Level Command device — listed as LowLevelCommand in Onlyview's device list — is the generic escape hatch for controlling equipment that has no dedicated plugin. Instead of implementing a protocol, you describe the exact bytes to put on the wire: you build a named list of commands, each one a frame made of literal text, escape sequences, raw hexadecimal bytes, optional parameters, and an optional checksum. Each command then becomes an action that a Command Cue or a QuickKey can fire.

Frames can be sent over a serial port, over TCP or as UDP datagrams. The device is send-only: incoming data is not read or parsed, so it cannot be used to poll a machine for status. Actions are executed on the Producer, which is therefore the machine that needs the serial port or the network route to the equipment.

A command set can be saved to, and loaded from, an XML driver file, so a protocol you have described once can be reused in other shows.

Setup

At the top of the setup dialog:

  • Device name: A descriptive name for this device.
  • Driver File — Load / Save: Loads or saves the whole configuration (communication settings, checksum type and the complete command list) as an XML file. See Driver files below.

The rest of the dialog is split into three tabs.

Communication tab

  • Communication Type: How the frames are transmitted.
    • None: Nothing is sent. Useful while you are still writing the commands.
    • Serial Port: Sends over an RS-232 port. Serial communication is only available on Windows.
    • TCP/IP Server
    • TCP/IP Client: Opens a TCP connection to the equipment.
    • UDP Client: Sends each frame as a UDP datagram.

For Serial Port:

  • Com port: The COM port number, so 4 means COM4. NO (zero) means no port, and nothing is sent.
  • Baud Rate: From 50 to 256000 bauds; the default is 9600.
  • Data Bits: 5, 6, 7 or 8 bits; the default is 8.
  • Stop Bits: 1, 1.5 or 2 bits.
  • Parity: None, Odd, Even, Mark or Space.

Hardware and software flow control are always off. If the port cannot be opened — wrong number, or another application already holds it — Onlyview reports it when the show starts.

For TCP/IP Server:

  • Port Adress: The TCP port used.

Info

Despite its name, TCP/IP Server does not accept incoming connections: it connects to the given port on the local machine. Use it to talk to a program running on the Producer itself; use TCP/IP Client for equipment elsewhere on the network.

For TCP/IP Client:

  • IP Adress: The address of the equipment.
  • Port Adress: Its TCP port.
  • Automatic reconnection: When enabled, a command sent while the connection is down triggers a new connection attempt, and the command is queued and sent as soon as the connection is established. With this option off, commands sent while disconnected are lost.

For UDP Client:

  • IP Adress and Port Adress: The destination the datagrams are sent to. A broadcast address is accepted.

Command tab

  • Commands: The list of commands defined on this device. The label underneath shows the selected command's name and its output frame.
  • New / Edit / Delete: Creates, modifies or removes a command. Command names must be unique.

Checksum tab

  • Checksum Type: How the checksum byte is computed — None, Sum, Xor or Or. The setting is per device, and applies to every command that asks for a checksum.

Commands

New or Edit on the Command tab opens the Command dialog:

  • Name: The name the command appears under in cues and action editors. It cannot contain the characters ( ) , [ ] @ ! \, which all have a meaning in the frame syntax.
  • Output frame: The frame itself, written as text (see below).
  • Output Parameter — New / Edit / Delete: Inserts a parameter at the cursor, or edits and removes one. Edit and Delete only become available once you have selected a complete (…) parameter block in the output frame with the mouse.

Writing a frame

Characters you type are sent as they are, one byte each. On top of that:

Syntax Byte sent
!FF Any byte, written as two hexadecimal digits (upper or lower case)
\r Carriage return, 0x0D
\n Line feed, 0x0A
\0 Zero byte, 0x00
\a Bell, 0x07
\b Backspace, 0x08
\t Tab, 0x09
\v Vertical tab, 0x0B
\f Form feed, 0x0C
\e Escape, 0x1B
\@ A literal @, 0x40
\! A literal !
\( \) A literal parenthesis

So PWR ON\r sends the six characters PWR ON followed by a carriage return, and !02!41!30!03 sends the four bytes 02 41 30 03.

Warning

A ! that is not followed by two valid hexadecimal digits is an error: the command is refused and nothing is sent. Write \! when you need the character itself.

Checksums

Put an @ at the start and another @ at the end of the part of the frame the checksum covers. At the closing @, Onlyview appends one byte computed from the bytes in between, according to the device's Checksum Type:

  • Sum: The 8-bit sum of the bytes.
  • Xor: All the bytes exclusive-ORed together.
  • Or: All the bytes ORed together.
  • None: No byte is appended; the @ markers are simply ignored.

Warning

Only bytes written as !FF hexadecimal codes, and parameters in Hexa mode or of type Enum, are accumulated into the checksum. Plain literal text between the markers is sent but does not contribute. Write the covered part of the frame in hexadecimal.

Parameters

A parameter is a value left open in the frame and filled in by whoever fires the command. New in the Output Parameter row opens the Command Parameter dialog:

  • Name: The parameter's name, subject to the same forbidden characters as a command name.
  • Type: Integer, String, Time or Enum.
  • Mode: How the value is turned into bytes — Hexa, Decimal or Literal. Choosing type Enum forces the mode to Literal.
  • Parameter Edition in Enum Type (type Enum only): The list of choices, managed with Add, Edit and Delete. Each entry has an Enum Name, which is what the operator picks from, and an Enum Value, which is what is actually sent. A value written as !FF is sent as that single hexadecimal byte; anything else is sent as text.

The parameter appears in the output frame as a block of the form (Name,Mode,Type), inserted where the cursor was — for example (Level,Decimal,Integer). Enum parameters carry their choices in the same block, as [Name,Value] pairs.

At send time:

  • Integer in Decimal or Literal mode is written as decimal ASCII digits; in Hexa mode it is written as the single byte of that value, and it is included in the checksum.
  • String is inserted as typed.
  • Time is written as a decimal number.
  • Enum inserts the value of the chosen entry.

A worked example

A device expecting STX, a two-byte command, a sum checksum and ETX, with a level as a raw byte:

!02@!41!30(Level,Hexa,Integer)@!03

Set Checksum Type to Sum. With Level set to 4, the frame sent is 02 41 30 04 75 03: the two literal command bytes, the parameter byte, the checksum 0x41 + 0x30 + 0x04 = 0x75, then ETX.

Firing a command

Drop the device on a Command Layer of a timeline to create a Command Cue, or attach it to a QuickKey, then double-click it to edit the action:

  • Action :: The command to send, chosen from the device's command list, or None to do nothing.
  • Parameter and Value: If the command has parameters, pick one in Parameter and give it a value. The Value editor follows the parameter's type: a spin box for Integer, a text field for String, a timecode field for Time, and an Enum Name list for Enum. Set each parameter in turn.

The cue is labelled Set Command followed by the parameter names and values.

There is no ActionGraph node for this device. To send raw bytes from an ActionGraph, use the UDP Out or Http send nodes described in the nodes reference instead.

Warning

Parameter values are stored per command and per parameter name, not per cue: two cues firing the same command share the same values, and the last value you edited is the one both will send. When a command needs to be sent with two different values, define two commands.

Device widget

The device can be dropped on a UserScreen. The widget shows the device number, a Status lamp — lit while the serial port is open or the TCP connection is established — and a Command Test field with a Take button.

Command Test sends whatever you type straight away, using the same escapes, hexadecimal codes and checksum markers as an output frame. It is meant for trying a frame out against the real equipment before saving it as a command; it does not substitute parameters, so (…) blocks are sent as literal text.

Driver files

Save, in the Driver File box, writes the device's whole configuration to an XML file: communication settings, checksum type, and every command with its parameters and their current values. Load reads such a file back, replacing the current communication settings and command list.

This is how a protocol is shared between shows: describe the equipment once, save the driver file next to the show, and load it into a new Low Level Command device whenever you meet the same equipment again.

Warning

Save also applies the settings currently shown in the dialog to the device immediately, before writing the file. Cancelling the dialog afterwards does not undo that.