# esp8266

ESP8266 Library for interfacing with an ESP8266 module via the USART.

Author | Rob Jansen, Copyright © 2018..2019, all rights reserved.
Adapted-by |
Compiler | 2.5r2

Description

    ----------
    Library for using the ESP8266 Wifi Module based on version 2.0.0 of the
    ESP8166 AT command set. Some functionality provided by this library:
    -) Supports Wifi, TCP, UDP and SSL
    -) Supports client and server mode
    -) Supports mutlti connection mode

Sources

    ------
    Inspired by https://github.com/bportaluri/WiFiEsp
    See ESP8266 Instruction Set version 2.0.0 and
    https://room-15.github.io/blog/2015/03/26/esp8266-at-command-reference/

Notes

    ----
    In order to make the use of this library more easy, all public pins
    constants, variable, functions and procedures are mentioned at the
    start of this library.
    Since the ESP8266 uses the USART as interface, function and procedure
    paramaters are mostly character (string) based.
    When using the device as web server, a sufficiently large receive buffer is
    needed as to be able to parse all received data.
    This library was tested using an ESP8266 ESP-12F.

Dependencies

- serial_hw_int_cts

## Summary

### Global variables/contants

- `const byte ESP8266_MODE_AP = 2`
- `const byte ESP8266_ERROR = 3`
- `const byte ESP8266_IDLE = 0`
- `const byte ESP8266_DISCONNECTED = 2`
- `const byte ESP8266_DEFAULT_CONNECTION = 0`
- `var word esp8266_bytes_received`
- `var byte _esp8266_link_id`
- `var byte _esp8266_mode`
- `const byte _ESP8266_LINE_FEED = 0x0A`
- `const byte ESP8266_MODE_STATION = 1`
- `const byte _ESP8266_COLON = 0x3A`
- `const byte _ESP8266_DOUBLE_QUOTE = 0x22`
- `const byte ESP8266_MODE_AP_STATION = 3`
- `const serial_hw_baudrate = 115200`
- `const byte _ESP8266_COMMA = 0x2C`
- `const byte _ESP8266_CARRIAGE_RETURN = 0x0D`
- `const _ESP8266_ACK_WAIT_TIME_US = 500_000`
- `const word _ESP8266_MAX_DATA_BYTES = 2048`
- `const byte ESP8266_CONNECTED = 1`
- `const dword _ESP8266_RESPONSE_TIMEOUT_10_US = 1_500_000`

### Procedures

- `esp8266_set_connection(byte in link_id)`
- `esp8266_give_serial_byte(byte out character)`

Private

- `_esp8266_copy_response()`
- `_esp8266_flush_serial_receive_buffer()`
- `_esp8266_send_data(byte in command[])`

### Functions

- `esp8266_reset() return bit`
- `esp8266_get_bssid() return bit`
- `esp8266_get_rssi() return bit`
- `esp8266_get_connection() return byte`
- `esp8266_get_ip_address() return bit`
- `esp8266_get_ap_ip_address() return bit`
- `esp8266_restore() return bit`
- `esp8266_get_ssid() return bit`
- `esp8266_server_start(byte in port[]) return bit`
- `esp8266_client_stop() return bit`
- `esp8266_get_mac_address() return bit`
- `esp8266_init() return bit`
- `esp8266_client_start_ssl(byte in host[], byte in port[]) return bit`
- `esp8266_server_stop(byte in port[]) return bit`
- `esp8266_close_connection() return bit`
- `esp8266_set_server_timeout(byte in timeout[]) return bit`
- `esp8266_start_ap(byte in ssid[], byte in password[], byte in channel[], byte in encoding[], byte in espmode[]) return bit`
- `esp8266_set_ap_ip_address(byte in ip_address[]) return bit`
- `esp8266_alive() return bit`
- `esp8266_data_available() return bit`
- `esp8266_connect_to_ap(byte in ssid[], byte in password[]) return bit`
- `esp8266_ping(byte in host[]) return bit`
- `esp8266_send_data(byte in command[]) return bit`
- `esp8266_disconnect_from_ap() return bit`
- `esp8266_get_data(byte out connection) return bit`
- `esp8266_client_start_tcp(byte in host[], byte in port[]) return bit`
- `esp8266_get_connection_status() return byte`
- `esp8266_client_start_udp(byte in host[], byte in port[]) return bit`
- `esp8266_get_channel() return bit`

Private

- `_esp8266_acknowledge() return bit`
- `_esp8266_strip_double_quoto() return bit`
- `_esp8266_check_response(byte in token[]) return bit`
- `_esp8266_extract_item(byte in item_number) return bit`
- `_esp8266_get_character(byte out character) return bit`
- `_esp8266_client_start(byte in connection_type[], byte in host[], byte in port[]) return bit`

## API details

