specs.rst

Specifications

Message format

The message format is NDEF. This is used to transmit data to a phone using NFC. An NDEF message has 3 fields: Type, Length and Value.

NDEF Msg.	CODEC_FEAT_1	CODEC_FEAT_2	Value
Byte	0	1 | 2 | 3	4...
Data	0x03	0xFF | MSB | LSB	CODEC_SPEC_3

NDEF URL record

Sensor data are stored in a URL record. As it is the only one in the message and of a known type, a phone opens the URL automatically in its default web browser.

NDEF record header

Desc	CODEC_SPEC_5	CODEC_FEAT_4	CODEC_FEAT_3	CODEC_FEAT_5
Byte	0	1	2 | 3 | 4 | 5	6
Data	0xC3	0x01	PL[3] | PL[2] | PL[1] | PL[0]	0x55

NDEF record payload start

Desc.	CODEC_FEAT_44	CODEC_FEAT_7	CODEC_FEAT_10	CODEC_FEAT_38
Data	0x03	t.plotsensor.com	/?t=AWg*	&s=YWJjZGVm

NDEF record payload continued

Desc.	CODEC_SPEC_18	CODEC_SPEC_15	CircBufferStart	CODEC_SPEC_12
Data	&v=AAAA	&x=AAABALEK	&q=	MDaWMDaW...

Circular Buffer

The circular buffer starts on a block boundary and occupies an integer number of 16-byte blocks. 1K of EEPROM is enough for 32 blocks.

Only two blocks are edited in RAM at a time:

Cursor Block	Next Block
Cursor Demi | Endstop   Demis	nbsp| (0,1) | Oldest Demi
P64\1 | P64\0 |	P64\N | P64\N-1
R64\3 | R64\2 | R64\1 | R64\0 |	R64\L | R64\L-1 | R64\L-2 | R64\L-3

Blocks are subdivided into two 8-byte demis. Each demi holds 2 base64 encoded pairs.

Each pair consists of 2 base64 encoded sensor readings. By default these will be captured simultaneously by a temperature sensor and a humidity sensor.

New sensor readings are written to Cursor Demi. Each time this occurs, the subsequent CODEC_SPEC_13 is updated.

When Cursor Demi is full, both it and the endstop are moved forward when the next sensor reading is added:

Cursor Block	Next Block
Demi | Cursor Demi	Endstop Demis (0,1)
S2 | S1 | S0 | Spad
R5 R3 R1

The previous oldest demi is overwritten. Note there can be a gap between the most recent sample and the start of the endstop demis. This is zero padded. The padding will not be decoded because the number of valid samples in the buffer is included in the endstop.

Endstop

The endstop occupies 2 demis (16 bytes) after the cursor demi. It is terminated with a unique character. This marks the end of the circular buffer; the divide between new and old data. The decoder finds this in order to unwrap the circular buffer into a list of samples, ordered newest to oldest.

Demi |	Endstop 0 |	Endstop 1
Byte	0 | 1 | 2 | 3 | 4 | 5 | 6 | 7	8 | 9 | 10 | 11 | 12 | 13 | 14 | 15
Description	CODEC_SPEC_14	CODEC_SPEC_17 | )

The endstop contains data about the current state of the circular buffer, for example the number of valid samples it contains. These data are appended to the circular buffer to meet CODEC_SPEC_2.

VFmt b64

This is a 3 byte structure that expands to 4 bytes after base64 encoding.

The unencoded structure is:

Byte	0	1	2
Description	:need:`CODE	C_FEAT_41`	CODEC_FEAT_42

HashN b64

This is a 9 byte structure that expands to 12 bytes after base64 encoding.

The unencoded structure is:

Byte	0	1	2	3	4	5	6	7	8
Description	:ne	ed:`	CODE	C_FE	AT_2	4`		:ne	ed:CODEC_FEAT_25

Status b64

This is a 6 byte structure that expands to 8 bytes after base64 encoding.

It corresponds to :cppstatus. Status information is used by the decoder to determine if the encoder and its microcontroller host are running ok.

The unencoded structure is:

Byte	0	1	2	3	4	5
Description	:need:`C	ODEC_FEAT_28`	:need:`C	ODEC_FEAT_29`	CODEC_FEAT_30	CODEC_SPEC_16

ResetCause

Flags to indicate causes of the most recent microcontroller reset.

Bit	0	1	2	3	4	5	6	7
Description	CODEC_FEAT_31	CODEC_FEAT_32	CODEC_FEAT_33	CODEC_FEAT_34	CODEC_FEAT_35	CODEC_FEAT_36		CODEC_FEAT_37

TNF + flags

TNF and flags for the NDEF record.

Bit	7	6	5	4	3	2	1	0
Field	CODEC_FEAT_17	CODEC_FEAT_18	CODEC_FEAT_19	CODEC_FEAT_20	CODEC_FEAT_21	CODEC_FEAT_22
Data	1	1	0	0	0	0x03

Low memory utilisation

The encoder must use <2K of RAM and <16K of non-volatile FRAM, as can be found on an MSP430FR2033 microcontroller.

Reduce EEPROM wear

Low power consumption

The encoder will run for >2 years on a hardware powered by a CR1620 battery.

Zero user configuration

The encoder must run without input from the user. This includes after the Power-on-Reset when a battery is replaced.

URL parameters decoded

Before the circular buffer is decoded, URL parameters such as CODEC_SPEC_18 are needed.

Circular buffer decoded

The decoder outputs a list of samples from the URL. Output depends on CODEC_FEAT_42. By default samples will contain temperature and humidity readings, converted to degrees C and percent respectively. Each will have a timestamp precise to one minute. This corresponds to the time that the sample was added to the circular buffer.