GlamBot: control protocol

The DZEN TECH Robot Arm Simplified Control API. All commands and replies are ASCII.

Interfaces

Interface	Parameters
USB (serial)	115200 bps · 8 data bits · 1 stop bit · no parity
RS232	115200 bps · 8 data bits · 1 stop bit · no parity
BLE	Service UUID 0xFFE0 (simple key service) · Characteristic UUID 0xFFE1 (read / write)
TCP/IP (via Ethernet)	Reserved — parameters to be finalized later

Encoding and command format

The Simplified protocol works in ASCII: every character and value is encoded as ASCII, and replies are returned as ASCII.

• Command prefix: #
• End of command: \r (CR — carriage return)

Command types:

• E (Execute) — perform an action
• G (Get) — read data / information / parameters
• S (Set) — set data / settings / parameters
• A (Abort) — cancel, stop movement

Command structure — #<TYPE>_<COMMAND>[=<data>]\r: prefix # · command type · _ delimiter · command name · optional = before data · optional data · \r.

#G_SC\r        request the currently selected scene (no parameters)
#S_SC=1\r      set scene ID 1 (with a parameter)

Response structure — #<TYPE>_<COMMAND>=<data | OK>\r:

• Without returned data — OK\r on success. Example: #S_SC=1\r → #S_SC=OK\r
• With returned data — the requested value in ASCII. Example: #G_SCNAME=1\r → #G_SCNAME=My Fancy Scene\r

Error handling

An error reply has the form #ERR=<code>\r, where <code> is an ASCII decimal number from 0 to 40.

Example: #G_SCNAME=42\r → #ERR=22\r

Error codes are unified with the base protocol; some of them are not used by the Simplified protocol.

Code	Symbolic name	Note
0	DTRA_COM_OK	not used in the simplified protocol
1	DTRA_COM_ERROR
2	DTRA_COM_BUSY
3	DTRA_COM_TIMEOUT
4	DTRA_COM_BUFF_OVERFLOW
5	DTRA_COM_PACKET_ERROR
6	DTRA_COM_CMD_ERROR
7	DTRA_COM_CRC_ERROR	not used in the simplified protocol
8	DTRA_COM_DATA_SIZE_ERROR
9	DTRA_COM_UNSUPPORTED_PROTOCOL
10	DTRA_COM_ARM_NOT_READY
11	DTRA_COM_ARM_NOT_HOMED
12	DTRA_COM_NA_WHILE_MOVING
13	DTRA_COM_NA_WHILE_SCENE_EXEC
14	DTRA_COM_POSE_DATA_ERROR
15	DTRA_COM_POSE_TYPE_ERROR
16	DTRA_COM_POSE_UNKNOWN
17	DTRA_COM_POSE_UNREACHABLE
18	DTRA_COM_POSE_SPEED_ERROR
19	DTRA_COM_POSE_ACCEL_ERROR
20	DTRA_COM_SPEED_ACCEL_OUT_OF_RANGE
21	DTRA_COM_SCENE_PLAY_TYPE_ERROR
22	DTRA_COM_SCENE_ID_ERROR
23	DTRA_COM_SCENE_IS_EMPTY
24	DTRA_COM_SCENE_HAS_BAD_POSE
25	DTRA_COM_SCENE_POSE_ID_ERROR
26	DTRA_COM_SCENE_POSE_IS_EMPTY
27	DTRA_COM_PRESET_ID_ERROR
28	DTRA_COM_PRESET_IS_NOT_EDITABLE	not used in the simplified protocol
29	DTRA_COM_PRESET_IS_EMPTY
30	DTRA_COM_PRESET_HAS_BAD_POSE	not used in the simplified protocol
31	DTRA_COM_NAME_IS_TOO_LONG	not used in the simplified protocol
32	DTRA_COM_MEMORY_WRITE_ERROR	not used in the simplified protocol
33	DTRA_COM_MEMORY_IS_EMPTY	not used in the simplified protocol
34	DTRA_COM_NOT_A_BITMASK_FLAG	not used in the simplified protocol
35	DTRA_COM_SAFETY_SYSTEM_UNKNOWN
36	DTRA_COM_SWITCH_TYPE_UNKNOWN
37	DTRA_COM_DATA_OUT_OF_RANGE
38	DTRA_COM_DATA_IS_NOT_INT	not used in the simplified protocol
39	DTRA_COM_DATA_IS_NOT_HEX	not used in the simplified protocol
40	DTRA_COM_DATA_IS_NOT_BIN	not used in the simplified protocol

Status and State

Get Status

#G_STATUS\r → a mask of 8 ASCII digits. It tells whether the arm is moving, whether a scene is playing, and whether there are warnings, software errors or hardware errors.

Example: #G_STATUS\r → #G_STATUS=11000000\r

Index	Field	Values
0	Moving State	0 = Idle; 1 = Moving
1	Scene State	0 = Stopped; 1 = Playing; 2 = Waiting
2	Warning State	0 = No warnings; 1 = Has warnings
3	Error State	0 = No errors; 1 = Has errors
4	Hardware Error State	0 = No errors; 1 = Has errors
5–7	Reserved	0

