GlamBot: протокол управления

Simplified Control API робо-руки DZEN TECH. Все команды и ответы — в ASCII.

Интерфейсы

Интерфейс	Параметры
USB (serial)	115200 бод · 8 бит данных · 1 стоп-бит · без чётности
RS232	115200 бод · 8 бит данных · 1 стоп-бит · без чётности
BLE	Service UUID 0xFFE0 (simple key service) · Characteristic UUID 0xFFE1 (read / write)
TCP/IP (через Ethernet)	Зарезервировано — параметры будут определены позже

Кодировка и формат команд

Упрощённый протокол работает в ASCII: все символы и значения кодируются в ASCII, ответы тоже приходят в ASCII.

• Префикс команды: #
• Конец команды: \r (CR — возврат каретки)

Типы команд:

• E (Execute) — выполнить действие
• G (Get) — получить данные / информацию / параметры
• S (Set) — задать данные / настройки / параметры
• A (Abort) — отмена, остановка движения

Структура команды — #<ТИП>_<КОМАНДА>[=<данные>]\r: префикс # · тип команды · разделитель _ · имя команды · опциональный = перед данными · опциональные данные · \r.

#G_SC\r        запросить текущую выбранную сцену (без параметров)
#S_SC=1\r      задать сцену с ID 1 (с параметром)

Структура ответа — #<ТИП>_<КОМАНДА>=<данные | OK>\r:

• Без возвращаемых данных — OK\r при успехе. Пример: #S_SC=1\r → #S_SC=OK\r
• С возвращаемыми данными — запрошенное значение в ASCII. Пример: #G_SCNAME=1\r → #G_SCNAME=My Fancy Scene\r

Обработка ошибок

Ответ об ошибке имеет вид #ERR=<код>\r, где <код> — десятичное ASCII-число от 0 до 40.

Пример: #G_SCNAME=42\r → #ERR=22\r

Коды ошибок унифицированы с базовым протоколом; часть из них в упрощённом протоколе не используется.

Код	Символьное имя	Примечание
0	DTRA_COM_OK	не используется в упрощённом протоколе
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	не используется в упрощённом протоколе
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	не используется в упрощённом протоколе
29	DTRA_COM_PRESET_IS_EMPTY
30	DTRA_COM_PRESET_HAS_BAD_POSE	не используется в упрощённом протоколе
31	DTRA_COM_NAME_IS_TOO_LONG	не используется в упрощённом протоколе
32	DTRA_COM_MEMORY_WRITE_ERROR	не используется в упрощённом протоколе
33	DTRA_COM_MEMORY_IS_EMPTY	не используется в упрощённом протоколе
34	DTRA_COM_NOT_A_BITMASK_FLAG	не используется в упрощённом протоколе
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	не используется в упрощённом протоколе
39	DTRA_COM_DATA_IS_NOT_HEX	не используется в упрощённом протоколе
40	DTRA_COM_DATA_IS_NOT_BIN	не используется в упрощённом протоколе

Status и State

Get Status

#G_STATUS\r → маска из 8 ASCII-цифр. Показывает, движется ли рука, играет ли сцена, есть ли предупреждения, программные или аппаратные ошибки.

Пример: #G_STATUS\r → #G_STATUS=11000000\r

Индекс	Поле	Значения
0	Moving State	0 = Idle; 1 = Moving
1	Scene State	0 = Stopped; 1 = Playing; 2 = Waiting
2	Warning State	0 = нет предупреждений; 1 = есть предупреждения
3	Error State	0 = нет ошибок; 1 = есть ошибки
4	Hardware Error State	0 = нет ошибок; 1 = есть ошибки
5–7	Reserved	0

Get State

#G_STATE\r → маска из 16 ASCII-цифр. Сообщает состояние калибровки, работу safety-систем и ошибки, возникшие во время работы.

Пример: #G_STATE\r → #G_STATE=1110000000000000\r

