# bluetooth_hc05

Library for the Bluetooth HC-05 module.

Author | Rob Jansen, Copyright © 2021..2021, all rights reserved.
Adapted-by |
Compiler | 2.5r5

Description

    JAL library for use of the Bluetooth HC-05 module.
                 Created for HC-05 firmware version: 4.0-20190815

Sources

    -) GHC-03/05 Embedded Bluetooth Serial Communication Module AT command set
                April, 2011
             -) EGBT-045MS-046S Hardware Manual & AT Commands Reference Manual
                Rev. 1r0

Notes

    The default serial interface of the HC-05 is 34800 baud, 1 stopbit,
           no parity and no flowcontrol.
           At least one of the JAL serial hardware libraries must be included and
           initialized by the main program with these settings.

Dependencies

No dependency found

## Summary

### Global variables/contants

- `const byte BLUETOOTH_HC05_INQUIRY_MODE_RSSI = 1`
- `const byte BLUETOOTH_HC05_BAUDRATE_19200 = 3`
- `const byte BLUETOOTH_HC05_PASSWORD_MAX_LENGTH = 16`
- `var byte bluetooth_hc05_bytes_received`
- `const byte BLUETOOTH_HC05_INQUIRY_MODE_STANDARD = 0`
- `const byte BLUETOOTH_HC05_BAUDRATE_115200 = 6`
- `const byte BLUETOOTH_HC05_BAUDRATE_460800 = 8`
- `var dword _bluetooth_hc05_wait_time`
- `var byte _bluetooth_hc05_read_pointer`
- `const byte BLUETOOTH_HC05_CONNECTION_MODE_SPECIFIC = 0`
- `const byte BLUETOOTH_HC05_BAUDRATE_1382400 = 10`
- `const byte BLUETOOTH_HC05_BAUDRATE_921600 = 9`
- `const byte BLUETOOTH_HC05_BAUDRATE_57600 = 5`
- `const byte BLUETOOTH_HC05_BAUDRATE_4800 = 1`
- `const byte BLUETOOTH_HC05_BAUDRATE_38400 = 4`
- `const byte BLUETOOTH_HC05_NAME_MAX_LENGTH = 32`
- `const byte BLUETOOTH_HC05_BAUDRATE_9600 = 2`
- `const byte BLUETOOTH_HC05_CONNECTION_MODE_TEST = 2`
- `const byte BLUETOOTH_HC05_ROLE_SLAVE_LOOP = 2`
- `const byte BLUETOOTH_HC05_ROLE_MASTER = 1`
- `const byte BLUETOOTH_HC05_ROLE_SLAVE = 0`
- `const byte BLUETOOTH_HC05_CONNECTION_MODE_ANY = 1`
- `const byte BLUETOOTH_HC05_BAUDRATE_230400 = 7`

### Procedures

- `bluetooth_hc05_data'put(byte in data)`
- `bluetooth_hc05_set_wait_time(dword in waittime)`

Private

- `_bluetooth_hc05_strip_crlf_from_receive_buffer()`
- `_bluetooth_hc05_send_byte_hex(byte in value)`
- `_bluetooth_hc05_flush_serial_receive_buffer()`
- `_bluetooth_hc05_purge_receive_buffer()`
- `_bluetooth_hc05_send_string(byte in string[])`
- `_bluetooth_hc05_send_crlf()`

### Functions

