git.zerfleddert.de Git - fnordlicht-mini/blame_incremental

... / ...

Commit	Line	Data
	1	SERIAL PROTOCOL FOR FNORDLICHT-NG FIRMWARE
	2	==========================================
	3
	4	Physical bus description
	5	------------------------
	6
	7	The serial bus consists of up to 254 devices, each device having the uart rx
	8	pin connected to the uart tx pin of the predecessor, the uart tx pin connected
	9	to the tx successor. The uart is used with a baud rate of 19200. A device
	10	will retransmit each received byte immediately and unaltered, the only
	11	exception is the address byte in the sync sequence (which is incremented by one
	12	before retransmission). An interrupt line is connected to each device.
	13
	14	Diagram:
	15
	16	+----------------+ +----------------+
	17	\| device N \| \| device N+1 \|
	18	UART: ... --> >-\|RX TX\|-> --> >-\|RX TX\|-> ...
	19	\| INT \| \| INT \|
	20	+-------+--------+ +-------+--------+
	21	\| \|
	22	INT: -------------------+--------------------------+----------> ...
	23
	24
	25	Bootloader startup procedure
	26	----------------------------
	27
	28	For updating the firmware installed on the devices of a bus, each device should
	29	be equipped with a bootloader program. At power-on, the bootloader should be
	30	started, sleep for 100ms and check afterwards, if the INT line is pulled down
	31	(by a bus-master). If INT is not pulled down, the bootloader is allowed to
	32	start the main firmware. Otherwise it should not attempt to start the main
	33	firmware, but wait for commands received over the bus. This procedure allows a
	34	recovery from a broken firmware which does not process commands received over
	35	the bus (such as the BOOTLOADER command). To enter the bootloader via the
	36	BOOTLOADER command, first pull down the INT line, then issue the command.
	37
	38	Initial sync sequence
	39	---------------------
	40
	41	For the purpose of (automatic) address discovery and resetting the bus, a
	42	sync sequence consisting of 15x ESC (0x1b) followed by an address byte is used.
	43	The controller sends 15x ESC, followed by a null byte. Please note that the
	44	length of the sync sequence (16 byte) is different from the length of a
	45	command packet, which is 15 byte!
	46
	47	A device MUST be able to detect this sequence asynchronously, i.e. even if it is
	48	in the middle of receiving a command packet. The device does not need to
	49	withhold the execution of the received command packet until it is clear if a
	50	sequence of ESC bytes constitutes a sync sequence.
	51
	52	Example:
	53	A device received 4 bytes, say A B C D, of a packet, then a sync sequence.
	54	It may (or may not) execute the packet
	55
	56	A B C D ESC ESC ... ESC
	57
	58	but the sync sequence must be detected, too.
	59
	60	Asynchronous detection of the sync sequence can be done by just counting the
	61	number of consecutive ESC bytes, as 15 consecutive ESC bytes can only occur
	62	in a sync sequence, never in a command packet (ESC cannot occur as a command in
	63	the second byte of a command packet).
	64
	65	Flow:
	66	* controller sends 15x ESC, followed by the address of the first device
	67	(usually a null)
	68	* first device on the bus receives and retransmits 15x ESC, receives address
	69	byte, stores own address in ram, increments address byte and transmits new
	70	address to next device on the bus
	71
	72	Result: Each device on the bus knows it's own address (=position).
	73
	74
	75	Commands
	76	--------
	77
	78	Commands are sent in packets, 15 bytes in length, and are passed from device
	79	to device unmodified. The first byte is the destination address (0-254, 255
	80	is broadcast), the second byte contains the command. The meaning of the
	81	following 13 bytes depends on the value of the second byte (command). A
	82	device ignores non-broadcast packets for which the address byte does not
	83	match it's own address. Bytes which are declared as "don't care" bytes SHOULD
	84	be set to zero, this makes future extensions easier.
	85
	86
	87	List of commands:
	88	-----------------
	89
	90	command \| function \| description
	91	--------------------------------------------------------
	92	0x01 \| FADE_RGB \| set color/fade to color (RGB)
	93	0x02 \| FADE_HSV \| set color/fade to color (HSV)
	94	0x03 \| SAVE_RGB \| save color to EEPROM (RGB)
	95	0x04 \| SAVE_HSV \| save color to EEPROM (HSV)
	96	0x05 \| SAVE_CURRENT \| save current color to EEPROM
	97	0x06 \| CONFIG_OFFSETS \| set global offset values
	98	0x07 \| START_PROGRAM \| start program
	99	0x08 \| STOP \| stop color changing
	100	0x09 \| MODIFY_CURRENT \| modify current color
	101	0x0A \| PULL_INT \| pull down INT line
	102	0x0B \| CONFIG_STARTUP \| configure startup
	103	0x0C \| POWERDOWN \| power down the device
	104	0x1B \| \| RESERVED (sync-sequence)
	105
	106	0x80 \| BOOTLOADER \| start bootloader
	107	0x81 \| BOOT_CONFIG \| configure bootloader
	108	0x82 \| BOOT_INIT \| initialize bootloader data buffer
	109	0x83 \| BOOT_DATA \| store data in bootloader data buffer
	110	0x84 \| BOOT_CRC_CHECK \| compare check-sum
	111	0x85 \| BOOT_CRC_FLASH \| compare check-sum with flash
	112	0x86 \| BOOT_FLASH \| write provided data to flash
	113	0x87 \| BOOT_ENTER_APP \| start application
	114
	115
	116	Command: FADE_RGB - set color/fade to color (RGB) (0x01)
	117	--------------------------------------------------------
	118
	119	Instruct the device to fade to the specified absolute color, given as a
	120	RGB value, with a specific speed. Step and delay might be modified by
	121	application of the global offsets (see CONFIG_OFFSETS), color values
	122	(red, green, blue) are used unmodified.
	123
	124	All values are unsigned 8 bit integers. If step is set to 255, the target
	125	color is set without fading. If delay is 0, the target color is set
	126	directly after receiving the command packet.
	127
	128	byte offset \| name \| description
	129	---------------------------------
	130	2 \| step \| increment step for fading
	131	3 \| delay \| delay between steps when fading (in 10ms)
	132	4 \| red \| red value
	133	5 \| green \| green value
	134	6 \| blue \| blue value
	135	7-14 \| - \| don't care
	136
	137
	138	Command: FADE_HSV - set color/fade to color (HSV) (0x02)
	139	--------------------------------------------------------
	140
	141	Instruct the device to fade to the specified absolute color, given as a
	142	HSV value, with a specific speed. Step, delay and hue might be modified
	143	by application of the global offsets, saturation and value might be scaled
	144	by global scales (see CONFIG_OFFSETS).
	145
	146	All values are unsigned 8 bit integers, except hue, which is a 16 bit
	147	little endian integer. If step is set to 255, the target color is set
	148	without fading. If delay is 0, the target color is set directly after
	149	receiving the command packet.
	150
	151	byte offset \| name \| description
	152	------------------------------------
	153	2 \| step \| increment step for fading
	154	3 \| delay \| delay between steps when fading (in 10ms)
	155	4-5 \| hue \| hue, 0-360, little endian
	156	6 \| saturation \| saturation
	157	7 \| value \| value (brightness)
	158	8-14 \| - \| don't care
	159
	160
	161	Command: SAVE_RGB - save color to EEPROM (RGB) (0x03)
	162	-----------------------------------------------------
	163
	164	Save a color in RGB format, a fade speed (step and delay) and a pause
	165	length to the EEPROM. The EEPROM can store 60 color and speed/delay
	166	values (see section "EEPROM color storage" below). While writing the
	167	data to the EEPROM, the INT line is pulled down.
	168
	169	All values are unsigned 8 bit integers, except pause, which is a little
	170	endian 16 bit integer.
	171
	172	byte offset \| name \| description
	173	------------------------------
	174	2 \| slot \| slot in the EEPROM (0-59)
	175	3 \| step \| increment step for fading
	176	4 \| delay \| delay between steps when fading (in 10ms)
	177	5-6 \| pause \| time to wait before fading to next color (in 100ms)
	178	7 \| red \| red value
	179	8 \| green \| green value
	180	9 \| blue \| blue value
	181	10-14 \| - \| don't care
	182
	183
	184	Command: SAVE_HSV - save color to EEPROM (HSV) (0x04)
	185	-----------------------------------------------------
	186
	187	Save a color in HSV format, a fade speed (step and delay) and a pause
	188	length to the EEPROM. The EEPROM can store 60 color and speed/delay
	189	values (see section "EEPROM color storage" below). While writing the
	190	data to the EEPROM, the INT line is pulled down.
	191
	192	All values are unsigned 8 bit integers, except pause and hue, which are
	193	little endian 16 bit integers.
	194
	195	byte offset \| name \| description
	196	-----------------------------------
	197	2 \| slot \| slot in the EEPROM (0-59)
	198	3 \| step \| increment step for fading
	199	4 \| delay \| delay between steps when fading (in 10ms)
	200	5-6 \| pause \| time to wait before fading to next color
	201	\| \| (in 100ms)
	202	7-8 \| hue \| hue, 0-360, little endian
	203	9 \| saturation \| saturation
	204	10 \| value \| value (brightness)
	205	11-14 \| - \| don't care
	206
	207
	208	Command: SAVE_CURRENT - save current color to EEPROM (0x05)
	209	-----------------------------------------------------------
	210
	211	Save the current color to EEPROM (RGB), together with a fade speed and a
	212	pause length. While writing the data to the EEPROM, the INT line is
	213	pulled down.
	214
	215	All values are unsigned 8 bit integers, except pause, which is a little
	216	endian 16 bit integers.
	217
	218	byte offset \| name \| description
	219	----------------------------------------
	220	2 \| slot \| slot in the EEPROM (0-59)
	221	3 \| step \| increment step for fading
	222	4 \| delay \| delay between steps when fading (in 10ms)
	223	5-6 \| pause \| time to wait before fading to next color
	224	\| \| (in 100ms)
	225	7-14 \| - \| don't care
	226
	227
	228	Command: CONFIG_OFFSETS - set global offset values (0x06)
	229	---------------------------------------------------------
	230
	231	Set global values which influence how fast and what colors are when using
	232	FADE_RGB or FADE_HSV or the static programs documented below. All bytes are
	233	signed 8 bit integers, except hue, which is a little endian signed 16 bit
	234	integer. Saturation and value are scales. This means, the final saturation
	235	and value will be scaled with saturation/255 and value/255, respectively.
	236
	237	byte offset \| name \| description
	238	-------------------------------------------
	239	2 \| step \| increment step for fading (offset)
	240	3 \| delay \| delay between steps when fading
	241	\| \| (in 10ms, offset)
	242	4-5 \| hue \| hue offset, signed, little endian
	243	6 \| saturation \| saturation scale, unsigned, 0-255
	244	7 \| value \| value scale, unsigned, 0-255
	245	8-14 \| - \| don't care
	246
	247
	248	Command: START_PROGRAM - start program (0x07)
	249	---------------------------------------------
	250
	251	Start a program (a function compiled into the firmware) with given
	252	parameters. This command stops all other programs (and EEPROM fade
	253	sequences). For a list of programs and parameters see section
	254	"Static Programs".
	255
	256	byte offset \| name \| description
	257	---------------------------------
	258	2 \| program \| program id, 0-255
	259	3-11 \| params \| 10 byte parameters passed to program
	260	12-13 \| - \| don't care
	261
	262
	263	Command: STOP - stop color changing (0x08)
	264	------------------------------------------
	265
	266	Stop all processes modifying the current color. Optionally, also stop
	267	the current fading process.
	268
	269	byte offset \| name \| description
	270	---------------------------------
	271	2 \| fade \| stop fading if set (1)
	272	3-14 \| - \| don't care
	273
	274
	275	Command: MODIFY_CURRENT - modify current color (0x09)
	276	-----------------------------------------------------
	277
	278	Instruct the device to fade to a new target color, which is determined
	279	relatively to the one currently visible. This works only if no
	280	program (or EEPROM fade sequence) is running. The current color is
	281	faded to the target color with the given step and delay values. The
	282	RGB offsets are applied before the HSV offsets. Setting either one to
	283	zero will not modify the color in that color space.
	284
	285	Step and delay are unsigned 8 bit integers, all other values are signed 8
	286	(or 16) bit integers.
	287
	288	byte offset \| name \| description
	289	-------------------------------------
	290	2 \| step \| increment step for fading
	291	3 \| delay \| delay between steps when fading (in 10ms)
	292	4 \| red \| red offset
	293	5 \| green \| green offset
	294	6 \| blue \| blue offset
	295	4-5 \| hue \| hue offset
	296	6 \| saturation \| saturation offset
	297	7 \| value \| value offset
	298	8-14 \| - \| don't care
	299
	300
	301	Command: PULL_INT - pull down INT line (0x0A)
	302	---------------------------------------------
	303
	304	Instruct the adressed device to immediately pull down the INT line
	305	(connected to all devices in parallel) for a given amount of time. This
	306	can be efficiently used to determine the number of devices listening to
	307	the bus (eg. by binary search).
	308
	309	byte offset \| name \| description
	310	---------------------------------
	311	2 \| delay \| time to wait before releasing the INT line
	312	\| (in 50ms, maximum 2550ms, jitter +-10ms)
	313	3-14 \| - \| don't care
	314
	315
	316	Command: CONFIG_STARTUP - configure startup (0x0B)
	317	--------------------------------------------------
	318
	319	Configure what a device should perform after power-up. Mode is an
	320	unsigned 8 bit integer, selecting the desired startup mode.
	321
	322	Two different modes can be configured:
	323
	324	* NOTHING (mode == 0):
	325	Do nothing after startup (ie do not show any color, stay black)
	326
	327	* PROGRAM (mode == 1):
	328	Start a static program compiled into the firmware, using the
	329	following 10 bytes as parameters for the program (for details
	330	see section "Static Programs").
	331
	332	If startup mode is PROGRAM, the CONFIGURE_STARTUP packet is constructed in
	333	this way (for the program indexes and meaning of the parameters see
	334	section "Static Programs"):
	335
	336	byte offset \| name \| description
	337	------------------------------------
	338	2 \| mode \| desired startup mode (1 in this case)
	339	3 \| program \| static program index
	340	4-14 \| parameters \| parameters to configured program
	341
	342
	343	Command: POWERDOWN - power down device (0x0C)
	344	---------------------------------------------
	345
	346	Power down the device. After receiving this command, the device should
	347	power down all light outputs and suspend itself to reduce the power
	348	consumption to a minimum. A device must resume operation after a falling
	349	edge on the INT pin. It is allowed to activate a pull-up resistor on
	350	that pin, to pull the pin to a defined level.
	351
	352	byte offset \| name \| description
	353	------------------------------------
	354	2-14 \| don't care \|
	355
	356
	357	Command: BOOTLOADER - start bootloader (0x80)
	358	---------------------------------------------
	359
	360	If a bootloader is installed, jump to the bootloader, otherwise just
	361	restart the device. A magic byte sequence of 0xfc27566b (little endian)
	362	must follow the command byte. Pull down the INT line BEFORE sending this
	363	command, otherwise the bootloader might not be able to detect wether to
	364	start the main firmware or remain within the bootloader code.
	365
	366	byte offset \| name \| description
	367	---------------------------------
	368	2 \| byte1 \| magic byte 1 (0x6b)
	369	3 \| byte2 \| magic byte 2 (0x56)
	370	4 \| byte3 \| magic byte 3 (0x27)
	371	5 \| byte4 \| magic byte 4 (0xfc)
	372	6-14 \| - \| don't care
	373
	374
	375	Command: BOOT_CONFIG - configure bootloader (0x81)
	376	--------------------------------------------------
	377
	378	Set configuration options of the bootloader. Currently the only
	379	options is the start address.
	380
	381	Start address is an unsigned 16-bit integer automatically incremented
	382	by the configured packet size upon each flash command.
	383
	384	byte offset \| name \| description
	385	---------------------------------
	386	2-3 \| start \| address to flash to
	387	4-14 \| - \| don't care
	388
	389
	390	Command: BOOT_INIT - initialize bootloader data buffer (0x82)
	391	-------------------------------------------------------------
	392
	393	This resets and clears the internal bootloader data buffer.
	394
	395	byte offset \| name \| description
	396	---------------------------------
	397	2-14 \| data \| payload
	398
	399
	400	Command: BOOT_DATA - store data in the bootloader data buffer (0x83)
	401	--------------------------------------------------------------------
	402
	403	Store data (up to 13 data bytes) at the end of the bootloader data
	404	buffer. If the buffer is full, additional bytes will be ignored.
	405
	406	byte offset \| name \| description
	407	---------------------------------
	408	2-14 \| data \| payload
	409
	410
	411	Command: BOOT_CRC_CHECK - compare check-sum (0x84)
	412	--------------------------------------------------
	413
	414	Compare provided CRC-16 checksum against calculated checksum over the
	415	first len bytes of previously received data in the data buffer. If both
	416	checksums do not match, the boot loader MUST immediately pull down the
	417	INT line. The INT line must be held down for the time specified in delay
	418	and be released afterwards. chksum is a little endian unsigned 16 bit
	419	integer.
	420
	421	The CRC calculation uses the polynomial x^16 + x^15 + x^2 + 1 (0xa001)
	422	and 0xffff as initial value.
	423
	424	byte offset \| name \| description
	425	---------------------------------
	426	2-3 \| len \| checksum over the first len buffer bytes in the buffer
	427	4-5 \| chksum \| CRC-16 checksum over the data chunk
	428	6 \| delay \| time to wait before releasing the INT line
	429	\| (in 50ms, maximum 2550ms, jitter +-10ms)
	430	7-14 \| - \| don't care
	431
	432
	433	Command: BOOT_CRC_FLASH - compare check-sum with flash (0x85)
	434	-------------------------------------------------------------
	435
	436	Compare provided CRC-16 checksum against calculated checksum over
	437	len bytes from flash starting at addr. If both checksums do not match,
	438	the boot loader MUST immediately pull down the INT line. The INT line
	439	must be held down for the time specified in delay and be released
	440	afterwards. Chksum, start and len are unsigned 16 bit little endian
	441	integers.
	442
	443	The CRC calculation uses the polynomial x^16 + x^15 + x^2 + 1 (0xa001)
	444	and 0xffff as initial value.
	445
	446	byte offset \| name \| description
	447	---------------------------------
	448	2-3 \| addr \| checksum len bytes starting at this address
	449	4-6 \| len \| checksum over the first len buffer bytes in the buffer
	450	6-8 \| chksum \| CRC-16 checksum over the data chunk
	451	9 \| delay \| time to wait before releasing the INT line
	452	\| (in 50ms, maximum 2550ms, jitter +-10ms)
	453	10-14 \| - \| don't care
	454
	455
	456	Command: BOOT_FLASH - write provided data to flash (0x86)
	457	---------------------------------------------------------
	458
	459	Write the data provided earlier to the flash memory of the device.
	460
	461	The device pulls the interrupt line down upon reception of the command
	462	and releases it on successful completion of the command. This way the
	463	master node is capable of detecting when the successing initial data
	464	packet may be provided by continuously sensing the interrupt line.
	465
	466	After completion of this command the address where to flash to is
	467	incremented by the configured chunk data size.
	468
	469
	470	byte offset \| name \| description
	471	---------------------------------
	472	2-14 \| - \| don't care
	473
	474
	475	Command: BOOT_ENTER_APP - start application (0x87)
	476	--------------------------------------------------
	477
	478	Leave bootloader and launch application code.
	479
	480
	481	byte offset \| name \| description
	482	------------------------------------
	483	2-14 \| - \| don't care
	484
	485
	486	Static Programs
	487	---------------
	488
	489	This section describes the programs which are (in the default version)
	490	compiled into the firmware.
	491
	492	program "colorwheel", program index 0
	493	-------------------------------------
	494
	495	This program fades throught the HSV color space, with fixed saturation and
	496	value, starting at hue_start. In each step, hue_step is added to the
	497	current hue value, afterwards the device fades to the resulting color (using
	498	fade_step and fade_delay) and waits for the time specified by fade_sleep.
	499
	500	If add_addr is nonzero (attention: signed integer!), the fade ist not
	501	started at hue_start but (hue_start + addr_add * device_address * hue_step).
	502
	503	This program honors the globally defined offsets set with the CONFIG_OFFSETS
	504	command in each step. If a global offset is reconfigured, the new value
	505	will be applied in the next color calculation of this program.
	506
	507	byte offset \| name \| description
	508	---------------------------------------------------------
	509	0 \| fade_step \| used for fading to new color
	510	\| \| (unsigned 8 bit integer)
	511	1 \| fade_delay \| used for fading to now color
	512	\| \| (unsigned 8 bit integer)
	513	2 \| fade_sleep \| sleep between steps (in seconds)
	514	\| \| (unsigned 8 bit integer)
	515	3-4 \| hue_start \| start at this hue value
	516	\| \| (unsigned 16 bit integer
	517	5-6 \| hue_step \| add this to the hue in each step
	518	\| \| (signed 16 bit integer)
	519	7 \| add_addr \| add hue_step address-times before start
	520	\| \| (signed 8 bit integer)
	521	8 \| saturation \| saturation
	522	\| \| (unsigned 8 bit integer)
	523	9 \| value \| value
	524	\| \| (unsigned 8 bit integer)
	525
	526
	527	program "random", program index 1
	528	---------------------------------
	529
	530	When this program is started, the pseudo-random generator is initialized
	531	with the seed value. If the use_address-bit within the flags byte is set,
	532	the address of a device is XORed with the seed before initializing the
	533	pseudo-random generator, so the random values also depend on the address of
	534	the device.
	535
	536	In each step, this program generates a new random hue value which is at
	537	least min_distance away from the current hue value. Afterwards the device
	538	fades to the new color (using the generated hue and the configured
	539	saturation and value from the parameters). The parameters fade_step and
	540	fade_delay are used in each fade. If the wait_for_fade-bit within the
	541	flags byte is set, the device waits until the target color is reached.
	542	Afterwards the device sleeps for a configurable amount of time (fade_sleep).
	543
	544	This program honors the globally defined offsets set with the CONFIG_OFFSETS
	545	command in each step. If a global offset is reconfigured, the new value
	546	will be applied in the next color calculation of this program.
	547
	548	flags (1 byte)
	549	--------------
	550
	551	Bits:
	552	MSB LSB
	553	7 6 5 4 3 2 1 0
	554	\| \| \| \|
	555	\| \| \| \- use_address -- XOR device address and seed before
	556	\| \| \| initializing the pseudo random generator
	557	\| \| \--- wait_for_fade -- wait until the (newly generated)
	558	\| \| target color is reached before sleeping
	559	\---------+----- reserved
	560
	561	byte offset \| name \| description
	562	----------------------------------------------------------------------
	563	0-1 \| seed \| used for initializing the random generator
	564	\| \| (unsigned 16 bit integer)
	565	2 \| flags \| flags
	566	\| \| (unsigned 8 bit integer)
	567	3 \| fade_step \| used for fading to new color
	568	\| \| (unsigned 8 bit integer)
	569	4 \| fade_delay \| used for fading to now color
	570	\| \| (unsigned 8 bit integer)
	571	5-6 \| fade_sleep \| sleep between steps (in 100ms)
	572	\| \| (unsigned 16 bit integer)
	573	7 \| saturation \| saturation
	574	\| \| (unsigned 8 bit integer)
	575	8 \| value \| value
	576	\| \| (unsigned 8 bit integer)
	577	9 \| min_distance \| minimal distance for new hue value
	578	\| \| (unsigned 8 bit integer)
	579
	580
	581	program "replay", program index 2
	582	---------------------------------
	583
	584	The commands SAVE_RGB, SAVE_HSV and SAVE_CURRENT stores a color,
	585	fade_step, fade_delay and fade_sleep to the EEPROM. This program replays
	586	the stored colors, from start to end. If repeat is 0, the sequence stops
	587	when end is reached, if repeat is 1, the sequence is restarted from the
	588	beginning and if repeat is 2, the color sequence is played in reverse
	589	order, from end to beginning.
	590
	591	This program honors the globally defined offsets set with the CONFIG_OFFSETS
	592	command for hsv colors in each step. If a global offset is reconfigured,
	593	the new value will be applied in the next color calculation of this program.
	594
	595	byte offset \| name \| description
	596	----------------------------------------------------------------------
	597	0 \| start \| index of the first color
	598	\| \| (unsigned 8 bit integer)
	599	1 \| end \| index of the last color (included)
	600	\| \| (unsigned 8 bit integer)
	601	3 \| repeat \| configure repetition
	602	\| \| (unsigned 8 bit integer)
	603	4-9 \| don't care \|