05.03.2017

API

Оглавление

Описание

Формат вызова

Возвращаемое значение

Общие функции

Функции состояния робота

GetFirmwareVersion

GetAPIVersion

GetBatteryCharge

Функции движения робота

Forward

Back

Stop

Left

Right

Функции классов робота

Основной класс робота

Планировщик заданий

Платформа

Драйвер двигателей

MotorPower

Bluetooth адаптер

SetBluetoothName

SetBluetoothPassword

SetBluetoothBaudrate

История изменений

Описание

Взаимодействие через API ведется в текстовом виде в формате JSON. Ответ функций так же кодируется в формат JSON. Параметры функций именованы, соответственно не важен порядок их следования. Это позволит в дальнейшем с большей легкостью менять API.

Т.к. вызов команды и получение результата разнесены во времени, то для сопоставления ответа запросу в запрос необходимо указать уникальный идентификатор запроса. Этот идентификатор будет возвращен в ответе на команду.

Каждая команда должна завершаться символом «;». Если быть точным, то этот символ указывает роботу, что команда передана полностью и робот начинает ее выполнение.

Команды до их исполнения ставятся в очередь и выполняются по правилу FIFO. После исполнения отправляется ответ с результатом.

Новые команды движения прерывают старые. В этот момент по старым приходит ответ о том, что она прервана. Это нужно для ускорения отклика при интерактивном управлении.

Максимальная длина команды — 70 символов. При превышении 70 символов будет выдаваться ошибка: EXCEEDINGSIZE.

Связь по последовательному порту осуществляется на скорости 115200 бод, без проверки, с одним стоповым битом.

Формат вызова

Формат вызова функций одинаков для всех функций.

{

«cmd»:»имя команды«,

«req»:»идентификатор запроса»,

«prm«:[

{«имя параметра 1»:значение параметра 1},

{«имя параметра 2»:значение параметра 2}

{«имя параметра n«:значение параметра n}

]

};

Примеры вызов:

Функция с двумя параметрами:

{

«cmd»:»MotorPower«,

«req»:»1234″,

«prm«:[

left«:50},

right«:20}

]

};

Функция без параметров:

{

«cmd»:»Stop«,

«req»:»1234″,

«prm»:[]

};

 

Причем, сами значения параметров могут быть не только простыми значениями, но и массивами и объектами. Они кодируются согласно правилам JSON.

Возвращаемое значение

Все операции возвращают два поляrst и req. В зависимости от операции результат может быть разных типов и содержания.

Пример результат операции:

{«req»:»1234″, «rst«:»1.1»}

Общие функции

Функции состояния робота

GetFirmwareVersion

Выдает версию программного обеспечения робота.

Выполняется в момент поступления команды и не добавляется в очередь задач.

Параметры: нет.

Возвращаемое значение:

  • rstстрока — Версия ПО робота.

Пример запроса:

{cmd”:”GetFirmwareVersion”, «req»:»1234″}

Пример возвращаемого значения:

{«req»:»1234″, «rst«:»1.1»}

GetAPIVersion

Выдает версию, используемого роботом программного интерфейса.

Выполняется в момент поступления команды и не добавляется в очередь задач.

Параметры: нет.

Возвращаемое значение:

  • rstстрока — Версия API робота.

Пример запроса:

{cmd”:”GetAPIVersion”, «req»:»1234″}

Пример возвращаемого значения:

{«req»:»1234″, «rst«:»1.1»}

GetBatteryCharge

Возвращает уровень заряда батареи в процентах.

Выполняется в момент поступления команды и не добавляется в очередь задач.

Параметры: нет.

Возвращаемое значение:

  • rstчислоуровень заряда батареи в процентах.

Пример запроса:

{cmd”:”GetBatteryCharge”, «req»:»1234″}

Пример возвращаемого значения:

{«req»:»1234″, «rst«:40}

Функции движения робота

Forward

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

Операция ставится в очередь задач, но вытесняется другими задачами которые ставятся в очередь. Ответ на запрос отправляется в момент выполнения команды.

 

Параметры:

  • spd – число, необязательное — процент от максимальной скорости робота.

Возвращаемое значение:

  • rstстрока — результат выполнения команды: OK, ERROR.

Пример запроса:

{cmd”:”Forward”, «req»:»1234″, prm”:[{“spd”:50}]}

Пример возвращаемого значения:

{«req»:»1234″, «rst«:»OK«}

Back

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

Операция ставится в очередь задач, но вытесняется другими задачами которые ставятся в очередь. Ответ на запрос отправляется в момент выполнения команды.

Параметры:

  • spd – число, необязательное — процент от максимальной скорости робота.

Возвращаемое значение:

  • rstстрока — результат выполнения команды: OK, ERROR.

Пример запроса:

{cmd”:”Back”, «req»:»1234″, prm”:[{“spd”:50}]}

Пример возвращаемого значения:

{«req»:»1234″, «rst«:»OK«}

Stop

Прекращает движение робота.

Параметры: нет.

Возвращаемое значение:

  • rstстрока — результат выполнения команды: OK, ERROR.

