Библиотека ioControl - описание функций

Библиотека ioControl - описание функций

Главная
/
Уроки и документации
/
Библиотека ioControl - описание функций

Файлы библиотеки

ZIP, GitHub

Для работы с Arduino IDE библиотеку необходимо установить. Ссылка на подробное описание как это сделать.

Подключение библиотеки

#include <iocontrol.h>

Инстанцирование (создание) объекта

iocontrol Obj( "ИМЯ_ПАНЕЛИ", ОБЪЕКТ_КЛИЕНТА );

или, если панель использует ключ:

iocontrol Obj( "ИМЯ_ПАНЕЛИ", "КЛЮЧ", ОБЪЕКТ_КЛИЕНТА );

Примеры:

До создания объекта библиотеки необходимо создать объект клиента того оборудования, которое будет использоваться и передать клиента этого оборудования в конструктор iocontrol.

  • Для ESP это WiFiClient;
  • для Ethernet Shield'a это EthernetClient;

Ethernet шилд

#include <iocontrol.h>

#include <SPI.h>
#include <Ethernet.h>

const char* myPanelName = "название_панели_на_сайте_iocontrol.ru";
// Если доступ к панели только по ключу
//const char* myKey = "ключ";

// создаём объект клиента Ethernet шилда
EthernetClient client;

// Передаём имя панели и объект клиента в конструктор iocontrol
iocontrol Obj("myPanelName", client);
// Или если панель использует ключ, передаём ключ
//iocontrol Obj("myPanelName", "myKey", client);

ESP32 и ESP8266

#include <iocontrol.h>

#include <WiFi.h> // для ESP32
//#include <ESP8266WiFi.h> // для ESP8266

const char* myPanelName = "название_панели_на_сайте_iocontrol.ru";
// Если доступ к панели только по ключу:
//const char* myKey = "ключ";

// создаём клиента WiFi
WiFiClient client;

// Передаём имя панели и объект клиента в конструктор iocontrol
iocontrol Obj("myPanelName", client);
// Или если панель использует ключ, передаём ключ
//iocontrol Obj("myPanelName", "myKey", client);

Описание функций библиотеки

Список функций

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

Функции для работы с модулем LED Матрица 8x8 - i2c

Функция begin()

  • Назначение: создание структуры данных в динамической памяти, инициирование работы с библиотекой
  • Синтаксис: Obj.begin()
  • Параметры: нет
  • Возвращаемые значения: int - результат инициализации (0 - успешная инициализация, значение отличное от нуля — номер статуса или ошибки. Подробнее см. Список статус кодов)
  • Примечание:
    • Функцию необходимо вызвать до обращения к любым другим функциям библиотеки;
    • Функцию достаточно вызвать один раз в коде setup
    • Функцию можно использовать для определения статуса или номера ошибки
  • Пример:
int status = Obj.begin();

/* При успешном выполнении функция возвращает 0.
 * Для удобства чтения кода в библиотеке определена
 * константа OK, равная нулю.
 */
if (status == OK) {
    Serial.println("OK");
}
else {
    // Выводим статус код
    Serial.println(status);
}

Функция readUpdate()

  • Назначение: Обновление значений всех переменных в памяти микроконтроллера на значения полученные с сервера.
  • Синтаксис: Obj.readUpdate()
  • Принимаемые параметры: нет
  • Возвращаемые значения: int - результат инициализации (0 - успешная инициализация, значение отличное от нуля - номер статуса или ошибки. Подробнее см. Список статус кодов)
  • Примечание:
    • Функция делает запросы через временной интервал, для предотвращения исчерпывания лимита запросов (подробнее про лимиты). 
    • Функцию необходимо вызывать в цикле loop(), если необходимо прочитать значения переменных с сервера. Функции readInt(), readFloat() и readString() читают переменные из памяти микроконтроллера.
  • Пример:
Obj.readUpdate();
int myInt = Obj.readInt("myIntName");

Функция writeUpdate()

  • Назначение: Обновление значений всех переменных на сервере на значения полученные из памяти микроконтроллера.
  • Синтаксис: Obj.writeUpdate()
  • Принимаемые параметры: нет
  • Возвращаемые значения: int - результат инициализации (0 - успешная инициализация, значение отличное от нуля - номер статуса или ошибки. Подробнее см. Список статус кодов)
  • Примечание:
    • Функция делает запросы через временной интервал, для предотвращения исчерпывания лимита запросов (подробнее про лимиты). 
    • Функцию необходимо вызывать в цикле loop(), если необходимо отправить переменные на сервер. Функции write() записывают переменные в память микроконтроллера.
  • Пример:
int myint = 42;

