tcp.md

LED Matrix TCP protocol

Command structure

A command is at most 8 bytes long and comprised of the following (in order)

1. Single byte header
2. Variable amount of arguments

Command sequencing

Multiple commands can be sequenced into one packet and they will be executed one by one. To use the faster method of putting multiple commands in one TCP packet they must be ordered sequentially and each command must be 8 bytes long.

Doing this wil configuration and graphics calls is recommended however you should not do this with query calls since the result of a query call has a 1/255 chance of being 0, and that will count as an error, causing all execution to stop

Command execution

When a command is executed an ASCII return code is given to indicate whether or not it executed successfully, if it failed then the entire list of commands in the packet are disposed of and the return code is given. Due to the nature of TCP transmission errors will not happen, so packet errors must be caused by the client.

If the command is a query call, no unique error code is given instead it just returns zero

Return codes

Name	#	Description
Success	0	It was successful
Invalid header	101	The header was not recognized
Invalid position	102	One or more of the provided coordinates is invalid
Invalid command param	103	One or more of the supplied parmeter(s) is invalid
Invalid command length	104	The command's length is invalid
Client too fast	201	The client is sending data faster then the server can handle it When triggered the client is disconnected and a return code may or may not be sent This can only happen if the client ignores the return codes
Unknown error	202	There was an unknown error

Valid commands

Name	Header	Arguments	Size	Description
Configuration calls				Calls used to modify the current configuration context
Reset	0xFF	7x 0xFF	8B	Resets the buffer and configuration context
Brightness	B	Brightness	2B	Sets the brightness (between 0 and 255)
Set color	C	RGB	4B	Sets the color
Stroke color	S	RGB	4B	Enables and sets the stroke color
Nostroke	N	None	1B	Disables the stroke entirely
Graphics calls				Calls used to draw to the screen
Update	u	None	1B	Updates the screen
Fill	f	None	1B	Fills the screen based off the fill color
Line	l	X1, Y1, X2, Y2	5B	Draws a line from (X1, Y1) to (X2, Y2)
Rect	r	X1, Y1, X2, Y2	5B	Draws a rectangle from (X1, Y1) to (X2, Y2)
Ellipse	e	X, Y, W, H	5B	Draws an ellipse centered at (X, Y) with size (W, H)
Pixel	p	X, Y	3B	Draws a pixel at (X, Y) with color fill color
Scroll left	>	Amount	2B	Scrolls the pixels on the display left by an amount
Scroll right	<	Amount	2B	Scrolls the pixels on the display right by an amount
Query calls				Calls used to query the display
Query width	?	W	2B	Returns the width of the display as an error
Query height	?	H	2B	Returns the height of the display as an error

Longevity of configuration calls

Any configuration changes are reset upon a new TCP connection or reset command