Описание библиотеки Bluetooth_HC05

Библиотека предназначена для работы с Bluetooth-модулем HC-05 и реализует все 36 функций, описанных в документации (datasheet) к модулю от компании Wavesen, в виде класса Bluetooth_HC05 и его методов. Почти все методы принимают в качестве последнего агрумента тайм-аут на чтение ответа от модуля (в миллисекундах). К класс Bluetooth_HC05 реализует интерфейс Print так что вы можете посылать данные, пользуясь методом print(), как в объект класса Serial. В качестве источника информации был использован китайский даташит с кучей ошибок и неясностей - такие места я буду обозначать специальным значком: 狗屁. Если вы видите этот значок в описании - значит, я ничерта не понял из документации и объяснить не могу.

По умолчанию скорость работы модуля - 38400 бод. Для правильной инициализации модуля требуется примерно 700 мс, так что сразу после вызова метода begin() желательно выдержать паузу в 1 секунду для гарантии.

  1. Методы
  2. Константы
  3. Типы

Методы

void begin(
  unsigned baud_rate = 38400,
  uint8_t reset_pin = 0xFF,
  uint8_t mode_pin = 0xFF,
  HC05_Mode mode = HC05_MODE_DATA
);
Подключает модуль HC-05

bool probe(unsigned long timeout = HC05_DEFAULT_TIMEOUT);
Простой тест работоспособности модуля путём посылки команды AT.

void hardReset();
Перезагружает модуль, прижимая его вывод RESET к 0 на 6 мс. Пин для управления выводом RESET задаётся в методе begin().

bool softReset(unsigned long timeout = HC05_DEFAULT_TIMEOUT);
Перезагружает модуль, посылая команду AT+RESET. Разумеется, это менее надёжно, чем управление выводом RESET.

bool getVersion(
  char *buffer,
  size_t buffer_size,
  unsigned long timeout = HC05_DEFAULT_TIMEOUT
);
Запрашивает версию и кладёт её в массив buffer размера buffer_size. Если размер буфера слишком мал, занесётся только влезающая по размеру часть версии.

bool restoreDefaults(unsigned long timeout = HC05_DEFAULT_TIMEOUT);
Восстанавливает заводские настройки: тип устройства 0 (неизвестное устрйоство), код опроса IAC - 0x009e8b33, роль - slave, соединение - по заданному адресу, скорость 38400 бод, 1 стоп-бит, без бита чётности, пароль - 1234, имя модуля - H-C-2010-06-01

bool getAddress(
  BluetoothAddress &address,
  unsigned long timeout = HC05_DEFAULT_TIMEOUT
);
Возвращает Bluetooth-адрес модуля в address.

bool getName(
  char *buffer,
  unsigned long timeout = HC05_DEFAULT_TIMEOUT
);
Возвращает имя модуля в buffer, размер которого должен быть не менее HC05_NAME_BUFSIZE.

bool setName(
  const char *name,
  unsigned long timeout = HC05_DEFAULT_TIMEOUT
);
Устанавливает имя модуля.

bool getRemoteDeviceName(
  const BluetoothAddress &address,
  char *buffer,
  size_t buffer_size,
  unsigned long timeout = HC05_DEFAULT_TIMEOUT
);
Возвращает имя устройства с адресом address в buffer размером buffer_size.

bool getRole(
  HC05_Role &role,
  unsigned long timeout = HC05_DEFAULT_TIMEOUT
);
Возвращает текущую роль модуля в role.

bool setRole(
  HC05_Role role,
  unsigned long timeout = HC05_DEFAULT_TIMEOUT
);
Устанавливает роль модуля.

bool getDeviceClass(
  uint32_t &device_class,
  unsigned long timeout = HC05_DEFAULT_TIMEOUT
);
Возвращает класс устройства в device_class.

bool setDeviceClass(
  uint32_t device_class,
  unsigned long timeout = HC05_DEFAULT_TIMEOUT
);
Устанавливает класс устройства

bool getInquiryAccessCode(
  uint32_t &iac,
  unsigned long timeout = HC05_DEFAULT_TIMEOUT
);
Возвращает в iac код опроса IAC.

bool setInquiryAccessCode(
  uint32_t iac,
  unsigned long timeout = HC05_DEFAULT_TIMEOUT
);
Устанавливает IAC.

bool getInquiryMode(
  HC05_InquiryMode &inq_mode,
  int16_t &max_devices,
  uint8_t &max_duration,
  unsigned long timeout = HC05_DEFAULT_TIMEOUT
);
Возвращает настройки опроса (inquiry): режим опроса в inq_mode, максимальное число опрашиваемых устройств в max_devices, максимальную длительность в max_duration (в интервалах по 1.28 с 狗屁).