Индекс	Поле	Значения
0	Initialised State	0 = не инициализирована; 1 = инициализирована
1	Ready State	0 = не готова; 1 = готова
2	Calibration State	0 = не откалибрована; 1 = откалибрована; 2 = калибруется
3	Emergency Stop Active	0 = не активен; 1 = активен
4	External Lock Active	0 = не активна; 1 = активна
5	Inverse Kinematics Error	0 = нет ошибок; 1 = есть ошибки
6	Inverse Kinematics Unreachable	0 = нет ошибок; 1 = недостижимо
7	Interface Timeout	0 = нет предупреждений; 1 = есть предупреждения
8	Pre-Collision Active	0 = не активна; 1 = обнаружено столкновение
9	Limit Switch Active	0 = не активен; 1 = сработал концевик
10	Home Switch Out Of Sync	0 = нет ошибок; 1 = рассинхрон
11–15	Reserved	0

Инициализация и деинициализация

После сборки руки и включения питания её нужно инициализировать — кнопкой на блоке управления или программно. Перед выключением руку нужно деинициализировать (при этом она также уходит в транспортное положение).

Команда	Запрос	Ответ
Execute Initialization	#E_SWON\r	#E_SWON=OK\r
Execute Power Off (деинициализация)	#E_SWOFF\r	#E_SWOFF=OK\r

Калибровка

Если рука не откалибрована, перед работой запустите калибровку. Для калибровки рука должна быть инициализирована.

Осторожно

Перед калибровкой убедитесь, что рука не движется.

Команда	Запрос	Ответ
Get Calibration State	#G_HOMING\r	#G_HOMING=1\r
Execute (автоматическая) Calibration	#E_HOMING\r	#E_HOMING=OK\r
Manual Calibration	#E_MHOMING\r	#E_MHOMING=OK\r

• Значение состояния калибровки — 0 = не откалибрована; 1 = откалибрована; 2 = калибруется.
• Автоматическая калибровка работает по встроенным датчикам: сбрасывает старую калибровку и уезжает на нулевые датчики — обычно до 10–15 секунд.
• Ручная калибровка может понадобиться при неисправности датчика калибровки или небольшом сбое оси. Выставьте руку в нулевое положение вручную и вызовите ручную калибровку — она принудительно задаёт нулевые точки осей в текущем положении руки.

Осторожно

Ручная калибровка выполняется только в аварийной ситуации, когда автоматическую по какой-то причине выполнить нельзя. Рекомендуем не размещать кнопку этой функции в легкодоступной части интерфейса.

Информация об устройстве

Команда	Запрос	Ответ (до 63 символов)
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- и защитные системы

В руке используется несколько типов защиты:

• Активная защита (pre-collision system) — набор датчиков, срабатывающих при препятствии в зоне безопасности; по умолчанию рука останавливается при контакте.
• Концевые датчики (limit switch) — не дают руке удариться о физический ограничитель при пропуске шагов.

Параметр защиты можно прочитать или задать как по ID, так и массово — через маску параметров. Каждая система — флаг: 1 = On, 0 = Off.

ID	Символьное имя	Примечание
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	игнорируется, если интерфейс заблокирован
6	DTRA_SAFETY_SYSTEM_TIMEOUT_BLUETOOTH	игнорируется, если интерфейс заблокирован
7	DTRA_SAFETY_SYSTEM_TIMEOUT_RS_232	игнорируется, если интерфейс заблокирован
8	DTRA_SAFETY_SYSTEM_TIMEOUT_AUX	игнорируется, если интерфейс заблокирован
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	—

Команда	Запрос	Ответ
Get all safety parameters	#G_SFALL\r	#G_SFALL=1011100000000…\r (маска из 32 цифр)
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 выключено, 1 включено
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

Срочная и аварийная остановка

Команда	Запрос	Ответ
Stop Immediately (срочная)	#A_NOW\r	#A_NOW=OK\r
Stop Emergency (аварийная)	#A_EM\r	#A_EM=OK\r

• Stop Immediately — рука останавливается с максимально быстрым плавным торможением. Если играла сцена, номер текущего шага сбрасывается в 0. Эта остановка не сбрасывает калибровку.
• Stop Emergency — программный аналог кнопки E-STOP: рука останавливается почти мгновенно, калибровка сбрасывается.

Опасно

Аварийная остановка сбрасывает калибровку руки, так как при таком торможении моторы могут пропустить шаги на быстрых движениях. После аварийной остановки перед продолжением работы калибровку нужно вызвать заново.

Воспроизведение сцен

В руке хранится до 32 сцен. У каждой сцены есть ID, имя и массив из до 32 шагов с параметрами позиции, скорости и ускорения.

Заметка