// Записываем переменную myint в ячейку памяти микроконтроллера
// соответствующую переменной myIoVar на сайте iocontrol.ru
Obj.write("myIoVar", myint);

/* Отправляем все подготовленные переменные на сайт.
 * Функция отправит запрос, только если превышен интервал
 * ожидания после предыдущего запроса.
 */
int status = Obj.writeUpdate();

if (status == OK)
    Serial.println("Updated");
else
    Serial.println(status);

Функция readInt()

  • Назначение: чтение целочисленной переменной
  • Синтаксис: Obj.readInt( НАЗВАНИЕ )
  • Принимаемые параметры:
    • НАЗВАНИЕ: String или char* - название переменной в панели на сайте iocontrol.ru
  • Возвращаемые значения: long - значение переменной в панели на сайте iocontrol.ru
  • Примечание:
  • Пример:
int myInt = 0;

if (Obj.readUpdate() == OK)
    myInt = Obj.readInt("myIntName");

Функция readFloat()

  • Назначение: чтение переменной вещественного числа с плавающей точкой
  • Синтаксис: Obj.readFloat( НАЗВАНИЕ )
  • Принимаемые параметры:
    • НАЗВАНИЕ: String или char* - название переменной в панели на сайте iocontrol.ru
  • Возвращаемые значения: float - значение переменной в панели на сайте iocontrol.ru
  • Пример:
float myFloat = 0.0;

// Обновляем переменные с сайта в памяти микроконтроллера
if (Obj.readUpdate() == OK)
    // Читаем переменную myFloatName с сайта и записываем в переменную myFloat
    myFloat = Obj.readFloat("myFloatName");

Функция getFloatPrec()

  • Назначение: получение количества знаков после точки (точность) вещественного числа
  • Синтаксис: Obj.getFloatPrec( НАЗВАНИЕ )
  • Принимаемые параметры:
    • НАЗВАНИЕ: String или char* - название переменной в панели на сайте iocontrol.ru
  • Возвращаемые значения: uint8_t - количество знаков после точки переменной float типа
  • Примечание: функция может быть полезной для вывода переменной float в монитор серийного порта или преобразования в объект String. Например: String s = String(Obj.readFloat("myFloat"), Obj.getFloatPrec("myFloat"));
  • Пример:
// Читаем переменную
float myFloat = Obj.readFloat("myFloatName");

// сохраняем количество знаков после точки
uint8_t prec = Obj.getFloatPrec("myFloatName");

// Выводим вещественную переменную, указывая количество знаков после точки
Serial.println(myFloat, prec);

// Преобразуем в объект String
String s = String(myFloat, prec);

Функция readString()

  • Назначение: чтение строковой переменной
  • Синтаксис: Obj.readString( НАЗВАНИЕ )
  • Принимаемые параметры:
    • НАЗВАНИЕ: String или char* - название переменной в панели на сайте iocontrol.ru
  • Возвращаемые значения: String - значение переменной в панели на сайте iocontrol.ru
  • Примечание:
  • Пример:
String myString = "";

// Обновляем переменные с сайта в памяти микроконтроллера
if (Obj.readUpdate() == OK)
    // Читаем переменную myStringName с сайта и записываем в переменную myString
    myString = Obj.readString("myStringName");

Функция readBool()

  • Назначение: чтение переменной булева числа
  • Синтаксис: Obj.readBool( НАЗВАНИЕ )
  • Принимаемые параметры:
    • НАЗВАНИЕ: String или char* - название переменной в панели на сайте iocontrol.ru
  • Возвращаемые значения: bool - значение переменной в панели на сайте iocontrol.ru
  • Пример:
bool myBool = false;

// Обновляем переменные с сайта в памяти микроконтроллера
if (Obj.readUpdate() == OK)
    // Читаем переменную myBoolName с сайта и записываем в переменную myBool
    myBool = Obj.readBool("myBoolName");

Функция write()

  • Назначение: запись переменной на сайт
  • Синтаксис: Obj.write( НАЗВАНИЕ, ПЕРЕМЕННАЯ )
  • Принимаемые параметры:
    • НАЗВАНИЕ: String или char* - название переменной в панели на сайте iocontrol.ru
    • ПЕРЕМЕННАЯ: bool, int, unsigned int, long, unsigned long, float, String - переменная, значение которой необходимо отправить на сайт iocontrol.ru
  • Возвращаемые значения: нет
  • Пример:
float myFloat = 3.1415;
int myInt = 42;

// Записываем целочисленную переменную
Obj.write("myIntName", myInt);
// Записываем вещественную переменную
Obj.write("myFloatName", myFloat);

// Обновляем переменные на сайте
if (Obj.writeUpdate() == OK)
    Serial.println("updated");