Get State

#G_STATE\r → a mask of 16 ASCII digits. It reports calibration, the state of the safety systems, and errors that occurred during operation.

Example: #G_STATE\r → #G_STATE=1110000000000000\r

Index	Field	Values
0	Initialised State	0 = Not initialized; 1 = Initialized
1	Ready State	0 = Not ready; 1 = Ready
2	Calibration State	0 = Not calibrated; 1 = Calibrated; 2 = Calibrating
3	Emergency Stop Active	0 = Not active; 1 = Active
4	External Lock Active	0 = Not active; 1 = Active
5	Inverse Kinematics Error	0 = No errors; 1 = Has errors
6	Inverse Kinematics Unreachable	0 = No errors; 1 = Unreachable
7	Interface Timeout	0 = No warnings; 1 = Has warnings
8	Pre-Collision Active	0 = Not active; 1 = Collision detected
9	Limit Switch Active	0 = Not active; 1 = Limit switch detected
10	Home Switch Out Of Sync	0 = No errors; 1 = Out of sync
11–15	Reserved	0

Initialization and de-initialization

After the arm is assembled and powered on it must be initialised — via the button on the control unit or programmatically. Before switching the arm off, de-initialise it (this also sends it to the transport position).

Command	Request	Reply
Execute Initialization	#E_SWON\r	#E_SWON=OK\r
Execute Power Off (de-initialization)	#E_SWOFF\r	#E_SWOFF=OK\r

Calibration

If the arm is not calibrated, run calibration before working with it. The arm must be initialised to calibrate.

Caution

Before calibrating, make sure the arm is not moving.

Command	Request	Reply
Get Calibration State	#G_HOMING\r	#G_HOMING=1\r
Execute (automatic) Calibration	#E_HOMING\r	#E_HOMING=OK\r
Manual Calibration	#E_MHOMING\r	#E_MHOMING=OK\r

• Calibration state value — 0 = Not calibrated; 1 = Calibrated; 2 = Calibrating.
• Automatic calibration works from the built-in sensors: it resets the old calibration and moves to the zero sensors — usually up to 10–15 seconds.
• Manual calibration may be needed if a calibration sensor fails or an axis is slightly off. Set the arm to the zero position by hand, then call manual calibration to force the axis zero points at the current arm position.

Caution

Manual calibration is only for emergencies, when automatic calibration cannot be performed. We recommend not placing its button in an easily accessible area of the interface.

Device information

Command	Request	Reply (up to 63 chars)
Get Device Name	#G_DEVNAME\r	#G_DEVNAME=DZEN TECH ROBOT ARM\r
Get Device Serial Number	#G_DEVSN\r	#G_DEVSN=1234567890\r
Get Device Version	#G_DEVVER\r	#G_DEVVER=1.0\r

Safety and protection systems

The arm uses several safety systems:

• Active safety (pre-collision system) — sensors that trigger when there’s an obstacle in the safety zone; by default the arm stops on contact.
• Limit switch sensors — prevent the arm from hitting a physical limiter if it skips steps.

You can read or set a safety parameter either by ID or in bulk via a parameter mask. Each system is a flag — 1 = On, 0 = Off.

ID	Symbolic name	Note
0	DTRA_SAFETY_SYSTEM_COLLISION_PAUSE
1	DTRA_SAFETY_SYSTEM_COLLISION_STOP
2	DTRA_SAFETY_SYSTEM_LIMIT_SWITCH
3	DTRA_SAFETY_SYSTEM_HOME_SWITCH_SYNC
4	DTRA_SAFETY_SYSTEM_E_STOP
5	DTRA_SAFETY_SYSTEM_TIMEOUT_USB_UART	ignored if the interface is locked
6	DTRA_SAFETY_SYSTEM_TIMEOUT_BLUETOOTH	ignored if the interface is locked
7	DTRA_SAFETY_SYSTEM_TIMEOUT_RS_232	ignored if the interface is locked
8	DTRA_SAFETY_SYSTEM_TIMEOUT_AUX	ignored if the interface is locked
9	DTRA_SAFETY_SYSTEM_LOCK_USB_UART
10	DTRA_SAFETY_SYSTEM_LOCK_BLUETOOTH
11	DTRA_SAFETY_SYSTEM_LOCK_RS_232
12	DTRA_SAFETY_SYSTEM_LOCK_AUX
13–31	Reserved	—

Command	Request	Reply
Get all safety parameters	#G_SFALL\r	#G_SFALL=1011100000000…\r (32-digit mask)
Set all safety parameters	#S_SFALL=1011100000000…\r	#S_SFALL=OK\r
Get safety parameter by ID	#G_SFID=0\r	#G_SFID=1\r — 0 disabled, 1 enabled
Set safety enable by ID	#S_SFEN=0\r	#S_SFEN=OK\r
Set safety disable by ID	#S_SFDIS=0\r	#S_SFDIS=OK\r

Urgent and emergency stop

Command	Request	Reply
Stop Immediately (urgent)	#A_NOW\r	#A_NOW=OK\r
Stop Emergency	#A_EM\r	#A_EM=OK\r