### Global variables/contants

- `const byte ESP8266_MODE_AP = 2`

  No documentation found

- `const byte ESP8266_ERROR = 3`

  No documentation found

- `const byte ESP8266_IDLE = 0`

      Connection status declarations.

- `const byte ESP8266_DISCONNECTED = 2`

  No documentation found

- `const byte ESP8266_DEFAULT_CONNECTION = 0`

      The default of is not by accident since in server mode the ESP8266 will
      also use this ID.

- `var word esp8266_bytes_received`

      Global variable that indicates how many bytes are in the global ESP8266
      receive buffer.

- `var byte _esp8266_link_id`

  No documentation found

- `var byte _esp8266_mode`

       Private variable declarations -----------------------------

- `const byte _ESP8266_LINE_FEED = 0x0A`

  No documentation found

- `const byte ESP8266_MODE_STATION = 1`

      Mode declarations.

- `const byte _ESP8266_COLON = 0x3A`

  No documentation found

- `const byte _ESP8266_DOUBLE_QUOTE = 0x22`

  No documentation found

- `const byte ESP8266_MODE_AP_STATION = 3`

  No documentation found

- `const serial_hw_baudrate = 115200`

      Public constant declarations -----------------------------

- `const byte _ESP8266_COMMA = 0x2C`

  No documentation found

- `const byte _ESP8266_CARRIAGE_RETURN = 0x0D`

      Special character declarations.

- `const _ESP8266_ACK_WAIT_TIME_US = 500_000`

      500 ms always.

- `const word _ESP8266_MAX_DATA_BYTES = 2048`

      We do not accept data transmissions >= 2k

- `const byte ESP8266_CONNECTED = 1`

  No documentation found

- `const dword _ESP8266_RESPONSE_TIMEOUT_10_US = 1_500_000`

      15 seconds max.

### Procedures

- `esp8266_set_connection(byte in link_id)`

      Set the connection number to be used when sending a response.

- `esp8266_give_serial_byte(byte out character)`

      Returns the byte from the serial buffer. Used for debugging.

Private

- `_esp8266_copy_response()`

      Copy the EPS8266 data from the serial buffer to the global EPS8266 receive
      buffer until a carriage return is received. The number of copied bytes is
      returned in the global variable esp8266_bytes_received

- `_esp8266_flush_serial_receive_buffer()`

  No documentation found

- `_esp8266_send_data(byte in command[])`

      Sends the given string to the USART.

### Functions

- `esp8266_reset() return bit`

      Reset the ESP8266. Returns true when succesfull.

- `esp8266_get_bssid() return bit`

      Returns the BSSID of the ESP8266 module in the receive buffer of the ESP8266.
      Returns TRUE when succesfull.

- `esp8266_get_rssi() return bit`

      Returns the rssi of the ESP8266 module in the receive buffer of the ESP8266.
      Returns TRUE when succesfull.

- `esp8266_get_connection() return byte`

      Get the currently set connection number

- `esp8266_get_ip_address() return bit`

      Returns the local IP address as a string in the ESP8266 receive buffer and
      returns TRUE when succesfull. For example you can get the following responses:
      +CIFSR:APIP,"192.168.4.1"
      +CIFSR:APMAC,"1a:fe:34:f3:02:cd"
      +CIFSR:STAIP,"10.0.0.11"
      +CIFSR:STAMAC,"18:fe:34:f3:02:cd"
      It returns the string without quotes, so: 10.0.0.11

- `esp8266_get_ap_ip_address() return bit`

      Returns the IP address of the access point as a string in the ESP8266
      receive buffer and returns TRUE when succesfull..
      It returns the string without quotes, e.g: 10.0.0.11

- `esp8266_restore() return bit`

      Put the ESP8266 back to its factory default settings. Returns TRUE if
      succesful.

- `esp8266_get_ssid() return bit`

      Returns the SSID to which the ESP8266 module is connected in the receive
      buffer of the ESP8266. Returns TRUE when succesfull.

- `esp8266_server_start(byte in port[]) return bit`

      Start TCP server on specified port. Returns TRUE when succesfull.

- `esp8266_client_stop() return bit`

      Stop the client connection. Returns TRUE when succesfull.

- `esp8266_get_mac_address() return bit`

      Returns the local MAC address as a string in the ESP8266 receive buffer and
      returns TRUE when succesfull. For example you can get the following responses:
      +CIFSR:APIP,"192.168.4.1"
      +CIFSR:APMAC,"1a:fe:34:f3:02:cd"
      +CIFSR:STAIP,"10.0.0.11"
      +CIFSR:STAMAC,"18:fe:34:f3:02:cd"
      It returns the string without quotes, so: 18:fe:34:f3:02:cd

- `esp8266_init() return bit`

      Initialze the serial interface and reset the ESP module. Returns TRUE if
      succesful.

