API

Материал из Руководство по эксплуатации системы me6cloud
Перейти к: навигация, поиск


ME6 Cloud API


Запрос - http request

Тип запроса – POST,

Адрес - /me6_api

Хост - ip или имя, если нелокальный сервер, то -  cl.me6cloud.com

полный адрес куда слать запрос будет например - http://cl.me6cloud.com/me6_api

Данные на сервер передавать в виде стандартных “&ключ=значение” пар.

Ответ с сервера идет в формате JSON.


Авторизация производится с созданием токена, который не даст произвести множественную авторизацию под одной учеткой:

Отправлять при авторизации

Запрос:

{

action: “login”,

login: “user_login”,

password: “user_password”

}

Ответ:

{

answer: true,

userId: 1335, //id юзера, который будет передаваться вместе с ключем при любых действиях

apiKey: “ee6ae676a7e67a6e7aa4e54ae” //ключ, который передается в каждом запросе для валидации доступа.

accountGroupId: 123,  // id группы учетных записей, в которую входит этот юзер

}


В случае ошибки в результате любого запроса будет возвращено:

{

answer: false,

error_code: 123, //определенный код ошибки, приходит в любом запросе при answer: false

error_msg: “string msg”, //какое-то описание ошибки. приходит обычно, когда

произошла ошибка с неопределенным кодом - error_code: 0

data: { //необязательно будет

trace: “string stack trace” //стэк вызовов на сервере, полезно во время разработки

}

}

Получение объектов

Запрос:

{

userId: 123,

apiKey: apiKey,

action: “getAllObjects”

}

Ответ:

{

answer: true,

error: “string msg”,

data: {

objects: [

{

id: 1,

title: “str”,

… ,

plans: [ {

id: 1,

title: “title”,

… ,

groups:[{

id: 1,

title: “title”,

use_beacon: 0|1, //управление группой по биконам

use_schedule: 0|1, //управление группой по расписанию

use_probe: 0|1, //управление группой по датчику

state: ok | // состояние группы: все норм

offline //все ноды оффлайн

empty | //группа пустая (не добавили нодов)

partyOffline, //часть нодов оффлайн, часть онлайн

offlineNode: [{ ipv6: …., title: …. }, … ], //список нодов, которые оффлайн

nodes: [{ },...] //список всех нодов группы

dimmable: full | // все диммируемые

     none | //все НЕ диммируемые

     party //часть диммируемые, часть нет.

schedule: { //активное в данный момент расписание

….

periods:[

{

start: 12, //время начала в минутах

  dim: 23  //яркость

},

...

]

},

hcl_groups: [{

…. //все аналогично обычным группам

temp: 2800, //цвет температура

},...]

rgb_groups: [{

…. //все аналогично обычным группам

col_r:  0..255, //цвет R

col_g: 0..255, //цвет G

col_b: 0..255, //цвет B

},...]

"beacon_info" : [ {

                   group_id: 64,

                   major: 2,

                   range: 2,

         minor: 1

}, … ],

"scenarios" : [ {

                             id: 64,

                  title: “scen title”

           }, … ],

} , … ]

}, … ]

},

...

]

}

}


  1. Управление группой - вкл

Запрос:

{

userId: 123,

apiKey: apiKey,

action: “group-on”,

groupId: 123 // либо массив [ 2, 4, 65, 345 ]

}

Ответ:

{

answer: true

}


  1. Управление группой - выкл

Запрос:

{

userId: 123,

apiKey: apiKey,

action: “group-off”,

groupId: 123 // либо массив [ 2, 4, 65, 345 ]

}

Ответ:

{

answer: true

}


  1. Управление группой - яркость

Запрос:

{

userId: 123,

apiKey: apiKey,

action: “group-dim”,

groupId: 123,  //либо массив [ 2, 4, 65]

dimVal: 1…100  //либо массив значений яркости для каждой группы [ 20, 40, 65 ]

}

Ответ:

{

answer: true

}


  1. Управление температурой (только для HCL групп)

Запрос:

{

userId: 123,

apiKey: apiKey,

action: "hcl-group-temp",

            groupId: 123,  //либо массив [ 2, 4, 65]

val: 2700…6000  //температура в кельвинах

}

Ответ:

{

answer: true

}

  1. Управление цветом (только для RGB групп)

Запрос:

