Host2Hub File Sync Protocol

Packet Format

AEach packet always starts with a colon (:). This is to filter out unrelated data by e.g. micropython itself.
This is followed by a one byte long identifier specifyingfollowed by the packetarguments. type.

The

Withoutend an argument

Without an argument,of the packet is nowsignalized closed withby a closing bracketSUB (]).0x1A) byte. (This is subject to change and will likely be replaced by a NUL (0x00) byte in the future. The different packets are listed below.

With

Generally, the host sends a packet to the hub and the hub responds. The only cases in which the hub actively sends a packet are if it reports an argmument

error,

Fourdelivers digitsa willprint specifymessage or tells the lengthhost ofabout theits followingblock base64 encoded argument.
status.

Packet Types

The Host can send these Packets, the Hub must handle these packets:

Identifier	Type	Meaning	Argmuent
Y (0x59)	Actively Sent	Start SYNC Mode
D (0x44)	Actively Sent	Ensure Directory exists	/path/to/dir
F (0x46)	Actively Sent	Ensure File has same Hash	/path/to/file SHA256
C (0x43)	Response	CHUNK	192 Bytes of the file data (base64-encoded compressed file)
E (0x45)	Response	End Of File
N (0x4E)	Actively Sent	End SYNC Mode
R (0x52)	Actively Sent	Remove File or Directory	/path/to/file/or/diretory
P (0x50)	Actively Sent	Start Program (loop() from /__init__.py)
X (0x58)	Actively Sent	Stop Program
& (0x26)	Actively Sent	Reboot
= (0x3D)	Actively Sent	Sync Communication	timestamp
> (0x3E)	Actively Sent	Enter REPL
$ (0x24)	Actively Sent	Reset State

The Hub can send these Packets, the Host must handle these packets:

P

Identifier	Type	Meaning	Argmuent
K (0x4B)	Response	OK
= (0x3D)	Response	Sync Communication	given timestamp
U (0x55)	Response	Request File Contents
! (0x21)	Actively Sent	Internal Error	traceback
E (0x45)	Actively Sent	User Error	traceback
$	Actively Sent	Please Reconnect
P(0x50)	Actively Sent	Print	json-encoded args & kwargs
B (0x42)	Actively Sent	Blocking call, will be inresponsive
D (0x44)	Actively Sent	No more blocking call, will be responsive again

Packets written in italics are not yet documented below.

Examples

Sync all files

If a full tree needs to be synced to the hub, this is the right choice.

1. Host sends Y to start SYNC Mode.
   Hub responds with K.
2. Here, Files and Directories are updated.
   Refer to Update an individual file and Update an individual directory.
3. Host sends N to stop SYNC Mode.
   Hub responds with K.

Effect

Upon receiving N, the Hub deletes all files and directories that were not updated since Y was sent.

Update an individual file

1. Host sends F. The argument is the file's path and its SHA256 Hash, seperated by a space. The file path needs to start with /.
   Hub responds with K, or with U.
2. If U was sent, Host repeatedly sends C with 192 bytes of the file as argmuent, or E if EOF is reached.
   Hub responds to each of these packets with K. Hub can respond with U to E if the hash is still not matching.

Effect

The Hub checks whether the file exists and has the correct hash. If it is correct, it responds with K. Otherwise, it sends U and stores the file received in the following C packets under the given file path.

Update an individual directory

1. Host sends D with the file path as argument. The file path needs to start with /.
   Hub responds with K.

Effect

The Hub ensures the directory exists.

Delete an individual file or directory

1. Host sends R with the file path as argument. The file path needs to start with /.
   Hub responds with K.

Effect

The Hub deletes the file or directory found under the given file path.
path if it exists. Non-empty directories are cleared.

Start the program

1. Host sends P.
   Hub responds with K.

Effect

The Hub stops the task it created when it received P the last time, if it exists.
The Hub starts the loop() function it found in the /__init__.py file by creating a new task using asyncio.

Stop the program

1. Host sends X.
   Hub responds with K.

Effect

The Hub stops the task it created when it received P the last time, if it exists.

Sync connection

1. Host sends = with somearbitrary uniwue identifier, eg. the current timestamp,data as argument.
   Hub echos the packet.

Effect

TheEcho. HostPing-Pong. skips all packets until it receives the echo in order to ignore the hubs responses made before the connection was established. It is recommended to use this at the start of everyVerify connection.

Open REPL

1. Host sends >.

Effect

The Hub stops all running tasks and returns control to the Micropython REPL.

[OUTDATED: This is to be preferred in comparison to sending Ctrl-C (which also works), as it makes sure the print() function works as expected afterwards.] -> [NOTE: Ctrl-C should not work]

Reboot Hub

1. Host sends &.

Effect

The Hub reboots.

ResetCancel Connectionsync

1. Host sends $.
   Hub responds with K.

Effect

The Hub resets its sync state. It is recommended to send this when a new connection is made.