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