{

userId: 123,

apiKey: apiKey,

action: "rgb-group-rgb",

           groupId: 123,  //либо массив [ 2, 4, 65]

val_r:  0…255,  //цвет R

val_g: 0…255,  //цвет G

val_b: 0…255,  //цвет B

}

Ответ:

{

answer: true

}





  1. Управление всеми группами этажа (плана) - вкл

Запрос:

{

userId: 123,

apiKey: apiKey,

action: “floor-on”,

floorId: 123

}

Ответ:

{

answer: true

}


  1. Управление всеми группами этажа (плана) - выкл

Запрос:

{

userId: 123,

apiKey: apiKey,

action: “floor-off”,

floorId: 123

}

Ответ:

{

answer: true

}


  1. Передача на сервер значений с биконов.

Запрос:

{
   userId: 123,

   apiKey = apiKey,
   "beacon_data" =     [
        {
           "group_id" = 63,
           status = 1
        },
        {
           "group_id" = 51,
           status = 1

        },
        {
           "group_id" = 62,
           status = 1
        }
    ]
}

Ответ:

{

answer: true

}



  1. Получение всех биконов на плане

Запрос:

{

userId: 123,

apiKey: apiKey,

action: “get-beacons”,

floorId: 123

}

Ответ:

{

answer: true,

data: [

   {

id: 123,

pos_x: 344,

    pos_y: 843,

    uuid: …..

    major: 3,

    minor: 43,

    ….

 }, …

         ]

}



  1. Добавление бикона на план

Возвращает параметры бикона, которые надо прошить в бикон.

Запрос:

{

userId: 123,

apiKey: apiKey,

action: “add-new-beacon”,

floorId: 123

}

Ответ:

{

answer: true,

data:

   {

id: 123,

pos_x: 344,

    pos_y: 843,

    uuid: …..

    major: 3,

    minor: 43,

password: ‘43434dea3’,

    ….

 }

}



  1. Подтверждение данных бикона

После перепрошивки бикона это запрос должен подверждать успешность операции

Запрос:

{

userId: 123,

apiKey: apiKey,

action: “confirm-beacon”,

beaconId: 123,

serial: …. ,

pos_x: 43, //необязательное

pos_y: 463, //необязательное

}

Ответ:

{

answer: true

}




  1. Обновление данных бикона

Запрос:

{

userId: 123,

apiKey: apiKey,

action: “update-beacon”,

beaconId: 123,

pos_x: 43,

pos_y: 463,

}

Ответ:

{

answer: true

}



  1. Добавление нода сканированием QR кода

Запрос:

{

userId: 123,

apiKey: apiKey,

action: “qr-add”,

qrString: “fdsfsdjkfdskfj”,

planId: 234 //id плана куда нод добавляем

}

Ответ:

{

answer: true

}



  1. Запрос данных по энергопотреблению

Запрос:

{

userId: 123,

apiKey: apiKey,с

action: “power-stat”,

type: “group” | “plan” | “object”, //за какой тип объекта данные слать

id: 1234, //id объекта запроса

period: “day” | “week” | “month” | “year” | “range”, //за какой период данные взять

dateStart: “2015-05-21 00:00:00” //дата начала периода. если это день, то вернет за 1 день, месяц - по дням, год - по месяцам. Для недели берет текущую дату и на 7 дней назад от нее выдаст

dateEnd: “2015-05-21 00:00:00” //дата конца периода. указывать если тип - range

}

Ответ:

{

answer: true,

data: {

period: “15min” | “hour” | “day” | “month”,

noPrice: 0 | 1, //есть или нет данные о стоимости энергопотребления

pdata: [

[ “2015-05-21 10:00:00”, 2345 ],

[ “2015-05-21 11:00:00”, 3432 ], ...

]

}

}



  1. Получить список сценариев на плане

Запрос:

{

userId: 123,

apiKey: apiKey,

action: “scenario-get”,

planId: 1234, //id плана

}

Ответ:

{

answer: true,

data: [

{id: 234, title: “scen title” },

{id: 237, title: “scen title2” },

]

}


  1. Применить настройки из сценария

Запрос:

{

userId: 123,

apiKey: apiKey,

action: “scenario-apply”,

id: 123 // id сценария

}

Ответ:

