{"id":21881527,"url":"https://github.com/jiribilek/wifispi","last_synced_at":"2025-04-15T05:17:03.120Z","repository":{"id":51364775,"uuid":"85570105","full_name":"JiriBilek/WiFiSpi","owner":"JiriBilek","description":"SPI library for Arduino AVR and STM32F1 to connect to ESP8266","archived":false,"fork":false,"pushed_at":"2021-05-13T10:52:12.000Z","size":183,"stargazers_count":62,"open_issues_count":5,"forks_count":13,"subscribers_count":12,"default_branch":"master","last_synced_at":"2025-04-15T05:16:55.988Z","etag":null,"topics":["arduino","spi-interface","wifi"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JiriBilek.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.txt","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-03-20T11:41:48.000Z","updated_at":"2024-06-04T13:16:58.000Z","dependencies_parsed_at":"2022-09-04T16:12:03.091Z","dependency_job_id":null,"html_url":"https://github.com/JiriBilek/WiFiSpi","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JiriBilek%2FWiFiSpi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JiriBilek%2FWiFiSpi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JiriBilek%2FWiFiSpi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JiriBilek%2FWiFiSpi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JiriBilek","download_url":"https://codeload.github.com/JiriBilek/WiFiSpi/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249010222,"owners_count":21197796,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["arduino","spi-interface","wifi"],"created_at":"2024-11-28T09:19:22.457Z","updated_at":"2025-04-15T05:17:03.102Z","avatar_url":"https://github.com/JiriBilek.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"WiFiSpi\n=======\n\nThis library connects Arduino to ESP8266 module and uses it as a dedicated WiFi device. The SPI interface is used because of its strictly master/slave nature.\n\nThe library allows Arduino to be client or server on the WiFi network.\n\n## News\n\n#### 2021-01-25\n\nAdded UDP Multicast support\n\n#### 2021-01-02\n\nFixed a bug with closing server connection when closing asynchronously opened another client.\nChanged deprecated boolean type to bool. \n\n#### 2019-02-18\n\nAdded SSL connection to WiFiClient class. Added verifySSL function.\n\n#### 2019-01-27\n\nEnhanced communications protocol (added CRC-8 and confirmation of message reception). Shortened the status message from 4 bytes to 2 bytes and added XOR check. The protocol version is now 0.2.0 and is incompatible with the former one.\n\nAdded support for hardware circuit removing the problems with ESP8266 reset by pulling GPIO15 (SS) pin to GND on reset.\n\n## Requirements\n\n### ESP8266 device\n\nThe ESP8266 has two SPI interfaces. The first is connected to the flash memory, the second (named HSPI) can be used by user. The HSPI signals are multiplexed with GPIO12-15. Suitable device for the slave is ESP-12. On the ESP device must be run a custom firmware - see WifiESPSPI project.\n\n### Wiring\n\nThe library uses hardware SPI on Arduino so most of the signals are fixed to certain pins.\n\nThe wiring is as follows:\n\n     Name  |   Uno   | STM32F103C8 |     ESP8266\n           |         |  SPI1 SPI2  |  GPIO    NodeMCU\n    -------+---------+---------------------------------\n      SS   |   D10   |  PA4  PB12  |   15       D8\n     MOSI  |   D11   |  PA7  PB15  |   13       D7\n     MISO  |   D12   |  PA6  PB14  |   12       D6\n     SCK   |   D13   |  PA5  PB13  |   14       D5\n\nThe SS pin is the only pin the user can change. Changing SS to another pin enables more devices on one SPI interface.\n\nPlease be careful, the ESP8266 chip ports are **NOT** 5V tolerant, if you're connecting to a 5V device you have to use a level converter.\n\n## Library Reference\n\nThe library implements almost the same functions as the [Arduino WiFi library](https://www.arduino.cc/en/Reference/WiFi).\n\n### Setup\n\nAll the important defines are in file **config.h**. The user can comment and/or uncomment them and modify the behaviour of the library.\n\n### WiFiSpiClass\n\nAfter including *WiFiSpi.h* header the *WiFiSpi* variable is automatically instantiated. Use the variable to perform the following calls.\n\n- **void init(int8_t pin, uint32_t max_speed = 0, SPIClass \\*in_spi = \u0026SPI, int8_t hwResetPin = -1)**\nInitializes the library and the Arduino SPI interface. Must be called on beginning of the communication. The parameter *max_speed* limits the SPI speed. Tests on STM32F1 show that speeds as high as 9 Mhz are usable. The parameter *in_spi* allows to use another SPI port (if there are more present in the MCU). Refer to a particular implementation of SPIClass. The optional parameter *hwResetPin* defines the pin which is connected to reset pin on ESP8266 for hardware reset. Then this parameter is present,  master resets the ESP8266 on start.\n\n- **char\\* firmwareVersion()**\nReturns version of custom firmware loaded into ESP8266.\n\n- **char\\* protocolVersion()**\nReturns version of protocol the ESP8266 firmware operates with.\n\n- **char\\* masterProtocolVersion()**\nReturns version of protocol the master runs.\n\n- **uint8_t checkProtocolVersion()**\nChecks master and ESP protocol version. If they match, returns 1, otherwise 0.\n\n- **uint8_t begin(const char\\* ssid)**\nConnects to an open (unencrypted) wifi. Returns a value from *wl_status_t* enum(when connected returns WL_CONNECTED). Establishing of the connection may last several seconds.\n\n- **uint8_t begin(const char\\* ssid, const char \\*passphrase)**\nConnects to a WPA/WPA2 encrypted wifi. Returns status from *wl_status_t* type (when connected returns WL_CONNECTED). Establishing of the connection may last several seconds.\n\n- **int disconnect(void)**\nDisconnects from the WiFi network. Returns a value from *wl_status_t* enum(when disconnected returns WL_DISCONNECTED).\n\n- **uint8_t status()**\nReturns the connection status of the WiFi interface. The returned value is one of the enum *wl_status_t*.\n\n- **int8_t hostByName(const char\\* aHostname, IPAddress\u0026 aResult)**\nResolves the given hostname to an IP address. Returns 1 for Ok else error code.\n\n- **void softReset(void)**\n Sends reset command to ESP8266. The ESP8266 then resets itself. The command is performed only if the connection between the host and ESP8266 is not broken. \n\n- **void hardReset(void)**\n Resets the ESP8266. One pin on master unit must be wired to reset pin on ESP8266. The pin is defined in **init** function.\n\n----------\n\n\n- **bool config(IPAddress local_ip)**\nChanges IP configuration, sets local IP address and disables DHCP client.\n\n- **bool config(IPAddress local_ip, IPAddress dns_server)**\nChanges IP configuration, sets local IP address, primary DNS server and disables DHCP client.\n\n- **bool config(IPAddress local_ip, IPAddress dns_server, IPAddress gateway)**\nChanges IP configuration, sets local IP address, primary DNS server, static gateway address and disables DHCP client.\n\n- **bool config(IPAddress local_ip, IPAddress dns_server, IPAddress gateway, IPAddress subnet)**\nChanges IP configuration, sets local IP address, primary DNS server, static gateway address, subnet mask and disables DHCP client.\n\n- **bool setDNS(IPAddress dns_server1)**\nChanges IP configuration, sets primary DNS server IP address.\n\n- **bool setDNS(IPAddress dns_server1, IPAddress dns_server2)**\nChanges IP configuration, sets primary and secondary DNS server IP addresses.\n\n- **uint8_t\\* macAddress(uint8_t\\* mac)**\nReturns MAC address value of the WiFi interface. The MAC address is copiend to the array *mac* and also returned as a pointer to this array. The array size must be at least 6 bytes.\n\n- **IPAddress localIP()**\nReturns local IP address value.\n\n- **IPAddress subnetMask()**\nReturns interface subnet mask value.\n\n- **IPAddress gatewayIP()**\nReturns interface gateway address value.\n\n- **char\\* SSID()**\nReturns the current SSID associated with the network.\n\n- **uint8_t\\* BSSID()**\nReturns the current BSSID associated with the network. It is in fact the MAC address of the Access Point. Returns a pointer to byte array of 6 byte length.\n\n- **int32_t RSSI()**\nReturns the currect RSSI (signal strength in dBm) as a signed value.\n\n\n----------\n\n\n- **int8_t scanNetworks()**\nScans the WiFi network. Returns the number of networks found or error value (WL_FAILURE). The call may last several seconds.\n\n- **char\\* SSID(uint8_t networkItem)**\nReturns the current SSID associated with the discovered network during the network scan. Parameter *networkItem* is the index into a discovered networks array.\n\n- **uint8_t\tencryptionType(uint8_t networkItem)**\nReturns the encryption type of the discovered network during the network scan. The returned value is one of the enum *wl_enc_type*. Parameter *networkItem* is the index into a discovered networks array.\n\n- **int32_t RSSI(uint8_t networkItem)**\nReturns the signal strength in dBm of the discovered network during the network scan. The returned value is signed 32 bit integer. Parameter *networkItem* is the index into a discovered networks array.\n\n----------\n\n- **uint8_t setSSLFingerprint(uint8_t\\* fingerprint)**\nLoads server certificate SHA-1 fingerprint into BearSSL engine. Subsequent connections are checked against\nthis fingerprint. The fingerprint is an array of type *uint8_t[20]*.\nNote that without checking the fingerprint the TLS connection is insecure and prone to MITM attacks.\n\n\n### WiFiSpiClient\n\nThe WiFiSpiClient class performs data communication between your program and the remote site. It is used not only with client connections (where Arduino acts as a client) but also in server connections (sending responses to a web request) and udp connections.\nThe library has a pool of 4 sockets and after exhausting all the sockets no more connection is available. Therefore it is important to close the socket (i. e. stop the client) when it is no longer used.\n\n- **WiFiSpiClient()**\nDefault constructor, creates a closed connection. Use it for client side of communication.\n\n- **WiFiSpiClient(uint8_t sock)**\nCreates client for open server connection. Called by the library in when server connection has data.\n\n- **int connect(IPAddress ip, uint16_t port)**\nConnects to the specified IP address and port. Returns a value from enum *wl_tcp_state* (for open connection returns ESTABLISHED).\n\n- **int connect(const char \\*host, uint16_t port)**\nConnects to the specified host and port. Returns a value from enum *wl_tcp_state* (for open connection returns ESTABLISHED).\n\n- **int connectSSL(IPAddress ip, uint16_t port)**\nConnects using SSL to the specified IP address and port. Returns a value from enum *wl_tcp_state* (for open connection returns ESTABLISHED). If there is a previously loaded certificate fingerprint, the server certificate is checked against the fingerprint, otherwise the connection is insecure (prone to MITM attacks).\n\n- **int connectSSL(const char \\*host, uint16_t port)**\nConnects using SSL to the specified host and port. Returns a value from enum *wl_tcp_state* (for open connection returns ESTABLISHED). If there is a previously loaded certificate fingerprint, the server certificate is checked against the fingerprint, otherwise the connection is insecure (prone to MITM attacks).\n\n- **uint8_t connected()**\nReturns connection state as a logic value: 1 = connected, 0 = error. Note that the connection could be closed by a server when ESP8266 reads all data in its internal buffer although the master haven't read it yet.\n\n- **uint8_t status()**\nReturns connection state as a value from enum *wl_tcp_state* (for open connection returns ESTABLISHED).\n\n- **void stop()**\nStops the client (disconnects from the remote server if still connected) and frees the socket used for the client.\n\n- **operator bool()**\nReturns true when the client is associated with a socket.\n\n----------\n\n- **int available()**\nReturns available bytes in the input queue (data received from the network) for reading.\n\n- **int read()**\nReads one byte from the input queue. Returns -1 for an error.\n\n- **int read(uint8_t \\*buf, size_t size)**\nReads *size* bytes into an input buffer *buf*. Returns 0 on success, -1 on error or insufficient data in the input queue.\n\n- **int peek()**\nPeeks into the input queue and returns the first byte in the queue. On error returns -1.\n\n- **size_t write(uint8_t)**\nSends one byte to the network. Returns 1 on success, 0 on error.\n\n- **size_t write(const void \\*buf, size_t size)**\nSends the buffer to the network. Returns number of bytes transmitted.\n\n- **size_t write(const char \\*str)**\nSends the character string to the network. Returns number of bytes transmitted.\n\n- **IPAddress remoteIP()**\nReturns the IP address of the host who sent the current incoming packet. When there is no incoming connection returns 0.0.0.0.\n \n- **uint16_t remotePort()**\nReturns the port of the host who sent the current incoming packet. When there is no incoming connection returns 0.\n\n### WiFiSpiServer\n\nThe library has a pool of 4 sockets and after exhausting all the sockets no more connection is available. Therefore it is important to close the socket (i. e. stop the server) when it is no longer used. This version of the library is further constrained to one client connection per server.\n\n- **WiFiSpiServer(uint16_t port)**\nConstructor. Does not open a connection.\n\n- **void begin()**\nCreates and starts the server listener on specified *port*.\n\n- **uint8_t status()**\nReturns the server's status. Return 1 for opened connection, 0 for closed or error.\n\n- **void stop()**\nStops the listener, stops the associated client (if any) and frees the socket.\n\n- **WiFiSpiClient available(uint8_t\\* status = NULL)**\nReturns WiFiSpiClient instance for communication with remote client. Returns opened WiFiSpiClient instance when there is a remote client connected. When there is no connection the function returns closed client. Use the WiFiSpiClient's bool operator on the return value to test it.\nWhen pointer *status* is not null, loads it with the remote client's status.\n  \n- **size_t write(uint8_t)**\nWrites a byte to the output queue. Returns 1 on success, 0 on error.\n\n- **size_t write(const uint8_t \\*buf, size_t size)**\nWrites a buffer to the output queue. Returns number of bytes written.\nNote: transmitting data can be also achieved using a WiFiSpiClient object returned by the *WiFiSpiServer::available()* function.\n\n### WiFiSpiUDP\n\n- **WiFiSpiUdp()**\nDefault constuctor.\n\n- **uint8_t begin(uint16_t port)**\nInitializes the instance, starts listening on specified *port*. Returns 1 if successful, 0 on error.\n\n- **uint8_t begin(uint16_t multicastIP, uint16_t port)**\nInitializes the instance, starts listening on specified *port* for multicast messages from *multicastIP* address. Returns 1 if successful, 0 on error.\n\n- **void stop()**\nStops listening on the UDP port, frees the UDP socket used.\n\n- **int beginPacket(IPAddress ip, uint16_t port)**\nStarts building up a packet to send to the remote host specific in *ip* and *port*. Returns 1 if successful, 0 if there was a problem with the connection. This function works for both unicast and multicast communication.\n    \n- **int endPacket()**\nFinishes the packet and sends it. Returns 1 if the packet was sent successfully, 0 if there was an error.\n  \n- **size_t write(uint8_t)**\nWrites a single byte into the packet. Returns 1 on sucesss, 0 on error.\n  \n- **size_t write(const uint8_t \\*buffer, size_t size)**\nWrites *size* bytes from buffer into the packet. Returns number of bytes written, on error returns 0.\n \n- **int parsePacket();**\nStarts processing the next available incoming packet. Returns the size of the packet in bytes, or 0 if no packets are available.\n    \n- **int available()**\nReturns the number of bytes remaining in the current packet.\n  \n - **int read()**\nReads a single byte from the current packet.\n\n- **int read(unsigned char\\* buffer, size_t len)**\n- **int read(char\\* buffer, size_t len)**\nReads up to *len* bytes from the current packet and places them into *buffer*. Returns the number of bytes read, or 0 if none are available or an error occurred.\n    \n- **int peek()**\nReturns the next byte from the current packet without moving on to the next byte.\n\n- **IPAddress remoteIP()**\nReturns the IP address of the host who sent the current incoming packet. When there is no incoming connection returns 0.0.0.0.\n \n- **uint16_t remotePort()**\nReturns the port of the host who sent the current incoming packet. When there is no incoming connection returns 0.\n\n## Examples\n\n- **ConnectWithWPA**\nConnects to the network and prints out some information.\n\n- **WiFiWebClient**\nConnects to the google.com site and transmits the http response.\n\n- **MQTT_Publish**\nSimple mqtt messaging.\n\n- **UdpNTPClient**\nReads current time and date from a NTP server.\n\n- **UDP_Multicast_Transmitter**\nPeridically transmits a short messaage via UDP multicast.\n\n- **UDP_Multicast_Receiver**\nListens for multicast messages, reads them and prints them out.\n\nMore examples to come soon. But you can easily use the ones from WiFi library. Don't forget to add a line *WiFiSpi.init();* before using other library functions.\n\n## Debugging\n\nFor some debugging information on Serial output uncomment line 23 (#define _DEBUG) in file espspi_srv.cpp.\n\n## ToDo and Wish Lists\n\n- more SPI protocol optimization\n- TLS: loading and checking server certificate chain instead of the fingerprint\n\n## Credits\n\nThe protocol running on SPI interface was inspired by protocol used in Arduino WiFi library. The code structure and some code is taken from this library, too.\n\nThe SPI master code was inspired and parts were taken from the [ESPSlave example](https://github.com/esp8266/Arduino/tree/master/libraries/SPISlave) of the ESP8266 Arduino project.\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjiribilek%2Fwifispi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjiribilek%2Fwifispi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjiribilek%2Fwifispi/lists"}