TRM: ESP32 interface - fvdhoef/aquarius-plus GitHub Wiki
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 |
| $0F |
GETMIDIDATA |
Get MIDI controller data |
MIDI 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 |
| $23 |
LSEEK |
Seek in file with offset and whence |
File |
| $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
VERSION
Request
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
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) |
GETMIDIDATA
Request
| Offset |
Value |
| 0 |
$0F |
| 1-2 |
Length to read (at most) (16-bit) |
Response
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) |
LSEEK
Request
| Offset |
Value |
| 0 |
$14 |
| 1 |
File descriptor |
| 2-5 |
Seek offset (signed 32-bit) |
| 6 |
Whence (0:SEEK_SET, 1:SEEK_CUR, 2:SEEK_END) |
Response
| Offset |
Value |
| 0 |
0 on success / error code (<0) |
| 1-4 |
New offset |
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
Response
| Offset |
Value |
| 0 |
0 on success / error code (<0) |
| 1-n |
Zero-terminated path |
CLOSEALL
Request
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) |