• Stop Immediately — the arm stops with the fastest smooth deceleration. If a scene was playing, the current step number is reset to 0. This stop does not reset calibration.
• Stop Emergency — the software equivalent of the E-STOP button; the arm stops almost instantly and calibration is reset.

Danger

An emergency stop resets the arm calibration, because this kind of stop can make the motors skip steps on fast movements. After an emergency stop, re-run calibration before continuing to use the arm.

Scenes playback

Up to 32 scenes can be stored. Each scene has an ID, a name, and an array of up to 32 steps with position, velocity and acceleration parameters.

Note

While a scene is playing, motion-changing commands are ignored and return the corresponding error. Stop the arm first, then send new movement commands.

Command	Request	Reply
Get Scene Num	#G_SCNUM\r	#G_SCNUM=6\r (0–32)
Get Scene Name by ID	#G_SCNAME=3\r	#G_SCNAME=My Fancy Moves\r (up to 64 chars)
Get Scene Size (steps) by ID	#G_SCSIZE=3\r	#G_SCSIZE=8\r (0–32)
Set Scene	#S_SC=1\r	#S_SC=OK\r
Get selected Scene	#G_SC\r	#G_SC=1\r
Execute Scene (start)	#E_SC\r	#E_SC=OK\r
Stop Scene	#A_SC\r	#A_SC=OK\r
Resume Scene	#E_SCRES\r	#E_SCRES=OK\r
Get Pose (current step)	#G_POSE\r	#G_POSE=2\r
Execute Pose by step ID	#E_POSE=3\r	#E_POSE=OK\r
Execute Next Pose	#E_NPOSE\r	#E_NPOSE=OK\r
Execute Prev Pose	#E_PPOSE\r	#E_PPOSE=OK\r

• Set Scene — the scene ID must be within the range of available scenes.
• Execute Scene — plays the selected scene from its first step.
• Stop Scene — the arm finishes the current step, then stops.
• Resume Scene — resumes movement through the scene from the current step.
• Execute Pose / Next Pose / Prev Pose — step-by-step playback: go to a given step, or to the next/previous step.

Pose presets

Presets are pre-recorded arm positions you can recall to set the arm to a given pose — useful between sessions, or to place the arm so users can comfortably work with a tablet to share their photo and video content.

Command	Request	Reply
Get Preset Num	#G_PRNUM\r	#G_PRNUM=5\r (0–32)
Get Preset Name by ID	#G_PRNAME=3\r	#G_PRNAME=Test Preset Pose\r (up to 63 chars)
Execute Preset	#E_PR=1\r	#E_PR=OK\r

The preset ID must be within the range of available presets.

Global Speed Scale

Scales speed and acceleration across all movement (scenes and presets).

• Range: 100 down to 10 percent.
• Default: 100 % — no change to the speeds set in scenes and presets.

Command	Request	Reply
Get Global Speed Scale	#G_GSS\r	#G_GSS=100\r (10–100 %)
Set Global Speed Scale	#S_GSS=90\r	#S_GSS=OK\r

Workflows

Connection checkup

1. Establish a connection on your chosen interface.
2. Get State — check for errors and warnings.
3. Check the Initialised state. If not initialized → ask the user to initialize the arm.
4. Check the Calibration state. If not calibrated → ask the user to calibrate the arm.
5. Get Status — check for errors and warnings.

Software initialization

1. Check the Initialised state with Get State. If it is 0, initialize.
2. Start with #E_SWON\r.
3. Check the state again with Get State.

Software de-initialization

1. Check the Initialised state with Get State. If it is 1, de-initialize.
2. Start with #E_SWOFF\r — de-initialization can take some time.
3. Check the Initialised state. If it is 0, the arm can be switched off and disassembled.

Automatic calibration

1. Call #E_HOMING\r to start automatic calibration against the sensors.
2. Poll Get Calibration State once per second — it stays Calibrating during the process.
3. When finished, the state changes to Calibrated.

Periodic checks during operation

1. Get Status — check for errors and warnings.
2. If any are indicated → Get State and check for errors and warnings.

Tip

Poll the status about once per second to keep the device’s operating state up to date.

Get the list of scenes

1. Get Scene Num.
2. Get each scene name with Get Scene Name + scene ID.
3. Get each scene’s step count with Get Scene Size + scene ID.

Get the list of presets

1. Get Preset Num.
2. Get each preset name with Get Preset Name + preset ID.

Play a scene to shoot a video

1. Get State — if the arm is Moving, stop it.
2. Set Scene with the desired scene ID.
3. Execute Pose + 0 to send the arm to the scene’s start position.
4. Execute Scene to start playback on demand.
5. Stop Scene to stop playback on demand.
6. Optional: Execute Preset + preset ID to park the arm in a waiting pose until the next session.

Play a scene step-by-step to shoot photos

1. Get State — if the arm is Moving, stop it.
2. Set Scene with the desired scene ID.
3. Execute Pose + 0 to send the arm to the scene’s start position.
4. Take a photo, then move to the next position with Execute Next Pose (or Execute Pose + ID).
5. Optional: Execute Preset + preset ID to park the arm in a waiting pose until the next session.