bool setInquiryMode(
  HC05_InquiryMode inq_mode,
  int16_t max_devices,
  uint8_t max_duration,
  unsigned long timeout = HC05_DEFAULT_TIMEOUT
);
Устанавливает настройки опроса.

bool getPassword(
  char *buffer,
  unsigned long timeout = HC05_DEFAULT_TIMEOUT
);
Возвращает пароль в buffer, который должет иметь размер не менее HC05_PASSWORD_BUFSIZE.

bool setPassword(
  const char *password,
  unsigned long timeout = HC05_DEFAULT_TIMEOUT
);
Устанавливает новый пароль.

bool getSerialMode(
  uint32_t &speed,
  uint8_t &stop_bits,
  HC05_Parity &parity,
  unsigned long timeout = HC05_DEFAULT_TIMEOUT
);
Возвращает настройки UART: скорость в speed, число стоп-битов в stop_bits, настройки чётности в parity.

bool setSerialMode(
  uint32_t speed,
  uint8_t stop_bits,
  HC05_Parity parity,
  unsigned long timeout = HC05_DEFAULT_TIMEOUT
);
Устанавливает настройки UART.

bool getConnectionMode(
  HC05_Connection &connection_mode,
  unsigned long timeout = HC05_DEFAULT_TIMEOUT
);
Возвращает режим соединения в connection_mode.

bool setConnectionMode(
  HC05_Connection connection_mode,
  unsigned long timeout = HC05_DEFAULT_TIMEOUT
);
Устанавливает режим соединения.

bool bind(
  const BluetoothAddress &address,
  unsigned long timeout = HC05_DEFAULT_TIMEOUT
);
Привязывает модуль к устройству с адресом address. Адрес 00:00:00:00:00:00 означает, что модуль не привязан к конкретному устройству.

bool getAddressBound(
  BluetoothAddress &address,
  unsigned long timeout = HC05_DEFAULT_TIMEOUT
);
Возвращает адрес, к которуму привязан модуль, в address.

bool getLeds(
  bool &led_status,
  bool &led_connection,
  unsigned long timeout = HC05_DEFAULT_TIMEOUT
);
Возвращает состояния (включен/выключен) индикаторов (светодиодов) статуса (PIO8) в led_status и соединения (PIO9) в led_connection.

bool setLeds(
  bool led_status,
  bool led_connection,
  unsigned long timeout = HC05_DEFAULT_TIMEOUT
);
Устанавливает состояния индикаторов статуса и соединения.

bool setPortState(
  uint8_t port_num,
  uint8_t port_state,
  unsigned long timeout = HC05_DEFAULT_TIMEOUT
);
Задаёт состояние port_num порта PIO с номером port_state.

bool getMultiplePorts(
  uint16_t &port_states,
  unsigned long timeout = HC05_DEFAULT_TIMEOUT
);
Возвращает состояния портов PIO в port_states в виде битовой маски: например, результат 0x008 (1 << 3) означает, что на PIO3 - логическая 1, а на остальных - 0.

bool setMultiplePorts(
  uint16_t port_states,
  unsigned long timeout = HC05_DEFAULT_TIMEOUT
);
Устанавливает состояние портов PIO.

bool getInquiryAndPagingParams(
  uint16_t &inquiry_interval,
  uint16_t &inquiry_duration,
  uint16_t &paging_interval,
  uint16_t &paging_duration,
  unsigned long timeout = HC05_DEFAULT_TIMEOUT
);
Возвращает интервалы и длительности опроса и какого-то paging 狗屁

bool setInquiryAndPagingParams(
  uint16_t inquiry_interval,
  uint16_t inquiry_duration,
  uint16_t paging_interval,
  uint16_t paging_duration,
  unsigned long timeout = HC05_DEFAULT_TIMEOUT
);
Устанавливает параметры, которые возвращает getInquiryAndPagingParams() 狗屁

bool getSniffParams(
  uint16_t &max_time,
  uint16_t &min_time,
  uint16_t &retry_interval,
  uint16_t &sniff_timeout,
  unsigned long timeout = HC05_DEFAULT_TIMEOUT
);
Возвращает параметры энергосберегающего (?) режима 狗屁

bool setSniffParams(
  uint16_t max_time,
  uint16_t min_time,
  uint16_t retry_interval,
  uint16_t sniff_timeout,
  unsigned long timeout = HC05_DEFAULT_TIMEOUT
);
Устанавливает параметры, которые возвращает getSniffParams() 狗屁

bool enterSniffMode(unsigned long timeout = HC05_DEFAULT_TIMEOUT);
Войти в режим энергосбережения (?) 狗屁

bool exitSniffMode(unsigned long timeout = HC05_DEFAULT_TIMEOUT);
Выйти и режима энергосбережения (?) 狗屁

