Difference between revisions of "IC ESP8266EX interface"

From InCircuit
Jump to: navigation, search
(Wifi-Network Settings)
Line 3: Line 3:
 
{| class="wikitable"
 
{| class="wikitable"
 
|
 
|
|colspan=3 | [[radino Library]]
+
|colspan=4 | [[radino Library]]
 +
|-
 +
|
 +
|colspan=3 | '''radino'''
 +
|'''radino32'''<br />[[radino32 software]]
 
|-
 
|-
 
|[[radino software]]
 
|[[radino software]]
|colspan=3 | [[radino WiFi software]]
+
|colspan=3 | [[radino WiFi software]]<br />[[radino WiFi software#First_Steps|First Steps]] | [[radino WiFi software#Howto|Howto]] | [[radino WiFi software#FAQ|FAQ]]
[[radino WiFi software#First_Steps|First Steps]] | [[radino WiFi software#Howto|Howto]] | [[radino WiFi software#FAQ|FAQ]]
+
|
 
|-
 
|-
 
|
 
|
Line 13: Line 17:
 
|[[ESP8266EX HTTPD]]
 
|[[ESP8266EX HTTPD]]
 
|[[IC ESP8266EX interface]]
 
|[[IC ESP8266EX interface]]
 +
|
 
|-
 
|-
 
|}
 
|}

Revision as of 17:51, 27 April 2015

This page is currently under construction and is daily updated with new information.

radino Library
radino radino32
radino32 software
radino software radino WiFi software
First Steps | Howto | FAQ
IC ESP ESP8266EX HTTPD IC ESP8266EX interface

In-Circuit ESP8266EX (lowlevel) interface.

Contents

General

The In-Circuit ESP8266EX interface provides maximum functionality with radino Wifi and makes the radino WiFi radio module the most easy to use and flexible Wifi module on market.

It extends the well-known "AT-Command"-stack for Espressif's ESP8266EX by In-Circuit's improved ESP8266EX command set. The improved command set offers

  • minimum latency and wait states
  • less data to be transferred while communicating with ESP8266EX
  • therefore saving important time
  • improvement of overall performance
  • minimization of response time of radino Wifi.


Comfortable access to the functionality is provided through our IC_ESP library for the Ardino IDE. By using our library the user is able to bring up the application with only few lines of Sketch-Code. The library offers:

  • flexible set up as Accesspoint AND/or Client
  • easy rewriting of new webpage by sketch or just via UART (for large webpages)
  • ESP-internal interpreter handles requests and
    only data aquisition is handled by the microcontroller of the radino
  • full TCP/UDP support

Command syntax

The ESP8266EX accepts READ-requests (IR) and WRITE-requests (IW) to access its registers.

The ESP8266EX itself initiates EVENT-Requests (IE), e.g. when new data on a socket arrives or additional data is needed to serve a HTTP request.

READ-Command

A read is always initiated by the host and send to the ESP8266EX. The ESP8266EX will answer with the corresponding register values (IR) or an appropiate ERROR-Response (IN).

Header Register Checksum
2 Bytes 1 Byte 1 Byte
IR 0 0

The register number must be binary. The following command initiates a READ from register 4:

cmd = char['I','R',4,0]

The ESP8266EX will either reply with a successfull READ-response or an unsuccessfull READ-response.


successfull READ-response

The successfull READ-response consists of Header (IR), binary register number, 2 Bytes containing dataType+dataLength information, the register data content and the checksum.

Header Register DataInfo Data Checksum
2 Bytes 1 Byte 2 Bytes n Bytes 1 Byte
IR 0 0 0 0

The field DataInfo encodes the type of data which the register holds and also how many Bytes Data contains. Please refer to the following table for detailed information:

DataInfo: Byte 15..13 Byte 12..0
DataType DataLength

DataLength defines the count of Bytes within Data. The 3 Bits of DataType are encoded as follows:

DataType Register content:
000 String
001 uInt32
010 sInt32
011 Float
100 endless String (only relevant for WRITE-BURST-command)

A possible successfull READ-response for the request shown in READ-Command could be the following:

readResponse = char['I','R',4,0,6,'r','a','d','i','n','o',0]
IR READ-response
4 register 4
0,6 DataType: String; DataCount: 6 Bytes
radino Data content
0 Checksum

WRITE-Command

A write is always initiated by the host and send to the ESP8266EX. The ESP8266EX will answer with the corresponding successfull-write-respone or an appropiate ERROR-Response.

Header Register DataInfo Data Checksum
2 Bytes 1 Byte 2 Bytes n Bytes 1 Byte
IW 0 0 0 0

The field DataInfo encodes the type of data which the register holds and also how many Bytes Data contains. Please refer to the following table for detailed information:

DataInfo: Byte 15..13 Byte 12..0
DataType DataLength

DataLength defines the count of Bytes within Data. The 3 Bits of DataType are encoded as follows:

DataType Register content:
000 String
001 uInt32
010 sInt32
011 Float
100 endless String (only relevant for WRITE-BURST-command)

The register number must be binary. The following command initiates a Write to register 4 with a 6 byte String "radino":

cmd = char['I','W',4,0,6,'r','a','d','i','n','o',0]

The ESP8266EX will either reply with a successfull WRITE-response or an unsuccessfull WRITE-response.


successfull WRITE-response

The successfull WRITE-response consists of Header (IW), binary register number, 2 Bytes additional information and the checksum.

Header Register additional Information Checksum
2 Bytes 1 Byte 2 Bytes 1 Byte
IW 0 00 0

The field additional Information enables the opportunity to return additional information after a WRITE, e.g. the TCP socket number after opening a new TCP-Socket.


A possible successfull WRITE-response for the request shown in WRITE-Command could be the following:

writeResponse = char['I','W',4,0,0,0]
IW WRITE-response
4 register 4
00 no additional information
0 Checksum

ERROR-Response

If a command was not completed successfully or understood wrong, the ESP8266 will answer with an appropiate ERROR-Response.

It consists of Header (IN), binary register number, HEX-encoded ERROR-Code and the checksum.

Header Register ERROR-Code Checksum
2 Bytes 1 Byte 2 Bytes 1 Byte
IN 0 00 0

The field ERROR-Code encodes the type of Error which caused the request to fail:

ERROR-Code Description
0x00 (not an Error-Code)
0x01 Register Write-Only
0x02 Register Read-Only
0x03 Execution error
0x04 Parameter error
0x0A Unknown register
0x0B Busy with other task
0x0C Network not available
0x0D Maximum connections reached
0x0E Functionality not implemented yet

A possible unsuccessfull response for the request shown in READ-Command or WRITE-Command could be the following:

errorResponse = char['I','N',4,0,4,0]
IN ERROR-response
4 register 4
0,4 ERROR-Type: Wrong parameter e.g. wrting a string to an uInt register
0 Checksum

WRITE-BURST-Command

The WRITE-BURST-Command is a WRITE-command which sends the DataType "endless String" followed by an arbitrary amount of data. It's useful when sending large amounts of data over TCP / HTTP to reduce upload time and transferred data volume.

When using the WRITE-Command combined with DataType "endless String", a timeout can be defined, too. If no data was sent for the timeout period, the WRITE-BURST-Command is finished and the ESP8266EX will send a appropiate response.

To initiate a WRITE-BURST, send the following command to the ESP8266EX. After receiving the response, data sending begins and will stop after the specified timeout ends.

Header Register DataInfo Checksum
2 Bytes 1 Byte 2 Bytes 1 Byte
IW 0 0 0

When using WRITE-BURST, the field DataInfo encodes the DataType "endless String" and the timeout (unit: 1ms).

Minimum for timeout is 2ms, maximum is ...ms.

The following example defines dataType 100 and a timeout of 500 ms

DataInfo: Byte 15..13 Byte 12..0
DataType Timeout (unit: 1 ms)
100 (binary) 500 (decimal)
DataType Register content:
000 String
001 uInt32
010 sInt32
011 Float
100 endless String (only relevant for WRITE-BURST-command)

The responses will be the same as for the usual WRITE-command. Please refer to WRITE-Command for more information.

Note: Not all registers support Burst-Writes. Please refer to the register table. Appropiate registers will be marked as "WRITE-BURST possible".

EVENT-Command

EVENT-Requests are initiated by the ESP8266EX. The ESP8266EX uses this command to send new data to the microcontroller, e.g. when data on TCP sockets arrive or if HTTP requests require further information.

The microcontroller will use the same structure to answer EVENT-commands.

Header EventType DataInfo Data Checksum
2 Bytes 1 Byte 2 Bytes n Bytes 1 Byte
IE 0 0 0 0

The field DataInfo encodes the type of data which the ESP8266EX sends and also how many Bytes Data contains. Please refer to the following table for detailed information:

DataInfo: Byte 15..13 Byte 12..0
DataType DataLength

DataLength defines the count of Bytes within Data. The 3 Bits of DataType are encoded as follows:

DataType Register content:
000 String
001 uInt32
010 sInt32
011 Float
100 endless String (not implemented yet on EVENT-command)

EventType defines the type of Event. Some events require the ATmega to answer, some don't require a response. The ESP will only wait for an answer until an internal timeout period ends.

The EventType is encoded as follows:

EventType Description answer data content data format
0 -No valid event type- --- --- ---
1 TCP server got data
2 UDP server got data
3 HTTPD SET request SET reponse tcp-socket,register-name,register-value,user-token bytearray [ socketid(uint8), register(bytearray), 0xFF, regsitervalue(bytearray), {0xFF, userip(uint32), usertoken(bytearray),} "\r\n" ]
4 HTTPD SET response tcp-socket,register-name,return-value,user-token bytearray [ socketid(uint8), register(bytearray), 0xFF, returnvalue(bytearray), {0xFF, userip(uint32), usertoken(bytearray),} "\r\n" ]
5 HTTPD GET request GET response tcp-socket,register-name,user-token bytearray [ socketid(uint8), register(bytearray), {0xFF, userip(uint32), usertoken(bytearray),} "\r\n" ]
6 HTTPD GET response tcp-socket,register-name,register-value,user-token bytearray [ socketid(uint8), register(bytearray), 0xFF, registervalue(bytearray), {0xFF, userip(uint32), usertoken(bytearray),} "\r\n" ]
7 HTTPD auth request auth response tcp-socket,user-ip,password bytearray [ socketid(uint8), userip(uint32), password(bytearray), "\r\n" ]
8 HTTPD auth response tcp-socket,user-ip,token bytearray [ socketid(uint8), userip(uint32), usertoken(bytearray), "\r\n" ]
9 HTTPD userlevel request userlevel response tcp-socket,user-token bytearray [ socketid(uint8), userip(uint32), usertoken(bytearray), "\r\n" ]
10 HTTPD userlevel response tcp-socket,user-token,userlevelmask bytearray [ socketid(uint8), userip(uint32), userlevelmask(uint8), usertoken(bytearray), "\r\n" ]
11 TCP Client data received tcp-socket, datalen, data bytearray [ socketid(uint8), datalen(uint16), data(bytearray) ]
12 HTTP Client data received tcp-socket, datalen, data bytearray [ socketid(uint8), datalen(uint16), data(bytearray) ]
13 Telnet server got TCP data tcp-socket, datalen, data bytearray [ socketid(uint8), datalen(uint16), data(bytearray) ]
14 Telnet server got UDP data datalen, data bytearray [ datalen(uint16), data(bytearray) ]
15 Telnet server TCP client connected tcp-socket, clientip, clientport bytearray [ socketid(uint8), clientip(uint32), clientport(uint16) ]
16 Telnet server TCP client disconnected tcp-socket bytearray [ socketid(uint8) ]

Register list

Please refer to the following table for any information about the implemented registers.


Wifi-Network Settings

This section describes register definitions for basic Wifi settings of your radino Wifi.

Nr. Name Datatype R/W Default Value Description Available Settings Storage group Implemented since firmware version
0x01 WIFI_MODE uInt32 R/W 0 Wifi-Connection-Mode 0: Off
1: Join
2: AP
3: Both
basic 1 - Write modes 1 and 2
0x02 WIFI_SSID_AP String R/W "radino Wifi" SSID for AP-Mode (Network name) basic 1 - Write
0x03 WIFI_PASSWD_AP String R/W "12345678" Password for AP-Mode basic 1 - Write
0x04 WIFI_AUTHMETHOD_AP uInt32 R/W 0 Authentication Method for AP-Mode 0: WEP
1: WPA-PSK
2: ...
basic -
0x05 WIFI_CHANNEL_AP uInt32 R/W 5 Channel for AP-Mode basic -
0x06 WIFI_SSID_JOIN String R/W "" SSID of target network to connect to basic 1 - Write
0x07 WIFI_PASSWD_JOIN String R/W "" Password for target network to connect to basic 1 - Write

IP-Settings

This section describes all registers that hold information about the IP settings.

Nr. Name Datatype R/W Default Value Description Available Settings Storage group Implemented since firmware version
0x10 IP_ADDR_READ uInt32 R 0 Read current IP address. This depends on the connection state / DHCP mode and can be a static one, or received by a DHCP server. - 1
0x11 IP_ADDR_AP uInt32 R/W 192 168 2 1 IP-address for AP-Mode basic -
0x12 IP_DHCPD_CONF_AP uInt32 R/W 1 DHCP-config for AP-Mode 0: DHCP off
1: DHCP on
basic -
0x13 IP_SUBNET_AP uInt32 R/W 255 255 255 0 Subnet-Mask basic -
0x14 IP_GATEWAY_AP uInt32 R/W 192 168 2 1 Gateway IP basic -
0x15 IP_DNS_AP uInt32 R/W 192 168 2 1 DNS-Server IP basic -
0x16 IP_ADDR_JOIN uInt32 R/W 0 IP-address for target network to join basic -
0x17 IP_DHCPC_CONF_JOIN uInt32 R/W 1 DHCP-config for target network to join 0: Static IP as configared at register IP_ADDR_JOIN
1: Retrieve IP via DHCP
basic -
0x18 IP_SUBNET_JOIN uInt32 R/W 0 Subnet-Mask basic -
0x19 IP_GATEWAY_JOIN uInt32 R/W 0 Gateway IP basic -
0x1A IP_DNS_JOIN uInt32 R/W 0 DNS-Server IP basic -

UDP-Settings

This section describes all registers that hold information about the UDP Server and Client.

Nr. Name Datatype R/W Default Value Description Available Settings Storage group Implemented since firmware version
0x20 UDP_STATUS uInt32 R 0 UDP status register Bit 0..7: Status
Bit 8...15:
Bit 16...23: number of active UDP servers
Bit 24...31: maximum number of UDP servers
- -
0x21 UDP_SERVER_ADDPORT uInt32 W 0 Open an additional UDP Server on the specified port Maximum number of UDP servers is limited. See register UDP-STATUS - -
0x22 UDP_SERVER_REMOVEPORT uInt32 W 0 Close an UDP Server on the specified port - -
0x23 UDP_SERVER_GETPORTS uInt32 R 0 Read ports of all currently open UDP servers This will always return 2 ports:
Port1 (High 16 Bit), Port2 (Low 16 Bit)

Repeated READ-requests will show all ports in a cycle:
Port1, Port2
Port3, Port4
...
Port1, Port2
- -
0x24 UDP_CLIENT_TARGET_IP uInt32 R/W 192 168 2 255 UDP Client Target IP UDP data will be sent to this IP address
Broadcast addresses e.g. 192.168.2.255 are possible
- -
0x25 UDP_CLIENT_TARGETPORT uInt32 R/W 12345 UDP Client Target Port - -
0x26 UDP_CLIENT_SOURCEPORT uInt32 R/W 0 UDP Client Source Port 0: automatic Port - -
0x27 UDP_CLIENT_SEND String W - UDP Client TXBUFFER / SEND register Send UDP packet to host configured with registers above - -

TCP-Settings

This section describes all registers that hold information about the TCP Server and Client.

Nr. Name Datatype R/W Default Value Description Available Settings Storage group Implemented since firmware version
0x40 TCP_STATUS uInt32 R 0 TCP status register Bit 0: TCP server ON
Bit 1: TCP server connected
Bit 16..31: TCP socket states (2Bit per socket, 31:30 socket id 0, (0:closed, 1:connecting, 2:listening, 3:open))
- -
0x41 TCP_STROBE uInt32 W 0 TCP Control Register
Write logic "1" to toggle following functions:
Bit 0: Start Server
Bit 1: Stop Server
Bit 2: Open TCP client connection as configured with registers beyond
- -
0x42 TCP_SERVER_PORT uInt32 R/W 0 TCP Server port - -
0x43 TCP_SERVER_TIMEOUT uInt32 R/W 0 TCP Server timeout unit: 1 ms - -
0x44 TCP_CLIENT_TARGETIP uInt32 R/W 0 TCP Client target IP - -
0x45 TCP_CLIENT_TARGETPORT uInt32 R/W 0 TCP Client target port only lower 16bit relevant - -
0x46 TCP_CLIENT_SOURCEPORT uInt32 R/W 0 TCP Client source port 0: automatic Port - -
0x47 TCP_CLIENT_TIMEOUT uInt32 R/W 0 TCP Client timeout unit: 1 ms - -
0x48 TCP_CLIENT_SEND_TARGETSOCKET uInt32 R/W 0 Define TCP socket to use for SEND
defaults to the last socket opened
- -
0x49 TCP_CLIENT_SEND String W 0 TCP Client send data on socket current socket is defined in register TCP_CLIENT_SEND_TARGETSOCKET

WRITE-BURST possible
- -
0x4A TCP_CLOSE_SOCKET uInt32 W 0 TCP close socket (applies for client and server) - -
0x4B TCP_PUSH String W 0 TCP TXBUFFER "fire & forget"
send data to target IP & port, close socket & don't wait for response
dataByte 0..3: target IP
dataByte 4..5: target port
dataByte 6...: data

WRITE-BURST possible
- 1

Telnet-Server-Settings

This section describes all registers that hold information about the Telnet-Server.

Nr. Name Datatype R/W Default Value Description Available Settings Storage group Implemented since firmware version
0x50 TELNET_STATUS uInt32 R 0 Telnet Status Bit 0: Telnet TCP enabled
Bit 1: Telnet UDP enabled
Bit 9: Telnet starting on PowerOn
- -
0x51 TELNET_STROBE uInt32 W 0 Telnet Control register Write logic "1" to toggle following functions:
Bit 0: Enable Telnet
Bit 1: Disable Telnet
Bit 2: Enable Start on PowerOn
Bit 3: Disable Start on PowerOn
- -
0x52 TELNET_PORT_TCP uInt32 R/W 0 Telnet TCP port - -
0x53 TELNET_PORT_UDP uInt32 R/W 0 Telnet UDP port - -
0x54 TELNET_PORT_UDP_BROADCAST uInt32 R/W 0 Telnet UDP Broadcast Target Port 0: UDP Broadcast disabled - -
0x55 TELNET_TARGET_SOCKET uInt32 R/W 0 Telnet TCP socket To which socket data will be sent - -
0x56 TELNET_SOCKET_SEND string W 0 Telnet TCP send Send data to the socket set at register TELNET_TARGET_SOCKET - -
0x57 TELNET_UDP_SEND String W 0 Telnet UDP send Send data as broadcast to the port set at register TELNET_PORT_UDP_BROADCAST - -
0x58 TELNET_BROADCAST_SEND String W 0 Telnet Broadcast send sends data to all currently open Telnet connections and the UDP broadcast port - -

HTTP-Settings

This section describes all registers that hold information about the HTTP Server and Client.

Nr. Name Datatype R/W Default Value Description Available Settings Storage group Implemented since firmware version
0x60 HTTP_STATUS uInt32 R 0 HTTP Status Bit 0: HTTP Server running
Bit 1: HTTP Server starting on PowerOn
Bit 2: HTTP client connected
- 1 - Bit0
0x61 HTTP_STROBE uInt32 W 0 HTTP Control Register Write logic "1" to toggle following functions:
Bit 0: Start HTTP Server
Bit 1: Stop HTTP Server
Bit 2: HTTP client connect
- 1 - Bit0
0x62 HTTP_SERVERPORT_ADD uInt32 W 0 HTTPD will listen on these ports for incoming requests - 1
0x63 HTTP_UPLOAD String W 0 HTTP Server Website Upload Upload a new Website to the integrated Webserver

Timeout-based writing to this register possible:
First 2 DataBytes define DataType "endless String" and Timeout, followed by arbitrary amount of data.
transfer ends when no data was sent for timeout duration
- 1
0x64 HTTP_SERVERPORT_REMOVE uInt32 W 0 Remove port from HTTP server - -
0x65 HTTP_SERVERPORTS uInt32 R 0 Get ports HTTPD listens on Each read delivers two ports from a cyclic list - -
0x68 HTTP_CLIENT_TARGETIP uInt32 R/W 0 HTTP Client target IP - -
0x69 HTTP_CLIENT_TARGETPORT uInt32 R/W 0 HTTP Client target port - -
0x6A HTTP_CLIENT_TARGETURI String R/W 0 HTTP Client target URI / address - -
0x6B HTTP_CLIENT_TYPE uInt32 R/W 0 HTTP Client request type 0: GET
1: POST
2: HEAT
3: GET_BODYONLY
4: POST_BODYONLY
- -
0x6C HTTP_CLIENT_TIMEOUT uInt32 R/W 0 HTTP Client timeout unit: 1 ms - -
0x6D HTTP_CLIENT_BODY String W 0 HTTP Client Body / implicite execute(strobe) Writing to this register will start HTTP client request

WRITE-BURST possible
- -

System-Settings

This section describes all registers that hold information about the general functionality.

Nr. Name Datatype R/W Default Value Description Available Settings Storage group Implemented since firmware version
0x71 SYSTEM_STATUS uInt32 R 0 System Status - -
0x72 SYSTEM_STROBE uInt32 W 0 System control register Write logic "1" to toggle following functions:
Bit 0: (Re)Start WiFi with configured settings
Bit 8: RESET
Bit 9: Light SLEEP
Bit 10: Medium SLEEP
Bit 11: Deep SLEEP
- 1 - Bit0
0x73 SYSTEM_UART uInt32 R/W 115200 System UART settings Bit 0..21: Baudrate
Bit 22..23: Databits
Bit 24..25: Startbits
Bit 26..27: Parity
Bit 28..29: Stopbits
- -
0x7F FIRMWARE_VERSION uInt32 R 0 Firmware version - 1
Personal tools