TRM: ESP32 interface

ESP32 interface (ESPCTRL/ESPDATA)

The Aq+ has an interface to communicate with an ESP32 module. This interface is used for file storage and network connectivity.

Communication is done via 2 IO registers: ESPCTRL and ESPDATA.

Writing a 1 to Transmit start-of-message will transmit a start-of-message to indicate the start of a new command.

Commands

Value	Function	Description	Category
$01	RESET	Indicate to ESP that system has been reset	General
$02	VERSION	Get version string	General
$03	GETDATETIME	Get current date/time	General
$08	KEYMODE	Set keyboard buffer mode	Keyboard
$0C	GETMOUSE	Get mouse state	Mouse
$0E	GETGAMECTRL	Get game controller state	Game Controller
$10	OPEN	Open / create file	File
$11	CLOSE	Close open file	File
$12	READ	Read from file	File
$13	WRITE	Write to file	File
$14	SEEK	Move read/write pointer	File
$15	TELL	Get current read/write	File
$16	OPENDIR	Open directory	Directory
$17	CLOSEDIR	Close open directory	Directory
$18	READDIR	Read from directory	Directory
$19	DELETE	Remove file or directory	File / Directory management
$1A	RENAME	Rename / move file or directory	File / Directory management
$1B	MKDIR	Create directory	File / Directory management
$1C	CHDIR	Change directory	File / Directory management
$1D	STAT	Get file status	File / Directory management
$1E	GETCWD	Get current working directory	File / Directory management
$1F	CLOSEALL	Close any open file/directory descriptor	File / Directory
$20	OPENDIR83	Open directory in 8.3 filename mode	Directory
$21	READLINE	Read line from file	File
$22	OPENDIREXT	Open directory with extended options	Directory
$40	LOADFPGA	Load FPGA bitstream	FPGA

Error codes

Value	Function	Description
-1	ERR_NOT_FOUND	File / directory not found
-2	ERR_TOO_MANY_OPEN	Too many open files / directories
-3	ERR_PARAM	Invalid parameter
-4	ERR_EOF	End of file / directory
-5	ERR_EXISTS	File already exists
-6	ERR_OTHER	Other error
-7	ERR_NO_DISK	No SD-card
-8	ERR_NOT_EMPTY	Not empty
-9	ERR_WRITE_PROTECT	Write protected SD-card

RESET

Offset	Value
0	$01

VERSION

Request

Offset	Value
0	$02

Response

Offset	Value
0-n	Zero-terminated version string

GETDATETIME

Request

Offset	Value
0	$03
1	Response type: $00 (to be used in future to support different response types)

Response (type: $00)

Offset	Value
0	0 on success / error code (<0)
1-n	Zero-terminated datetime string of format YYYYMMDDHHmmss

KEYMODE

See the page on the keyboard buffer for more info.

Request

Offset	Value
0	$08
1	Keyboard buffer mode flags

Response

Offset	Value
0	0 on success / error code (<0)

GETMOUSE

Request

Offset	Value
0	$0C

Response

Offset	Value
0	0 on success / ERR_NOT_FOUND if no mouse
1-2	X position (0-319)
3	Y position (0-199)
4	Buttons (bit 0: left, bit 1: right, bit 2: middle)
5	Mouse wheel delta (-128-127)

GETGAMECTRL

Request

Offset	Value
0	$0E
1	0 (game controller index, for now only index 0 is supported)

Response

Offset	Value
0	0 on success / ERR_NOT_FOUND if game controller not present
1	Left stick X (-128-127)
2	Left stick Y (-128-127)
3	Right stick X (-128-127)
4	Right stick Y (-128-127)
5	Left trigger (0-255)
6	Right trigger (0-255)
7-8	Buttons bitmask (16-bit little endian)

Buttons:

Idx	Description
0	A
1	B
2	X
3	Y
4	View
5	Guide (Xbox button)
6	Menu
7	LS (Button in left stick)
8	RS (Button in right stick)
9	LB (Left shoulder button)
10	RB (Right shoulder button)
11	D-pad up
12	D-pad down
13	D-pad left
14	D-pad right
15	Share (only present on Xbox Series S/X controller, not on Xbox One controller)

OPEN

Flags

Bit	Name	Description
1:0 = 0	RDONLY	Open for reading only
1:0 = 1	WRONLY	Open for writing only
1:0 = 2	RDWR	Open for reading and writing
2 ($04)	APPEND	Append mode
3 ($08)	CREATE	Create if non-existant
4 ($10)	TRUNC	Truncate to zero length
5 ($20)	EXCL	Error if already exists

Request

Offset	Value
0	$10
1	Flags
2-n	Zero-terminated path

Response

Offset	Value
0	File descriptor / Error code (<0)

CLOSE

Request

Offset	Value
0	$11
1	File descriptor

Response

Offset	Value
0	0 on success / error code (<0)

READ

Request

Offset	Value
0	$12
1	File descriptor
2-3	Length to read (16-bit)

Response

Offset	Value
0	0 on success / error code (<0)
1-2	Length read
3-n	Data bytes

READLINE

Request

Offset	Value
0	$21
1	File descriptor
2-3	Maximum length to read (16-bit) including terminating zero byte

Response

Offset	Value
0	0 on success / error code (<0)
1-n	Zero terminated string, CR/LF are not included

WRITE

Request

Offset	Value
0	$13
1	File descriptor
2-3	Length to write (16-bit)
4-n	Data bytes

Response

Offset	Value
0	0 on success / error code (<0)
1-2	Length written

SEEK

Request

Offset	Value
0	$14
1	File descriptor
2-5	Seek offset

Response

Offset	Value
0	0 on success / error code (<0)

TELL

Request

Offset	Value
0	$15
1	File descriptor

Response

Offset	Value
0	0 on success / error code (<0)
1-4	Current offset

OPENDIR / OPENDIR83

Request

Offset	Value
0	$16 / $20
1-n	Zero-terminated path

Response

Offset	Value
0	Directory descriptor / error code (<0)

OPENDIREXT

Flags

Bit	Description
0	Always include directories (even when filter doesn't match)
1	Include hidden files (system/hidden attribute set or starting with a '.')
2	Include '..' entry for non-root directory
3	Return 8.3 entries

Request

Offset	Value
0	$22
1	Flags
2-3	Number of entries to skip (after filtering)
4-n	Zero-terminated path

Response

Offset	Value
0	Directory descriptor / error code (<0)

CLOSEDIR

Request

Offset	Value
0	$17
1	Directory descriptor

Response

Offset	Value
0	0 on success / error code (<0)

READDIR

Request

Offset	Value
0	$18
1	Directory descriptor

Response

Offset	Value
0	0 on success / error code (<0)
1-2	Date
3-4	Time
5	Attribute (bit 0:DIR)
6-9	File size
10-n	Zero terminated filename

DELETE

Request

Offset	Value
0	$19
1-n	Zero-terminated path

Response

Offset	Value
0	0 on success / error code (<0)

RENAME

Request

Offset	Value
0	$1A
1-n	Old zero-terminated path
(n+1)-m	New zero-terminated path

Response

Offset	Value
0	0 on success / error code (<0)

MKDIR

Request

Offset	Value
0	$1B
1-n	Zero-terminated path

Response

Offset	Value
0	0 on success / error code (<0)

CHDIR

Request

Offset	Value
0	$1C
1-n	Zero-terminated path

Response

Offset	Value
0	0 on success / error code (<0)

STAT

Request

Offset	Value
0	$1D
1-n	Zero-terminated path

Response

Offset	Value
0	0 on success / error code (<0)
1-2	Date
3-4	Time
5	Attribute (bit 0:DIR)
6-9	File size

GETCWD

Request

Offset	Value
0	$1E

Response

Offset	Value
0	0 on success / error code (<0)
1-n	Zero-terminated path

CLOSEALL

Request

Offset	Value
0	$1F

Response

Offset	Value
0	0 on success / error code (<0)

LOADFPGA

Request

Offset	Value
0	$40
1-n	Zero-terminated path

Response

Offset	Value
0	0 on success / error code (<0)