bool getSecurityAndEncryption(
  HC05_Security &security,
  HC05_Encryption &encryption,
  unsigned long timeout = HC05_DEFAULT_TIMEOUT
);
Возвращает в security настройки безопасности соединения, а в encryption - настройки шифрования.

bool setSecurityAndEncryption(
  HC05_Security security,
  HC05_Encryption encryption,
  unsigned long timeout = HC05_DEFAULT_TIMEOUT
);
Устаннавливает настройки безопасности и шифрования соединения.

bool deleteDeviceFromList(
  const BluetoothAddress &address,
  unsigned long timeout = HC05_DEFAULT_TIMEOUT
);
Удаляет устройство с адресом address из списка авторизованных.

bool deleteAllDevicesFromList(unsigned long timeout = HC05_DEFAULT_TIMEOUT);
Удаляет все адреса устройств из списка авторизованных (оцищает список).

bool findDeviceInList(
  const BluetoothAddress &address,
  unsigned long timeout = HC05_DEFAULT_TIMEOUT
);
Ищет устройство с адресом address в списке авторизованных. Возвращает true, если устройство в списке.

bool countDevicesInList(
  uint8_t &device_count,
  unsigned long timeout = HC05_DEFAULT_TIMEOUT
);
Возвращает длину списка авторизованных устройств.

bool getLastAuthenticatedDevice(
  BluetoothAddress &address,
  unsigned long timeout = HC05_DEFAULT_TIMEOUT
);
Возвращает адрес последнего авторизованного устройства в address.

bool getState(
  HC05_State &state,
  unsigned long timeout = HC05_DEFAULT_TIMEOUT
);
Возвращает текущее состояние модуля в state.

bool initSerialPortProfile(unsigned long timeout = HC05_DEFAULT_TIMEOUT);
Инициализирует профиль последовательного порта. Только после этого модуль сможет устанавливать соединения.

bool inquire(
  InquiryCallback callback,
  unsigned long timeout = HC05_DEFAULT_TIMEOUT
);
Опрашивает Bluetooth-устройства в эфире. В качестве аргумента callback нужно передать адрес функции, принимающей Bluetooth-адрес - inquire() будет вызывать её каждый раз при обнаружении нового устройства в эфире.

bool cancelInquiry(unsigned long timeout = HC05_DEFAULT_TIMEOUT);
Останавливает опрос устройств.

bool pair(
  const BluetoothAddress &address,
  unsigned long timeout = HC05_DEFAULT_TIMEOUT
);
Образует пару с указанным устройством (address).

bool connect(
  const BluetoothAddress &address,
  unsigned long timeout = HC05_DEFAULT_TIMEOUT
);
Образует соединение с указанным устройством (address).

bool disconnect(unsigned long timeout = HC05_DEFAULT_TIMEOUT);
Разрывает соединение.

HC05_Result getLastError();
Возвращает код результата последней выполненной команды.

Константы

HC05_DEFAULT_TIMEOUT
Тайм-аут по умолчанию для большинства команд.

HC05_INQUIRY_DEFAULT_TIMEOUT
Тайм-аут по умолчанию для опроса (inquiry) Bluetooth-устройств.

HC05_PAIRING_DEFAULT_TIMEOUT
Тайм-аут по умолчанию для образования пары (pairing) между устройствами.

HC05_PASSWORD_MAXLEN
Максимальная длина пароля (PIN-кода), которую позволяет задать модуль.

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

HC05_NAME_MAXLEN
Максимальная длина имени устройства.

HC05_NAME_BUFSIZE
Размер буфера для имени устройства.

HC05_ADDRESS_MAXLEN
Максимальная длина строкового представления адреса Bluetooth-устройства.

HC05_ADDRESS_BUFSIZE
Размер буфера для строкового представления Bluetooth-адреса.

Типы

BluetoothAddress
Адрес Bluetooth-устройства, 6-байтовый массив

InquiryCallback
Callback-функция, принимающая в качестве аргумента адрес Bluetooth-устройства. Вызывается методом inquire() при обнаружении очередного Bluetooth-устройства в эфире.

HC05_Mode
Режим работы модуля

HC05_MODE_DATA
приём-передача данных

HC05_MODE_COMMAND
управление AT-командами

HC05_Role
Роль Bluetooth-модуля

HC05_ROLE_SLAVE
Пассивное подключение (к модулю можно подключаться)

HC05_ROLE_MASTER
Активное подключение (модуль сам подключается к устройствам)

HC05_ROLE_SLAVE_LOOP
Пассивное подключение с эхом: все принятые данные передаются обратно

HC05_InquiryMode
Режим опроса устройств

HC05_INQUIRY_STANDARD
Обычный (все устройства)

HC05_INQUIRY_RSSI
Только устройства с RSSI

HC05_Parity
Использование бита чётности

HC05_NO_PARITY
Без бита чётности

