Client API

August 30, 2021

Client API

Введение

Client API предоставляет интерфейс для взаимодействия с BARY сервером через WebSocket соединение (Socket.IO). API позволяет получать данные об устройствах в реальном времени, управлять ими, а также выполнять CRUD операции с пользователями, зонами, устройствами, действиями и скриптами.

Подключение к серверу

Создание WebSocket соединения

createSocket() {
  this.socket = socketIo(this.address, {transports: ['websocket']});
}

Параметры:

  • address — адрес BARY сервера (например, https://bary.io или локальный IP)
  • transports — используется только WebSocket для стабильного соединения

Отключение от сервера

destroySocket() {
  this.socket.disconnect();
}

Аутентификация

После подключения необходимо выполнить аутентификацию:

authenticate() {
  this.send('authenticate', {token: this.token});
}

Параметры:

  • token — токен аутентификации (генерируется автоматически при инициализации)

События:

  • authenticate — получение подтверждения успешной аутентификации

Шифрование данных

Все данные между клиентом и сервером шифруются:

// Отправка зашифрованных данных
encrypt(data, email)

// Получение и расшифровка данных
decrypt(data, log = null)

События WebSocket

Client API поддерживает следующие события для получения данных в реальном времени:

device — Обновление данных устройств

Получение информации об устройствах и их состоянии:

socket.on('device', (data) => {
  // data содержит массив устройств с обновленными данными
});

Подписка через Observable:

deviceSub().subscribe(data => {
  console.log('Обновление устройств:', data);
});

summary — Сводная информация

Получение сводки по всем устройствам, погоде и другой информации:

socket.on('summary', (data) => {
  // data.info — общая информация
  // data.devices — список устройств
  // data.weather — данные о погоде
});

Получение сводки:

getSummary() {
  this.send('get-summary');
}

channels — Каналы связи

Информация о доступных каналах связи с устройствами:

getChannels() {
  this.send('get-channels');
}

stats — Статистика

Статистика использования системы и устройств.

events — События системы

Получение событий, происходящих в системе (срабатывание датчиков, выполнение сценариев и т.д.).

notify — Уведомления

Получение уведомлений от сервера:

notifySub().subscribe(notification => {
  console.log('Уведомление:', notification);
});

logs — Логи системы

Получение логов работы сервера и устройств.

room-sensors — Датчики комнат

Получение данных датчиков, сгруппированных по комнатам:

getRoomSensors() {
  this.send('get-room-sensors');
}

exception — Ошибки

Получение информации об ошибках:

socket.on('exception', (error) => {
  console.error('Ошибка:', error);
});

REST API через WebSocket

Client API позволяет выполнять HTTP-запросы через WebSocket соединение с помощью метода sendRequest:

sendRequest(method, path, data = null)

Параметры:

  • method — HTTP метод (get, post, put, delete)
  • path — путь к API endpoint
  • data — данные для отправки (для POST/PUT запросов)

Возвращает: Promise с результатом запроса

Пример использования:

const devices = await sendRequest('get', '/api/v2/devices');
console.log('Список устройств:', devices);

Пользователи

Получение списка пользователей

getUsers() {
  return this.sendRequest('get', '/api/v2/users');
}

Возвращает: Массив объектов пользователей

Сохранение пользователя

saveUser(data) {
  return this.sendRequest('post', '/api/v2/users', data);
}

Параметры:

  • data.name — имя пользователя
  • data.email — email
  • data.role — роль (admin, user)
  • data.permissions — права доступа

Зоны (комнаты)

Получение списка зон

getZones() {
  return this.sendRequest('get', '/api/v2/zones');
}

Добавление зоны

addZone(data) {
  return this.sendRequest('post', '/api/v2/zones', data);
}

Параметры:

  • data.name — название зоны (например, “Гостиная”)
  • data.icon — иконка зоны

Обновление зоны

saveZone(id, data) {
  return this.sendRequest('put', `/api/v2/zones/${id}`, data);
}

Удаление зоны

deleteZone(id) {
  return this.sendRequest('delete', `/api/v2/zones/${id}`);
}

Устройства

Получение списка устройств

getDevices() {
  return this.sendRequest('get', '/api/v2/devices');
}

Возвращает: Массив всех устройств с их параметрами

Добавление устройства

addDevice(data) {
  return this.sendRequest('post', '/api/v2/devices', data);
}

Параметры:

  • data.name — название устройства
  • data.type — тип устройства
  • data.zone_id — ID зоны
  • data.config — конфигурация устройства

Обновление устройства

saveDevice(id, data) {
  return this.sendRequest('put', `/api/v2/devices/${id}`, data);
}

Удаление устройства

deleteDevice(id) {
  return this.sendRequest('delete', `/api/v2/devices/${id}`);
}

Управление устройством

Отправка команд устройству:

postData(data) {
  this.send('post-data', data);
}

Пример включения света:

postData({
  ident: 'light_bedroom_main',
  state: 'on',
  brightness: 80
});

Автоматизации (Actions)

Автоматизации — это настраиваемые действия для управления одним или несколькими устройствами одновременно. Например, “Выключить весь свет” или “Режим кино”.

Получение списка автоматизаций

getActions() {
  return this.sendRequest('get', '/api/v2/actions');
}

Сохранение автоматизации

saveAction(data) {
  return this.sendRequest('post', '/api/v2/actions', data);
}

Параметры:

  • data.name — название автоматизации (например, “Уходу из дома”)
  • data.devices — массив устройств и команд для выполнения
  • data.icon — иконка автоматизации

Сценарии (Scripts)

Сценарии — это автоматизация на основе условий и действий.

Получение списка сценариев

getScripts() {
  return this.sendRequest('get', '/api/v2/scripts');
}

Сохранение сценария

saveScript(data) {
  return this.sendRequest('post', '/api/v2/scripts', data);
}

Параметры:

  • data.name — название сценария
  • data.triggers — триггеры (условия запуска)
  • data.actions — действия при срабатывании
  • data.enabled — активен ли сценарий

Примеры использования

Пример 1: Получение данных об устройствах

// Подключение к серверу
const socket = new Socket();
socket.address = 'https://your-server.local';
socket.email = 'user@example.com';
socket.key = 'your-encryption-key';

socket.createSocket();

// Ожидание подключения
socket.on('connect', () => {
  socket.authenticate();
});

// Получение данных после аутентификации
socket.on('authenticate', () => {
  socket.getDevices().then(devices => {
    console.log('Устройства:', devices);
  });
});

Пример 2: Подписка на обновления в реальном времени

// Подписка на изменения устройств
socket.deviceSub().subscribe(data => {
  console.log('Устройства обновлены:', data);
  // Обновление интерфейса
});

// Подписка на уведомления
socket.notifySub().subscribe(notification => {
  console.log('Новое уведомление:', notification);
  // Показать уведомление пользователю
});

Пример 3: Управление светом

// Включение света на 50%
socket.postData({
  ident: 'light_living_room',
  state: 'on',
  brightness: 50
});

// Изменение цвета RGB лампы
socket.postData({
  ident: 'light_bedroom_rgb',
  state: 'on',
  color: {r: 255, g: 100, b: 50}
});

Пример 4: Создание автоматизации

// Создание сценария "Доброе утро"
const script = {
  name: 'Доброе утро',
  enabled: true,
  triggers: [
    {
      type: 'time',
      time: '07:00',
      days: [1, 2, 3, 4, 5] // Пн-Пт
    }
  ],
  actions: [
    {
      device: 'light_bedroom',
      state: 'on',
      brightness: 30
    },
    {
      device: 'coffee_maker',
      state: 'on'
    }
  ]
};

socket.saveScript(script).then(result => {
  console.log('Сценарий создан:', result);
});

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

Все методы sendRequest возвращают Promise, который может быть отклонен в случае ошибки:

socket.getDevices()
  .then(devices => {
    console.log('Успех:', devices);
  })
  .catch(error => {
    console.error('Ошибка:', error);
    // Обработка ошибки
  });

Также можно подписаться на глобальные ошибки:

socket.on('exception', (error) => {
  console.error('Системная ошибка:', error);
});

Поиск устройств

Поиск новых устройств в сети

socket.on('find-device', (devices) => {
  console.log('Найдены устройства:', devices);
});

Поиск WiFi сетей

socket.on('find-wifi', (networks) => {
  console.log('Доступные WiFi сети:', networks);
});

Безопасность

  1. Шифрование: Все данные между клиентом и сервером шифруются с использованием ключа key
  2. Аутентификация: Каждое соединение требует токен аутентификации
  3. Authorization header: REST запросы используют Bearer токен в заголовках

Пример безопасного запроса:

wsRequest({
  method: 'get',
  path: '/api/v2/devices',
  headers: {
    'Authorization': `Bearer ${this.token}`
  }
});

Поддержка

Если у вас возникли вопросы по использованию Client API: