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).

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
  • `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`.
• `_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`.