Во время проигрывания сцены команды изменения движения игнорируются и возвращают соответствующую ошибку. Сначала остановите руку, затем подавайте новые команды движения.

Команда	Запрос	Ответ
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 (до 64 символов)
Get Scene Size (шаги) by ID	#G_SCSIZE=3\r	#G_SCSIZE=8\r (0–32)
Set Scene	#S_SC=1\r	#S_SC=OK\r
Get выбранной Scene	#G_SC\r	#G_SC=1\r
Execute Scene (старт)	#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 (текущий шаг)	#G_POSE\r	#G_POSE=2\r
Execute Pose по 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 — ID сцены должен быть в пределах доступных сцен.
• Execute Scene — проигрывает выбранную сцену с первого шага.
• Stop Scene — рука доходит до конца текущего шага и останавливается.
• Resume Scene — возобновляет движение по сцене с текущего шага.
• Execute Pose / Next Pose / Prev Pose — пошаговое воспроизведение: переход к заданному шагу или к следующему / предыдущему.

Пресеты поз

Пресеты — заранее записанные положения руки, которые можно вызвать, чтобы выставить руку в нужную позу. Удобно между сессиями или чтобы поставить руку так, чтобы пользователям было комфортно работать с планшетом при отправке фото и видео.

Команда	Запрос	Ответ
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 (до 63 символов)
Execute Preset	#E_PR=1\r	#E_PR=OK\r

ID пресета должен быть в пределах доступных пресетов.

Global Speed Scale

Масштабирует скорость и ускорение на всех типах движения (сцены и пресеты).

• Диапазон: от 100 до 10 процентов.
• По умолчанию: 100 % — не меняет скорости, заданные в сценах и пресетах.

Команда	Запрос	Ответ
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

Сценарии

Проверка соединения

1. Установите соединение на выбранном интерфейсе.
2. Get State — проверьте ошибки и предупреждения.
3. Проверьте Initialised state. Если не инициализирована → попросите пользователя инициализировать руку.
4. Проверьте Calibration state. Если не откалибрована → попросите пользователя откалибровать руку.
5. Get Status — проверьте ошибки и предупреждения.

Программная инициализация

1. Проверьте Initialised state через Get State. Если 0 — выполните инициализацию.
2. Запустите командой #E_SWON\r.
3. Снова проверьте состояние через Get State.

Программная деинициализация

1. Проверьте Initialised state через Get State. Если 1 — выполните деинициализацию.
2. Запустите командой #E_SWOFF\r — деинициализация может занять некоторое время.
3. Проверьте Initialised state. Если 0 — руку можно выключить и разбирать.

Автоматическая калибровка

1. Вызовите #E_HOMING\r, чтобы запустить автоматическую калибровку по датчикам.
2. Опрашивайте Get Calibration State раз в секунду — во время процесса он держит значение Calibrating.
3. По окончании состояние меняется на Calibrated.

Периодические проверки во время работы

1. Get Status — проверьте ошибки и предупреждения.
2. Если что-то отмечено → Get State и проверьте ошибки и предупреждения.

Совет

Опрашивайте статус примерно раз в секунду, чтобы держать рабочее состояние устройства в актуальном виде.

Получить список сцен

1. Get Scene Num.
2. По одному получите имена сцен: Get Scene Name + ID сцены.
3. По одному получите число шагов: Get Scene Size + ID сцены.

Получить список пресетов

1. Get Preset Num.
2. По одному получите имена пресетов: Get Preset Name + ID пресета.

Проиграть сцену для съёмки видео

1. Get State — если рука Moving, остановите её.
2. Set Scene с нужным ID сцены.
3. Execute Pose + 0, чтобы вывести руку в стартовое положение сцены.
4. Execute Scene — старт воспроизведения по требованию.
5. Stop Scene — остановка воспроизведения по требованию.
6. Опционально: Execute Preset + ID пресета, чтобы отправить руку в позу ожидания до следующей сессии.

Пошагово проиграть сцену для съёмки фото

1. Get State — если рука Moving, остановите её.
2. Set Scene с нужным ID сцены.
3. Execute Pose + 0, чтобы вывести руку в стартовое положение сцены.
4. Сделайте фото и переведите руку в следующее положение командой Execute Next Pose (или Execute Pose + ID).
5. Опционально: Execute Preset + ID пресета, чтобы отправить руку в позу ожидания до следующей сессии.