- `esp8266_client_start_ssl(byte in host[], byte in port[]) return bit`

      Start a client ssl connection and return TRUE if connected. Note that when there
      was already a connection, FALSE is returned.

- `esp8266_server_stop(byte in port[]) return bit`

      Stop TCP server on specified port. Returns TRUE when succesfull.

- `esp8266_close_connection() return bit`

      Close the currently set connection. Returns TRUE when succesfull.

- `esp8266_set_server_timeout(byte in timeout[]) return bit`

      Set TCP server timeout. Timeout is given in miliseconds. "0" means not
      timeout. Returns TRUE when succesfull.

- `esp8266_start_ap(byte in ssid[], byte in password[], byte in channel[], byte in encoding[], byte in espmode[]) return bit`

      Set the WiFi mode and start the access point.

- `esp8266_set_ap_ip_address(byte in ip_address[]) return bit`

      Set IP address of the access point of the ESP8266 module. The IP address
      must be given as text string. Returns TRUE when succesfull.

- `esp8266_alive() return bit`

      Returns true if the ESP8266 is responding.

- `esp8266_data_available() return bit`

      Returns TRUE if data is present in the serial buffer. The data must be
      processes as soon as possible using the function esp8266_get_data().

- `esp8266_connect_to_ap(byte in ssid[], byte in password[]) return bit`

      Connect to access point not saving this to flash. For use of special
      characters in the parameters see the instruction set of the ESP8266.
      Returns TRUE if succesfull.

- `esp8266_ping(byte in host[]) return bit`

      Ping to the host and return TRUE when succesful.

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

      Sends the given string via the ESP8266 to the current connection.
      Returns TRUE when succesfull.

- `esp8266_disconnect_from_ap() return bit`

      Disconnect the ESP8266 module from the Access Point. Returns TRUE when
      succesfull.

- `esp8266_get_data(byte out connection) return bit`

      Call this function when data is available. The serial data is processed and
      copied to the global receive buffer. It returns TRUE when all data is
      correctly processed and it returns the connection number from which the
      data was received. Note that more data can be received than we can handle
      in the receive buffer. Because of that we copy no more bytes than can be
      stored in the receive buffer. All remaining data will then be lost.

- `esp8266_client_start_tcp(byte in host[], byte in port[]) return bit`

      Start a client tcp connection and return TRUE if connected. Note that when there
      was already a connection, FALSE is returned.

- `esp8266_get_connection_status() return byte`

      Return the connection status of the ESP8266. Status can be:
      ESP8266_IDEL, ESP8266_CONNECTED, ESP8266_DISCONNECTED, ESP8266_ERROR

- `esp8266_client_start_udp(byte in host[], byte in port[]) return bit`

      Start a client udp connection and return TRUE if connected. Note that when there
      was already a connection, FALSE is returned.

- `esp8266_get_channel() return bit`

      Returns the channel to which the ESP8266 module is connected in the receive
      buffer of the ESP8266. Returns TRUE when succesfull.

Private

- `_esp8266_acknowledge() return bit`

      Check for acknoledge of a send command (OK). The wait time after having
      received the acknowledge it to prevent that commands are given to fast to the
      ESP8266 module. We flush the buffer as to remove the carriage return and line
      feed after the OK.

- `_esp8266_strip_double_quoto() return bit`

      Search for a string with double quotes in the receive buffer and strip them
      from the string. The results is placed back in the receive buffer.
      Double quotes are used for example in IP and MAC addresses.

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

      Parse the data in the serial buffer, received from the ESP8266 and return
      true if the given token if found.

- `_esp8266_extract_item(byte in item_number) return bit`

      This function extract the given item from the receive buffer and moves it
      to the front of the receive buffer. Each item in the receive buffer must be
      separated by a comma. The first item is always at the start of the buffer.

- `_esp8266_get_character(byte out character) return bit`

      Wait a certain time for a character to be receives and return TRUE when a
      character was received and return the character. Note that once read,
      from the serial buffer the character is gone.

- `_esp8266_client_start(byte in connection_type[], byte in host[], byte in port[]) return bit`

      Start the ESP8266 module to act as client. Returns TRUE when succesfull.

## Related samples

Here are the list of samples which use this library:

16f1825 | 16f1825_esp8266_web_server_led.jal
16f1825 | 16f1825_esp8266_tcp_server_led.jal
16f19176 | 16f19176_esp8266_tcp_server.jal
16f19176 | 16f19176_esp8266_web_server_led.jal
16f19176 | 16f19176_esp8266_connect.jal
16f19176 | 16f19176_esp8266_tcp_server_led.jal
16f19176 | 16f19176_esp8266_web_server.jal
16f19176 | 16f19176_esp8266_web_client.jal