Функция info()

  • Назначение: Формирование строки информации о текущей панели, например для вывода в монитор последовательного порта
  • Синтаксис: Serial.println(Obj.info())
  • Принимаемые параметры: нет
  • Возвращаемые значения: объект String
  • Примечание: Для вывода информации последовательный порт должен быть инициирован (например, Serial.begin(9600))
  • Пример:
Serial.begin(9600);
Obj.begin();
// Выводим информацию о панели
Serial.println(Obj.info());

Функция setDeviceCountOnIP()

  • Назначение: Установка множителя интервала запросов для нескольких устройств на одном IP адресе
  • Синтаксис: Obj.setDeviceCountOnIP( КОЛИЧЕСТВО )
  • Принимаемые параметры: uint8_t КОЛИЧЕСТВО - количество устройств на одном IP адресе, использующих сервис iocontrol.ru
  • Возвращаемые значения: нет
  • Примечание:
    • Необходимо вызвать до функции begin()
    • Сервер iocontrol ведёт учёт количества запросов по IP адресу. Если Ваша локальная сеть работает через NAT, то все устройства в ней будут выглядеть как один IP адрес для сервера. Функции библиотеки readUpdate() и writeUpdate() делают запросы на сервер через интервал, установленный сервером. В случае если у Вас в сети несколько устройств, использующих сервис, запросы на сервер будут поступать чаще во столько раз, сколько у Вас устройств. В таком случае, сервер может дать отказ в доступе из-за превышения лимита запросов. С помощью этой функции можно установить множитель, равный количеству устройств в локальной сети. Так же можно обойтись без использования этой функции, посчитав время запросов вручную и установив соответствующий delay() в функции loop(). Подробнее про лимиты сервиса можно узнать по ссылке.
  • Пример:
Obj.setDeviceCountOnIP(2);
Obj.begin();

Функция setHttps()

  • Назначение: Переключение объекта библиотеки в режим работы через протокол HTTPS
  • Синтаксис: Obj.setHttps()
  • Принимаемые параметры: нет
  • Возвращаемые значения: нет
  • Примечание:
    • Необходимо вызвать до функции begin()
  • Пример:
Obj.setHttps();
Obj.begin();

На заметку: функции ниже предназначены для работы с матрицами 8x8, которые подключаются к Ardiuno по шине i2c

Функция readMatrix()

  • Назначение: чтение изображения матрицы 8x8 с сайта
  • Синтаксис: Obj.readMatrix( НАЗВАНИЕ, МАССИВ )
  • Принимаемые параметры:
    • НАЗВАНИЕ: String или char* - название переменной в панели на сайте iocontrol.ru
    • МАССИВ: массив uint8_t из 8 байтов, изображение матрицы 8x8.
  • Возвращаемые значения: нет
  • Пример:
uint8_t image[8]{0};

// Читаем изображение матрицы с сайта в переменную
Obj.readMatrix("myMatrix", image);

//Выводим изображение на матрицу 8x8
MatrixObj.drawImage(image);

Функция writeMatrix()

  • Назначение: запись изображения матрицы 8x8 на сайт
  • Синтаксис: Obj.writeMatrix( НАЗВАНИЕ, МАССИВ )
  • Принимаемые параметры:
    • НАЗВАНИЕ: String или char* - название переменной в панели на сайте iocontrol.ru
    • МАССИВ: массив uint8_t из 8 байтов, изображение матрицы 8x8.
  • Возвращаемые значения: нет
  • Пример:
uint8_t image[8] = {
                    0b00000000,
                    0b00100100,
                    0b00000000,
                    0b00000000,
                    0b01000010,
                    0b00111100,
                    0b00000000,
                    0b00000000
};

//Записываем изображение в переменную на сайт
Obj.writeMatrix("myMatrix", image);

Obj.writeUpdate();

Список статус кодов

Код Значение
100-599 статус коды HTTP
601 пустой JSON
602 некорректный JSON
603 программе не удалось прочитать тип переменной
604 пустая панель iocontrol
606 нет изменений значений переменных после последнего запроса
701 некорректный заголовок HTTP
702 не истёк интервал между запросами
703 некорректный ответ от сервера
801 не удалось подключиться к серверу
1002 не указано имя панели или имя панели некорректной длины
1003 панель с таким именем не существует или к ней возможен только по ключу
1004 не указано имя переменной
1005 некорректное имя переменной
1007 не указан параметр передаваемого значения
1008 ошибка сохранения в базу данных
Главная
Панели
Кабинет
О сервисе
Библиотека
    Для работы с Arduino, Piranha, ESP32 или ESP8266
  • Скачать: ZIP, GitHub