{
   "data": {
       "groups": [
           {

  "group_id": "54",
               "done": 1, //признак того, что группа отработала
               "data": { //данные о группе, которые стали после применения сценария
                   "turned_on": "1",
                   "dim": "50",
                   "use_schedule": "1",
                   "use_beacon": "0",
                   "use_probe": "0"
               }
           },
           {
               "done": 0 //если группа по какой-то причине не отработала

           }
       ],
       "done": 1
   } ,
   "answer": true
}



Коды ошибок:

0

Неизвестная ошибка. Какая-то дополнительная инфа может быть в error_msg

1

Ошибка авторизации, неверный логин и/или пароль

2

Команда не была выполнена me6d сервером

3

Попытка включить группу, где нет нодов. Теперь это будет ошибкой, т.к. оч часто вносит неопределенность, да и просто бессмысленно.

100

Нет apiKey в запросе на сервер

101

Неправильный apiKey для данного юзера. Скорее всегда надо заново авторизоваться в системе.

102

Неправильный QR код при сканировании

103

Нод с этим QR уже добавлен к учетке сканирующего

104

Нод с этим QR уже добавлен к другой учетке

200

Не хватает прав на выполнение заданного действия




ME6 Math


Трилатерация:

запрос:

{

 action: "locate",

 areaBox: { //точки ограничения области.

a: [1, 4],

b: [34, 52]

 }

 nodes: [

{

      ip: "",

      has_coords: true || false,

      x: 34.33,

      y: 21.34  

} ,

...

 ]

}


Ответ:

{

 nodes: [

{

      ip: "",

      x: 34.33,

      y: 21.34  

},

...

 ]

}



Передача показаний датчика:

запрос:

{

 action: "lux_reg",

 val: 0...9999,

 groupId: 123,

 groupDim: 0...100,

 groupPower: 0 | 1,

 need: 0..999, //значение, которое надо поддерживать на датчике. Берется из пресета группы.

}



Передача показаний для калибровки:

запрос:

{

 action: "lux_calib",

 groupId: 123,

 val: 0...100 //диммирование группы

}


Событие завершения калибровки группы:

запрос:

{

 action: "lux_calib_finished",

 groupId: 123

}





ME6 WebSocket

DEPRECATED - будет заменено на MQTT

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


Команды по изменению управления(вкл-выкл-дим), которые идут от сервера(пхп) к вебсокет серверу и далее к юзерам в группе акков:

Изменения управления

{

account_group_id: 3,

action: "group-power",

groupId: 123,

power: 0 | 1

}

{

account_group_id: 3,

action: "group-dim",

groupId: 123,

dimVal: 0...100

}

{

account_group_id: 3,

action: "group-power-dim",

groupId: 123,

power: 0 | 1,

dimVal: 0...100

}


События при отваливании/появлении нода

{

action: "node-online",

account_group_id: 3, //к какой приписан нод

planId: 234, //куда закреплен нод

eui64: "001f7000000008d8"

}

{

action: "node-offline",

account_group_id: 3, //к какой приписан нод

planId: 234, //куда закреплен нод

eui64: "001f7000000008d8"

}



Команды идущие от сервера(пхп, нод) к вебсокет серверу:

Показания с датчика

{

action: "sensor",

val:   0...255,

eui64: "001f7000000008d8"

}

{
action: 'sensor-lux',
lux: 345.45,
eui64: '0f00ff000232F4E'
}

{
action: 'sensor-rgb',
r: 150,
g: 50,
b: 210,
eui64: '0f00ff000232F4E'
}



Команды от юзера к вебсокет серверу:

Передача инфы о юзере на текущем соединении

{

action: 'setId',

grId: 123, //account_group_id

id: 475 //user_id

}


Указание о том, что этому юзеру (соединению) нужно присылать данные с датчика с заданным eui64

{

action: 'accept-sensor',

eui64: "001f7000000008d8"

}



ME6 me6d nodejs client

Далее реализовать асинхронный режим, при котором из пхп будет отсылаться команда, а далее уже по факту ее исполнения будет производиться оповещение. - реализую после основных задач по перепрошивке, алертам и др.


Появились ответы на команды с более развернутым статусом:

{

  status: 'lost', //тип ошибки. lost - не до всех нодов дошло.

  lostCount: 3 //кол-во потеряных нодов

}


{

 status: 'errcmd', //тип ошибки. опечатка в тексте команды.

 errMsg: errMsg //сообщение об ошибке команды от me6d

}



ME6 MQTT events

Реально исп будет только для уведомлений о событиях и отправки данных об изменений!


DEBUG server

host: debug.me6cloud.com

mqtt port: 1883

mqtt tls-psk: 9000

             client_id12345678:111111178f76ee76da39af146c32314

ws port: 8000

ws ssl port: 8443


Алерты будут приходить сразу на всех языках системы. Сейчас это ru, en

acc/{account_group_id} /alert/{lang}


Значения освещенности в люксах с датчика:

acc/{account_group_id} /sensor/{eui64}


Для групп все события управления:

                   /group/{groupId}

                                     /control

                                             /dim 0..100

                                             /power 0|1

                                             /fadetime 0..1000

                                             /temp 2700..5800

                                             /schedule on|off|update

                                             /schedule_sensor on|off управление по датчику, включенное из расписание

                                             /schedule_manaul on|off управление вручную включенное из расписания - пока что нет, но будет.

                                             /schedule_actual структура расписания актуального на данный момент, если оно обновилось:

{

 "account_group_id" = 3,

 "creator_id" = 123,

 days = [

   tuesday

 ],

 id = 198,

 periods = [

  {

    dim = 31,

    end = 180,

    start = 0,

    "schedule_id" = 198,

   }, …

 ]

}

                                             /sensor on|off

                                            


                                     /state - данные в json, как в api

{

state: ok|offline|empty|partyOffline,

offlineNodes: [{

id: 123,

eui64: '...',

title: 'node 1231',

serial: 'G05AB',

online: 0

},

{...}]

}


Различные действия с самим объектом группы

                                     /data

                                          /update - данные в json, что  обновилось.

                                          /delete 34 - в качестве значения присылается id плана, в который входила группа.

                                          /create - данные в json о группе.



Управление именно нодом. Чуть позже добавлю вкладку в управлении, чтобы можно было именно нодами управлять. Доступ будет только у админов группы учеток.

                      /node/{eui64} -в случае hcl нодов это будет hcl_{id нода}

                                 /control

                                         /dim 0..100

                                         /power 0|1

                                         /fadetime 0..1000

                                         /rxchan 11..26

                                         /temp 2700..5800

                                 /state online|offline

                                 /reflash done | 0xXXXX - прогресс прошивки. сделано или текущая прошитая последняя страница прошивки.


Добавить еще события create, update, delete на объекты, планы.


Системные события:

system/me6d

          /event disconnected|connected

          /alert //сейчас тут событие о рестарте может быть вида: rebooted at 2016-07-14 04:35





ME6HOME

Получение прошивок:

  • cl.me6cloud.com/me6home/firmwares/release/

  • cl.me6cloud.com/me6home/firmwares/release/last

  • cl.me6cloud.com/me6home/firmwares/debug/

  • cl.me6cloud.com/me6home/firmwares/debug/last

Если в конце идет last - то это выдаст только самую последнюю прошивку к каждому типу устройств.

В ответ придет такой json:

{
   "data": [
       {
           "id": "8", //внутренний ид в бд, для приложения оно не нужно наверн
           "dev_type": "2", //номер типа устройства см. ниже таблицу типов
           "type": "release", //релизн или дебаг прошивка
           "ts_added": "2015-09-18 16:30:09", //дата добавления ее на сайт
           "fname": "8.bin", //файл с прошивкой, не нужен для приложения
           "url": "http:\/\/cl.me6cloud.com\/files\/home_fw\/8.bin", //собственно ссылка на файл с прошивкой, откуда ее скачать нужно.
           "descr": "fdfdf" //какое-то текстовое описание.
       },...    ],
   "answer": true
}


Типы устройств:

Номер

Описание

0

Кнопочный

512

Удаленный

256

Модульный одноконтурный 200

272

Модульный одноконтурный 800

288

Модульный двухконтурный 200

304

Модульный двухконтурный 800



Отправка логов из приложения:

На https://cl.me6cloud.com/me6home/logs/add  через POST присылать:

{

   key: 'ключ для проверки, чтоб особо не спамили из левых источников',

   email: 'asd@asd.dd',

   descr: 'комментарий от юзера какой-то длиной до 1000символов'

   log: 'текст лога до 16Мб длиной'

}

В отверт JSON:

{

answer: true | false,

error: 'какое-то сообщение об ошибке, если она есть'

}