Пример запроса:

{cmd”:”Stop”, «req»:»1234″}

Пример возвращаемого значения:

{«req»:»1234″, «rst«:»OK«}

Left

Дает команду роботу повернуться вокруг оси на лево.

Операция ставится в очередь задач, но вытесняется другими задачами которые ставятся в очередь. Ответ на запрос отправляется в момент выполнения команды.

Параметры: нет

Возвращаемое значение:

  • rstстрока — результат выполнения команды: OK, ERROR.

Пример запроса:

{cmd”:”Left”, «req»:»1234″, prm”:[{“angle”:90}]}

Пример возвращаемого значения:

{«req»:»1234″, «rst«:»OK«}

Right

Дает команду роботу повернуться вокруг оси на право.

Операция ставится в очередь задач, но вытесняется другими задачами которые ставятся в очередь. Ответ на запрос отправляется в момент выполнения команды.

Параметры: нет

Возвращаемое значение:

  • rstстрока — результат выполнения команды: OK, ERROR.

Пример запроса:

{cmd”:”Right”, «req»:»1234″, prm”:[{“angle”:90}]}

Пример возвращаемого значения:

{«requestId»:»1234″, «result«:»OK«}

Функции классов робота

Основной класс робота

Пока нет функций.

Планировщик заданий

Пока нет функций.

Платформа

Пока нет функций.

Драйвер двигателей

MotorPower

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

Операция ставится в очередь задач, но вытесняется другими задачами которые ставятся в очередь. Ответ на запрос отправляется в момент выполнения команды.

Параметры:

  • left – число, необязательноемощность левого двигателя в процентах от максимальной;

  • right – число, необязательноемощность левого двигателя в процентах от максимальной.

Возвращаемое значение:

  • rstстрока — результат выполнения команды: OK, ERROR.

Пример запроса:

{cmd”:”MotorPower”, «req»:»1234″, prm”:[{“left”:90}, {“right”:90}]}

Пример возвращаемого значения:

{«req»:»1234″, «rst«:»OK«}

Bluetooth адаптер

SetBluetoothName

Устанавливает новое имя bluetooth адаптеру.

Возвращает успешный результат после выполнения, либо отказ если произошла ошибка.

Параметры:

  • name – строка, обязательноеновое имя bluetooth адаптера.

Возвращаемое значение:

  • rstстрока, обязательноерезультат выполнения команды: OK, ERROR.

Пример запроса:

{cmd”:”SetBluetoothName”, «req»:»1234″, prm”:[{“name”:”HC-06”}]}

Пример возвращаемого значения:

{«req»:»1234″, «rst«:»OK«}

SetBluetoothPassword

Устанавливает новый пароль для подключения к bluetooth адаптеру.

Возвращает успешный результат после выполнения, либо отказ если произошла ошибка.

Параметры:

  • pass – строка, обязательноеНовый пароль bluetooth адаптера.

Возвращаемое значение:

  • rstстрока — результат выполнения команды: OK, ERROR.

Пример запроса:

{cmd”:”SetBluetoothPassword”, «req»:»1234″, prm”:[{“pass”:”1234”}]}

Пример возвращаемого значения:

{«req»:»1234″, «rst«:»OK«}

SetBluetoothBaudrate

Устанавливает скорость bluetooth адаптера.

Возвращает успешный результат после выполнения, либо отказ если произошла ошибка.

Параметры:

  • spdчисло, обязательноеСкорость работы bluetooth адаптера. Возможны значения: 1200, 2400, 4800, 9600, 19200, 38400, 57600, 115200.

Возвращаемое значение:

  • rstстрока — результат выполнения команды: OK, ERROR.

Пример запроса:

{cmd”:”SetBluetoothBaudrate”, «req»:»1234″, prm”:[{“spd”:1200}]}

Пример возвращаемого значения:

{«req»:»1234″, «rst«:»OK«}

 

История изменений

01.08.2016 — Первая версия документа. Описаны основные функции.

14.08.2016 – Версия 1.1 — Команды должны завершаться символом «;». В названия методов класса bluetooth добавлено слово bluetooth.

17.08.2016 —Версия 1.2 — В связи с истечением срока разработки API решено операции GoForward, GoBack, TurnToLeft, TurnToRight делать без проверки дистанции и угла. Решено не делать операцию GetCurrentTask, т. к. нет смысла и не делать операцию GetOrientation. Параметры остаются в документации и зарезервированы на будущее.

18.08.2016 — Версия 1.3 — Решено все возвраты процедур сделать одинаковыми, c полем result. Это позволит уменьшить объем памяти занимаемой программой.

17.10.2016 – Версия 1.4 — Из за ограничений на передачу данных пришлось сократить многие ключевые слова.

13.03.2017 – Версия 1.5 — Убрана процедура GetOrientation. Убран параметр dist из операций Frwd, Back. Исправлена ошибка в написании параметра result операции Right. Убрана процедура GetCurrentTask. Дополнил операции примерами запросов. Операция Frwd переименована в Forward. Убран параметр angle из операций Left и Right.