- `bluetooth_hc05_init() return bit`
- `bluetooth_hc05_set_inquire_access_code(dword in access_code) return bit`
- `bluetooth_hc05_get_device_name() return bit`
- `bluetooth_hc05_send_command(byte in command[]) return bit`
- `bluetooth_hc05_set_device_name(byte in name[]) return bit`
- `bluetooth_hc05_get_firmware_version() return bit`
- `bluetooth_hc05_get_device_password() return bit`
- `bluetooth_hc05_set_baudrate(byte in baudrate) return bit`
- `bluetooth_hc05_get_device_role(byte out role) return bit`
- `bluetooth_hc05_get_connection_mode(byte out connection_mode) return bit`
- `bluetooth_hc05_data_ready() return bit`
- `bluetooth_hc05_get_device_baudrate() return bit`
- `bluetooth_hc05_set_device_role(byte in role) return bit`
- `bluetooth_hc05_reset() return bit`
- `bluetooth_hc05_restore_default() return bit`
- `bluetooth_hc05_set_device_class(dword in class) return bit`
- `bluetooth_hc05_available() return bit`
- `bluetooth_hc05_get_inquire_access_code(dword out access_code) return bit`
- `bluetooth_hc05_clear_all_paired_devices() return bit`
- `bluetooth_hc05_data'get() return byte`
- `bluetooth_hc05_data_available() return bit`
- `bluetooth_hc05_get_device_class(dword out class) return bit`
- `bluetooth_hc05_set_device_password(byte in password[]) return bit`
- `bluetooth_hc05_initialize_ssp_profile() return bit`
- `bluetooth_hc05_set_connection_mode(byte in connection_mode) return bit`

Private

- `_bluetooth_hc05_ascii_to_binary() return dword`
- `_bluetooth_hc05_wait_and_get_data_ok() return bit`
- `_bluetooth_hc05_hex_char_to_value(byte in character) return byte`
- `_bluetooth_hc05_wait_and_find_token(byte in token[]) return bit`
- `_bluetooth_hc05_value_to_hex_char(byte in value) return byte`
- `_bluetooth_hc05_get_received_byte(byte out character) return bit`
- `_bluetooth_hc05_get_bluetooth_address_part() return dword`
- `_bluetooth_hc05_is_valid_ascii_hex(byte in character) return bit`
- `_bluetooth_hc05_find_token(byte in token[]) return bit`

## API details

### Global variables/contants

- `const byte BLUETOOTH_HC05_INQUIRY_MODE_RSSI = 1`

  No documentation found

- `const byte BLUETOOTH_HC05_BAUDRATE_19200 = 3`

  No documentation found

- `const byte BLUETOOTH_HC05_PASSWORD_MAX_LENGTH = 16`

      Other size definitions.

- `var byte bluetooth_hc05_bytes_received`

      The number of bytes available in the receive buffer (excluding 'OK').

- `const byte BLUETOOTH_HC05_INQUIRY_MODE_STANDARD = 0`

      Inquiry modes.

- `const byte BLUETOOTH_HC05_BAUDRATE_115200 = 6`

  No documentation found

- `const byte BLUETOOTH_HC05_BAUDRATE_460800 = 8`

  No documentation found

- `var dword _bluetooth_hc05_wait_time`

       Implementation -----------------------------------

      Wait for response of the HC-05 module in steps of 100 us.

- `var byte _bluetooth_hc05_read_pointer`

      We use a read pointer on the receive buffer so that we can more easily process
      the data.

- `const byte BLUETOOTH_HC05_CONNECTION_MODE_SPECIFIC = 0`

      Connection modes.

- `const byte BLUETOOTH_HC05_BAUDRATE_1382400 = 10`

  No documentation found

- `const byte BLUETOOTH_HC05_BAUDRATE_921600 = 9`

  No documentation found

- `const byte BLUETOOTH_HC05_BAUDRATE_57600 = 5`

  No documentation found

- `const byte BLUETOOTH_HC05_BAUDRATE_4800 = 1`

      Baudrate definitions. Default baudrate of the HC-05 module is 9600 baud.
      Baudrate setting is using no parity and one stopbit which is the default.

- `const byte BLUETOOTH_HC05_BAUDRATE_38400 = 4`

  No documentation found

- `const byte BLUETOOTH_HC05_NAME_MAX_LENGTH = 32`

  No documentation found

- `const byte BLUETOOTH_HC05_BAUDRATE_9600 = 2`

  No documentation found

- `const byte BLUETOOTH_HC05_CONNECTION_MODE_TEST = 2`

  No documentation found

- `const byte BLUETOOTH_HC05_ROLE_SLAVE_LOOP = 2`

  No documentation found