HC05_PARITY_ODD
Нечётный

HC05_PARITY_EVEN
Чётный

HC05_Connection
Режим соединения

HC05_CONNECT_BOUND
Принимать соединение только от устройства с определённым адресом, задаваемым методом bind()

HC05_CONNECT_ANY
Принимать соединения от любых устройств

HC05_CONNECT_SLAVE_LOOP
slave-loop?狗屁

HC05_Security
Настройки безопасности

HC05_SEC_OFF
Выключено?狗屁

HC05_SEC_NON_SECURE
Незащищённое соединение

HC05_SEC_SERVICE
Защита на сервисном уровне (service-level)

HC05_SEC_LINK
Защита на уровне соединения (link-level)

HC05_SEC_UNKNOWN
Неизвестный режим?狗屁

HC05_Encryption
Настройки шифрования (см. статью по безопасности, раздел Packet Encryption)

HC05_ENC_OFF
Без шифрования

HC05_ENC_PTP
Шифруется только трафик PTP (point-to-point)

HC05_ENC_PTP_BROADCAST
Шифруется весь трафик

HC05_State
Состояние модуля

HC05_INITIALIZED
Инициализирован

HC05_READY
Готов. К чему?狗屁

HC05_PAIRABLE
Готов к образованию пары

HC05_PAIRED
Образована пара

HC05_INQUIRING
Опрашивает устройства

HC05_CONNECTING
Соединяется

HC05_CONNECTED
Соединён

HC05_DISCONNECTED
Отсоединён

HC05_UNKNOWN
Неизвестное состояние?狗屁

HC05_Result
Результат последней выполненной команды

HC05_OK
Команда выполнена успешно

HC05_FAIL
Ошибка выполнения, причина неизвестна狗屁

HC05_ERR_TIMEOUT
Вышло время ожидания ответа от модуля

HC05_ERR_ARGUMENT
Методу переданы неверные аргументы

HC05_ERR_DISC_LINK_LOSS
Связь с устройсвом потеряна

HC05_ERR_DISC_NO_SLC
狗屁

HC05_ERR_DISC_TIMEOUT
Тайм-аут отсоединения?狗屁

HC05_ERR_DISC_ERROR
Ошибка отсоединения?狗屁

HC05_ERR_AT_COMMAND
Ошибка синтаксиса AT-команды

HC05_ERR_DEFAULT_RESULT
Результат по умолчанию?狗屁

HC05_ERR_PSKEY_WRITE
Ошибка сохранения пароля

HC05_ERR_DEVICE_NAME_TOO_LONG
Слишком длиное имя устройства

HC05_ERR_NO_DEVICE_NAME
Имя устройства не указано

HC05_ERR_NAP_TOO_LONG
Часть адреса NAP слишком длинная

HC05_ERR_UAP_TOO_LONG
Часть адреса UAP слишком длинная

HC05_ERR_LAP_TOO_LONG
Часть адреса LAP слишком длинная

HC05_ERR_NO_PIO_MASK
Не указана маска портов

HC05_ERR_NO_PIO_NUMBER
Не указан номер порта

HC05_ERR_NO_DEVICE_TYPE
Не указан класс устройства

HC05_ERR_DEVICE_TYPE_TOO_LONG
Слишком длинное значение класса устройства

HC05_ERR_NO_IAC
Пустой код опроса IAC (Inquire Access Code)

HC05_ERR_IAC_TOO_LONG
Слишком длинный IAC

HC05_ERR_INVALID_IAC
Недопустимый IAC

HC05_ERR_NO_PASSWORD
Пароль пуст

HC05_ERR_PASSWORD_TOO_LONG
Слишком длинный пароль

HC05_ERR_INVALID_MODULE_ROLE
Неверная роль устройства

HC05_ERR_INVALID_BAUD_RATE
Недопустимая скорость передачи

HC05_ERR_INVALID_STOP_BITS
Недопустимая настройка стоп-битов

HC05_ERR_INVALID_PARITY_BITS
Недопустимая настройка бита чётности

HC05_ERR_DEVICE_NOT_IN_LIST
Устройство не в списке авторизованных

HC05_ERR_SPP_NOT_INITIALIZED
Профиль последовательного порта (SPP, Serial Port Profile) не инициализирован

HC05_ERR_SPP_REINIT
Повторная инициализация SPP

HC05_ERR_INVALID_INQUIRY_MODE
Недопустимый режим опроса

HC05_ERR_INQUIRY_TIMEOUT_TOO_LONG
Слишком большой тайм-аут опроса

HC05_ERR_NO_BLUETOOTH_ADDRESS
Не указан Bluetooth-адрес

HC05_ERR_SECURITY_MODE
Недопустимый режим безопасности

HC05_ERR_ENCRYPTION_MODE
Недопустимый режим шифрования