ESPTerm implements commands for device-to-device messaging and for requesting external servers. This can be used e.g. for remote control, status reporting or data upload / download.

Networking commands use the format `\e^...\a`, a Privacy Message (PM). PM is similar to OSC, which uses `]` in place of `^`. The PM payload (text between `\e^` and `\a`) must be shorter than 256 bytes, and should not contain any control characters (ASCII < 32).

Device-to-device Messaging

To send a message to another ESPTerm module, use: `\e^M;DestIP;message\a`.

This command sends a POST request to `http://<DestIP>/api/v1/msg`. The IP address may be appended by a port, if needed (eg. :8080). In addition to POST, a GET request can also be used. In that case, any GET arguments (`/api/v1/msg?arguments`) will be used instead of the request body. This is intended for external access when sending POST requests is not convenient.

Each ESPTerm listens for such requests and relays them to UART: `\e^m;SrcIP;L=length;message\a`, with _length_ being the byte length of _message_, as ASCII.

Notice a pattern with the first letter: capital is always a command, lower case a response. This is followed with the HTTP commands and any networking commands added in the future.

*Example:* Node 192.168.0.10 sends a message to 192.168.0.19: `\e^M;192.168.0.19;Hello\a`. Node 192.168.0.19 receives `\e^m;192.168.0.10;L=5;Hello\a` on the UART. Note that the IP address in the reception message is that of the first node, thus it can be used to send a message back.

External HTTP requests

To request an external server, use `\e^H;method;options;url\nbody\a`.

• `_method_` - can be any usual HTTP verb, such as `GET`, `POST`, `PUT`, `HEAD`.
• `_options_` - is a comma-separated list of flags and parameters:
  • `H` - get response headers
  • `B` - get response body
  • `X` - ignore the response, return nothing
  • `N=nonce` - a custom string that will be added in the options field of the response message. Use this to keep track of which request a response belongs to.
  • `T=ms` - request timeout (default 5000~ms), in milliseconds
  • `L=bytes` - limit response length (default 0 = don't limit). Applies to the head, body, or both combined, depending on the `H` and `B` flags
  • `l=bytes` - limit the response buffer size (default 5000~B). This can reduce RAM usage, however it shouldn't be set too small, as this buffer is used for both headers and the response body.
• `_url_` - full request URL, including `http://`. Port may be specified if different from :80, and GET arguments may be appended to the URL if needed.
• `_body_` - optional, separated from `_url_` by a single line feed character (`\n`). This can be used for POST and PUT requests. Note: the command may be truncated to the maximum total length of 256 characters if too long.

The response has the following format: `\e^h;status;options;response\a`

• `_status_` - a HTTP status code, eg. 200 is OK, 404 Not found.
• `_options_` - similar to those in the request, here describing the response data. This field can contain comma-separated `B`, `H` and `L=bytes` and `N=nonce`.
• `_response_` - the response, as requested. If both headers and body are received, they will be separated by an empty line (i.e. `\r\n\r\n`). Response can be up to several kilobytes long, depending on the `L=` and `l=` options.

*Example:* `\e^H;GET;B;http://wtfismyip.com/text\a` - get the body of a web page (wtfismyip.com is a service that sends back your IP address). A response could be `\e^h;200;B,L=11;80.70.60.50\a`.