- `const byte BLUETOOTH_HC05_ROLE_MASTER = 1`

  No documentation found

- `const byte BLUETOOTH_HC05_ROLE_SLAVE = 0`

      Role definitions.

- `const byte BLUETOOTH_HC05_CONNECTION_MODE_ANY = 1`

  No documentation found

- `const byte BLUETOOTH_HC05_BAUDRATE_230400 = 7`

  No documentation found

### Procedures

- `bluetooth_hc05_data'put(byte in data)`

      Pseudo variable to send data to the module. Wait for the serial interface to
      be ready and send a data byte. Note that this is a blocking call until the
      previous byte is transmitted.

- `bluetooth_hc05_set_wait_time(dword in waittime)`

      Set the wait time for the HC-05 to respond. Time is set in 100 us times.

Private

- `_bluetooth_hc05_strip_crlf_from_receive_buffer()`

      Strip carriage return and linefeed from the end of the receive buffer

- `_bluetooth_hc05_send_byte_hex(byte in value)`

      Send on byte in ascii hex format to the module.

- `_bluetooth_hc05_flush_serial_receive_buffer()`

      Flush the serial receive buffer. Also reset the read pointer and
      the number of bytes received.

- `_bluetooth_hc05_purge_receive_buffer()`

      Purge the receive buffer, that is move all data starting at the read pointer
      to the first location of the receive buffer, removing stuff that we no
      longer need. The number of bytes in the receive buffer is adjusted and the
      read pointer is reset.

- `_bluetooth_hc05_send_string(byte in string[])`

      Sends the given string to the module over the serial interface. We will also
      clear the receive buffer to be prepared for the response.

- `_bluetooth_hc05_send_crlf()`

      Sends a carriage returen + linefeed over the serial interface.

### Functions

- `bluetooth_hc05_init() return bit`

      Initialize (reset) the module. The wait time is set to 1 second.
      Returns TRUE if succesful.

- `bluetooth_hc05_set_inquire_access_code(dword in access_code) return bit`

      Set the device access code. Returns TRUE when succesful.
      The access code is a 24 bit number.

- `bluetooth_hc05_get_device_name() return bit`

      Get the device name of the module. Returns TRUE if succesful. The
      device name is returned in the bluetooth_hc05_receive_buffer.

- `bluetooth_hc05_send_command(byte in command[]) return bit`

      Send a command to the module and return TRUE when succesful. This function
      can be used if the firmware of the module uses commands not supported by
      this library.

- `bluetooth_hc05_set_device_name(byte in name[]) return bit`

      Set the device name. The device name may not be longer than
      BLUETOOTH_HC05_NAME_MAX_LENGTH. Returns TRUE when succcesful.

- `bluetooth_hc05_get_firmware_version() return bit`

      Get the firmware version number. Returns TRUE if succesful. The version
      is returned in the bluetooth_hc05_receive_buffer.

- `bluetooth_hc05_get_device_password() return bit`

      Get the device password. Returns TRUE if succesful. The device password
      is returned in the bluetooth_hc05_receive_buffer.

- `bluetooth_hc05_set_baudrate(byte in baudrate) return bit`

      Set the baudrate of the module and the baudrate of the serial interface
      connected to the module. Returns TRUE when succesful. Baudrate is set
      to 1 stop bit, no parity.
      Note: The baudrate changes after a new power up of the module. Make sure
      that the baudrate of the PIC is also changed to this new baudrate
      after power up.

- `bluetooth_hc05_get_device_role(byte out role) return bit`

      Get the device role. Returns TRUE if succesful.

- `bluetooth_hc05_get_connection_mode(byte out connection_mode) return bit`

      Get the connection mode. Returns TRUE when succesful.

- `bluetooth_hc05_data_ready() return bit`

      Returns TRUE when data can be sent to the module. The data can then be sent
      by writing to the variable 'bluetooth_hc05_data'.

- `bluetooth_hc05_get_device_baudrate() return bit`

      Get the device baudrate. Returns TRUE if succesful. The device baudrate
      is returned in the bluetooth_hc05_receive_buffer.

- `bluetooth_hc05_set_device_role(byte in role) return bit`

      Set the role of the device. Return TRUE when succesful.

- `bluetooth_hc05_reset() return bit`

      Resets the bluetooth module.

- `bluetooth_hc05_restore_default() return bit`

      Restore the device to the factory defaults. Returns TRUE when succcesful.

- `bluetooth_hc05_set_device_class(dword in class) return bit`

      Set the device class. Returns TRUE when succesful. The device class
      is a 24 bit number.

- `bluetooth_hc05_available() return bit`

      Returns TRUE if the module is responding, otherwise FALSE is returned.
      When the module is connected to the host the response will also be FALSE.

- `bluetooth_hc05_get_inquire_access_code(dword out access_code) return bit`

      Get the device access code and return it as dword. Returns TRUE when succesful.
      The access code is a 24 bit number.

- `bluetooth_hc05_clear_all_paired_devices() return bit`

      Deletes all authenticated devices in the pair list.

- `bluetooth_hc05_data'get() return byte`

      Pseudo variable to receive data from the module. Wait for a data byte from
      the module and return it. Note that this is a blocking call until data is
      received.

- `bluetooth_hc05_data_available() return bit`

      Returns TRUE if data is received from the module. Data can then be obtained
      by reading from the variable 'bluetooth_hc05_data'.

- `bluetooth_hc05_get_device_class(dword out class) return bit`

      Get the device class and return it as dword. Returns TRUE when succesful.
      The device class is a 24 bit number.

- `bluetooth_hc05_set_device_password(byte in password[]) return bit`

      Set the device password. The password may not be longer than
      BLUETOOTH_HC05_PASSWORD_MAX_LENGTH. Returns TRUE when succesful.
      The default factory password is "1234".

- `bluetooth_hc05_initialize_ssp_profile() return bit`

      Initialize the SSP profile.

- `bluetooth_hc05_set_connection_mode(byte in connection_mode) return bit`

  No documentation found

Private

- `_bluetooth_hc05_ascii_to_binary() return dword`

      Convert the ascii string in the bluetooth_hc05_receive_buffer to a binary number.

- `_bluetooth_hc05_wait_and_get_data_ok() return bit`

      Wait for data from the module and copy all data to the bluetooth receive
      buffer until 'OK' is found. If 'OK' is found the function returns TRUE.
      The number of bytes in the receive buffer is stored in the global variable
      bluetooth_hc05_bytes_received and the read pointer is reset.
      Note that 'OK' is not stored in bluetooth_hc05_bytes_received but the
      carriage return and line feed are.

- `_bluetooth_hc05_hex_char_to_value(byte in character) return byte`

      Convert a hexadecimal ascii character to a value.

- `_bluetooth_hc05_wait_and_find_token(byte in token[]) return bit`

      Wait for data and find the given token in the receive buffer. Returns TRUE
      if the given token if found. The receive buffer is purged to remove the
      token from the buffer but the rest of the buffer remains.

- `_bluetooth_hc05_value_to_hex_char(byte in value) return byte`

      Convert a value to a hexadecimal ascii character.

- `_bluetooth_hc05_get_received_byte(byte out character) return bit`

      Get a byte from the bluetooth receive buffer. Returs TRUE if a byte is available.
      The read pointer is advanced to the next byte in the buffer.

- `_bluetooth_hc05_get_bluetooth_address_part() return dword`

      Get a part of the Bluetooth adress from the receive buffer. The receive
      buffer calculates the part of the address until ':' is received. The
      received data is hexadecimal.

- `_bluetooth_hc05_is_valid_ascii_hex(byte in character) return bit`

      Check if the given byte is a valid hexdeximal ascii character.
      Returns TRUE when OK.

- `_bluetooth_hc05_find_token(byte in token[]) return bit`

      Find the given token in the receive buffer. Returns TRUE if the given
      token if found. The read pointer is adjusted until the end of the token
      by the call the the get received byte function.

## Related samples

Here are the list of samples which use this library:

16f15325 | 16f15325_bluetooth_hc05_master.jal