Exploitee.rs - User contributions [en]

Nest Hacking

2014-08-10T21:13:51Z

Luke-Jr: /* Backplate state */

== Hardware ==

[https://www.ifixit.com/Teardown/Nest+Learning+Thermostat+2nd+Generation+Teardown/13818 Pictures]

=== Backplate ===
* ST Microelectronics STM32L151VB ultra-low-power 32 MHz ARM Cortex-M3 MCU
* Sensirion SHT20 humidity and temperature sensor
* Texas Instruments LW051A 8-channel CMOS analog multiplexer/demultiplexer

=== Display ===
* Texas Instruments AM3703CUS Sitara ARM Cortex A8 microprocessor
* Texas Instruments TPS65921B power management and USB single chip
* Samsung K4X51163PK 512 Mb mobile DRAM
* Ember EM357 integrated ZigBee/802.15.4 system-on-chip
* Micron MT29F2G16ABBEAH4 2 Gb NAND flash memory
* Skyworks 2436L high power 2.4 GHz 802.15.4 front-end module
* Texas Instruments WL1270B 802.11 b/g/n Wi-Fi solution
* Avago ADBM-A350 optical finger navigation module (knob movement sensor)

== Info ==
* /dev/event1 is the knob; /dev/event2 is the button
* /sys/class/hwmon/hwmon0/device/in0_battery_type * 0.003 is battery voltage
** Nest turns off wifi below 3.7 V, and waits until 3.8 V to automatically reconnect
* Display serial number is located in U-Boot environment variable "serial#"

== Nest software ==
/nestlabs/sbin/nlclient -config /nestlabs/etc/client.config -config /nestlabs/etc/Display/Display-2/client.config

=== Backplate communications ===
Backplate communications can be decoded from a (filtered) strace log using [http://luke.dashjr.org/programs/freeabode/kindling/NestDecode.pl NestDecode.pl], or decoded in real time using [http://luke.dashjr.org/programs/freeabode/kindling/nest-intercept.c nest-intercept.c].

nest-intercept.c requires one argument, the thread id reading from the backplate controller.
The easiest way to get this is to strace the nlclient process with -ff and look for a thread reading from fd 54.

Note that nest-intercept.c also has a "hack" variable which can be set to 0 (default is 2) in order to corrupt the TFE version response and trigger nlclient into uploading the firmware again.

=== Backplate firmware ===
Found in /nestlabs/share/bp/data/firmware/nlbpfirmware.plist

There are 12 different firmwares in the file:
* Test vs Production
* Backplate 2 vs Backplate 3
* TFE (BP_D2 for Bp2, AMBER_BP for Bp3) vs BSL
* For TFE firmwares, hex vs srec (which for some reason DO differ!)

Python script to extract them into individual files: [http://luke.dashjr.org/programs/freeabode/kindling/extract-fw.py extract-fw.py]

=== Backplate initialisation ===
When the backplate is first connected, the following sequence occurs:
tcflush(fd, TCIFLUSH)
Set baud to 115200 (-opost -isig -icanon -echo ...)
tcflush(fd, TCIOFLUSH)
tcsendbreak(fd, 1)
Send [[#Reset|00ff - Reset]]
Recv 0001 - (message from backplate; ASCII)
Recv [[#FET presence|0004 - FET presence]]
Recv [[#FET presence|0009 - FET presence]]
Send [[#FET presence|008f - FET presence]]
Send [[#Periodic status|0083 - Periodic status request]]
Send 0090 - get Mono/TFE id (no data; response 0010 with 3 bytes)
Recv 0001 - (message from backplate; ASCII)
Recv 0001 - (message from backplate; ASCII)
Recv 0010 - (24-bit data)
Send [[#Get Mono/TFE version|0098 - Get Mono/TFE version]]
Recv 000a - (every second; 16-bit data)
Recv 0007 - (every second; 16-bit data)
Recv [[#Get Mono/TFE version|0018 - Get Mono/TFE version (response)]]
Send [[#Get Mono/TFE build info|0099 - Get Mono/TFE build info]]
Recv [[#Get Mono/TFE build info|0019 - Get Mono/TFE build info (response)]]
Sometimes:
Send 009d - get BSL id (no data; responds with 001d)
Recv 001d - bsl id (response to 009d; 16-bit data)
Sometimes:
Send [[#Get BSL version|009b - Get BSL version]]
Recv [[#Get BSL version|001b - Get BSL version (response)]]
Sometimes:
Send 009c - get BSL info (no data; responds with 001c (constant?) data="BSL")
Recv 001c - Response to 009c; always(?) "BSL"
Send [[#Get serial number|009f - Get serial number]]
Recv [[#Get serial number|001f - Get serial number (response)]]
Send [[#Get hardware version|009e - Get hardware version]]
Recv [[#Get hardware version|001e - Get hardware version (response)]]

== Nest backplate interface ==
* Connected on /dev/ttyO2
* All communications with backplate begin with (d5)d5aa96 (d5 is doubled only for data FROM backplate)
* Everything is little endian
* 16-bit command
* 16-bit data length
* <data>
* 16-bit checksum

Monitor:
strace -ff -p $(pidof nlclient) -x -s9999 -e read,write 2>&1 | grep '(54'

NOTE: Most of this documentation is reverse engineered from firmware version BSL-2.1 and/or TFE_BP_D2-4.0.21 for Backplate-2.x.

=== Checksum ===
<Bytes-from-end>.<bit-value> <xor-with>
00.01 2110 (1021)
00.02 4220 (2042: 1021<<1)
00.04 8440 (4084: 2048<<1)
00.08 0881 (8108: 4084<<1)
00.10 3112 (1231: 8108<<1^1021)
00.20 6224 (2462: 1231<<1)
00.40 c448 (48c4: 2462<<1)
00.80 8891 (9188: 48c4<<1)
01.01 3133 (3313: 9188<<1^1021)
01.02 6266
01.04 c4cc
01.08 a989
01.10 7303
01.20 e606
01.40 cc0d
01.80 981b
02.01 3037
02.02 606e
...
03.01 b476
03.02 68ed
03.04 f1ca
03.08 c385
03.10 a71b
03.20 4e37
03.40 9c6e
03.80 38dd
...
07.20 687b

If you compute the contribution of the individual bit changes in the data you end up with the xor table above; byte offset from the end of the data, bit pattern, xor value. Correcting for little endianess in the output you end up with the hex values in parenthesis. The least significant bit is 0x1021 and each subsequent bit is a shift left, if the XOR value has the 0x8000 bit set then it is XORed with 0x1021. This is the CRC-CCITT polynomial.

8 7 6 5 4 3 2 1 0
d5 aa 96 82 00 02 00 00 00: 08b2
|| |
|| 68ed
|408b
20d4

08b2: 68ed ^ 408b ^ 20d4

Starting at the least significant bit and filling in the XOR values for each bit gives the above diagram; the diagram stops at the 20d4 XOR value because at that point it matches the final CRC. This tells us that the CRC covers the 6 bytes prior.

#!/usr/bin/env perl
use Digest::CRC qw(crc);
my $data = pack("H*", "820002000000");
printf("%04x\n", crc($data,16,0,0,0,0x1021,0,0));

We can also compute the same CRC in Perl; note the result will be byte swapped since the data encodes the number as little endian.

=== Command ids ===

==== Display to backplate ====
[[#FET control|0082 - FET control]]
[[#Periodic status|0083 - Periodic status request]]
[[#FET presence|008f - FET presence]]
0090 - get Mono/TFE id (no data; response 0010 with 3 bytes)
[[#Backplate firmware upload|0091 - Backplate firmware upload (start)]]
[[#Backplate firmware upload|0092 - Backplate firmware upload]]
[[#Backplate firmware upload|0093 - Backplate firmware upload (finish)]]
[[#Get Mono/TFE version|0098 - Get Mono/TFE version]]
[[#Get Mono/TFE build info|0099 - Get Mono/TFE build info]]
[[#Get BSL version|009b - Get BSL version]]
009c - get BSL info (no data; responds with 001c (constant?) data="BSL")
009d - get BSL id (no data; responds with 001d)
[[#Get hardware version|009e - Get hardware version]]
[[#Get serial number|009f - Get serial number]]
00a1 - quiet (16-bit max sleep seconds)
[[#"Buffers"|00a2 - Request "buffers" (every 30 seconds; no data; triggers [0025] [0027] 0022 0023 [0029] [002b] 000c 002f)]]
[[#"Buffers"|00a3 - ACK to 002f (no data)]]
00a4 - set wakeup mask (16-bit data)
00b1 - "temperature lock" (sent when button pressed/unpressed; no data)
00b3 - set humidity thresholds (32-bit data)
00b5 - set near pir threshold (16-bit data)
00b7 - set pir thresholds (??? data)
00b8 - set proximity thresholds (??? data)
00b9 - set als thresholds (32-bit data)
00ba - set vergence mode (48-bit data)
00c2 - set wakeup temperatures (48-bit data)
00c3 - set temp comp mode request (??? data)
00fe - DEBUG MODE
[[#Reset|00ff - Reset]]

==== Backplate to display ====
0001 - (message from backplate; ASCII)
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
[[#FET presence|0004 - FET presence]]
0005 - pir? (32-bit data)
0006 - "ack switch" (data: 8-bit switch id, 8-bit state)
0007 - near pid? (every second; 16-bit data)
0008 - proximity?
[[#FET presence|0009 - FET presence]]
000a - als? (every second; 2x(?) 16-bit data)
[[#Backplate state|000b - Backplate state]]
000c - sensor? (16-bit values: pir, px1, px1 divisor, px2, px2 divisor, alir, av; included in [[#"Buffers"|"buffers" data]])
000e - power?
0010 - (24-bit data)
[[#Backplate firmware upload|0011 - Backplate firmware upload (ACK)]]
0012 - ?
0013 - "Wakeup"?
0014 - "WakeVector" (16-bit data)
[[#Get Mono/TFE version|0018 - Get Mono/TFE version (response)]]
[[#Get Mono/TFE build info|0019 - Get Mono/TFE build info (response)]]
[[#Get BSL version|001b - Get BSL version (response)]]
001c - Response to 009c; always(?) "BSL"
001d - bsl id (response to 009d; 16-bit data)
[[#Get hardware version|001e - Get hardware version (response)]]
[[#Get serial number|001f - Get serial number (response)]]
[[#"Buffers"|0022 - buffered temperature reading (possibly multiple times)]]
[[#"Buffers"|0023 - BufferedSourceTemperature (3x 16-bit data; possibly multiple times)]]
[[#"Buffers"|0025 - BufferedNearPir (16-bit data; possibly multiple times)]]
[[#"Buffers"|0027 - BufferedPassiveInfrared (64-bit data; possibly multiple times)]]
[[#"Buffers"|0029 - BufferedAmbientLightSensor (48-bit data; likely 3x 16-bit; possibly multiple times)]]
[[#"Buffers"|002b - BufferedPowerData (64-bit data; possibly multiple times)]]
[[#"Buffers"|002f - End of "buffers" (16-bit data)]]

=== Backplate firmware upload ===
For uploading the firmware, the following sequence is used:
Send 0091 data=0000<firmware type>
Recv 0011 data=0000
Send 0092 data=0100...
Recv 0011 data=0100
Send 0092 data=0200...
Recv 0011 data=0200
...
Send 0092 data=a901...
Recv 0011 data=a901
Send 0093 data=aa01
Recv 0011 data=aa01
Following the upload, the [[#Backplate initialisation|backplate initialisation process]] begins immediately (that is, without message 00ff being sent to order a reset).
Presumably the 0011 message is an ACK, and the first 16 bits of each message is the line number.
The format itself appears to be Motorola S-record (SREC).
Uploading the BSL firmware was followed by the TFE firmware, so it may be required (though uploading the TFE firmware does ''not'' require uploading the BSL).

Firmware type is either 4d for TFE or 42 for BSL.

=== Backplate state ===
Data:
* 8-bit "state"
* 8-bit "flags"
** Bit 0x40 = charger off (?)
* 8-bit "px0" (may be wider?)
* ? 16-bit "sw" fraction (0800 = 08/00)
* ? 8-bit "p2"
* ? 16-bit "voc"
* 16-bit centi-volts "vi"
* 16-bit milli-volts "vo"
* 16-bit milli-volts "vb"
* 8-bit "pins"
* 8-bit "wires"

=== "Buffers" ===
The 00a2 message requests the backplate send the contents of various "buffers", which are returned in messages [0025], [0027], 0022, 0023, [0029], and [002b] (empty ones will NOT be sent; brackets infer commonly-empty buffers).
00a2 also triggers 000c immediately following these.
After all the buffers (including 000c) have been sent, the message 002f indicates "end of buffers".
The display is then expected to acknowledge it with message 00a3.

Buffers:
[[#Temperature reading|0022 - Temperature reading]]
0023 - BufferedSourceTemperature (not sure what that means)
0025 - BufferedNearPir
0027 - BufferedPassiveInfrared
0029 - BufferedAmbientLightSensor
002b - BufferedPowerData

=== FET control ===
Turn on W1: d5aa96 8200 0200 00 01 29a2
Turn off W1: d5aa96 8200 0200 00 00 08b2
Turn on Y1: d5aa96 8200 0200 01 01 1891
Turn off Y1: d5aa96 8200 0200 01 00 3981
Turn on G : d5aa96 8200 0200 02 01 4bc4
Turn off G : d5aa96 8200 0200 02 00 6ad4
Turn on OB: d5aa96 8200 0200 03 01 7af7
Turn off OB: d5aa96 8200 0200 03 00 5be7
Turn on W2: d5aa96 8200 0200 04 01 ed6e
Turn off W2: d5aa96 8200 0200 04 00 cc7e
Turn on Y2: d5aa96 8200 0200 07 01 be3b
Turn off Y2: d5aa96 8200 0200 07 00 9f2b
Turn on * : d5aa96 8200 0200 0b 01 d37e
Turn off * : d5aa96 8200 0200 0b 00 f26e

For the sake of documentation, we will refer to the unique id numbers for each wire as "wire id numbers".
So wire id 0 is W1, wire id 1 is Y1, wire id B is *, etc.

=== FET presence ===
The backplate will, at least upon connection, send information about which FETs have a wire present.
This data is received with command ids 0004 and 0009, in that order.
Each sensor is represented by one byte which is either 00 (not present) or 01 (present).

The content of 0004 is in order of the "wire id numbers" used for control:
W1, Y1, G, OB, W2, ?0, ?0, Y2, C, RC, ?0, *, ?0

The content of 0009 is arranged differently and has 2 more values:
W1, Y1, C, RC, ?0, G, OB, W2, ?0, Y2, ?0, *, ?0, ?0, ?0

0009 seems to indicate a wire is physically plugged in, while 0004 indicates that it is connected to something (?).

After these are received, the display sends back command 008f with the exact data from message 0004.
Message 008f does not itself receive any response.

In a power outage condition, 0004 will report all absent (including unknown ones), whereas 0009 will continue to report the same as when power is available.

=== Get Mono/TFE build info ===
Message 0099 (no data) requests the backplate report information about its build.
The response will be message 0019 in ASCII (one line, no trailing newline).

=== Get hardware version ===
Message 009e (no data) requests the backplate report a "Backplate-"X.Y version string.
Since the firmware file on the display CPU uses these strings as "MinApplicability" and "MaxApplicability" ranges, it is probable they refer to the hardware.

Witnessed versions:
"Backplate-2.8" - Florida Lowes

=== Get BSL version ===
Message 009b (no data) requests the backplate report its BSL version number.
The response will be message 001b in ASCII.

=== Get Mono/TFE version ===
Message 0098 (no data) requests the backplate report its TFE version number.
The response will be message 0018 in ASCII.

=== Get serial number ===
Message 009f (no data) requests the backplate report its serial number (a 64-bit hexadecimal value).
The response will be message 001f in uppercase ASCII.

=== Periodic status ===
Sending message 0083 (no data) will trigger various periodic messages:
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
000a - (every second; 16-bit data)

The Nest client sends 0083 every 30 seconds, but at least the periodic temperature status will continue on for an hour before stopping.

=== Power management ===
Wake vector bits:
0001 - timer
0002 - buffers full
0004 - temperature
0008 - pir
0010 - proximity
0020 - humidity
0040 - near pir
0080 - als
0100 - "vbat"
0200 - "vergence"

=== Temperature reading ===
The backplate will send message 0002 every 30 seconds.
The data contains two 16-bit numbers, which nlclient logs in decimal.
The first number is the temperature in centi-celcius.
The second number is the humidity in per-millis.

See also: [[#"Buffers"|"Buffers"]]

=== Reset ===
At least upon connection, the display sends message 00ff to the backplate to reset.

The backplate answers with:
0001 msg "<version> <build timestamp "YYYY-MM-DD HH:MM:SS"> K"
[[#FET presence|0004 FET presence]]
[[#FET presence|0009 FET presence]]
0001 msg "*sense 06d1 06d0 0001 0001 0000 0000 0000 0001 06d9 06d8 06d8; detect 09d3 065c"
0001 msg "BRK"

== Run BeagleBone/Debian programs ==
ln -s . /lib/arm-linux-gnueabihf
ln -s ld-2.11.1.so /lib/ld-linux-armhf.so.3

Nest Hacking

2014-08-10T21:08:05Z

Luke-Jr: /* Backplate to display */

== Hardware ==

[https://www.ifixit.com/Teardown/Nest+Learning+Thermostat+2nd+Generation+Teardown/13818 Pictures]

=== Backplate ===
* ST Microelectronics STM32L151VB ultra-low-power 32 MHz ARM Cortex-M3 MCU
* Sensirion SHT20 humidity and temperature sensor
* Texas Instruments LW051A 8-channel CMOS analog multiplexer/demultiplexer

=== Display ===
* Texas Instruments AM3703CUS Sitara ARM Cortex A8 microprocessor
* Texas Instruments TPS65921B power management and USB single chip
* Samsung K4X51163PK 512 Mb mobile DRAM
* Ember EM357 integrated ZigBee/802.15.4 system-on-chip
* Micron MT29F2G16ABBEAH4 2 Gb NAND flash memory
* Skyworks 2436L high power 2.4 GHz 802.15.4 front-end module
* Texas Instruments WL1270B 802.11 b/g/n Wi-Fi solution
* Avago ADBM-A350 optical finger navigation module (knob movement sensor)

== Info ==
* /dev/event1 is the knob; /dev/event2 is the button
* /sys/class/hwmon/hwmon0/device/in0_battery_type * 0.003 is battery voltage
** Nest turns off wifi below 3.7 V, and waits until 3.8 V to automatically reconnect
* Display serial number is located in U-Boot environment variable "serial#"

== Nest software ==
/nestlabs/sbin/nlclient -config /nestlabs/etc/client.config -config /nestlabs/etc/Display/Display-2/client.config

=== Backplate communications ===
Backplate communications can be decoded from a (filtered) strace log using [http://luke.dashjr.org/programs/freeabode/kindling/NestDecode.pl NestDecode.pl], or decoded in real time using [http://luke.dashjr.org/programs/freeabode/kindling/nest-intercept.c nest-intercept.c].

nest-intercept.c requires one argument, the thread id reading from the backplate controller.
The easiest way to get this is to strace the nlclient process with -ff and look for a thread reading from fd 54.

Note that nest-intercept.c also has a "hack" variable which can be set to 0 (default is 2) in order to corrupt the TFE version response and trigger nlclient into uploading the firmware again.

=== Backplate firmware ===
Found in /nestlabs/share/bp/data/firmware/nlbpfirmware.plist

There are 12 different firmwares in the file:
* Test vs Production
* Backplate 2 vs Backplate 3
* TFE (BP_D2 for Bp2, AMBER_BP for Bp3) vs BSL
* For TFE firmwares, hex vs srec (which for some reason DO differ!)

Python script to extract them into individual files: [http://luke.dashjr.org/programs/freeabode/kindling/extract-fw.py extract-fw.py]

=== Backplate initialisation ===
When the backplate is first connected, the following sequence occurs:
tcflush(fd, TCIFLUSH)
Set baud to 115200 (-opost -isig -icanon -echo ...)
tcflush(fd, TCIOFLUSH)
tcsendbreak(fd, 1)
Send [[#Reset|00ff - Reset]]
Recv 0001 - (message from backplate; ASCII)
Recv [[#FET presence|0004 - FET presence]]
Recv [[#FET presence|0009 - FET presence]]
Send [[#FET presence|008f - FET presence]]
Send [[#Periodic status|0083 - Periodic status request]]
Send 0090 - get Mono/TFE id (no data; response 0010 with 3 bytes)
Recv 0001 - (message from backplate; ASCII)
Recv 0001 - (message from backplate; ASCII)
Recv 0010 - (24-bit data)
Send [[#Get Mono/TFE version|0098 - Get Mono/TFE version]]
Recv 000a - (every second; 16-bit data)
Recv 0007 - (every second; 16-bit data)
Recv [[#Get Mono/TFE version|0018 - Get Mono/TFE version (response)]]
Send [[#Get Mono/TFE build info|0099 - Get Mono/TFE build info]]
Recv [[#Get Mono/TFE build info|0019 - Get Mono/TFE build info (response)]]
Sometimes:
Send 009d - get BSL id (no data; responds with 001d)
Recv 001d - bsl id (response to 009d; 16-bit data)
Sometimes:
Send [[#Get BSL version|009b - Get BSL version]]
Recv [[#Get BSL version|001b - Get BSL version (response)]]
Sometimes:
Send 009c - get BSL info (no data; responds with 001c (constant?) data="BSL")
Recv 001c - Response to 009c; always(?) "BSL"
Send [[#Get serial number|009f - Get serial number]]
Recv [[#Get serial number|001f - Get serial number (response)]]
Send [[#Get hardware version|009e - Get hardware version]]
Recv [[#Get hardware version|001e - Get hardware version (response)]]

== Nest backplate interface ==
* Connected on /dev/ttyO2
* All communications with backplate begin with (d5)d5aa96 (d5 is doubled only for data FROM backplate)
* Everything is little endian
* 16-bit command
* 16-bit data length
* <data>
* 16-bit checksum

Monitor:
strace -ff -p $(pidof nlclient) -x -s9999 -e read,write 2>&1 | grep '(54'

NOTE: Most of this documentation is reverse engineered from firmware version BSL-2.1 and/or TFE_BP_D2-4.0.21 for Backplate-2.x.

=== Checksum ===
<Bytes-from-end>.<bit-value> <xor-with>
00.01 2110 (1021)
00.02 4220 (2042: 1021<<1)
00.04 8440 (4084: 2048<<1)
00.08 0881 (8108: 4084<<1)
00.10 3112 (1231: 8108<<1^1021)
00.20 6224 (2462: 1231<<1)
00.40 c448 (48c4: 2462<<1)
00.80 8891 (9188: 48c4<<1)
01.01 3133 (3313: 9188<<1^1021)
01.02 6266
01.04 c4cc
01.08 a989
01.10 7303
01.20 e606
01.40 cc0d
01.80 981b
02.01 3037
02.02 606e
...
03.01 b476
03.02 68ed
03.04 f1ca
03.08 c385
03.10 a71b
03.20 4e37
03.40 9c6e
03.80 38dd
...
07.20 687b

If you compute the contribution of the individual bit changes in the data you end up with the xor table above; byte offset from the end of the data, bit pattern, xor value. Correcting for little endianess in the output you end up with the hex values in parenthesis. The least significant bit is 0x1021 and each subsequent bit is a shift left, if the XOR value has the 0x8000 bit set then it is XORed with 0x1021. This is the CRC-CCITT polynomial.

8 7 6 5 4 3 2 1 0
d5 aa 96 82 00 02 00 00 00: 08b2
|| |
|| 68ed
|408b
20d4

08b2: 68ed ^ 408b ^ 20d4

Starting at the least significant bit and filling in the XOR values for each bit gives the above diagram; the diagram stops at the 20d4 XOR value because at that point it matches the final CRC. This tells us that the CRC covers the 6 bytes prior.

#!/usr/bin/env perl
use Digest::CRC qw(crc);
my $data = pack("H*", "820002000000");
printf("%04x\n", crc($data,16,0,0,0,0x1021,0,0));

We can also compute the same CRC in Perl; note the result will be byte swapped since the data encodes the number as little endian.

=== Command ids ===

==== Display to backplate ====
[[#FET control|0082 - FET control]]
[[#Periodic status|0083 - Periodic status request]]
[[#FET presence|008f - FET presence]]
0090 - get Mono/TFE id (no data; response 0010 with 3 bytes)
[[#Backplate firmware upload|0091 - Backplate firmware upload (start)]]
[[#Backplate firmware upload|0092 - Backplate firmware upload]]
[[#Backplate firmware upload|0093 - Backplate firmware upload (finish)]]
[[#Get Mono/TFE version|0098 - Get Mono/TFE version]]
[[#Get Mono/TFE build info|0099 - Get Mono/TFE build info]]
[[#Get BSL version|009b - Get BSL version]]
009c - get BSL info (no data; responds with 001c (constant?) data="BSL")
009d - get BSL id (no data; responds with 001d)
[[#Get hardware version|009e - Get hardware version]]
[[#Get serial number|009f - Get serial number]]
00a1 - quiet (16-bit max sleep seconds)
[[#"Buffers"|00a2 - Request "buffers" (every 30 seconds; no data; triggers [0025] [0027] 0022 0023 [0029] [002b] 000c 002f)]]
[[#"Buffers"|00a3 - ACK to 002f (no data)]]
00a4 - set wakeup mask (16-bit data)
00b1 - "temperature lock" (sent when button pressed/unpressed; no data)
00b3 - set humidity thresholds (32-bit data)
00b5 - set near pir threshold (16-bit data)
00b7 - set pir thresholds (??? data)
00b8 - set proximity thresholds (??? data)
00b9 - set als thresholds (32-bit data)
00ba - set vergence mode (48-bit data)
00c2 - set wakeup temperatures (48-bit data)
00c3 - set temp comp mode request (??? data)
00fe - DEBUG MODE
[[#Reset|00ff - Reset]]

==== Backplate to display ====
0001 - (message from backplate; ASCII)
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
[[#FET presence|0004 - FET presence]]
0005 - pir? (32-bit data)
0006 - "ack switch" (data: 8-bit switch id, 8-bit state)
0007 - near pid? (every second; 16-bit data)
0008 - proximity?
[[#FET presence|0009 - FET presence]]
000a - als? (every second; 2x(?) 16-bit data)
[[#Backplate state|000b - Backplate state]]
000c - sensor? (16-bit values: pir, px1, px1 divisor, px2, px2 divisor, alir, av; included in [[#"Buffers"|"buffers" data]])
000e - power?
0010 - (24-bit data)
[[#Backplate firmware upload|0011 - Backplate firmware upload (ACK)]]
0012 - ?
0013 - "Wakeup"?
0014 - "WakeVector" (16-bit data)
[[#Get Mono/TFE version|0018 - Get Mono/TFE version (response)]]
[[#Get Mono/TFE build info|0019 - Get Mono/TFE build info (response)]]
[[#Get BSL version|001b - Get BSL version (response)]]
001c - Response to 009c; always(?) "BSL"
001d - bsl id (response to 009d; 16-bit data)
[[#Get hardware version|001e - Get hardware version (response)]]
[[#Get serial number|001f - Get serial number (response)]]
[[#"Buffers"|0022 - buffered temperature reading (possibly multiple times)]]
[[#"Buffers"|0023 - BufferedSourceTemperature (3x 16-bit data; possibly multiple times)]]
[[#"Buffers"|0025 - BufferedNearPir (16-bit data; possibly multiple times)]]
[[#"Buffers"|0027 - BufferedPassiveInfrared (64-bit data; possibly multiple times)]]
[[#"Buffers"|0029 - BufferedAmbientLightSensor (48-bit data; likely 3x 16-bit; possibly multiple times)]]
[[#"Buffers"|002b - BufferedPowerData (64-bit data; possibly multiple times)]]
[[#"Buffers"|002f - End of "buffers" (16-bit data)]]

=== Backplate firmware upload ===
For uploading the firmware, the following sequence is used:
Send 0091 data=0000<firmware type>
Recv 0011 data=0000
Send 0092 data=0100...
Recv 0011 data=0100
Send 0092 data=0200...
Recv 0011 data=0200
...
Send 0092 data=a901...
Recv 0011 data=a901
Send 0093 data=aa01
Recv 0011 data=aa01
Following the upload, the [[#Backplate initialisation|backplate initialisation process]] begins immediately (that is, without message 00ff being sent to order a reset).
Presumably the 0011 message is an ACK, and the first 16 bits of each message is the line number.
The format itself appears to be Motorola S-record (SREC).
Uploading the BSL firmware was followed by the TFE firmware, so it may be required (though uploading the TFE firmware does ''not'' require uploading the BSL).

Firmware type is either 4d for TFE or 42 for BSL.

=== Backplate state ===
Data:
* 8-bit "state"
* 8-bit "flags"
** Bit 0x40 = charger off (?)
* 8-bit "px0" (may be wider?)
* ? 16-bit "sw" fraction (0800 = 08/00)
* ? 8-bit "p2"
* ? 16-bit "voc"
* 16-bit centi-volts "vi"
* 16-bit milli-volts "vo"
* 16-bit milli-volts "vb"
* 8-bit ("pins" or "wires")
* 8-bit ("wires" or "pins")
* 16-bit UNKNOWN

=== "Buffers" ===
The 00a2 message requests the backplate send the contents of various "buffers", which are returned in messages [0025], [0027], 0022, 0023, [0029], and [002b] (empty ones will NOT be sent; brackets infer commonly-empty buffers).
00a2 also triggers 000c immediately following these.
After all the buffers (including 000c) have been sent, the message 002f indicates "end of buffers".
The display is then expected to acknowledge it with message 00a3.

Buffers:
[[#Temperature reading|0022 - Temperature reading]]
0023 - BufferedSourceTemperature (not sure what that means)
0025 - BufferedNearPir
0027 - BufferedPassiveInfrared
0029 - BufferedAmbientLightSensor
002b - BufferedPowerData

=== FET control ===
Turn on W1: d5aa96 8200 0200 00 01 29a2
Turn off W1: d5aa96 8200 0200 00 00 08b2
Turn on Y1: d5aa96 8200 0200 01 01 1891
Turn off Y1: d5aa96 8200 0200 01 00 3981
Turn on G : d5aa96 8200 0200 02 01 4bc4
Turn off G : d5aa96 8200 0200 02 00 6ad4
Turn on OB: d5aa96 8200 0200 03 01 7af7
Turn off OB: d5aa96 8200 0200 03 00 5be7
Turn on W2: d5aa96 8200 0200 04 01 ed6e
Turn off W2: d5aa96 8200 0200 04 00 cc7e
Turn on Y2: d5aa96 8200 0200 07 01 be3b
Turn off Y2: d5aa96 8200 0200 07 00 9f2b
Turn on * : d5aa96 8200 0200 0b 01 d37e
Turn off * : d5aa96 8200 0200 0b 00 f26e

For the sake of documentation, we will refer to the unique id numbers for each wire as "wire id numbers".
So wire id 0 is W1, wire id 1 is Y1, wire id B is *, etc.

=== FET presence ===
The backplate will, at least upon connection, send information about which FETs have a wire present.
This data is received with command ids 0004 and 0009, in that order.
Each sensor is represented by one byte which is either 00 (not present) or 01 (present).

The content of 0004 is in order of the "wire id numbers" used for control:
W1, Y1, G, OB, W2, ?0, ?0, Y2, C, RC, ?0, *, ?0

The content of 0009 is arranged differently and has 2 more values:
W1, Y1, C, RC, ?0, G, OB, W2, ?0, Y2, ?0, *, ?0, ?0, ?0

0009 seems to indicate a wire is physically plugged in, while 0004 indicates that it is connected to something (?).

After these are received, the display sends back command 008f with the exact data from message 0004.
Message 008f does not itself receive any response.

In a power outage condition, 0004 will report all absent (including unknown ones), whereas 0009 will continue to report the same as when power is available.

=== Get Mono/TFE build info ===
Message 0099 (no data) requests the backplate report information about its build.
The response will be message 0019 in ASCII (one line, no trailing newline).

=== Get hardware version ===
Message 009e (no data) requests the backplate report a "Backplate-"X.Y version string.
Since the firmware file on the display CPU uses these strings as "MinApplicability" and "MaxApplicability" ranges, it is probable they refer to the hardware.

Witnessed versions:
"Backplate-2.8" - Florida Lowes

=== Get BSL version ===
Message 009b (no data) requests the backplate report its BSL version number.
The response will be message 001b in ASCII.

=== Get Mono/TFE version ===
Message 0098 (no data) requests the backplate report its TFE version number.
The response will be message 0018 in ASCII.

=== Get serial number ===
Message 009f (no data) requests the backplate report its serial number (a 64-bit hexadecimal value).
The response will be message 001f in uppercase ASCII.

=== Periodic status ===
Sending message 0083 (no data) will trigger various periodic messages:
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
000a - (every second; 16-bit data)

The Nest client sends 0083 every 30 seconds, but at least the periodic temperature status will continue on for an hour before stopping.

=== Power management ===
Wake vector bits:
0001 - timer
0002 - buffers full
0004 - temperature
0008 - pir
0010 - proximity
0020 - humidity
0040 - near pir
0080 - als
0100 - "vbat"
0200 - "vergence"

=== Temperature reading ===
The backplate will send message 0002 every 30 seconds.
The data contains two 16-bit numbers, which nlclient logs in decimal.
The first number is the temperature in centi-celcius.
The second number is the humidity in per-millis.

See also: [[#"Buffers"|"Buffers"]]

=== Reset ===
At least upon connection, the display sends message 00ff to the backplate to reset.

The backplate answers with:
0001 msg "<version> <build timestamp "YYYY-MM-DD HH:MM:SS"> K"
[[#FET presence|0004 FET presence]]
[[#FET presence|0009 FET presence]]
0001 msg "*sense 06d1 06d0 0001 0001 0000 0000 0000 0001 06d9 06d8 06d8; detect 09d3 065c"
0001 msg "BRK"

== Run BeagleBone/Debian programs ==
ln -s . /lib/arm-linux-gnueabihf
ln -s ld-2.11.1.so /lib/ld-linux-armhf.so.3

Nest Hacking

2014-08-10T21:01:08Z

Luke-Jr: /* Backplate state */

== Hardware ==

[https://www.ifixit.com/Teardown/Nest+Learning+Thermostat+2nd+Generation+Teardown/13818 Pictures]

=== Backplate ===
* ST Microelectronics STM32L151VB ultra-low-power 32 MHz ARM Cortex-M3 MCU
* Sensirion SHT20 humidity and temperature sensor
* Texas Instruments LW051A 8-channel CMOS analog multiplexer/demultiplexer

=== Display ===
* Texas Instruments AM3703CUS Sitara ARM Cortex A8 microprocessor
* Texas Instruments TPS65921B power management and USB single chip
* Samsung K4X51163PK 512 Mb mobile DRAM
* Ember EM357 integrated ZigBee/802.15.4 system-on-chip
* Micron MT29F2G16ABBEAH4 2 Gb NAND flash memory
* Skyworks 2436L high power 2.4 GHz 802.15.4 front-end module
* Texas Instruments WL1270B 802.11 b/g/n Wi-Fi solution
* Avago ADBM-A350 optical finger navigation module (knob movement sensor)

== Info ==
* /dev/event1 is the knob; /dev/event2 is the button
* /sys/class/hwmon/hwmon0/device/in0_battery_type * 0.003 is battery voltage
** Nest turns off wifi below 3.7 V, and waits until 3.8 V to automatically reconnect
* Display serial number is located in U-Boot environment variable "serial#"

== Nest software ==
/nestlabs/sbin/nlclient -config /nestlabs/etc/client.config -config /nestlabs/etc/Display/Display-2/client.config

=== Backplate communications ===
Backplate communications can be decoded from a (filtered) strace log using [http://luke.dashjr.org/programs/freeabode/kindling/NestDecode.pl NestDecode.pl], or decoded in real time using [http://luke.dashjr.org/programs/freeabode/kindling/nest-intercept.c nest-intercept.c].

nest-intercept.c requires one argument, the thread id reading from the backplate controller.
The easiest way to get this is to strace the nlclient process with -ff and look for a thread reading from fd 54.

Note that nest-intercept.c also has a "hack" variable which can be set to 0 (default is 2) in order to corrupt the TFE version response and trigger nlclient into uploading the firmware again.

=== Backplate firmware ===
Found in /nestlabs/share/bp/data/firmware/nlbpfirmware.plist

There are 12 different firmwares in the file:
* Test vs Production
* Backplate 2 vs Backplate 3
* TFE (BP_D2 for Bp2, AMBER_BP for Bp3) vs BSL
* For TFE firmwares, hex vs srec (which for some reason DO differ!)

Python script to extract them into individual files: [http://luke.dashjr.org/programs/freeabode/kindling/extract-fw.py extract-fw.py]

=== Backplate initialisation ===
When the backplate is first connected, the following sequence occurs:
tcflush(fd, TCIFLUSH)
Set baud to 115200 (-opost -isig -icanon -echo ...)
tcflush(fd, TCIOFLUSH)
tcsendbreak(fd, 1)
Send [[#Reset|00ff - Reset]]
Recv 0001 - (message from backplate; ASCII)
Recv [[#FET presence|0004 - FET presence]]
Recv [[#FET presence|0009 - FET presence]]
Send [[#FET presence|008f - FET presence]]
Send [[#Periodic status|0083 - Periodic status request]]
Send 0090 - get Mono/TFE id (no data; response 0010 with 3 bytes)
Recv 0001 - (message from backplate; ASCII)
Recv 0001 - (message from backplate; ASCII)
Recv 0010 - (24-bit data)
Send [[#Get Mono/TFE version|0098 - Get Mono/TFE version]]
Recv 000a - (every second; 16-bit data)
Recv 0007 - (every second; 16-bit data)
Recv [[#Get Mono/TFE version|0018 - Get Mono/TFE version (response)]]
Send [[#Get Mono/TFE build info|0099 - Get Mono/TFE build info]]
Recv [[#Get Mono/TFE build info|0019 - Get Mono/TFE build info (response)]]
Sometimes:
Send 009d - get BSL id (no data; responds with 001d)
Recv 001d - bsl id (response to 009d; 16-bit data)
Sometimes:
Send [[#Get BSL version|009b - Get BSL version]]
Recv [[#Get BSL version|001b - Get BSL version (response)]]
Sometimes:
Send 009c - get BSL info (no data; responds with 001c (constant?) data="BSL")
Recv 001c - Response to 009c; always(?) "BSL"
Send [[#Get serial number|009f - Get serial number]]
Recv [[#Get serial number|001f - Get serial number (response)]]
Send [[#Get hardware version|009e - Get hardware version]]
Recv [[#Get hardware version|001e - Get hardware version (response)]]

== Nest backplate interface ==
* Connected on /dev/ttyO2
* All communications with backplate begin with (d5)d5aa96 (d5 is doubled only for data FROM backplate)
* Everything is little endian
* 16-bit command
* 16-bit data length
* <data>
* 16-bit checksum

Monitor:
strace -ff -p $(pidof nlclient) -x -s9999 -e read,write 2>&1 | grep '(54'

NOTE: Most of this documentation is reverse engineered from firmware version BSL-2.1 and/or TFE_BP_D2-4.0.21 for Backplate-2.x.

=== Checksum ===
<Bytes-from-end>.<bit-value> <xor-with>
00.01 2110 (1021)
00.02 4220 (2042: 1021<<1)
00.04 8440 (4084: 2048<<1)
00.08 0881 (8108: 4084<<1)
00.10 3112 (1231: 8108<<1^1021)
00.20 6224 (2462: 1231<<1)
00.40 c448 (48c4: 2462<<1)
00.80 8891 (9188: 48c4<<1)
01.01 3133 (3313: 9188<<1^1021)
01.02 6266
01.04 c4cc
01.08 a989
01.10 7303
01.20 e606
01.40 cc0d
01.80 981b
02.01 3037
02.02 606e
...
03.01 b476
03.02 68ed
03.04 f1ca
03.08 c385
03.10 a71b
03.20 4e37
03.40 9c6e
03.80 38dd
...
07.20 687b

If you compute the contribution of the individual bit changes in the data you end up with the xor table above; byte offset from the end of the data, bit pattern, xor value. Correcting for little endianess in the output you end up with the hex values in parenthesis. The least significant bit is 0x1021 and each subsequent bit is a shift left, if the XOR value has the 0x8000 bit set then it is XORed with 0x1021. This is the CRC-CCITT polynomial.

8 7 6 5 4 3 2 1 0
d5 aa 96 82 00 02 00 00 00: 08b2
|| |
|| 68ed
|408b
20d4

08b2: 68ed ^ 408b ^ 20d4

Starting at the least significant bit and filling in the XOR values for each bit gives the above diagram; the diagram stops at the 20d4 XOR value because at that point it matches the final CRC. This tells us that the CRC covers the 6 bytes prior.

#!/usr/bin/env perl
use Digest::CRC qw(crc);
my $data = pack("H*", "820002000000");
printf("%04x\n", crc($data,16,0,0,0,0x1021,0,0));

We can also compute the same CRC in Perl; note the result will be byte swapped since the data encodes the number as little endian.

=== Command ids ===

==== Display to backplate ====
[[#FET control|0082 - FET control]]
[[#Periodic status|0083 - Periodic status request]]
[[#FET presence|008f - FET presence]]
0090 - get Mono/TFE id (no data; response 0010 with 3 bytes)
[[#Backplate firmware upload|0091 - Backplate firmware upload (start)]]
[[#Backplate firmware upload|0092 - Backplate firmware upload]]
[[#Backplate firmware upload|0093 - Backplate firmware upload (finish)]]
[[#Get Mono/TFE version|0098 - Get Mono/TFE version]]
[[#Get Mono/TFE build info|0099 - Get Mono/TFE build info]]
[[#Get BSL version|009b - Get BSL version]]
009c - get BSL info (no data; responds with 001c (constant?) data="BSL")
009d - get BSL id (no data; responds with 001d)
[[#Get hardware version|009e - Get hardware version]]
[[#Get serial number|009f - Get serial number]]
00a1 - quiet (16-bit max sleep seconds)
[[#"Buffers"|00a2 - Request "buffers" (every 30 seconds; no data; triggers [0025] [0027] 0022 0023 [0029] [002b] 000c 002f)]]
[[#"Buffers"|00a3 - ACK to 002f (no data)]]
00a4 - set wakeup mask (16-bit data)
00b1 - "temperature lock" (sent when button pressed/unpressed; no data)
00b3 - set humidity thresholds (32-bit data)
00b5 - set near pir threshold (16-bit data)
00b7 - set pir thresholds (??? data)
00b8 - set proximity thresholds (??? data)
00b9 - set als thresholds (32-bit data)
00ba - set vergence mode (48-bit data)
00c2 - set wakeup temperatures (48-bit data)
00c3 - set temp comp mode request (??? data)
00fe - DEBUG MODE
[[#Reset|00ff - Reset]]

==== Backplate to display ====
0001 - (message from backplate; ASCII)
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
[[#FET presence|0004 - FET presence]]
0005 - pir? (32-bit data)
0006 - ack switch?
0007 - near pid? (every second; 16-bit data)
0008 - proximity?
[[#FET presence|0009 - FET presence]]
000a - als? (every second; 2x(?) 16-bit data)
[[#Backplate state|000b - Backplate state]]
000c - sensor? (16-bit values: pir, px1, px1 divisor, px2, px2 divisor, alir, av; included in [[#"Buffers"|"buffers" data]])
000e - power?
0010 - (24-bit data)
[[#Backplate firmware upload|0011 - Backplate firmware upload (ACK)]]
0012 - ?
0013 - "Wakeup"?
0014 - "WakeVector" (16-bit data)
[[#Get Mono/TFE version|0018 - Get Mono/TFE version (response)]]
[[#Get Mono/TFE build info|0019 - Get Mono/TFE build info (response)]]
[[#Get BSL version|001b - Get BSL version (response)]]
001c - Response to 009c; always(?) "BSL"
001d - bsl id (response to 009d; 16-bit data)
[[#Get hardware version|001e - Get hardware version (response)]]
[[#Get serial number|001f - Get serial number (response)]]
[[#"Buffers"|0022 - buffered temperature reading (possibly multiple times)]]
[[#"Buffers"|0023 - BufferedSourceTemperature (3x 16-bit data; possibly multiple times)]]
[[#"Buffers"|0025 - BufferedNearPir (16-bit data; possibly multiple times)]]
[[#"Buffers"|0027 - BufferedPassiveInfrared (64-bit data; possibly multiple times)]]
[[#"Buffers"|0029 - BufferedAmbientLightSensor (48-bit data; likely 3x 16-bit; possibly multiple times)]]
[[#"Buffers"|002b - BufferedPowerData (64-bit data; possibly multiple times)]]
[[#"Buffers"|002f - End of "buffers" (16-bit data)]]

=== Backplate firmware upload ===
For uploading the firmware, the following sequence is used:
Send 0091 data=0000<firmware type>
Recv 0011 data=0000
Send 0092 data=0100...
Recv 0011 data=0100
Send 0092 data=0200...
Recv 0011 data=0200
...
Send 0092 data=a901...
Recv 0011 data=a901
Send 0093 data=aa01
Recv 0011 data=aa01
Following the upload, the [[#Backplate initialisation|backplate initialisation process]] begins immediately (that is, without message 00ff being sent to order a reset).
Presumably the 0011 message is an ACK, and the first 16 bits of each message is the line number.
The format itself appears to be Motorola S-record (SREC).
Uploading the BSL firmware was followed by the TFE firmware, so it may be required (though uploading the TFE firmware does ''not'' require uploading the BSL).

Firmware type is either 4d for TFE or 42 for BSL.

=== Backplate state ===
Data:
* 8-bit "state"
* 8-bit "flags"
** Bit 0x40 = charger off (?)
* 8-bit "px0" (may be wider?)
* ? 16-bit "sw" fraction (0800 = 08/00)
* ? 8-bit "p2"
* ? 16-bit "voc"
* 16-bit centi-volts "vi"
* 16-bit milli-volts "vo"
* 16-bit milli-volts "vb"
* 8-bit ("pins" or "wires")
* 8-bit ("wires" or "pins")
* 16-bit UNKNOWN

=== "Buffers" ===
The 00a2 message requests the backplate send the contents of various "buffers", which are returned in messages [0025], [0027], 0022, 0023, [0029], and [002b] (empty ones will NOT be sent; brackets infer commonly-empty buffers).
00a2 also triggers 000c immediately following these.
After all the buffers (including 000c) have been sent, the message 002f indicates "end of buffers".
The display is then expected to acknowledge it with message 00a3.

Buffers:
[[#Temperature reading|0022 - Temperature reading]]
0023 - BufferedSourceTemperature (not sure what that means)
0025 - BufferedNearPir
0027 - BufferedPassiveInfrared
0029 - BufferedAmbientLightSensor
002b - BufferedPowerData

=== FET control ===
Turn on W1: d5aa96 8200 0200 00 01 29a2
Turn off W1: d5aa96 8200 0200 00 00 08b2
Turn on Y1: d5aa96 8200 0200 01 01 1891
Turn off Y1: d5aa96 8200 0200 01 00 3981
Turn on G : d5aa96 8200 0200 02 01 4bc4
Turn off G : d5aa96 8200 0200 02 00 6ad4
Turn on OB: d5aa96 8200 0200 03 01 7af7
Turn off OB: d5aa96 8200 0200 03 00 5be7
Turn on W2: d5aa96 8200 0200 04 01 ed6e
Turn off W2: d5aa96 8200 0200 04 00 cc7e
Turn on Y2: d5aa96 8200 0200 07 01 be3b
Turn off Y2: d5aa96 8200 0200 07 00 9f2b
Turn on * : d5aa96 8200 0200 0b 01 d37e
Turn off * : d5aa96 8200 0200 0b 00 f26e

For the sake of documentation, we will refer to the unique id numbers for each wire as "wire id numbers".
So wire id 0 is W1, wire id 1 is Y1, wire id B is *, etc.

=== FET presence ===
The backplate will, at least upon connection, send information about which FETs have a wire present.
This data is received with command ids 0004 and 0009, in that order.
Each sensor is represented by one byte which is either 00 (not present) or 01 (present).

The content of 0004 is in order of the "wire id numbers" used for control:
W1, Y1, G, OB, W2, ?0, ?0, Y2, C, RC, ?0, *, ?0

The content of 0009 is arranged differently and has 2 more values:
W1, Y1, C, RC, ?0, G, OB, W2, ?0, Y2, ?0, *, ?0, ?0, ?0

0009 seems to indicate a wire is physically plugged in, while 0004 indicates that it is connected to something (?).

After these are received, the display sends back command 008f with the exact data from message 0004.
Message 008f does not itself receive any response.

In a power outage condition, 0004 will report all absent (including unknown ones), whereas 0009 will continue to report the same as when power is available.

=== Get Mono/TFE build info ===
Message 0099 (no data) requests the backplate report information about its build.
The response will be message 0019 in ASCII (one line, no trailing newline).

=== Get hardware version ===
Message 009e (no data) requests the backplate report a "Backplate-"X.Y version string.
Since the firmware file on the display CPU uses these strings as "MinApplicability" and "MaxApplicability" ranges, it is probable they refer to the hardware.

Witnessed versions:
"Backplate-2.8" - Florida Lowes

=== Get BSL version ===
Message 009b (no data) requests the backplate report its BSL version number.
The response will be message 001b in ASCII.

=== Get Mono/TFE version ===
Message 0098 (no data) requests the backplate report its TFE version number.
The response will be message 0018 in ASCII.

=== Get serial number ===
Message 009f (no data) requests the backplate report its serial number (a 64-bit hexadecimal value).
The response will be message 001f in uppercase ASCII.

=== Periodic status ===
Sending message 0083 (no data) will trigger various periodic messages:
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
000a - (every second; 16-bit data)

The Nest client sends 0083 every 30 seconds, but at least the periodic temperature status will continue on for an hour before stopping.

=== Power management ===
Wake vector bits:
0001 - timer
0002 - buffers full
0004 - temperature
0008 - pir
0010 - proximity
0020 - humidity
0040 - near pir
0080 - als
0100 - "vbat"
0200 - "vergence"

=== Temperature reading ===
The backplate will send message 0002 every 30 seconds.
The data contains two 16-bit numbers, which nlclient logs in decimal.
The first number is the temperature in centi-celcius.
The second number is the humidity in per-millis.

See also: [[#"Buffers"|"Buffers"]]

=== Reset ===
At least upon connection, the display sends message 00ff to the backplate to reset.

The backplate answers with:
0001 msg "<version> <build timestamp "YYYY-MM-DD HH:MM:SS"> K"
[[#FET presence|0004 FET presence]]
[[#FET presence|0009 FET presence]]
0001 msg "*sense 06d1 06d0 0001 0001 0000 0000 0000 0001 06d9 06d8 06d8; detect 09d3 065c"
0001 msg "BRK"

== Run BeagleBone/Debian programs ==
ln -s . /lib/arm-linux-gnueabihf
ln -s ld-2.11.1.so /lib/ld-linux-armhf.so.3

Nest Hacking

2014-08-10T07:32:26Z

Luke-Jr: /* Power management */

== Hardware ==

[https://www.ifixit.com/Teardown/Nest+Learning+Thermostat+2nd+Generation+Teardown/13818 Pictures]

=== Backplate ===
* ST Microelectronics STM32L151VB ultra-low-power 32 MHz ARM Cortex-M3 MCU
* Sensirion SHT20 humidity and temperature sensor
* Texas Instruments LW051A 8-channel CMOS analog multiplexer/demultiplexer

=== Display ===
* Texas Instruments AM3703CUS Sitara ARM Cortex A8 microprocessor
* Texas Instruments TPS65921B power management and USB single chip
* Samsung K4X51163PK 512 Mb mobile DRAM
* Ember EM357 integrated ZigBee/802.15.4 system-on-chip
* Micron MT29F2G16ABBEAH4 2 Gb NAND flash memory
* Skyworks 2436L high power 2.4 GHz 802.15.4 front-end module
* Texas Instruments WL1270B 802.11 b/g/n Wi-Fi solution
* Avago ADBM-A350 optical finger navigation module (knob movement sensor)

== Info ==
* /dev/event1 is the knob; /dev/event2 is the button
* /sys/class/hwmon/hwmon0/device/in0_battery_type * 0.003 is battery voltage
** Nest turns off wifi below 3.7 V, and waits until 3.8 V to automatically reconnect
* Display serial number is located in U-Boot environment variable "serial#"

== Nest software ==
/nestlabs/sbin/nlclient -config /nestlabs/etc/client.config -config /nestlabs/etc/Display/Display-2/client.config

=== Backplate communications ===
Backplate communications can be decoded from a (filtered) strace log using [http://luke.dashjr.org/programs/freeabode/kindling/NestDecode.pl NestDecode.pl], or decoded in real time using [http://luke.dashjr.org/programs/freeabode/kindling/nest-intercept.c nest-intercept.c].

nest-intercept.c requires one argument, the thread id reading from the backplate controller.
The easiest way to get this is to strace the nlclient process with -ff and look for a thread reading from fd 54.

Note that nest-intercept.c also has a "hack" variable which can be set to 0 (default is 2) in order to corrupt the TFE version response and trigger nlclient into uploading the firmware again.

=== Backplate firmware ===
Found in /nestlabs/share/bp/data/firmware/nlbpfirmware.plist

There are 12 different firmwares in the file:
* Test vs Production
* Backplate 2 vs Backplate 3
* TFE (BP_D2 for Bp2, AMBER_BP for Bp3) vs BSL
* For TFE firmwares, hex vs srec (which for some reason DO differ!)

Python script to extract them into individual files: [http://luke.dashjr.org/programs/freeabode/kindling/extract-fw.py extract-fw.py]

=== Backplate initialisation ===
When the backplate is first connected, the following sequence occurs:
tcflush(fd, TCIFLUSH)
Set baud to 115200 (-opost -isig -icanon -echo ...)
tcflush(fd, TCIOFLUSH)
tcsendbreak(fd, 1)
Send [[#Reset|00ff - Reset]]
Recv 0001 - (message from backplate; ASCII)
Recv [[#FET presence|0004 - FET presence]]
Recv [[#FET presence|0009 - FET presence]]
Send [[#FET presence|008f - FET presence]]
Send [[#Periodic status|0083 - Periodic status request]]
Send 0090 - get Mono/TFE id (no data; response 0010 with 3 bytes)
Recv 0001 - (message from backplate; ASCII)
Recv 0001 - (message from backplate; ASCII)
Recv 0010 - (24-bit data)
Send [[#Get Mono/TFE version|0098 - Get Mono/TFE version]]
Recv 000a - (every second; 16-bit data)
Recv 0007 - (every second; 16-bit data)
Recv [[#Get Mono/TFE version|0018 - Get Mono/TFE version (response)]]
Send [[#Get Mono/TFE build info|0099 - Get Mono/TFE build info]]
Recv [[#Get Mono/TFE build info|0019 - Get Mono/TFE build info (response)]]
Sometimes:
Send 009d - get BSL id (no data; responds with 001d)
Recv 001d - bsl id (response to 009d; 16-bit data)
Sometimes:
Send [[#Get BSL version|009b - Get BSL version]]
Recv [[#Get BSL version|001b - Get BSL version (response)]]
Sometimes:
Send 009c - get BSL info (no data; responds with 001c (constant?) data="BSL")
Recv 001c - Response to 009c; always(?) "BSL"
Send [[#Get serial number|009f - Get serial number]]
Recv [[#Get serial number|001f - Get serial number (response)]]
Send [[#Get hardware version|009e - Get hardware version]]
Recv [[#Get hardware version|001e - Get hardware version (response)]]

== Nest backplate interface ==
* Connected on /dev/ttyO2
* All communications with backplate begin with (d5)d5aa96 (d5 is doubled only for data FROM backplate)
* Everything is little endian
* 16-bit command
* 16-bit data length
* <data>
* 16-bit checksum

Monitor:
strace -ff -p $(pidof nlclient) -x -s9999 -e read,write 2>&1 | grep '(54'

NOTE: Most of this documentation is reverse engineered from firmware version BSL-2.1 and/or TFE_BP_D2-4.0.21 for Backplate-2.x.

=== Checksum ===
<Bytes-from-end>.<bit-value> <xor-with>
00.01 2110 (1021)
00.02 4220 (2042: 1021<<1)
00.04 8440 (4084: 2048<<1)
00.08 0881 (8108: 4084<<1)
00.10 3112 (1231: 8108<<1^1021)
00.20 6224 (2462: 1231<<1)
00.40 c448 (48c4: 2462<<1)
00.80 8891 (9188: 48c4<<1)
01.01 3133 (3313: 9188<<1^1021)
01.02 6266
01.04 c4cc
01.08 a989
01.10 7303
01.20 e606
01.40 cc0d
01.80 981b
02.01 3037
02.02 606e
...
03.01 b476
03.02 68ed
03.04 f1ca
03.08 c385
03.10 a71b
03.20 4e37
03.40 9c6e
03.80 38dd
...
07.20 687b

If you compute the contribution of the individual bit changes in the data you end up with the xor table above; byte offset from the end of the data, bit pattern, xor value. Correcting for little endianess in the output you end up with the hex values in parenthesis. The least significant bit is 0x1021 and each subsequent bit is a shift left, if the XOR value has the 0x8000 bit set then it is XORed with 0x1021. This is the CRC-CCITT polynomial.

8 7 6 5 4 3 2 1 0
d5 aa 96 82 00 02 00 00 00: 08b2
|| |
|| 68ed
|408b
20d4

08b2: 68ed ^ 408b ^ 20d4

Starting at the least significant bit and filling in the XOR values for each bit gives the above diagram; the diagram stops at the 20d4 XOR value because at that point it matches the final CRC. This tells us that the CRC covers the 6 bytes prior.

#!/usr/bin/env perl
use Digest::CRC qw(crc);
my $data = pack("H*", "820002000000");
printf("%04x\n", crc($data,16,0,0,0,0x1021,0,0));

We can also compute the same CRC in Perl; note the result will be byte swapped since the data encodes the number as little endian.

=== Command ids ===

==== Display to backplate ====
[[#FET control|0082 - FET control]]
[[#Periodic status|0083 - Periodic status request]]
[[#FET presence|008f - FET presence]]
0090 - get Mono/TFE id (no data; response 0010 with 3 bytes)
[[#Backplate firmware upload|0091 - Backplate firmware upload (start)]]
[[#Backplate firmware upload|0092 - Backplate firmware upload]]
[[#Backplate firmware upload|0093 - Backplate firmware upload (finish)]]
[[#Get Mono/TFE version|0098 - Get Mono/TFE version]]
[[#Get Mono/TFE build info|0099 - Get Mono/TFE build info]]
[[#Get BSL version|009b - Get BSL version]]
009c - get BSL info (no data; responds with 001c (constant?) data="BSL")
009d - get BSL id (no data; responds with 001d)
[[#Get hardware version|009e - Get hardware version]]
[[#Get serial number|009f - Get serial number]]
00a1 - quiet (16-bit max sleep seconds)
[[#"Buffers"|00a2 - Request "buffers" (every 30 seconds; no data; triggers [0025] [0027] 0022 0023 [0029] [002b] 000c 002f)]]
[[#"Buffers"|00a3 - ACK to 002f (no data)]]
00a4 - set wakeup mask (16-bit data)
00b1 - "temperature lock" (sent when button pressed/unpressed; no data)
00b3 - set humidity thresholds (32-bit data)
00b5 - set near pir threshold (16-bit data)
00b7 - set pir thresholds (??? data)
00b8 - set proximity thresholds (??? data)
00b9 - set als thresholds (32-bit data)
00ba - set vergence mode (48-bit data)
00c2 - set wakeup temperatures (48-bit data)
00c3 - set temp comp mode request (??? data)
00fe - DEBUG MODE
[[#Reset|00ff - Reset]]

==== Backplate to display ====
0001 - (message from backplate; ASCII)
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
[[#FET presence|0004 - FET presence]]
0005 - pir? (32-bit data)
0006 - ack switch?
0007 - near pid? (every second; 16-bit data)
0008 - proximity?
[[#FET presence|0009 - FET presence]]
000a - als? (every second; 2x(?) 16-bit data)
[[#Backplate state|000b - Backplate state]]
000c - sensor? (16-bit values: pir, px1, px1 divisor, px2, px2 divisor, alir, av; included in [[#"Buffers"|"buffers" data]])
000e - power?
0010 - (24-bit data)
[[#Backplate firmware upload|0011 - Backplate firmware upload (ACK)]]
0012 - ?
0013 - "Wakeup"?
0014 - "WakeVector" (16-bit data)
[[#Get Mono/TFE version|0018 - Get Mono/TFE version (response)]]
[[#Get Mono/TFE build info|0019 - Get Mono/TFE build info (response)]]
[[#Get BSL version|001b - Get BSL version (response)]]
001c - Response to 009c; always(?) "BSL"
001d - bsl id (response to 009d; 16-bit data)
[[#Get hardware version|001e - Get hardware version (response)]]
[[#Get serial number|001f - Get serial number (response)]]
[[#"Buffers"|0022 - buffered temperature reading (possibly multiple times)]]
[[#"Buffers"|0023 - BufferedSourceTemperature (3x 16-bit data; possibly multiple times)]]
[[#"Buffers"|0025 - BufferedNearPir (16-bit data; possibly multiple times)]]
[[#"Buffers"|0027 - BufferedPassiveInfrared (64-bit data; possibly multiple times)]]
[[#"Buffers"|0029 - BufferedAmbientLightSensor (48-bit data; likely 3x 16-bit; possibly multiple times)]]
[[#"Buffers"|002b - BufferedPowerData (64-bit data; possibly multiple times)]]
[[#"Buffers"|002f - End of "buffers" (16-bit data)]]

=== Backplate firmware upload ===
For uploading the firmware, the following sequence is used:
Send 0091 data=0000<firmware type>
Recv 0011 data=0000
Send 0092 data=0100...
Recv 0011 data=0100
Send 0092 data=0200...
Recv 0011 data=0200
...
Send 0092 data=a901...
Recv 0011 data=a901
Send 0093 data=aa01
Recv 0011 data=aa01
Following the upload, the [[#Backplate initialisation|backplate initialisation process]] begins immediately (that is, without message 00ff being sent to order a reset).
Presumably the 0011 message is an ACK, and the first 16 bits of each message is the line number.
The format itself appears to be Motorola S-record (SREC).
Uploading the BSL firmware was followed by the TFE firmware, so it may be required (though uploading the TFE firmware does ''not'' require uploading the BSL).

Firmware type is either 4d for TFE or 42 for BSL.

=== Backplate state ===
Data:
* 8-bit "state"
* 8-bit "flags"
** Bit 0x40 = charger off (?)
* 8-bit "px0" (may be wider?)
* 40-bit UNKNOWN (includes at least "p2" and "voc")
* 16-bit centi-volts "vi"
* 16-bit milli-volts "vo"
* 16-bit milli-volts "vb"
* 8-bit ("pins" or "wires")
* 8-bit ("wires" or "pins")
* 16-bit UNKNOWN

=== "Buffers" ===
The 00a2 message requests the backplate send the contents of various "buffers", which are returned in messages [0025], [0027], 0022, 0023, [0029], and [002b] (empty ones will NOT be sent; brackets infer commonly-empty buffers).
00a2 also triggers 000c immediately following these.
After all the buffers (including 000c) have been sent, the message 002f indicates "end of buffers".
The display is then expected to acknowledge it with message 00a3.

Buffers:
[[#Temperature reading|0022 - Temperature reading]]
0023 - BufferedSourceTemperature (not sure what that means)
0025 - BufferedNearPir
0027 - BufferedPassiveInfrared
0029 - BufferedAmbientLightSensor
002b - BufferedPowerData

=== FET control ===
Turn on W1: d5aa96 8200 0200 00 01 29a2
Turn off W1: d5aa96 8200 0200 00 00 08b2
Turn on Y1: d5aa96 8200 0200 01 01 1891
Turn off Y1: d5aa96 8200 0200 01 00 3981
Turn on G : d5aa96 8200 0200 02 01 4bc4
Turn off G : d5aa96 8200 0200 02 00 6ad4
Turn on OB: d5aa96 8200 0200 03 01 7af7
Turn off OB: d5aa96 8200 0200 03 00 5be7
Turn on W2: d5aa96 8200 0200 04 01 ed6e
Turn off W2: d5aa96 8200 0200 04 00 cc7e
Turn on Y2: d5aa96 8200 0200 07 01 be3b
Turn off Y2: d5aa96 8200 0200 07 00 9f2b
Turn on * : d5aa96 8200 0200 0b 01 d37e
Turn off * : d5aa96 8200 0200 0b 00 f26e

For the sake of documentation, we will refer to the unique id numbers for each wire as "wire id numbers".
So wire id 0 is W1, wire id 1 is Y1, wire id B is *, etc.

=== FET presence ===
The backplate will, at least upon connection, send information about which FETs have a wire present.
This data is received with command ids 0004 and 0009, in that order.
Each sensor is represented by one byte which is either 00 (not present) or 01 (present).

The content of 0004 is in order of the "wire id numbers" used for control:
W1, Y1, G, OB, W2, ?0, ?0, Y2, C, RC, ?0, *, ?0

The content of 0009 is arranged differently and has 2 more values:
W1, Y1, C, RC, ?0, G, OB, W2, ?0, Y2, ?0, *, ?0, ?0, ?0

0009 seems to indicate a wire is physically plugged in, while 0004 indicates that it is connected to something (?).

After these are received, the display sends back command 008f with the exact data from message 0004.
Message 008f does not itself receive any response.

In a power outage condition, 0004 will report all absent (including unknown ones), whereas 0009 will continue to report the same as when power is available.

=== Get Mono/TFE build info ===
Message 0099 (no data) requests the backplate report information about its build.
The response will be message 0019 in ASCII (one line, no trailing newline).

=== Get hardware version ===
Message 009e (no data) requests the backplate report a "Backplate-"X.Y version string.
Since the firmware file on the display CPU uses these strings as "MinApplicability" and "MaxApplicability" ranges, it is probable they refer to the hardware.

Witnessed versions:
"Backplate-2.8" - Florida Lowes

=== Get BSL version ===
Message 009b (no data) requests the backplate report its BSL version number.
The response will be message 001b in ASCII.

=== Get Mono/TFE version ===
Message 0098 (no data) requests the backplate report its TFE version number.
The response will be message 0018 in ASCII.

=== Get serial number ===
Message 009f (no data) requests the backplate report its serial number (a 64-bit hexadecimal value).
The response will be message 001f in uppercase ASCII.

=== Periodic status ===
Sending message 0083 (no data) will trigger various periodic messages:
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
000a - (every second; 16-bit data)

The Nest client sends 0083 every 30 seconds, but at least the periodic temperature status will continue on for an hour before stopping.

=== Power management ===
Wake vector bits:
0001 - timer
0002 - buffers full
0004 - temperature
0008 - pir
0010 - proximity
0020 - humidity
0040 - near pir
0080 - als
0100 - "vbat"
0200 - "vergence"

=== Temperature reading ===
The backplate will send message 0002 every 30 seconds.
The data contains two 16-bit numbers, which nlclient logs in decimal.
The first number is the temperature in centi-celcius.
The second number is the humidity in per-millis.

See also: [[#"Buffers"|"Buffers"]]

=== Reset ===
At least upon connection, the display sends message 00ff to the backplate to reset.

The backplate answers with:
0001 msg "<version> <build timestamp "YYYY-MM-DD HH:MM:SS"> K"
[[#FET presence|0004 FET presence]]
[[#FET presence|0009 FET presence]]
0001 msg "*sense 06d1 06d0 0001 0001 0000 0000 0000 0001 06d9 06d8 06d8; detect 09d3 065c"
0001 msg "BRK"

== Run BeagleBone/Debian programs ==
ln -s . /lib/arm-linux-gnueabihf
ln -s ld-2.11.1.so /lib/ld-linux-armhf.so.3

Nest Hacking

2014-08-10T04:51:23Z

Luke-Jr: /* Backplate state */

== Hardware ==

[https://www.ifixit.com/Teardown/Nest+Learning+Thermostat+2nd+Generation+Teardown/13818 Pictures]

=== Backplate ===
* ST Microelectronics STM32L151VB ultra-low-power 32 MHz ARM Cortex-M3 MCU
* Sensirion SHT20 humidity and temperature sensor
* Texas Instruments LW051A 8-channel CMOS analog multiplexer/demultiplexer

=== Display ===
* Texas Instruments AM3703CUS Sitara ARM Cortex A8 microprocessor
* Texas Instruments TPS65921B power management and USB single chip
* Samsung K4X51163PK 512 Mb mobile DRAM
* Ember EM357 integrated ZigBee/802.15.4 system-on-chip
* Micron MT29F2G16ABBEAH4 2 Gb NAND flash memory
* Skyworks 2436L high power 2.4 GHz 802.15.4 front-end module
* Texas Instruments WL1270B 802.11 b/g/n Wi-Fi solution
* Avago ADBM-A350 optical finger navigation module (knob movement sensor)

== Info ==
* /dev/event1 is the knob; /dev/event2 is the button
* /sys/class/hwmon/hwmon0/device/in0_battery_type * 0.003 is battery voltage
** Nest turns off wifi below 3.7 V, and waits until 3.8 V to automatically reconnect
* Display serial number is located in U-Boot environment variable "serial#"

== Nest software ==
/nestlabs/sbin/nlclient -config /nestlabs/etc/client.config -config /nestlabs/etc/Display/Display-2/client.config

=== Backplate communications ===
Backplate communications can be decoded from a (filtered) strace log using [http://luke.dashjr.org/programs/freeabode/kindling/NestDecode.pl NestDecode.pl], or decoded in real time using [http://luke.dashjr.org/programs/freeabode/kindling/nest-intercept.c nest-intercept.c].

nest-intercept.c requires one argument, the thread id reading from the backplate controller.
The easiest way to get this is to strace the nlclient process with -ff and look for a thread reading from fd 54.

Note that nest-intercept.c also has a "hack" variable which can be set to 0 (default is 2) in order to corrupt the TFE version response and trigger nlclient into uploading the firmware again.

=== Backplate firmware ===
Found in /nestlabs/share/bp/data/firmware/nlbpfirmware.plist

There are 12 different firmwares in the file:
* Test vs Production
* Backplate 2 vs Backplate 3
* TFE (BP_D2 for Bp2, AMBER_BP for Bp3) vs BSL
* For TFE firmwares, hex vs srec (which for some reason DO differ!)

Python script to extract them into individual files: [http://luke.dashjr.org/programs/freeabode/kindling/extract-fw.py extract-fw.py]

=== Backplate initialisation ===
When the backplate is first connected, the following sequence occurs:
tcflush(fd, TCIFLUSH)
Set baud to 115200 (-opost -isig -icanon -echo ...)
tcflush(fd, TCIOFLUSH)
tcsendbreak(fd, 1)
Send [[#Reset|00ff - Reset]]
Recv 0001 - (message from backplate; ASCII)
Recv [[#FET presence|0004 - FET presence]]
Recv [[#FET presence|0009 - FET presence]]
Send [[#FET presence|008f - FET presence]]
Send [[#Periodic status|0083 - Periodic status request]]
Send 0090 - get Mono/TFE id (no data; response 0010 with 3 bytes)
Recv 0001 - (message from backplate; ASCII)
Recv 0001 - (message from backplate; ASCII)
Recv 0010 - (24-bit data)
Send [[#Get Mono/TFE version|0098 - Get Mono/TFE version]]
Recv 000a - (every second; 16-bit data)
Recv 0007 - (every second; 16-bit data)
Recv [[#Get Mono/TFE version|0018 - Get Mono/TFE version (response)]]
Send [[#Get Mono/TFE build info|0099 - Get Mono/TFE build info]]
Recv [[#Get Mono/TFE build info|0019 - Get Mono/TFE build info (response)]]
Sometimes:
Send 009d - get BSL id (no data; responds with 001d)
Recv 001d - bsl id (response to 009d; 16-bit data)
Sometimes:
Send [[#Get BSL version|009b - Get BSL version]]
Recv [[#Get BSL version|001b - Get BSL version (response)]]
Sometimes:
Send 009c - get BSL info (no data; responds with 001c (constant?) data="BSL")
Recv 001c - Response to 009c; always(?) "BSL"
Send [[#Get serial number|009f - Get serial number]]
Recv [[#Get serial number|001f - Get serial number (response)]]
Send [[#Get hardware version|009e - Get hardware version]]
Recv [[#Get hardware version|001e - Get hardware version (response)]]

== Nest backplate interface ==
* Connected on /dev/ttyO2
* All communications with backplate begin with (d5)d5aa96 (d5 is doubled only for data FROM backplate)
* Everything is little endian
* 16-bit command
* 16-bit data length
* <data>
* 16-bit checksum

Monitor:
strace -ff -p $(pidof nlclient) -x -s9999 -e read,write 2>&1 | grep '(54'

NOTE: Most of this documentation is reverse engineered from firmware version BSL-2.1 and/or TFE_BP_D2-4.0.21 for Backplate-2.x.

=== Checksum ===
<Bytes-from-end>.<bit-value> <xor-with>
00.01 2110 (1021)
00.02 4220 (2042: 1021<<1)
00.04 8440 (4084: 2048<<1)
00.08 0881 (8108: 4084<<1)
00.10 3112 (1231: 8108<<1^1021)
00.20 6224 (2462: 1231<<1)
00.40 c448 (48c4: 2462<<1)
00.80 8891 (9188: 48c4<<1)
01.01 3133 (3313: 9188<<1^1021)
01.02 6266
01.04 c4cc
01.08 a989
01.10 7303
01.20 e606
01.40 cc0d
01.80 981b
02.01 3037
02.02 606e
...
03.01 b476
03.02 68ed
03.04 f1ca
03.08 c385
03.10 a71b
03.20 4e37
03.40 9c6e
03.80 38dd
...
07.20 687b

If you compute the contribution of the individual bit changes in the data you end up with the xor table above; byte offset from the end of the data, bit pattern, xor value. Correcting for little endianess in the output you end up with the hex values in parenthesis. The least significant bit is 0x1021 and each subsequent bit is a shift left, if the XOR value has the 0x8000 bit set then it is XORed with 0x1021. This is the CRC-CCITT polynomial.

8 7 6 5 4 3 2 1 0
d5 aa 96 82 00 02 00 00 00: 08b2
|| |
|| 68ed
|408b
20d4

08b2: 68ed ^ 408b ^ 20d4

Starting at the least significant bit and filling in the XOR values for each bit gives the above diagram; the diagram stops at the 20d4 XOR value because at that point it matches the final CRC. This tells us that the CRC covers the 6 bytes prior.

#!/usr/bin/env perl
use Digest::CRC qw(crc);
my $data = pack("H*", "820002000000");
printf("%04x\n", crc($data,16,0,0,0,0x1021,0,0));

We can also compute the same CRC in Perl; note the result will be byte swapped since the data encodes the number as little endian.

=== Command ids ===

==== Display to backplate ====
[[#FET control|0082 - FET control]]
[[#Periodic status|0083 - Periodic status request]]
[[#FET presence|008f - FET presence]]
0090 - get Mono/TFE id (no data; response 0010 with 3 bytes)
[[#Backplate firmware upload|0091 - Backplate firmware upload (start)]]
[[#Backplate firmware upload|0092 - Backplate firmware upload]]
[[#Backplate firmware upload|0093 - Backplate firmware upload (finish)]]
[[#Get Mono/TFE version|0098 - Get Mono/TFE version]]
[[#Get Mono/TFE build info|0099 - Get Mono/TFE build info]]
[[#Get BSL version|009b - Get BSL version]]
009c - get BSL info (no data; responds with 001c (constant?) data="BSL")
009d - get BSL id (no data; responds with 001d)
[[#Get hardware version|009e - Get hardware version]]
[[#Get serial number|009f - Get serial number]]
00a1 - quiet (16-bit max sleep seconds)
[[#"Buffers"|00a2 - Request "buffers" (every 30 seconds; no data; triggers [0025] [0027] 0022 0023 [0029] [002b] 000c 002f)]]
[[#"Buffers"|00a3 - ACK to 002f (no data)]]
00a4 - set wakeup mask (16-bit data)
00b1 - "temperature lock" (sent when button pressed/unpressed; no data)
00b3 - set humidity thresholds (32-bit data)
00b5 - set near pir threshold (16-bit data)
00b7 - set pir thresholds (??? data)
00b8 - set proximity thresholds (??? data)
00b9 - set als thresholds (32-bit data)
00ba - set vergence mode (48-bit data)
00c2 - set wakeup temperatures (48-bit data)
00c3 - set temp comp mode request (??? data)
00fe - DEBUG MODE
[[#Reset|00ff - Reset]]

==== Backplate to display ====
0001 - (message from backplate; ASCII)
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
[[#FET presence|0004 - FET presence]]
0005 - pir? (32-bit data)
0006 - ack switch?
0007 - near pid? (every second; 16-bit data)
0008 - proximity?
[[#FET presence|0009 - FET presence]]
000a - als? (every second; 2x(?) 16-bit data)
[[#Backplate state|000b - Backplate state]]
000c - sensor? (16-bit values: pir, px1, px1 divisor, px2, px2 divisor, alir, av; included in [[#"Buffers"|"buffers" data]])
000e - power?
0010 - (24-bit data)
[[#Backplate firmware upload|0011 - Backplate firmware upload (ACK)]]
0012 - ?
0013 - "Wakeup"?
0014 - "WakeVector" (16-bit data)
[[#Get Mono/TFE version|0018 - Get Mono/TFE version (response)]]
[[#Get Mono/TFE build info|0019 - Get Mono/TFE build info (response)]]
[[#Get BSL version|001b - Get BSL version (response)]]
001c - Response to 009c; always(?) "BSL"
001d - bsl id (response to 009d; 16-bit data)
[[#Get hardware version|001e - Get hardware version (response)]]
[[#Get serial number|001f - Get serial number (response)]]
[[#"Buffers"|0022 - buffered temperature reading (possibly multiple times)]]
[[#"Buffers"|0023 - BufferedSourceTemperature (3x 16-bit data; possibly multiple times)]]
[[#"Buffers"|0025 - BufferedNearPir (16-bit data; possibly multiple times)]]
[[#"Buffers"|0027 - BufferedPassiveInfrared (64-bit data; possibly multiple times)]]
[[#"Buffers"|0029 - BufferedAmbientLightSensor (48-bit data; likely 3x 16-bit; possibly multiple times)]]
[[#"Buffers"|002b - BufferedPowerData (64-bit data; possibly multiple times)]]
[[#"Buffers"|002f - End of "buffers" (16-bit data)]]

=== Backplate firmware upload ===
For uploading the firmware, the following sequence is used:
Send 0091 data=0000<firmware type>
Recv 0011 data=0000
Send 0092 data=0100...
Recv 0011 data=0100
Send 0092 data=0200...
Recv 0011 data=0200
...
Send 0092 data=a901...
Recv 0011 data=a901
Send 0093 data=aa01
Recv 0011 data=aa01
Following the upload, the [[#Backplate initialisation|backplate initialisation process]] begins immediately (that is, without message 00ff being sent to order a reset).
Presumably the 0011 message is an ACK, and the first 16 bits of each message is the line number.
The format itself appears to be Motorola S-record (SREC).
Uploading the BSL firmware was followed by the TFE firmware, so it may be required (though uploading the TFE firmware does ''not'' require uploading the BSL).

Firmware type is either 4d for TFE or 42 for BSL.

=== Backplate state ===
Data:
* 8-bit "state"
* 8-bit "flags"
** Bit 0x40 = charger off (?)
* 8-bit "px0" (may be wider?)
* 40-bit UNKNOWN (includes at least "p2" and "voc")
* 16-bit centi-volts "vi"
* 16-bit milli-volts "vo"
* 16-bit milli-volts "vb"
* 8-bit ("pins" or "wires")
* 8-bit ("wires" or "pins")
* 16-bit UNKNOWN

=== "Buffers" ===
The 00a2 message requests the backplate send the contents of various "buffers", which are returned in messages [0025], [0027], 0022, 0023, [0029], and [002b] (empty ones will NOT be sent; brackets infer commonly-empty buffers).
00a2 also triggers 000c immediately following these.
After all the buffers (including 000c) have been sent, the message 002f indicates "end of buffers".
The display is then expected to acknowledge it with message 00a3.

Buffers:
[[#Temperature reading|0022 - Temperature reading]]
0023 - BufferedSourceTemperature (not sure what that means)
0025 - BufferedNearPir
0027 - BufferedPassiveInfrared
0029 - BufferedAmbientLightSensor
002b - BufferedPowerData

=== FET control ===
Turn on W1: d5aa96 8200 0200 00 01 29a2
Turn off W1: d5aa96 8200 0200 00 00 08b2
Turn on Y1: d5aa96 8200 0200 01 01 1891
Turn off Y1: d5aa96 8200 0200 01 00 3981
Turn on G : d5aa96 8200 0200 02 01 4bc4
Turn off G : d5aa96 8200 0200 02 00 6ad4
Turn on OB: d5aa96 8200 0200 03 01 7af7
Turn off OB: d5aa96 8200 0200 03 00 5be7
Turn on W2: d5aa96 8200 0200 04 01 ed6e
Turn off W2: d5aa96 8200 0200 04 00 cc7e
Turn on Y2: d5aa96 8200 0200 07 01 be3b
Turn off Y2: d5aa96 8200 0200 07 00 9f2b
Turn on * : d5aa96 8200 0200 0b 01 d37e
Turn off * : d5aa96 8200 0200 0b 00 f26e

For the sake of documentation, we will refer to the unique id numbers for each wire as "wire id numbers".
So wire id 0 is W1, wire id 1 is Y1, wire id B is *, etc.

=== FET presence ===
The backplate will, at least upon connection, send information about which FETs have a wire present.
This data is received with command ids 0004 and 0009, in that order.
Each sensor is represented by one byte which is either 00 (not present) or 01 (present).

The content of 0004 is in order of the "wire id numbers" used for control:
W1, Y1, G, OB, W2, ?0, ?0, Y2, C, RC, ?0, *, ?0

The content of 0009 is arranged differently and has 2 more values:
W1, Y1, C, RC, ?0, G, OB, W2, ?0, Y2, ?0, *, ?0, ?0, ?0

0009 seems to indicate a wire is physically plugged in, while 0004 indicates that it is connected to something (?).

After these are received, the display sends back command 008f with the exact data from message 0004.
Message 008f does not itself receive any response.

In a power outage condition, 0004 will report all absent (including unknown ones), whereas 0009 will continue to report the same as when power is available.

=== Get Mono/TFE build info ===
Message 0099 (no data) requests the backplate report information about its build.
The response will be message 0019 in ASCII (one line, no trailing newline).

=== Get hardware version ===
Message 009e (no data) requests the backplate report a "Backplate-"X.Y version string.
Since the firmware file on the display CPU uses these strings as "MinApplicability" and "MaxApplicability" ranges, it is probable they refer to the hardware.

Witnessed versions:
"Backplate-2.8" - Florida Lowes

=== Get BSL version ===
Message 009b (no data) requests the backplate report its BSL version number.
The response will be message 001b in ASCII.

=== Get Mono/TFE version ===
Message 0098 (no data) requests the backplate report its TFE version number.
The response will be message 0018 in ASCII.

=== Get serial number ===
Message 009f (no data) requests the backplate report its serial number (a 64-bit hexadecimal value).
The response will be message 001f in uppercase ASCII.

=== Periodic status ===
Sending message 0083 (no data) will trigger various periodic messages:
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
000a - (every second; 16-bit data)

The Nest client sends 0083 every 30 seconds, but at least the periodic temperature status will continue on for an hour before stopping.

=== Temperature reading ===
The backplate will send message 0002 every 30 seconds.
The data contains two 16-bit numbers, which nlclient logs in decimal.
The first number is the temperature in centi-celcius.
The second number is the humidity in per-millis.

See also: [[#"Buffers"|"Buffers"]]

=== Reset ===
At least upon connection, the display sends message 00ff to the backplate to reset.

The backplate answers with:
0001 msg "<version> <build timestamp "YYYY-MM-DD HH:MM:SS"> K"
[[#FET presence|0004 FET presence]]
[[#FET presence|0009 FET presence]]
0001 msg "*sense 06d1 06d0 0001 0001 0000 0000 0000 0001 06d9 06d8 06d8; detect 09d3 065c"
0001 msg "BRK"

== Run BeagleBone/Debian programs ==
ln -s . /lib/arm-linux-gnueabihf
ln -s ld-2.11.1.so /lib/ld-linux-armhf.so.3

Nest Hacking

2014-08-09T07:51:17Z

Luke-Jr: /* Display to backplate */

== Hardware ==

[https://www.ifixit.com/Teardown/Nest+Learning+Thermostat+2nd+Generation+Teardown/13818 Pictures]

=== Backplate ===
* ST Microelectronics STM32L151VB ultra-low-power 32 MHz ARM Cortex-M3 MCU
* Sensirion SHT20 humidity and temperature sensor
* Texas Instruments LW051A 8-channel CMOS analog multiplexer/demultiplexer

=== Display ===
* Texas Instruments AM3703CUS Sitara ARM Cortex A8 microprocessor
* Texas Instruments TPS65921B power management and USB single chip
* Samsung K4X51163PK 512 Mb mobile DRAM
* Ember EM357 integrated ZigBee/802.15.4 system-on-chip
* Micron MT29F2G16ABBEAH4 2 Gb NAND flash memory
* Skyworks 2436L high power 2.4 GHz 802.15.4 front-end module
* Texas Instruments WL1270B 802.11 b/g/n Wi-Fi solution
* Avago ADBM-A350 optical finger navigation module (knob movement sensor)

== Info ==
* /dev/event1 is the knob; /dev/event2 is the button
* /sys/class/hwmon/hwmon0/device/in0_battery_type * 0.003 is battery voltage
** Nest turns off wifi below 3.7 V, and waits until 3.8 V to automatically reconnect
* Display serial number is located in U-Boot environment variable "serial#"

== Nest software ==
/nestlabs/sbin/nlclient -config /nestlabs/etc/client.config -config /nestlabs/etc/Display/Display-2/client.config

=== Backplate communications ===
Backplate communications can be decoded from a (filtered) strace log using [http://luke.dashjr.org/programs/freeabode/kindling/NestDecode.pl NestDecode.pl], or decoded in real time using [http://luke.dashjr.org/programs/freeabode/kindling/nest-intercept.c nest-intercept.c].

nest-intercept.c requires one argument, the thread id reading from the backplate controller.
The easiest way to get this is to strace the nlclient process with -ff and look for a thread reading from fd 54.

Note that nest-intercept.c also has a "hack" variable which can be set to 0 (default is 2) in order to corrupt the TFE version response and trigger nlclient into uploading the firmware again.

=== Backplate firmware ===
Found in /nestlabs/share/bp/data/firmware/nlbpfirmware.plist

There are 12 different firmwares in the file:
* Test vs Production
* Backplate 2 vs Backplate 3
* TFE (BP_D2 for Bp2, AMBER_BP for Bp3) vs BSL
* For TFE firmwares, hex vs srec (which for some reason DO differ!)

Python script to extract them into individual files: [http://luke.dashjr.org/programs/freeabode/kindling/extract-fw.py extract-fw.py]

=== Backplate initialisation ===
When the backplate is first connected, the following sequence occurs:
tcflush(fd, TCIFLUSH)
Set baud to 115200 (-opost -isig -icanon -echo ...)
tcflush(fd, TCIOFLUSH)
tcsendbreak(fd, 1)
Send [[#Reset|00ff - Reset]]
Recv 0001 - (message from backplate; ASCII)
Recv [[#FET presence|0004 - FET presence]]
Recv [[#FET presence|0009 - FET presence]]
Send [[#FET presence|008f - FET presence]]
Send [[#Periodic status|0083 - Periodic status request]]
Send 0090 - get Mono/TFE id (no data; response 0010 with 3 bytes)
Recv 0001 - (message from backplate; ASCII)
Recv 0001 - (message from backplate; ASCII)
Recv 0010 - (24-bit data)
Send [[#Get Mono/TFE version|0098 - Get Mono/TFE version]]
Recv 000a - (every second; 16-bit data)
Recv 0007 - (every second; 16-bit data)
Recv [[#Get Mono/TFE version|0018 - Get Mono/TFE version (response)]]
Send [[#Get Mono/TFE build info|0099 - Get Mono/TFE build info]]
Recv [[#Get Mono/TFE build info|0019 - Get Mono/TFE build info (response)]]
Sometimes:
Send 009d - get BSL id (no data; responds with 001d)
Recv 001d - bsl id (response to 009d; 16-bit data)
Sometimes:
Send [[#Get BSL version|009b - Get BSL version]]
Recv [[#Get BSL version|001b - Get BSL version (response)]]
Sometimes:
Send 009c - get BSL info (no data; responds with 001c (constant?) data="BSL")
Recv 001c - Response to 009c; always(?) "BSL"
Send [[#Get serial number|009f - Get serial number]]
Recv [[#Get serial number|001f - Get serial number (response)]]
Send [[#Get hardware version|009e - Get hardware version]]
Recv [[#Get hardware version|001e - Get hardware version (response)]]

== Nest backplate interface ==
* Connected on /dev/ttyO2
* All communications with backplate begin with (d5)d5aa96 (d5 is doubled only for data FROM backplate)
* Everything is little endian
* 16-bit command
* 16-bit data length
* <data>
* 16-bit checksum

Monitor:
strace -ff -p $(pidof nlclient) -x -s9999 -e read,write 2>&1 | grep '(54'

NOTE: Most of this documentation is reverse engineered from firmware version BSL-2.1 and/or TFE_BP_D2-4.0.21 for Backplate-2.x.

=== Checksum ===
<Bytes-from-end>.<bit-value> <xor-with>
00.01 2110 (1021)
00.02 4220 (2042: 1021<<1)
00.04 8440 (4084: 2048<<1)
00.08 0881 (8108: 4084<<1)
00.10 3112 (1231: 8108<<1^1021)
00.20 6224 (2462: 1231<<1)
00.40 c448 (48c4: 2462<<1)
00.80 8891 (9188: 48c4<<1)
01.01 3133 (3313: 9188<<1^1021)
01.02 6266
01.04 c4cc
01.08 a989
01.10 7303
01.20 e606
01.40 cc0d
01.80 981b
02.01 3037
02.02 606e
...
03.01 b476
03.02 68ed
03.04 f1ca
03.08 c385
03.10 a71b
03.20 4e37
03.40 9c6e
03.80 38dd
...
07.20 687b

If you compute the contribution of the individual bit changes in the data you end up with the xor table above; byte offset from the end of the data, bit pattern, xor value. Correcting for little endianess in the output you end up with the hex values in parenthesis. The least significant bit is 0x1021 and each subsequent bit is a shift left, if the XOR value has the 0x8000 bit set then it is XORed with 0x1021. This is the CRC-CCITT polynomial.

8 7 6 5 4 3 2 1 0
d5 aa 96 82 00 02 00 00 00: 08b2
|| |
|| 68ed
|408b
20d4

08b2: 68ed ^ 408b ^ 20d4

Starting at the least significant bit and filling in the XOR values for each bit gives the above diagram; the diagram stops at the 20d4 XOR value because at that point it matches the final CRC. This tells us that the CRC covers the 6 bytes prior.

#!/usr/bin/env perl
use Digest::CRC qw(crc);
my $data = pack("H*", "820002000000");
printf("%04x\n", crc($data,16,0,0,0,0x1021,0,0));

We can also compute the same CRC in Perl; note the result will be byte swapped since the data encodes the number as little endian.

=== Command ids ===

==== Display to backplate ====
[[#FET control|0082 - FET control]]
[[#Periodic status|0083 - Periodic status request]]
[[#FET presence|008f - FET presence]]
0090 - get Mono/TFE id (no data; response 0010 with 3 bytes)
[[#Backplate firmware upload|0091 - Backplate firmware upload (start)]]
[[#Backplate firmware upload|0092 - Backplate firmware upload]]
[[#Backplate firmware upload|0093 - Backplate firmware upload (finish)]]
[[#Get Mono/TFE version|0098 - Get Mono/TFE version]]
[[#Get Mono/TFE build info|0099 - Get Mono/TFE build info]]
[[#Get BSL version|009b - Get BSL version]]
009c - get BSL info (no data; responds with 001c (constant?) data="BSL")
009d - get BSL id (no data; responds with 001d)
[[#Get hardware version|009e - Get hardware version]]
[[#Get serial number|009f - Get serial number]]
00a1 - quiet (16-bit max sleep seconds)
[[#"Buffers"|00a2 - Request "buffers" (every 30 seconds; no data; triggers [0025] [0027] 0022 0023 [0029] [002b] 000c 002f)]]
[[#"Buffers"|00a3 - ACK to 002f (no data)]]
00a4 - set wakeup mask (16-bit data)
00b1 - "temperature lock" (sent when button pressed/unpressed; no data)
00b3 - set humidity thresholds (32-bit data)
00b5 - set near pir threshold (16-bit data)
00b7 - set pir thresholds (??? data)
00b8 - set proximity thresholds (??? data)
00b9 - set als thresholds (32-bit data)
00ba - set vergence mode (48-bit data)
00c2 - set wakeup temperatures (48-bit data)
00c3 - set temp comp mode request (??? data)
00fe - DEBUG MODE
[[#Reset|00ff - Reset]]

==== Backplate to display ====
0001 - (message from backplate; ASCII)
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
[[#FET presence|0004 - FET presence]]
0005 - pir? (32-bit data)
0006 - ack switch?
0007 - near pid? (every second; 16-bit data)
0008 - proximity?
[[#FET presence|0009 - FET presence]]
000a - als? (every second; 2x(?) 16-bit data)
[[#Backplate state|000b - Backplate state]]
000c - sensor? (16-bit values: pir, px1, px1 divisor, px2, px2 divisor, alir, av; included in [[#"Buffers"|"buffers" data]])
000e - power?
0010 - (24-bit data)
[[#Backplate firmware upload|0011 - Backplate firmware upload (ACK)]]
0012 - ?
0013 - "Wakeup"?
0014 - "WakeVector" (16-bit data)
[[#Get Mono/TFE version|0018 - Get Mono/TFE version (response)]]
[[#Get Mono/TFE build info|0019 - Get Mono/TFE build info (response)]]
[[#Get BSL version|001b - Get BSL version (response)]]
001c - Response to 009c; always(?) "BSL"
001d - bsl id (response to 009d; 16-bit data)
[[#Get hardware version|001e - Get hardware version (response)]]
[[#Get serial number|001f - Get serial number (response)]]
[[#"Buffers"|0022 - buffered temperature reading (possibly multiple times)]]
[[#"Buffers"|0023 - BufferedSourceTemperature (3x 16-bit data; possibly multiple times)]]
[[#"Buffers"|0025 - BufferedNearPir (16-bit data; possibly multiple times)]]
[[#"Buffers"|0027 - BufferedPassiveInfrared (64-bit data; possibly multiple times)]]
[[#"Buffers"|0029 - BufferedAmbientLightSensor (48-bit data; likely 3x 16-bit; possibly multiple times)]]
[[#"Buffers"|002b - BufferedPowerData (64-bit data; possibly multiple times)]]
[[#"Buffers"|002f - End of "buffers" (16-bit data)]]

=== Backplate firmware upload ===
For uploading the firmware, the following sequence is used:
Send 0091 data=0000<firmware type>
Recv 0011 data=0000
Send 0092 data=0100...
Recv 0011 data=0100
Send 0092 data=0200...
Recv 0011 data=0200
...
Send 0092 data=a901...
Recv 0011 data=a901
Send 0093 data=aa01
Recv 0011 data=aa01
Following the upload, the [[#Backplate initialisation|backplate initialisation process]] begins immediately (that is, without message 00ff being sent to order a reset).
Presumably the 0011 message is an ACK, and the first 16 bits of each message is the line number.
The format itself appears to be Motorola S-record (SREC).
Uploading the BSL firmware was followed by the TFE firmware, so it may be required (though uploading the TFE firmware does ''not'' require uploading the BSL).

Firmware type is either 4d for TFE or 42 for BSL.

=== Backplate state ===
Data:
* 8-bit "state"
* 8-bit "flags"
* 8-bit "px0" (may be wider?)
* 40-bit UNKNOWN (includes at least "p2" and "voc")
* 16-bit centi-volts "vi"
* 16-bit milli-volts "vo"
* 16-bit milli-volts "vb"
* 8-bit ("pins" or "wires")
* 8-bit ("wires" or "pins")
* 16-bit UNKNOWN

=== "Buffers" ===
The 00a2 message requests the backplate send the contents of various "buffers", which are returned in messages [0025], [0027], 0022, 0023, [0029], and [002b] (empty ones will NOT be sent; brackets infer commonly-empty buffers).
00a2 also triggers 000c immediately following these.
After all the buffers (including 000c) have been sent, the message 002f indicates "end of buffers".
The display is then expected to acknowledge it with message 00a3.

Buffers:
[[#Temperature reading|0022 - Temperature reading]]
0023 - BufferedSourceTemperature (not sure what that means)
0025 - BufferedNearPir
0027 - BufferedPassiveInfrared
0029 - BufferedAmbientLightSensor
002b - BufferedPowerData

=== FET control ===
Turn on W1: d5aa96 8200 0200 00 01 29a2
Turn off W1: d5aa96 8200 0200 00 00 08b2
Turn on Y1: d5aa96 8200 0200 01 01 1891
Turn off Y1: d5aa96 8200 0200 01 00 3981
Turn on G : d5aa96 8200 0200 02 01 4bc4
Turn off G : d5aa96 8200 0200 02 00 6ad4
Turn on OB: d5aa96 8200 0200 03 01 7af7
Turn off OB: d5aa96 8200 0200 03 00 5be7
Turn on W2: d5aa96 8200 0200 04 01 ed6e
Turn off W2: d5aa96 8200 0200 04 00 cc7e
Turn on Y2: d5aa96 8200 0200 07 01 be3b
Turn off Y2: d5aa96 8200 0200 07 00 9f2b
Turn on * : d5aa96 8200 0200 0b 01 d37e
Turn off * : d5aa96 8200 0200 0b 00 f26e

For the sake of documentation, we will refer to the unique id numbers for each wire as "wire id numbers".
So wire id 0 is W1, wire id 1 is Y1, wire id B is *, etc.

=== FET presence ===
The backplate will, at least upon connection, send information about which FETs have a wire present.
This data is received with command ids 0004 and 0009, in that order.
Each sensor is represented by one byte which is either 00 (not present) or 01 (present).

The content of 0004 is in order of the "wire id numbers" used for control:
W1, Y1, G, OB, W2, ?0, ?0, Y2, C, RC, ?0, *, ?0

The content of 0009 is arranged differently and has 2 more values:
W1, Y1, C, RC, ?0, G, OB, W2, ?0, Y2, ?0, *, ?0, ?0, ?0

0009 seems to indicate a wire is physically plugged in, while 0004 indicates that it is connected to something (?).

After these are received, the display sends back command 008f with the exact data from message 0004.
Message 008f does not itself receive any response.

In a power outage condition, 0004 will report all absent (including unknown ones), whereas 0009 will continue to report the same as when power is available.

=== Get Mono/TFE build info ===
Message 0099 (no data) requests the backplate report information about its build.
The response will be message 0019 in ASCII (one line, no trailing newline).

=== Get hardware version ===
Message 009e (no data) requests the backplate report a "Backplate-"X.Y version string.
Since the firmware file on the display CPU uses these strings as "MinApplicability" and "MaxApplicability" ranges, it is probable they refer to the hardware.

Witnessed versions:
"Backplate-2.8" - Florida Lowes

=== Get BSL version ===
Message 009b (no data) requests the backplate report its BSL version number.
The response will be message 001b in ASCII.

=== Get Mono/TFE version ===
Message 0098 (no data) requests the backplate report its TFE version number.
The response will be message 0018 in ASCII.

=== Get serial number ===
Message 009f (no data) requests the backplate report its serial number (a 64-bit hexadecimal value).
The response will be message 001f in uppercase ASCII.

=== Periodic status ===
Sending message 0083 (no data) will trigger various periodic messages:
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
000a - (every second; 16-bit data)

The Nest client sends 0083 every 30 seconds, but at least the periodic temperature status will continue on for an hour before stopping.

=== Temperature reading ===
The backplate will send message 0002 every 30 seconds.
The data contains two 16-bit numbers, which nlclient logs in decimal.
The first number is the temperature in centi-celcius.
The second number is the humidity in per-millis.

See also: [[#"Buffers"|"Buffers"]]

=== Reset ===
At least upon connection, the display sends message 00ff to the backplate to reset.

The backplate answers with:
0001 msg "<version> <build timestamp "YYYY-MM-DD HH:MM:SS"> K"
[[#FET presence|0004 FET presence]]
[[#FET presence|0009 FET presence]]
0001 msg "*sense 06d1 06d0 0001 0001 0000 0000 0000 0001 06d9 06d8 06d8; detect 09d3 065c"
0001 msg "BRK"

== Run BeagleBone/Debian programs ==
ln -s . /lib/arm-linux-gnueabihf
ln -s ld-2.11.1.so /lib/ld-linux-armhf.so.3

Nest Hacking

2014-08-09T06:40:18Z

Luke-Jr: /* Backplate to display */

== Hardware ==

[https://www.ifixit.com/Teardown/Nest+Learning+Thermostat+2nd+Generation+Teardown/13818 Pictures]

=== Backplate ===
* ST Microelectronics STM32L151VB ultra-low-power 32 MHz ARM Cortex-M3 MCU
* Sensirion SHT20 humidity and temperature sensor
* Texas Instruments LW051A 8-channel CMOS analog multiplexer/demultiplexer

=== Display ===
* Texas Instruments AM3703CUS Sitara ARM Cortex A8 microprocessor
* Texas Instruments TPS65921B power management and USB single chip
* Samsung K4X51163PK 512 Mb mobile DRAM
* Ember EM357 integrated ZigBee/802.15.4 system-on-chip
* Micron MT29F2G16ABBEAH4 2 Gb NAND flash memory
* Skyworks 2436L high power 2.4 GHz 802.15.4 front-end module
* Texas Instruments WL1270B 802.11 b/g/n Wi-Fi solution
* Avago ADBM-A350 optical finger navigation module (knob movement sensor)

== Info ==
* /dev/event1 is the knob; /dev/event2 is the button
* /sys/class/hwmon/hwmon0/device/in0_battery_type * 0.003 is battery voltage
** Nest turns off wifi below 3.7 V, and waits until 3.8 V to automatically reconnect
* Display serial number is located in U-Boot environment variable "serial#"

== Nest software ==
/nestlabs/sbin/nlclient -config /nestlabs/etc/client.config -config /nestlabs/etc/Display/Display-2/client.config

=== Backplate communications ===
Backplate communications can be decoded from a (filtered) strace log using [http://luke.dashjr.org/programs/freeabode/kindling/NestDecode.pl NestDecode.pl], or decoded in real time using [http://luke.dashjr.org/programs/freeabode/kindling/nest-intercept.c nest-intercept.c].

nest-intercept.c requires one argument, the thread id reading from the backplate controller.
The easiest way to get this is to strace the nlclient process with -ff and look for a thread reading from fd 54.

Note that nest-intercept.c also has a "hack" variable which can be set to 0 (default is 2) in order to corrupt the TFE version response and trigger nlclient into uploading the firmware again.

=== Backplate firmware ===
Found in /nestlabs/share/bp/data/firmware/nlbpfirmware.plist

There are 12 different firmwares in the file:
* Test vs Production
* Backplate 2 vs Backplate 3
* TFE (BP_D2 for Bp2, AMBER_BP for Bp3) vs BSL
* For TFE firmwares, hex vs srec (which for some reason DO differ!)

Python script to extract them into individual files: [http://luke.dashjr.org/programs/freeabode/kindling/extract-fw.py extract-fw.py]

=== Backplate initialisation ===
When the backplate is first connected, the following sequence occurs:
tcflush(fd, TCIFLUSH)
Set baud to 115200 (-opost -isig -icanon -echo ...)
tcflush(fd, TCIOFLUSH)
tcsendbreak(fd, 1)
Send [[#Reset|00ff - Reset]]
Recv 0001 - (message from backplate; ASCII)
Recv [[#FET presence|0004 - FET presence]]
Recv [[#FET presence|0009 - FET presence]]
Send [[#FET presence|008f - FET presence]]
Send [[#Periodic status|0083 - Periodic status request]]
Send 0090 - get Mono/TFE id (no data; response 0010 with 3 bytes)
Recv 0001 - (message from backplate; ASCII)
Recv 0001 - (message from backplate; ASCII)
Recv 0010 - (24-bit data)
Send [[#Get Mono/TFE version|0098 - Get Mono/TFE version]]
Recv 000a - (every second; 16-bit data)
Recv 0007 - (every second; 16-bit data)
Recv [[#Get Mono/TFE version|0018 - Get Mono/TFE version (response)]]
Send [[#Get Mono/TFE build info|0099 - Get Mono/TFE build info]]
Recv [[#Get Mono/TFE build info|0019 - Get Mono/TFE build info (response)]]
Sometimes:
Send 009d - get BSL id (no data; responds with 001d)
Recv 001d - bsl id (response to 009d; 16-bit data)
Sometimes:
Send [[#Get BSL version|009b - Get BSL version]]
Recv [[#Get BSL version|001b - Get BSL version (response)]]
Sometimes:
Send 009c - get BSL info (no data; responds with 001c (constant?) data="BSL")
Recv 001c - Response to 009c; always(?) "BSL"
Send [[#Get serial number|009f - Get serial number]]
Recv [[#Get serial number|001f - Get serial number (response)]]
Send [[#Get hardware version|009e - Get hardware version]]
Recv [[#Get hardware version|001e - Get hardware version (response)]]

== Nest backplate interface ==
* Connected on /dev/ttyO2
* All communications with backplate begin with (d5)d5aa96 (d5 is doubled only for data FROM backplate)
* Everything is little endian
* 16-bit command
* 16-bit data length
* <data>
* 16-bit checksum

Monitor:
strace -ff -p $(pidof nlclient) -x -s9999 -e read,write 2>&1 | grep '(54'

NOTE: Most of this documentation is reverse engineered from firmware version BSL-2.1 and/or TFE_BP_D2-4.0.21 for Backplate-2.x.

=== Checksum ===
<Bytes-from-end>.<bit-value> <xor-with>
00.01 2110 (1021)
00.02 4220 (2042: 1021<<1)
00.04 8440 (4084: 2048<<1)
00.08 0881 (8108: 4084<<1)
00.10 3112 (1231: 8108<<1^1021)
00.20 6224 (2462: 1231<<1)
00.40 c448 (48c4: 2462<<1)
00.80 8891 (9188: 48c4<<1)
01.01 3133 (3313: 9188<<1^1021)
01.02 6266
01.04 c4cc
01.08 a989
01.10 7303
01.20 e606
01.40 cc0d
01.80 981b
02.01 3037
02.02 606e
...
03.01 b476
03.02 68ed
03.04 f1ca
03.08 c385
03.10 a71b
03.20 4e37
03.40 9c6e
03.80 38dd
...
07.20 687b

If you compute the contribution of the individual bit changes in the data you end up with the xor table above; byte offset from the end of the data, bit pattern, xor value. Correcting for little endianess in the output you end up with the hex values in parenthesis. The least significant bit is 0x1021 and each subsequent bit is a shift left, if the XOR value has the 0x8000 bit set then it is XORed with 0x1021. This is the CRC-CCITT polynomial.

8 7 6 5 4 3 2 1 0
d5 aa 96 82 00 02 00 00 00: 08b2
|| |
|| 68ed
|408b
20d4

08b2: 68ed ^ 408b ^ 20d4

Starting at the least significant bit and filling in the XOR values for each bit gives the above diagram; the diagram stops at the 20d4 XOR value because at that point it matches the final CRC. This tells us that the CRC covers the 6 bytes prior.

#!/usr/bin/env perl
use Digest::CRC qw(crc);
my $data = pack("H*", "820002000000");
printf("%04x\n", crc($data,16,0,0,0,0x1021,0,0));

We can also compute the same CRC in Perl; note the result will be byte swapped since the data encodes the number as little endian.

=== Command ids ===

==== Display to backplate ====
[[#FET control|0082 - FET control]]
[[#Periodic status|0083 - Periodic status request]]
[[#FET presence|008f - FET presence]]
0090 - get Mono/TFE id (no data; response 0010 with 3 bytes)
[[#Backplate firmware upload|0091 - Backplate firmware upload (start)]]
[[#Backplate firmware upload|0092 - Backplate firmware upload]]
[[#Backplate firmware upload|0093 - Backplate firmware upload (finish)]]
[[#Get Mono/TFE version|0098 - Get Mono/TFE version]]
[[#Get Mono/TFE build info|0099 - Get Mono/TFE build info]]
[[#Get BSL version|009b - Get BSL version]]
009c - get BSL info (no data; responds with 001c (constant?) data="BSL")
009d - get BSL id (no data; responds with 001d)
[[#Get hardware version|009e - Get hardware version]]
[[#Get serial number|009f - Get serial number]]
00a1 - quiet (16-bit max sleep seconds)
[[#"Buffers"|00a2 - Request "buffers" (every 30 seconds; no data; triggers [0025] [0027] 0022 0023 [0029] [002b] 000c 002f)]]
[[#"Buffers"|00a3 - ACK to 002f (no data)]]
00a4 - set wakeup mask (16-bit data)
00b1 - "temperature lock" (sent when button pressed/unpressed; no data)
00b3 - set humidity thresholds (32-bit data)
00b5 - set near pir threshold (16-bit data)
00b7 - set pir thresholds (??? data)
00b8 - set proximity thresholds (??? data)
00b9 - set als thresholds (32-bit data)
00ba - set vergence mode (48-bit data)
00c2 - set wakeup temperatures (48-bit data)
00c3 - set temp comp mode request (??? data)
[[#Reset|00ff - Reset]]

==== Backplate to display ====
0001 - (message from backplate; ASCII)
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
[[#FET presence|0004 - FET presence]]
0005 - pir? (32-bit data)
0006 - ack switch?
0007 - near pid? (every second; 16-bit data)
0008 - proximity?
[[#FET presence|0009 - FET presence]]
000a - als? (every second; 2x(?) 16-bit data)
[[#Backplate state|000b - Backplate state]]
000c - sensor? (16-bit values: pir, px1, px1 divisor, px2, px2 divisor, alir, av; included in [[#"Buffers"|"buffers" data]])
000e - power?
0010 - (24-bit data)
[[#Backplate firmware upload|0011 - Backplate firmware upload (ACK)]]
0012 - ?
0013 - "Wakeup"?
0014 - "WakeVector" (16-bit data)
[[#Get Mono/TFE version|0018 - Get Mono/TFE version (response)]]
[[#Get Mono/TFE build info|0019 - Get Mono/TFE build info (response)]]
[[#Get BSL version|001b - Get BSL version (response)]]
001c - Response to 009c; always(?) "BSL"
001d - bsl id (response to 009d; 16-bit data)
[[#Get hardware version|001e - Get hardware version (response)]]
[[#Get serial number|001f - Get serial number (response)]]
[[#"Buffers"|0022 - buffered temperature reading (possibly multiple times)]]
[[#"Buffers"|0023 - BufferedSourceTemperature (3x 16-bit data; possibly multiple times)]]
[[#"Buffers"|0025 - BufferedNearPir (16-bit data; possibly multiple times)]]
[[#"Buffers"|0027 - BufferedPassiveInfrared (64-bit data; possibly multiple times)]]
[[#"Buffers"|0029 - BufferedAmbientLightSensor (48-bit data; likely 3x 16-bit; possibly multiple times)]]
[[#"Buffers"|002b - BufferedPowerData (64-bit data; possibly multiple times)]]
[[#"Buffers"|002f - End of "buffers" (16-bit data)]]

=== Backplate firmware upload ===
For uploading the firmware, the following sequence is used:
Send 0091 data=0000<firmware type>
Recv 0011 data=0000
Send 0092 data=0100...
Recv 0011 data=0100
Send 0092 data=0200...
Recv 0011 data=0200
...
Send 0092 data=a901...
Recv 0011 data=a901
Send 0093 data=aa01
Recv 0011 data=aa01
Following the upload, the [[#Backplate initialisation|backplate initialisation process]] begins immediately (that is, without message 00ff being sent to order a reset).
Presumably the 0011 message is an ACK, and the first 16 bits of each message is the line number.
The format itself appears to be Motorola S-record (SREC).
Uploading the BSL firmware was followed by the TFE firmware, so it may be required (though uploading the TFE firmware does ''not'' require uploading the BSL).

Firmware type is either 4d for TFE or 42 for BSL.

=== Backplate state ===
Data:
* 8-bit "state"
* 8-bit "flags"
* 8-bit "px0" (may be wider?)
* 40-bit UNKNOWN (includes at least "p2" and "voc")
* 16-bit centi-volts "vi"
* 16-bit milli-volts "vo"
* 16-bit milli-volts "vb"
* 8-bit ("pins" or "wires")
* 8-bit ("wires" or "pins")
* 16-bit UNKNOWN

=== "Buffers" ===
The 00a2 message requests the backplate send the contents of various "buffers", which are returned in messages [0025], [0027], 0022, 0023, [0029], and [002b] (empty ones will NOT be sent; brackets infer commonly-empty buffers).
00a2 also triggers 000c immediately following these.
After all the buffers (including 000c) have been sent, the message 002f indicates "end of buffers".
The display is then expected to acknowledge it with message 00a3.

Buffers:
[[#Temperature reading|0022 - Temperature reading]]
0023 - BufferedSourceTemperature (not sure what that means)
0025 - BufferedNearPir
0027 - BufferedPassiveInfrared
0029 - BufferedAmbientLightSensor
002b - BufferedPowerData

=== FET control ===
Turn on W1: d5aa96 8200 0200 00 01 29a2
Turn off W1: d5aa96 8200 0200 00 00 08b2
Turn on Y1: d5aa96 8200 0200 01 01 1891
Turn off Y1: d5aa96 8200 0200 01 00 3981
Turn on G : d5aa96 8200 0200 02 01 4bc4
Turn off G : d5aa96 8200 0200 02 00 6ad4
Turn on OB: d5aa96 8200 0200 03 01 7af7
Turn off OB: d5aa96 8200 0200 03 00 5be7
Turn on W2: d5aa96 8200 0200 04 01 ed6e
Turn off W2: d5aa96 8200 0200 04 00 cc7e
Turn on Y2: d5aa96 8200 0200 07 01 be3b
Turn off Y2: d5aa96 8200 0200 07 00 9f2b
Turn on * : d5aa96 8200 0200 0b 01 d37e
Turn off * : d5aa96 8200 0200 0b 00 f26e

For the sake of documentation, we will refer to the unique id numbers for each wire as "wire id numbers".
So wire id 0 is W1, wire id 1 is Y1, wire id B is *, etc.

=== FET presence ===
The backplate will, at least upon connection, send information about which FETs have a wire present.
This data is received with command ids 0004 and 0009, in that order.
Each sensor is represented by one byte which is either 00 (not present) or 01 (present).

The content of 0004 is in order of the "wire id numbers" used for control:
W1, Y1, G, OB, W2, ?0, ?0, Y2, C, RC, ?0, *, ?0

The content of 0009 is arranged differently and has 2 more values:
W1, Y1, C, RC, ?0, G, OB, W2, ?0, Y2, ?0, *, ?0, ?0, ?0

0009 seems to indicate a wire is physically plugged in, while 0004 indicates that it is connected to something (?).

After these are received, the display sends back command 008f with the exact data from message 0004.
Message 008f does not itself receive any response.

In a power outage condition, 0004 will report all absent (including unknown ones), whereas 0009 will continue to report the same as when power is available.

=== Get Mono/TFE build info ===
Message 0099 (no data) requests the backplate report information about its build.
The response will be message 0019 in ASCII (one line, no trailing newline).

=== Get hardware version ===
Message 009e (no data) requests the backplate report a "Backplate-"X.Y version string.
Since the firmware file on the display CPU uses these strings as "MinApplicability" and "MaxApplicability" ranges, it is probable they refer to the hardware.

Witnessed versions:
"Backplate-2.8" - Florida Lowes

=== Get BSL version ===
Message 009b (no data) requests the backplate report its BSL version number.
The response will be message 001b in ASCII.

=== Get Mono/TFE version ===
Message 0098 (no data) requests the backplate report its TFE version number.
The response will be message 0018 in ASCII.

=== Get serial number ===
Message 009f (no data) requests the backplate report its serial number (a 64-bit hexadecimal value).
The response will be message 001f in uppercase ASCII.

=== Periodic status ===
Sending message 0083 (no data) will trigger various periodic messages:
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
000a - (every second; 16-bit data)

The Nest client sends 0083 every 30 seconds, but at least the periodic temperature status will continue on for an hour before stopping.

=== Temperature reading ===
The backplate will send message 0002 every 30 seconds.
The data contains two 16-bit numbers, which nlclient logs in decimal.
The first number is the temperature in centi-celcius.
The second number is the humidity in per-millis.

See also: [[#"Buffers"|"Buffers"]]

=== Reset ===
At least upon connection, the display sends message 00ff to the backplate to reset.

The backplate answers with:
0001 msg "<version> <build timestamp "YYYY-MM-DD HH:MM:SS"> K"
[[#FET presence|0004 FET presence]]
[[#FET presence|0009 FET presence]]
0001 msg "*sense 06d1 06d0 0001 0001 0000 0000 0000 0001 06d9 06d8 06d8; detect 09d3 065c"
0001 msg "BRK"

== Run BeagleBone/Debian programs ==
ln -s . /lib/arm-linux-gnueabihf
ln -s ld-2.11.1.so /lib/ld-linux-armhf.so.3

Nest Hacking

2014-08-09T04:08:06Z

Luke-Jr: /* Backplate to display */

== Hardware ==

[https://www.ifixit.com/Teardown/Nest+Learning+Thermostat+2nd+Generation+Teardown/13818 Pictures]

=== Backplate ===
* ST Microelectronics STM32L151VB ultra-low-power 32 MHz ARM Cortex-M3 MCU
* Sensirion SHT20 humidity and temperature sensor
* Texas Instruments LW051A 8-channel CMOS analog multiplexer/demultiplexer

=== Display ===
* Texas Instruments AM3703CUS Sitara ARM Cortex A8 microprocessor
* Texas Instruments TPS65921B power management and USB single chip
* Samsung K4X51163PK 512 Mb mobile DRAM
* Ember EM357 integrated ZigBee/802.15.4 system-on-chip
* Micron MT29F2G16ABBEAH4 2 Gb NAND flash memory
* Skyworks 2436L high power 2.4 GHz 802.15.4 front-end module
* Texas Instruments WL1270B 802.11 b/g/n Wi-Fi solution
* Avago ADBM-A350 optical finger navigation module (knob movement sensor)

== Info ==
* /dev/event1 is the knob; /dev/event2 is the button
* /sys/class/hwmon/hwmon0/device/in0_battery_type * 0.003 is battery voltage
** Nest turns off wifi below 3.7 V, and waits until 3.8 V to automatically reconnect
* Display serial number is located in U-Boot environment variable "serial#"

== Nest software ==
/nestlabs/sbin/nlclient -config /nestlabs/etc/client.config -config /nestlabs/etc/Display/Display-2/client.config

=== Backplate communications ===
Backplate communications can be decoded from a (filtered) strace log using [http://luke.dashjr.org/programs/freeabode/kindling/NestDecode.pl NestDecode.pl], or decoded in real time using [http://luke.dashjr.org/programs/freeabode/kindling/nest-intercept.c nest-intercept.c].

nest-intercept.c requires one argument, the thread id reading from the backplate controller.
The easiest way to get this is to strace the nlclient process with -ff and look for a thread reading from fd 54.

Note that nest-intercept.c also has a "hack" variable which can be set to 0 (default is 2) in order to corrupt the TFE version response and trigger nlclient into uploading the firmware again.

=== Backplate firmware ===
Found in /nestlabs/share/bp/data/firmware/nlbpfirmware.plist

There are 12 different firmwares in the file:
* Test vs Production
* Backplate 2 vs Backplate 3
* TFE (BP_D2 for Bp2, AMBER_BP for Bp3) vs BSL
* For TFE firmwares, hex vs srec (which for some reason DO differ!)

Python script to extract them into individual files: [http://luke.dashjr.org/programs/freeabode/kindling/extract-fw.py extract-fw.py]

=== Backplate initialisation ===
When the backplate is first connected, the following sequence occurs:
tcflush(fd, TCIFLUSH)
Set baud to 115200 (-opost -isig -icanon -echo ...)
tcflush(fd, TCIOFLUSH)
tcsendbreak(fd, 1)
Send [[#Reset|00ff - Reset]]
Recv 0001 - (message from backplate; ASCII)
Recv [[#FET presence|0004 - FET presence]]
Recv [[#FET presence|0009 - FET presence]]
Send [[#FET presence|008f - FET presence]]
Send [[#Periodic status|0083 - Periodic status request]]
Send 0090 - get Mono/TFE id (no data; response 0010 with 3 bytes)
Recv 0001 - (message from backplate; ASCII)
Recv 0001 - (message from backplate; ASCII)
Recv 0010 - (24-bit data)
Send [[#Get Mono/TFE version|0098 - Get Mono/TFE version]]
Recv 000a - (every second; 16-bit data)
Recv 0007 - (every second; 16-bit data)
Recv [[#Get Mono/TFE version|0018 - Get Mono/TFE version (response)]]
Send [[#Get Mono/TFE build info|0099 - Get Mono/TFE build info]]
Recv [[#Get Mono/TFE build info|0019 - Get Mono/TFE build info (response)]]
Sometimes:
Send 009d - get BSL id (no data; responds with 001d)
Recv 001d - bsl id (response to 009d; 16-bit data)
Sometimes:
Send [[#Get BSL version|009b - Get BSL version]]
Recv [[#Get BSL version|001b - Get BSL version (response)]]
Sometimes:
Send 009c - get BSL info (no data; responds with 001c (constant?) data="BSL")
Recv 001c - Response to 009c; always(?) "BSL"
Send [[#Get serial number|009f - Get serial number]]
Recv [[#Get serial number|001f - Get serial number (response)]]
Send [[#Get hardware version|009e - Get hardware version]]
Recv [[#Get hardware version|001e - Get hardware version (response)]]

== Nest backplate interface ==
* Connected on /dev/ttyO2
* All communications with backplate begin with (d5)d5aa96 (d5 is doubled only for data FROM backplate)
* Everything is little endian
* 16-bit command
* 16-bit data length
* <data>
* 16-bit checksum

Monitor:
strace -ff -p $(pidof nlclient) -x -s9999 -e read,write 2>&1 | grep '(54'

NOTE: Most of this documentation is reverse engineered from firmware version BSL-2.1 and/or TFE_BP_D2-4.0.21 for Backplate-2.x.

=== Checksum ===
<Bytes-from-end>.<bit-value> <xor-with>
00.01 2110 (1021)
00.02 4220 (2042: 1021<<1)
00.04 8440 (4084: 2048<<1)
00.08 0881 (8108: 4084<<1)
00.10 3112 (1231: 8108<<1^1021)
00.20 6224 (2462: 1231<<1)
00.40 c448 (48c4: 2462<<1)
00.80 8891 (9188: 48c4<<1)
01.01 3133 (3313: 9188<<1^1021)
01.02 6266
01.04 c4cc
01.08 a989
01.10 7303
01.20 e606
01.40 cc0d
01.80 981b
02.01 3037
02.02 606e
...
03.01 b476
03.02 68ed
03.04 f1ca
03.08 c385
03.10 a71b
03.20 4e37
03.40 9c6e
03.80 38dd
...
07.20 687b

If you compute the contribution of the individual bit changes in the data you end up with the xor table above; byte offset from the end of the data, bit pattern, xor value. Correcting for little endianess in the output you end up with the hex values in parenthesis. The least significant bit is 0x1021 and each subsequent bit is a shift left, if the XOR value has the 0x8000 bit set then it is XORed with 0x1021. This is the CRC-CCITT polynomial.

8 7 6 5 4 3 2 1 0
d5 aa 96 82 00 02 00 00 00: 08b2
|| |
|| 68ed
|408b
20d4

08b2: 68ed ^ 408b ^ 20d4

Starting at the least significant bit and filling in the XOR values for each bit gives the above diagram; the diagram stops at the 20d4 XOR value because at that point it matches the final CRC. This tells us that the CRC covers the 6 bytes prior.

#!/usr/bin/env perl
use Digest::CRC qw(crc);
my $data = pack("H*", "820002000000");
printf("%04x\n", crc($data,16,0,0,0,0x1021,0,0));

We can also compute the same CRC in Perl; note the result will be byte swapped since the data encodes the number as little endian.

=== Command ids ===

==== Display to backplate ====
[[#FET control|0082 - FET control]]
[[#Periodic status|0083 - Periodic status request]]
[[#FET presence|008f - FET presence]]
0090 - get Mono/TFE id (no data; response 0010 with 3 bytes)
[[#Backplate firmware upload|0091 - Backplate firmware upload (start)]]
[[#Backplate firmware upload|0092 - Backplate firmware upload]]
[[#Backplate firmware upload|0093 - Backplate firmware upload (finish)]]
[[#Get Mono/TFE version|0098 - Get Mono/TFE version]]
[[#Get Mono/TFE build info|0099 - Get Mono/TFE build info]]
[[#Get BSL version|009b - Get BSL version]]
009c - get BSL info (no data; responds with 001c (constant?) data="BSL")
009d - get BSL id (no data; responds with 001d)
[[#Get hardware version|009e - Get hardware version]]
[[#Get serial number|009f - Get serial number]]
00a1 - quiet (16-bit max sleep seconds)
[[#"Buffers"|00a2 - Request "buffers" (every 30 seconds; no data; triggers [0025] [0027] 0022 0023 [0029] [002b] 000c 002f)]]
[[#"Buffers"|00a3 - ACK to 002f (no data)]]
00a4 - set wakeup mask (16-bit data)
00b1 - "temperature lock" (sent when button pressed/unpressed; no data)
00b3 - set humidity thresholds (32-bit data)
00b5 - set near pir threshold (16-bit data)
00b7 - set pir thresholds (??? data)
00b8 - set proximity thresholds (??? data)
00b9 - set als thresholds (32-bit data)
00ba - set vergence mode (48-bit data)
00c2 - set wakeup temperatures (48-bit data)
00c3 - set temp comp mode request (??? data)
[[#Reset|00ff - Reset]]

==== Backplate to display ====
0001 - (message from backplate; ASCII)
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
[[#FET presence|0004 - FET presence]]
0005 - (32-bit data)
0006 - ?
0007 - (every second; 16-bit data)
0008 - ?
[[#FET presence|0009 - FET presence]]
000a - (every second; 2x(?) 16-bit data)
[[#Backplate state|000b - Backplate state]]
000c - (16-bit values: pir, px1, px1 divisor, px2, px2 divisor, alir, av; included in [[#"Buffers"|"buffers" data]])
000e - ?
0010 - (24-bit data)
[[#Backplate firmware upload|0011 - Backplate firmware upload (ACK)]]
0012 - ?
0013 - ?
0014 - "WakeVector" (16-bit data)
[[#Get Mono/TFE version|0018 - Get Mono/TFE version (response)]]
[[#Get Mono/TFE build info|0019 - Get Mono/TFE build info (response)]]
[[#Get BSL version|001b - Get BSL version (response)]]
001c - Response to 009c; always(?) "BSL"
001d - bsl id (response to 009d; 16-bit data)
[[#Get hardware version|001e - Get hardware version (response)]]
[[#Get serial number|001f - Get serial number (response)]]
[[#"Buffers"|0022 - buffered temperature reading (possibly multiple times)]]
[[#"Buffers"|0023 - BufferedSourceTemperature (3x 16-bit data; possibly multiple times)]]
[[#"Buffers"|0025 - BufferedNearPir (16-bit data; possibly multiple times)]]
[[#"Buffers"|0027 - BufferedPassiveInfrared (64-bit data; possibly multiple times)]]
[[#"Buffers"|0029 - BufferedAmbientLightSensor (48-bit data; likely 3x 16-bit; possibly multiple times)]]
[[#"Buffers"|002b - BufferedPowerData (64-bit data; possibly multiple times)]]
[[#"Buffers"|002f - End of "buffers" (16-bit data)]]

=== Backplate firmware upload ===
For uploading the firmware, the following sequence is used:
Send 0091 data=0000<firmware type>
Recv 0011 data=0000
Send 0092 data=0100...
Recv 0011 data=0100
Send 0092 data=0200...
Recv 0011 data=0200
...
Send 0092 data=a901...
Recv 0011 data=a901
Send 0093 data=aa01
Recv 0011 data=aa01
Following the upload, the [[#Backplate initialisation|backplate initialisation process]] begins immediately (that is, without message 00ff being sent to order a reset).
Presumably the 0011 message is an ACK, and the first 16 bits of each message is the line number.
The format itself appears to be Motorola S-record (SREC).
Uploading the BSL firmware was followed by the TFE firmware, so it may be required (though uploading the TFE firmware does ''not'' require uploading the BSL).

Firmware type is either 4d for TFE or 42 for BSL.

=== Backplate state ===
Data:
* 8-bit "state"
* 8-bit "flags"
* 8-bit "px0" (may be wider?)
* 40-bit UNKNOWN (includes at least "p2" and "voc")
* 16-bit centi-volts "vi"
* 16-bit milli-volts "vo"
* 16-bit milli-volts "vb"
* 8-bit ("pins" or "wires")
* 8-bit ("wires" or "pins")
* 16-bit UNKNOWN

=== "Buffers" ===
The 00a2 message requests the backplate send the contents of various "buffers", which are returned in messages [0025], [0027], 0022, 0023, [0029], and [002b] (empty ones will NOT be sent; brackets infer commonly-empty buffers).
00a2 also triggers 000c immediately following these.
After all the buffers (including 000c) have been sent, the message 002f indicates "end of buffers".
The display is then expected to acknowledge it with message 00a3.

Buffers:
[[#Temperature reading|0022 - Temperature reading]]
0023 - BufferedSourceTemperature (not sure what that means)
0025 - BufferedNearPir
0027 - BufferedPassiveInfrared
0029 - BufferedAmbientLightSensor
002b - BufferedPowerData

=== FET control ===
Turn on W1: d5aa96 8200 0200 00 01 29a2
Turn off W1: d5aa96 8200 0200 00 00 08b2
Turn on Y1: d5aa96 8200 0200 01 01 1891
Turn off Y1: d5aa96 8200 0200 01 00 3981
Turn on G : d5aa96 8200 0200 02 01 4bc4
Turn off G : d5aa96 8200 0200 02 00 6ad4
Turn on OB: d5aa96 8200 0200 03 01 7af7
Turn off OB: d5aa96 8200 0200 03 00 5be7
Turn on W2: d5aa96 8200 0200 04 01 ed6e
Turn off W2: d5aa96 8200 0200 04 00 cc7e
Turn on Y2: d5aa96 8200 0200 07 01 be3b
Turn off Y2: d5aa96 8200 0200 07 00 9f2b
Turn on * : d5aa96 8200 0200 0b 01 d37e
Turn off * : d5aa96 8200 0200 0b 00 f26e

For the sake of documentation, we will refer to the unique id numbers for each wire as "wire id numbers".
So wire id 0 is W1, wire id 1 is Y1, wire id B is *, etc.

=== FET presence ===
The backplate will, at least upon connection, send information about which FETs have a wire present.
This data is received with command ids 0004 and 0009, in that order.
Each sensor is represented by one byte which is either 00 (not present) or 01 (present).

The content of 0004 is in order of the "wire id numbers" used for control:
W1, Y1, G, OB, W2, ?0, ?0, Y2, C, RC, ?0, *, ?0

The content of 0009 is arranged differently and has 2 more values:
W1, Y1, C, RC, ?0, G, OB, W2, ?0, Y2, ?0, *, ?0, ?0, ?0

0009 seems to indicate a wire is physically plugged in, while 0004 indicates that it is connected to something (?).

After these are received, the display sends back command 008f with the exact data from message 0004.
Message 008f does not itself receive any response.

In a power outage condition, 0004 will report all absent (including unknown ones), whereas 0009 will continue to report the same as when power is available.

=== Get Mono/TFE build info ===
Message 0099 (no data) requests the backplate report information about its build.
The response will be message 0019 in ASCII (one line, no trailing newline).

=== Get hardware version ===
Message 009e (no data) requests the backplate report a "Backplate-"X.Y version string.
Since the firmware file on the display CPU uses these strings as "MinApplicability" and "MaxApplicability" ranges, it is probable they refer to the hardware.

Witnessed versions:
"Backplate-2.8" - Florida Lowes

=== Get BSL version ===
Message 009b (no data) requests the backplate report its BSL version number.
The response will be message 001b in ASCII.

=== Get Mono/TFE version ===
Message 0098 (no data) requests the backplate report its TFE version number.
The response will be message 0018 in ASCII.

=== Get serial number ===
Message 009f (no data) requests the backplate report its serial number (a 64-bit hexadecimal value).
The response will be message 001f in uppercase ASCII.

=== Periodic status ===
Sending message 0083 (no data) will trigger various periodic messages:
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
000a - (every second; 16-bit data)

The Nest client sends 0083 every 30 seconds, but at least the periodic temperature status will continue on for an hour before stopping.

=== Temperature reading ===
The backplate will send message 0002 every 30 seconds.
The data contains two 16-bit numbers, which nlclient logs in decimal.
The first number is the temperature in centi-celcius.
The second number is the humidity in per-millis.

See also: [[#"Buffers"|"Buffers"]]

=== Reset ===
At least upon connection, the display sends message 00ff to the backplate to reset.

The backplate answers with:
0001 msg "<version> <build timestamp "YYYY-MM-DD HH:MM:SS"> K"
[[#FET presence|0004 FET presence]]
[[#FET presence|0009 FET presence]]
0001 msg "*sense 06d1 06d0 0001 0001 0000 0000 0000 0001 06d9 06d8 06d8; detect 09d3 065c"
0001 msg "BRK"

== Run BeagleBone/Debian programs ==
ln -s . /lib/arm-linux-gnueabihf
ln -s ld-2.11.1.so /lib/ld-linux-armhf.so.3

Nest Hacking

2014-08-08T21:16:00Z

Luke-Jr:

== Hardware ==

[https://www.ifixit.com/Teardown/Nest+Learning+Thermostat+2nd+Generation+Teardown/13818 Pictures]

=== Backplate ===
* ST Microelectronics STM32L151VB ultra-low-power 32 MHz ARM Cortex-M3 MCU
* Sensirion SHT20 humidity and temperature sensor
* Texas Instruments LW051A 8-channel CMOS analog multiplexer/demultiplexer

=== Display ===
* Texas Instruments AM3703CUS Sitara ARM Cortex A8 microprocessor
* Texas Instruments TPS65921B power management and USB single chip
* Samsung K4X51163PK 512 Mb mobile DRAM
* Ember EM357 integrated ZigBee/802.15.4 system-on-chip
* Micron MT29F2G16ABBEAH4 2 Gb NAND flash memory
* Skyworks 2436L high power 2.4 GHz 802.15.4 front-end module
* Texas Instruments WL1270B 802.11 b/g/n Wi-Fi solution
* Avago ADBM-A350 optical finger navigation module (knob movement sensor)

== Info ==
* /dev/event1 is the knob; /dev/event2 is the button
* /sys/class/hwmon/hwmon0/device/in0_battery_type * 0.003 is battery voltage
** Nest turns off wifi below 3.7 V, and waits until 3.8 V to automatically reconnect
* Display serial number is located in U-Boot environment variable "serial#"

== Nest software ==
/nestlabs/sbin/nlclient -config /nestlabs/etc/client.config -config /nestlabs/etc/Display/Display-2/client.config

=== Backplate communications ===
Backplate communications can be decoded from a (filtered) strace log using [http://luke.dashjr.org/programs/freeabode/kindling/NestDecode.pl NestDecode.pl], or decoded in real time using [http://luke.dashjr.org/programs/freeabode/kindling/nest-intercept.c nest-intercept.c].

nest-intercept.c requires one argument, the thread id reading from the backplate controller.
The easiest way to get this is to strace the nlclient process with -ff and look for a thread reading from fd 54.

Note that nest-intercept.c also has a "hack" variable which can be set to 0 (default is 2) in order to corrupt the TFE version response and trigger nlclient into uploading the firmware again.

=== Backplate firmware ===
Found in /nestlabs/share/bp/data/firmware/nlbpfirmware.plist

There are 12 different firmwares in the file:
* Test vs Production
* Backplate 2 vs Backplate 3
* TFE (BP_D2 for Bp2, AMBER_BP for Bp3) vs BSL
* For TFE firmwares, hex vs srec (which for some reason DO differ!)

Python script to extract them into individual files: [http://luke.dashjr.org/programs/freeabode/kindling/extract-fw.py extract-fw.py]

=== Backplate initialisation ===
When the backplate is first connected, the following sequence occurs:
tcflush(fd, TCIFLUSH)
Set baud to 115200 (-opost -isig -icanon -echo ...)
tcflush(fd, TCIOFLUSH)
tcsendbreak(fd, 1)
Send [[#Reset|00ff - Reset]]
Recv 0001 - (message from backplate; ASCII)
Recv [[#FET presence|0004 - FET presence]]
Recv [[#FET presence|0009 - FET presence]]
Send [[#FET presence|008f - FET presence]]
Send [[#Periodic status|0083 - Periodic status request]]
Send 0090 - get Mono/TFE id (no data; response 0010 with 3 bytes)
Recv 0001 - (message from backplate; ASCII)
Recv 0001 - (message from backplate; ASCII)
Recv 0010 - (24-bit data)
Send [[#Get Mono/TFE version|0098 - Get Mono/TFE version]]
Recv 000a - (every second; 16-bit data)
Recv 0007 - (every second; 16-bit data)
Recv [[#Get Mono/TFE version|0018 - Get Mono/TFE version (response)]]
Send [[#Get Mono/TFE build info|0099 - Get Mono/TFE build info]]
Recv [[#Get Mono/TFE build info|0019 - Get Mono/TFE build info (response)]]
Sometimes:
Send 009d - get BSL id (no data; responds with 001d)
Recv 001d - bsl id (response to 009d; 16-bit data)
Sometimes:
Send [[#Get BSL version|009b - Get BSL version]]
Recv [[#Get BSL version|001b - Get BSL version (response)]]
Sometimes:
Send 009c - get BSL info (no data; responds with 001c (constant?) data="BSL")
Recv 001c - Response to 009c; always(?) "BSL"
Send [[#Get serial number|009f - Get serial number]]
Recv [[#Get serial number|001f - Get serial number (response)]]
Send [[#Get hardware version|009e - Get hardware version]]
Recv [[#Get hardware version|001e - Get hardware version (response)]]

== Nest backplate interface ==
* Connected on /dev/ttyO2
* All communications with backplate begin with (d5)d5aa96 (d5 is doubled only for data FROM backplate)
* Everything is little endian
* 16-bit command
* 16-bit data length
* <data>
* 16-bit checksum

Monitor:
strace -ff -p $(pidof nlclient) -x -s9999 -e read,write 2>&1 | grep '(54'

NOTE: Most of this documentation is reverse engineered from firmware version BSL-2.1 and/or TFE_BP_D2-4.0.21 for Backplate-2.x.

=== Checksum ===
<Bytes-from-end>.<bit-value> <xor-with>
00.01 2110 (1021)
00.02 4220 (2042: 1021<<1)
00.04 8440 (4084: 2048<<1)
00.08 0881 (8108: 4084<<1)
00.10 3112 (1231: 8108<<1^1021)
00.20 6224 (2462: 1231<<1)
00.40 c448 (48c4: 2462<<1)
00.80 8891 (9188: 48c4<<1)
01.01 3133 (3313: 9188<<1^1021)
01.02 6266
01.04 c4cc
01.08 a989
01.10 7303
01.20 e606
01.40 cc0d
01.80 981b
02.01 3037
02.02 606e
...
03.01 b476
03.02 68ed
03.04 f1ca
03.08 c385
03.10 a71b
03.20 4e37
03.40 9c6e
03.80 38dd
...
07.20 687b

If you compute the contribution of the individual bit changes in the data you end up with the xor table above; byte offset from the end of the data, bit pattern, xor value. Correcting for little endianess in the output you end up with the hex values in parenthesis. The least significant bit is 0x1021 and each subsequent bit is a shift left, if the XOR value has the 0x8000 bit set then it is XORed with 0x1021. This is the CRC-CCITT polynomial.

8 7 6 5 4 3 2 1 0
d5 aa 96 82 00 02 00 00 00: 08b2
|| |
|| 68ed
|408b
20d4

08b2: 68ed ^ 408b ^ 20d4

Starting at the least significant bit and filling in the XOR values for each bit gives the above diagram; the diagram stops at the 20d4 XOR value because at that point it matches the final CRC. This tells us that the CRC covers the 6 bytes prior.

#!/usr/bin/env perl
use Digest::CRC qw(crc);
my $data = pack("H*", "820002000000");
printf("%04x\n", crc($data,16,0,0,0,0x1021,0,0));

We can also compute the same CRC in Perl; note the result will be byte swapped since the data encodes the number as little endian.

=== Command ids ===

==== Display to backplate ====
[[#FET control|0082 - FET control]]
[[#Periodic status|0083 - Periodic status request]]
[[#FET presence|008f - FET presence]]
0090 - get Mono/TFE id (no data; response 0010 with 3 bytes)
[[#Backplate firmware upload|0091 - Backplate firmware upload (start)]]
[[#Backplate firmware upload|0092 - Backplate firmware upload]]
[[#Backplate firmware upload|0093 - Backplate firmware upload (finish)]]
[[#Get Mono/TFE version|0098 - Get Mono/TFE version]]
[[#Get Mono/TFE build info|0099 - Get Mono/TFE build info]]
[[#Get BSL version|009b - Get BSL version]]
009c - get BSL info (no data; responds with 001c (constant?) data="BSL")
009d - get BSL id (no data; responds with 001d)
[[#Get hardware version|009e - Get hardware version]]
[[#Get serial number|009f - Get serial number]]
00a1 - quiet (16-bit max sleep seconds)
[[#"Buffers"|00a2 - Request "buffers" (every 30 seconds; no data; triggers [0025] [0027] 0022 0023 [0029] [002b] 000c 002f)]]
[[#"Buffers"|00a3 - ACK to 002f (no data)]]
00a4 - set wakeup mask (16-bit data)
00b1 - "temperature lock" (sent when button pressed/unpressed; no data)
00b3 - set humidity thresholds (32-bit data)
00b5 - set near pir threshold (16-bit data)
00b7 - set pir thresholds (??? data)
00b8 - set proximity thresholds (??? data)
00b9 - set als thresholds (32-bit data)
00ba - set vergence mode (48-bit data)
00c2 - set wakeup temperatures (48-bit data)
00c3 - set temp comp mode request (??? data)
[[#Reset|00ff - Reset]]

==== Backplate to display ====
0001 - (message from backplate; ASCII)
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
[[#FET presence|0004 - FET presence]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
[[#FET presence|0009 - FET presence]]
000a - (every second; 2x(?) 16-bit data)
[[#Backplate state|000b - Backplate state]]
000c - (16-bit values: pir, px1, px1 divisor, px2, px2 divisor, alir, av; included in [[#"Buffers"|"buffers" data]])
0010 - (24-bit data)
[[#Backplate firmware upload|0011 - Backplate firmware upload (ACK)]]
0014 - "WakeVector" (16-bit data)
[[#Get Mono/TFE version|0018 - Get Mono/TFE version (response)]]
[[#Get Mono/TFE build info|0019 - Get Mono/TFE build info (response)]]
[[#Get BSL version|001b - Get BSL version (response)]]
001c - Response to 009c; always(?) "BSL"
001d - bsl id (response to 009d; 16-bit data)
[[#Get hardware version|001e - Get hardware version (response)]]
[[#Get serial number|001f - Get serial number (response)]]
[[#"Buffers"|0022 - buffered temperature reading (possibly multiple times)]]
[[#"Buffers"|0023 - BufferedSourceTemperature (3x 16-bit data; possibly multiple times)]]
[[#"Buffers"|0025 - BufferedNearPir (16-bit data; possibly multiple times)]]
[[#"Buffers"|0027 - BufferedPassiveInfrared (64-bit data; possibly multiple times)]]
[[#"Buffers"|0029 - BufferedAmbientLightSensor (48-bit data; likely 3x 16-bit; possibly multiple times)]]
[[#"Buffers"|002b - BufferedPowerData (64-bit data; possibly multiple times)]]
[[#"Buffers"|002f - End of "buffers" (16-bit data)]]

=== Backplate firmware upload ===
For uploading the firmware, the following sequence is used:
Send 0091 data=0000<firmware type>
Recv 0011 data=0000
Send 0092 data=0100...
Recv 0011 data=0100
Send 0092 data=0200...
Recv 0011 data=0200
...
Send 0092 data=a901...
Recv 0011 data=a901
Send 0093 data=aa01
Recv 0011 data=aa01
Following the upload, the [[#Backplate initialisation|backplate initialisation process]] begins immediately (that is, without message 00ff being sent to order a reset).
Presumably the 0011 message is an ACK, and the first 16 bits of each message is the line number.
The format itself appears to be Motorola S-record (SREC).
Uploading the BSL firmware was followed by the TFE firmware, so it may be required (though uploading the TFE firmware does ''not'' require uploading the BSL).

Firmware type is either 4d for TFE or 42 for BSL.

=== Backplate state ===
Data:
* 8-bit "state"
* 8-bit "flags"
* 8-bit "px0" (may be wider?)
* 40-bit UNKNOWN (includes at least "p2" and "voc")
* 16-bit centi-volts "vi"
* 16-bit milli-volts "vo"
* 16-bit milli-volts "vb"
* 8-bit ("pins" or "wires")
* 8-bit ("wires" or "pins")
* 16-bit UNKNOWN

=== "Buffers" ===
The 00a2 message requests the backplate send the contents of various "buffers", which are returned in messages [0025], [0027], 0022, 0023, [0029], and [002b] (empty ones will NOT be sent; brackets infer commonly-empty buffers).
00a2 also triggers 000c immediately following these.
After all the buffers (including 000c) have been sent, the message 002f indicates "end of buffers".
The display is then expected to acknowledge it with message 00a3.

Buffers:
[[#Temperature reading|0022 - Temperature reading]]
0023 - BufferedSourceTemperature (not sure what that means)
0025 - BufferedNearPir
0027 - BufferedPassiveInfrared
0029 - BufferedAmbientLightSensor
002b - BufferedPowerData

=== FET control ===
Turn on W1: d5aa96 8200 0200 00 01 29a2
Turn off W1: d5aa96 8200 0200 00 00 08b2
Turn on Y1: d5aa96 8200 0200 01 01 1891
Turn off Y1: d5aa96 8200 0200 01 00 3981
Turn on G : d5aa96 8200 0200 02 01 4bc4
Turn off G : d5aa96 8200 0200 02 00 6ad4
Turn on OB: d5aa96 8200 0200 03 01 7af7
Turn off OB: d5aa96 8200 0200 03 00 5be7
Turn on W2: d5aa96 8200 0200 04 01 ed6e
Turn off W2: d5aa96 8200 0200 04 00 cc7e
Turn on Y2: d5aa96 8200 0200 07 01 be3b
Turn off Y2: d5aa96 8200 0200 07 00 9f2b
Turn on * : d5aa96 8200 0200 0b 01 d37e
Turn off * : d5aa96 8200 0200 0b 00 f26e

For the sake of documentation, we will refer to the unique id numbers for each wire as "wire id numbers".
So wire id 0 is W1, wire id 1 is Y1, wire id B is *, etc.

=== FET presence ===
The backplate will, at least upon connection, send information about which FETs have a wire present.
This data is received with command ids 0004 and 0009, in that order.
Each sensor is represented by one byte which is either 00 (not present) or 01 (present).

The content of 0004 is in order of the "wire id numbers" used for control:
W1, Y1, G, OB, W2, ?0, ?0, Y2, C, RC, ?0, *, ?0

The content of 0009 is arranged differently and has 2 more values:
W1, Y1, C, RC, ?0, G, OB, W2, ?0, Y2, ?0, *, ?0, ?0, ?0

0009 seems to indicate a wire is physically plugged in, while 0004 indicates that it is connected to something (?).

After these are received, the display sends back command 008f with the exact data from message 0004.
Message 008f does not itself receive any response.

In a power outage condition, 0004 will report all absent (including unknown ones), whereas 0009 will continue to report the same as when power is available.

=== Get Mono/TFE build info ===
Message 0099 (no data) requests the backplate report information about its build.
The response will be message 0019 in ASCII (one line, no trailing newline).

=== Get hardware version ===
Message 009e (no data) requests the backplate report a "Backplate-"X.Y version string.
Since the firmware file on the display CPU uses these strings as "MinApplicability" and "MaxApplicability" ranges, it is probable they refer to the hardware.

Witnessed versions:
"Backplate-2.8" - Florida Lowes

=== Get BSL version ===
Message 009b (no data) requests the backplate report its BSL version number.
The response will be message 001b in ASCII.

=== Get Mono/TFE version ===
Message 0098 (no data) requests the backplate report its TFE version number.
The response will be message 0018 in ASCII.

=== Get serial number ===
Message 009f (no data) requests the backplate report its serial number (a 64-bit hexadecimal value).
The response will be message 001f in uppercase ASCII.

=== Periodic status ===
Sending message 0083 (no data) will trigger various periodic messages:
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
000a - (every second; 16-bit data)

The Nest client sends 0083 every 30 seconds, but at least the periodic temperature status will continue on for an hour before stopping.

=== Temperature reading ===
The backplate will send message 0002 every 30 seconds.
The data contains two 16-bit numbers, which nlclient logs in decimal.
The first number is the temperature in centi-celcius.
The second number is the humidity in per-millis.

See also: [[#"Buffers"|"Buffers"]]

=== Reset ===
At least upon connection, the display sends message 00ff to the backplate to reset.

The backplate answers with:
0001 msg "<version> <build timestamp "YYYY-MM-DD HH:MM:SS"> K"
[[#FET presence|0004 FET presence]]
[[#FET presence|0009 FET presence]]
0001 msg "*sense 06d1 06d0 0001 0001 0000 0000 0000 0001 06d9 06d8 06d8; detect 09d3 065c"
0001 msg "BRK"

== Run BeagleBone/Debian programs ==
ln -s . /lib/arm-linux-gnueabihf
ln -s ld-2.11.1.so /lib/ld-linux-armhf.so.3

Nest Hacking

2014-08-08T20:48:17Z

Luke-Jr:

== Hardware ==

[https://www.ifixit.com/Teardown/Nest+Learning+Thermostat+2nd+Generation+Teardown/13818 Pictures]

=== Backplate ===
* ST Microelectronics STM32L151VB ultra-low-power 32 MHz ARM Cortex-M3 MCU
* Sensirion SHT20 humidity and temperature sensor
* Texas Instruments LW051A 8-channel CMOS analog multiplexer/demultiplexer

=== Display ===
* Texas Instruments AM3703CUS Sitara ARM Cortex A8 microprocessor
* Texas Instruments TPS65921B power management and USB single chip
* Samsung K4X51163PK 512 Mb mobile DRAM
* Ember EM357 integrated ZigBee/802.15.4 system-on-chip
* Micron MT29F2G16ABBEAH4 2 Gb NAND flash memory
* Skyworks 2436L high power 2.4 GHz 802.15.4 front-end module
* Texas Instruments WL1270B 802.11 b/g/n Wi-Fi solution
* Avago ADBM-A350 optical finger navigation module (knob movement sensor)

== Info ==
* /dev/event1 is the knob; /dev/event2 is the button
* /sys/class/hwmon/hwmon0/device/in0_battery_type * 0.003 is battery voltage
** Nest turns off wifi below 3.7 V, and waits until 3.8 V to automatically reconnect
* Display serial number is located in U-Boot environment variable "serial#"

== Nest software ==
/nestlabs/sbin/nlclient -config /nestlabs/etc/client.config -config /nestlabs/etc/Display/Display-2/client.config

=== Backplate communications ===
Backplate communications can be decoded from a (filtered) strace log using [http://luke.dashjr.org/programs/freeabode/kindling/NestDecode.pl NestDecode.pl], or decoded in real time using [http://luke.dashjr.org/programs/freeabode/kindling/nest-intercept.c nest-intercept.c].

nest-intercept.c requires one argument, the thread id reading from the backplate controller.
The easiest way to get this is to strace the nlclient process with -ff and look for a thread reading from fd 54.

Note that nest-intercept.c also has a "hack" variable which can be set to 0 (default is 2) in order to corrupt the TFE version response and trigger nlclient into uploading the firmware again.

=== Backplate firmware ===
Found in /nestlabs/share/bp/data/firmware/nlbpfirmware.plist

There are 12 different firmwares in the file:
* Test vs Production
* Backplate 2 vs Backplate 3
* TFE (BP_D2 for Bp2, AMBER_BP for Bp3) vs BSL
* For TFE firmwares, hex vs srec (which for some reason DO differ!)

Python script to extract them into individual files: [http://luke.dashjr.org/programs/freeabode/kindling/extract-fw.py extract-fw.py]

=== Backplate initialisation ===
When the backplate is first connected, the following sequence occurs:
tcflush(fd, TCIFLUSH)
Set baud to 115200 (-opost -isig -icanon -echo ...)
tcflush(fd, TCIOFLUSH)
tcsendbreak(fd, 1)
Send [[#Reset|00ff - Reset]]
Recv 0001 - (message from backplate; ASCII)
Recv [[#FET presence|0004 - FET presence]]
Recv [[#FET presence|0009 - FET presence]]
Send [[#FET presence|008f - FET presence]]
Send [[#Periodic status|0083 - Periodic status request]]
Send 0090 - get mono id (no data; response 0010 with 3 bytes)
Recv 0001 - (message from backplate; ASCII)
Recv 0001 - (message from backplate; ASCII)
Recv 0010 - (24-bit data)
Send [[#Get TFE version|0098 - Get TFE version]]
Recv 000a - (every second; 16-bit data)
Recv 0007 - (every second; 16-bit data)
Recv [[#Get TFE version|0018 - Get TFE version (response)]]
Send [[#Get build info|0099 - Get build info]]
Recv [[#Get build info|0019 - Get build info (response)]]
Sometimes:
Send 009d - get bsl id (no data; responds with 001d)
Recv 001d - bsl id (response to 009d; 16-bit data)
Sometimes:
Send [[#Get BSL version|009b - Get BSL version]]
Recv [[#Get BSL version|001b - Get BSL version (response)]]
Sometimes:
Send 009c - (no data; responds with 001c (constant?) data="BSL")
Recv 001c - Response to 009c; always(?) "BSL"
Send [[#Get serial number|009f - Get serial number]]
Recv [[#Get serial number|001f - Get serial number (response)]]
Send [[#Get hardware version?|009e - Get hardware version?]]
Recv [[#Get hardware version?|001e - Get hardware version? (response)]]

== Nest backplate interface ==
* Connected on /dev/ttyO2
* All communications with backplate begin with (d5)d5aa96 (d5 is doubled only for data FROM backplate)
* Everything is little endian
* 16-bit command
* 16-bit data length
* <data>
* 16-bit checksum

Monitor:
strace -ff -p $(pidof nlclient) -x -s9999 -e read,write 2>&1 | grep '(54'

NOTE: Most of this documentation is reverse engineered from firmware version BSL-2.1 and/or TFE_BP_D2-4.0.21 for Backplate-2.x.

=== Checksum ===
<Bytes-from-end>.<bit-value> <xor-with>
00.01 2110 (1021)
00.02 4220 (2042: 1021<<1)
00.04 8440 (4084: 2048<<1)
00.08 0881 (8108: 4084<<1)
00.10 3112 (1231: 8108<<1^1021)
00.20 6224 (2462: 1231<<1)
00.40 c448 (48c4: 2462<<1)
00.80 8891 (9188: 48c4<<1)
01.01 3133 (3313: 9188<<1^1021)
01.02 6266
01.04 c4cc
01.08 a989
01.10 7303
01.20 e606
01.40 cc0d
01.80 981b
02.01 3037
02.02 606e
...
03.01 b476
03.02 68ed
03.04 f1ca
03.08 c385
03.10 a71b
03.20 4e37
03.40 9c6e
03.80 38dd
...
07.20 687b

If you compute the contribution of the individual bit changes in the data you end up with the xor table above; byte offset from the end of the data, bit pattern, xor value. Correcting for little endianess in the output you end up with the hex values in parenthesis. The least significant bit is 0x1021 and each subsequent bit is a shift left, if the XOR value has the 0x8000 bit set then it is XORed with 0x1021. This is the CRC-CCITT polynomial.

8 7 6 5 4 3 2 1 0
d5 aa 96 82 00 02 00 00 00: 08b2
|| |
|| 68ed
|408b
20d4

08b2: 68ed ^ 408b ^ 20d4

Starting at the least significant bit and filling in the XOR values for each bit gives the above diagram; the diagram stops at the 20d4 XOR value because at that point it matches the final CRC. This tells us that the CRC covers the 6 bytes prior.

#!/usr/bin/env perl
use Digest::CRC qw(crc);
my $data = pack("H*", "820002000000");
printf("%04x\n", crc($data,16,0,0,0,0x1021,0,0));

We can also compute the same CRC in Perl; note the result will be byte swapped since the data encodes the number as little endian.

=== Command ids ===

==== Display to backplate ====
[[#FET control|0082 - FET control]]
[[#Periodic status|0083 - Periodic status request]]
[[#FET presence|008f - FET presence]]
0090 - get mono id (no data; response 0010 with 3 bytes)
[[#Backplate firmware upload|0091 - Backplate firmware upload (start)]]
[[#Backplate firmware upload|0092 - Backplate firmware upload]]
[[#Backplate firmware upload|0093 - Backplate firmware upload (finish)]]
[[#Get TFE version|0098 - Get TFE version]]
[[#Get build info|0099 - Get build info]]
[[#Get BSL version|009b - Get BSL version]]
009c - (no data; responds with 001c (constant?) data="BSL")
009d - get bsl id (no data; responds with 001d)
[[#Get hardware version?|009e - Get hardware version?]]
[[#Get serial number|009f - Get serial number]]
00a1 - quiet (16-bit max sleep seconds)
[[#"Buffers"|00a2 - Request "buffers" (every 30 seconds; no data; triggers [0025] [0027] 0022 0023 [0029] [002b] 000c 002f)]]
[[#"Buffers"|00a3 - ACK to 002f (no data)]]
00a4 - set wakeup mask (16-bit data)
00b1 - button pressed/unpressed (no data)
00b3 - set humidity thresholds (32-bit data)
00b5 - set near pir threshold (16-bit data)
00b9 - set als thresholds (32-bit data)
00ba - set vergence mode (48-bit data)
00c2 - (48-bit data)
[[#Reset|00ff - Reset]]

==== Backplate to display ====
0001 - (message from backplate; ASCII)
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
[[#FET presence|0004 - FET presence]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
[[#FET presence|0009 - FET presence]]
000a - (every second; 2x(?) 16-bit data)
[[#Backplate state|000b - Backplate state]]
000c - (16-bit values: pir, px1, px1 divisor, px2, px2 divisor, alir, av; included in [[#"Buffers"|"buffers" data]])
0010 - (24-bit data)
[[#Backplate firmware upload|0011 - Backplate firmware upload (ACK)]]
0014 - "WakeVector" (16-bit data)
[[#Get TFE version|0018 - Get TFE version (response)]]
[[#Get build info|0019 - Get build info (response)]]
[[#Get BSL version|001b - Get BSL version (response)]]
001c - Response to 009c; always(?) "BSL"
001d - bsl id (response to 009d; 16-bit data)
[[#Get hardware version?|001e - Get hardware version? (response)]]
[[#Get serial number|001f - Get serial number (response)]]
[[#"Buffers"|0022 - buffered temperature reading (possibly multiple times)]]
[[#"Buffers"|0023 - BufferedSourceTemperature (3x 16-bit data; possibly multiple times)]]
[[#"Buffers"|0025 - BufferedNearPir (16-bit data; possibly multiple times)]]
[[#"Buffers"|0027 - BufferedPassiveInfrared (64-bit data; possibly multiple times)]]
[[#"Buffers"|0029 - BufferedAmbientLightSensor (48-bit data; likely 3x 16-bit; possibly multiple times)]]
[[#"Buffers"|002b - BufferedPowerData (64-bit data; possibly multiple times)]]
[[#"Buffers"|002f - End of "buffers" (16-bit data)]]

=== Backplate firmware upload ===
For uploading the firmware, the following sequence is used:
Send 0091 data=0000<firmware type>
Recv 0011 data=0000
Send 0092 data=0100...
Recv 0011 data=0100
Send 0092 data=0200...
Recv 0011 data=0200
...
Send 0092 data=a901...
Recv 0011 data=a901
Send 0093 data=aa01
Recv 0011 data=aa01
Following the upload, the [[#Backplate initialisation|backplate initialisation process]] begins immediately (that is, without message 00ff being sent to order a reset).
Presumably the 0011 message is an ACK, and the first 16 bits of each message is the line number.
The format itself appears to be Motorola S-record (SREC).
Uploading the BSL firmware was followed by the TFE firmware, so it may be required (though uploading the TFE firmware does ''not'' require uploading the BSL).

Firmware type is either 4d for TFE or 42 for BSL.

=== Backplate state ===
Data:
* 8-bit "state"
* 8-bit "flags"
* 8-bit "px0" (may be wider?)
* 40-bit UNKNOWN (includes at least "p2" and "voc")
* 16-bit centi-volts "vi"
* 16-bit milli-volts "vo"
* 16-bit milli-volts "vb"
* 8-bit ("pins" or "wires")
* 8-bit ("wires" or "pins")
* 16-bit UNKNOWN

=== "Buffers" ===
The 00a2 message requests the backplate send the contents of various "buffers", which are returned in messages [0025], [0027], 0022, 0023, [0029], and [002b] (empty ones will NOT be sent; brackets infer commonly-empty buffers).
00a2 also triggers 000c immediately following these.
After all the buffers (including 000c) have been sent, the message 002f indicates "end of buffers".
The display is then expected to acknowledge it with message 00a3.

Buffers:
[[#Temperature reading|0022 - Temperature reading]]
0023 - BufferedSourceTemperature (not sure what that means)
0025 - BufferedNearPir
0027 - BufferedPassiveInfrared
0029 - BufferedAmbientLightSensor
002b - BufferedPowerData

=== FET control ===
Turn on W1: d5aa96 8200 0200 00 01 29a2
Turn off W1: d5aa96 8200 0200 00 00 08b2
Turn on Y1: d5aa96 8200 0200 01 01 1891
Turn off Y1: d5aa96 8200 0200 01 00 3981
Turn on G : d5aa96 8200 0200 02 01 4bc4
Turn off G : d5aa96 8200 0200 02 00 6ad4
Turn on OB: d5aa96 8200 0200 03 01 7af7
Turn off OB: d5aa96 8200 0200 03 00 5be7
Turn on W2: d5aa96 8200 0200 04 01 ed6e
Turn off W2: d5aa96 8200 0200 04 00 cc7e
Turn on Y2: d5aa96 8200 0200 07 01 be3b
Turn off Y2: d5aa96 8200 0200 07 00 9f2b
Turn on * : d5aa96 8200 0200 0b 01 d37e
Turn off * : d5aa96 8200 0200 0b 00 f26e

For the sake of documentation, we will refer to the unique id numbers for each wire as "wire id numbers".
So wire id 0 is W1, wire id 1 is Y1, wire id B is *, etc.

=== FET presence ===
The backplate will, at least upon connection, send information about which FETs have a wire present.
This data is received with command ids 0004 and 0009, in that order.
Each sensor is represented by one byte which is either 00 (not present) or 01 (present).

The content of 0004 is in order of the "wire id numbers" used for control:
W1, Y1, G, OB, W2, ?0, ?0, Y2, C, RC, ?0, *, ?0

The content of 0009 is arranged differently and has 2 more values:
W1, Y1, C, RC, ?0, G, OB, W2, ?0, Y2, ?0, *, ?0, ?0, ?0

0009 seems to indicate a wire is physically plugged in, while 0004 indicates that it is connected to something (?).

After these are received, the display sends back command 008f with the exact data from message 0004.
Message 008f does not itself receive any response.

In a power outage condition, 0004 will report all absent (including unknown ones), whereas 0009 will continue to report the same as when power is available.

=== Get build info ===
Message 0099 (no data) requests the backplate report information about its build.
The response will be message 0019 in ASCII (one line, no trailing newline).

=== Get hardware version? ===
Message 009e (no data) requests the backplate report a "Backplate-"X.Y version string.
Since the firmware file on the display CPU uses these strings as "MinApplicability" and "MaxApplicability" ranges, it is probable they refer to the hardware.

Witnessed versions:
"Backplate-2.8" - Florida Lowes

=== Get BSL version ===
Message 009b (no data) requests the backplate report its BSL version number.
The response will be message 001b in ASCII.

=== Get TFE version ===
Message 0098 (no data) requests the backplate report its TFE version number.
The response will be message 0018 in ASCII.

=== Get serial number ===
Message 009f (no data) requests the backplate report its serial number (a 64-bit hexadecimal value).
The response will be message 001f in uppercase ASCII.

=== Periodic status ===
Sending message 0083 (no data) will trigger various periodic messages:
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
000a - (every second; 16-bit data)

The Nest client sends 0083 every 30 seconds, but at least the periodic temperature status will continue on for an hour before stopping.

=== Temperature reading ===
The backplate will send message 0002 every 30 seconds.
The data contains two 16-bit numbers, which nlclient logs in decimal.
The first number is the temperature in centi-celcius.
The second number is the humidity in per-millis.

See also: [[#"Buffers"|"Buffers"]]

=== Reset ===
At least upon connection, the display sends message 00ff to the backplate to reset.

The backplate answers with:
0001 msg "<version> <build timestamp "YYYY-MM-DD HH:MM:SS"> K"
[[#FET presence|0004 FET presence]]
[[#FET presence|0009 FET presence]]
0001 msg "*sense 06d1 06d0 0001 0001 0000 0000 0000 0001 06d9 06d8 06d8; detect 09d3 065c"
0001 msg "BRK"

== Run BeagleBone/Debian programs ==
ln -s . /lib/arm-linux-gnueabihf
ln -s ld-2.11.1.so /lib/ld-linux-armhf.so.3

Nest Hacking

2014-08-08T20:29:27Z

Luke-Jr:

== Hardware ==

[https://www.ifixit.com/Teardown/Nest+Learning+Thermostat+2nd+Generation+Teardown/13818 Pictures]

=== Backplate ===
* ST Microelectronics STM32L151VB ultra-low-power 32 MHz ARM Cortex-M3 MCU
* Sensirion SHT20 humidity and temperature sensor
* Texas Instruments LW051A 8-channel CMOS analog multiplexer/demultiplexer

=== Display ===
* Texas Instruments AM3703CUS Sitara ARM Cortex A8 microprocessor
* Texas Instruments TPS65921B power management and USB single chip
* Samsung K4X51163PK 512 Mb mobile DRAM
* Ember EM357 integrated ZigBee/802.15.4 system-on-chip
* Micron MT29F2G16ABBEAH4 2 Gb NAND flash memory
* Skyworks 2436L high power 2.4 GHz 802.15.4 front-end module
* Texas Instruments WL1270B 802.11 b/g/n Wi-Fi solution
* Avago ADBM-A350 optical finger navigation module (knob movement sensor)

== Info ==
* /dev/event1 is the knob; /dev/event2 is the button
* /sys/class/hwmon/hwmon0/device/in0_battery_type * 0.003 is battery voltage
** Nest turns off wifi below 3.7 V, and waits until 3.8 V to automatically reconnect
* Display serial number is located in U-Boot environment variable "serial#"

== Nest software ==
/nestlabs/sbin/nlclient -config /nestlabs/etc/client.config -config /nestlabs/etc/Display/Display-2/client.config

=== Backplate communications ===
Backplate communications can be decoded from a (filtered) strace log using [http://luke.dashjr.org/programs/freeabode/kindling/NestDecode.pl NestDecode.pl], or decoded in real time using [http://luke.dashjr.org/programs/freeabode/kindling/nest-intercept.c nest-intercept.c].

nest-intercept.c requires one argument, the thread id reading from the backplate controller.
The easiest way to get this is to strace the nlclient process with -ff and look for a thread reading from fd 54.

Note that nest-intercept.c also has a "hack" variable which can be set to 0 (default is 2) in order to corrupt the TFE version response and trigger nlclient into uploading the firmware again.

=== Backplate firmware ===
Found in /nestlabs/share/bp/data/firmware/nlbpfirmware.plist

There are 12 different firmwares in the file:
* Test vs Production
* Backplate 2 vs Backplate 3
* TFE (BP_D2 for Bp2, AMBER_BP for Bp3) vs BSL
* For TFE firmwares, hex vs srec (which for some reason DO differ!)

Python script to extract them into individual files: [http://luke.dashjr.org/programs/freeabode/kindling/extract-fw.py extract-fw.py]

=== Backplate initialisation ===
When the backplate is first connected, the following sequence occurs:
tcflush(fd, TCIFLUSH)
Set baud to 115200 (-opost -isig -icanon -echo ...)
tcflush(fd, TCIOFLUSH)
tcsendbreak(fd, 1)
Send [[#Reset|00ff - Reset]]
Recv 0001 - (message from backplate; ASCII)
Recv [[#FET presence|0004 - FET presence]]
Recv [[#FET presence|0009 - FET presence]]
Send [[#FET presence|008f - FET presence]]
Send [[#Periodic status|0083 - Periodic status request]]
Send 0090 - get mono id (no data; response 0010 with 3 bytes)
Recv 0001 - (message from backplate; ASCII)
Recv 0001 - (message from backplate; ASCII)
Recv 0010 - (24-bit data)
Send [[#Get TFE version|0098 - Get TFE version]]
Recv 000a - (every second; 16-bit data)
Recv 0007 - (every second; 16-bit data)
Recv [[#Get TFE version|0018 - Get TFE version (response)]]
Send [[#Get build info|0099 - Get build info]]
Recv [[#Get build info|0019 - Get build info (response)]]
Sometimes:
Send 009d - (no data; responds with 001d)
Recv 001d - Response to 009d (16-bit data)
Sometimes:
Send [[#Get BSL version|009b - Get BSL version]]
Recv [[#Get BSL version|001b - Get BSL version (response)]]
Sometimes:
Send 009c - (no data; responds with 001c (constant?) data="BSL")
Recv 001c - Response to 009c; always(?) "BSL"
Send [[#Get serial number|009f - Get serial number]]
Recv [[#Get serial number|001f - Get serial number (response)]]
Send [[#Get hardware version?|009e - Get hardware version?]]
Recv [[#Get hardware version?|001e - Get hardware version? (response)]]

== Nest backplate interface ==
* Connected on /dev/ttyO2
* All communications with backplate begin with (d5)d5aa96 (d5 is doubled only for data FROM backplate)
* Everything is little endian
* 16-bit command
* 16-bit data length
* <data>
* 16-bit checksum

Monitor:
strace -ff -p $(pidof nlclient) -x -s9999 -e read,write 2>&1 | grep '(54'

NOTE: Most of this documentation is reverse engineered from firmware version BSL-2.1 and/or TFE_BP_D2-4.0.21 for Backplate-2.x.

=== Checksum ===
<Bytes-from-end>.<bit-value> <xor-with>
00.01 2110 (1021)
00.02 4220 (2042: 1021<<1)
00.04 8440 (4084: 2048<<1)
00.08 0881 (8108: 4084<<1)
00.10 3112 (1231: 8108<<1^1021)
00.20 6224 (2462: 1231<<1)
00.40 c448 (48c4: 2462<<1)
00.80 8891 (9188: 48c4<<1)
01.01 3133 (3313: 9188<<1^1021)
01.02 6266
01.04 c4cc
01.08 a989
01.10 7303
01.20 e606
01.40 cc0d
01.80 981b
02.01 3037
02.02 606e
...
03.01 b476
03.02 68ed
03.04 f1ca
03.08 c385
03.10 a71b
03.20 4e37
03.40 9c6e
03.80 38dd
...
07.20 687b

If you compute the contribution of the individual bit changes in the data you end up with the xor table above; byte offset from the end of the data, bit pattern, xor value. Correcting for little endianess in the output you end up with the hex values in parenthesis. The least significant bit is 0x1021 and each subsequent bit is a shift left, if the XOR value has the 0x8000 bit set then it is XORed with 0x1021. This is the CRC-CCITT polynomial.

8 7 6 5 4 3 2 1 0
d5 aa 96 82 00 02 00 00 00: 08b2
|| |
|| 68ed
|408b
20d4

08b2: 68ed ^ 408b ^ 20d4

Starting at the least significant bit and filling in the XOR values for each bit gives the above diagram; the diagram stops at the 20d4 XOR value because at that point it matches the final CRC. This tells us that the CRC covers the 6 bytes prior.

#!/usr/bin/env perl
use Digest::CRC qw(crc);
my $data = pack("H*", "820002000000");
printf("%04x\n", crc($data,16,0,0,0,0x1021,0,0));

We can also compute the same CRC in Perl; note the result will be byte swapped since the data encodes the number as little endian.

=== Command ids ===

==== Display to backplate ====
[[#FET control|0082 - FET control]]
[[#Periodic status|0083 - Periodic status request]]
[[#FET presence|008f - FET presence]]
0090 - get mono id (no data; response 0010 with 3 bytes)
[[#Backplate firmware upload|0091 - Backplate firmware upload (start)]]
[[#Backplate firmware upload|0092 - Backplate firmware upload]]
[[#Backplate firmware upload|0093 - Backplate firmware upload (finish)]]
[[#Get TFE version|0098 - Get TFE version]]
[[#Get build info|0099 - Get build info]]
[[#Get BSL version|009b - Get BSL version]]
009c - (no data; responds with 001c (constant?) data="BSL")
009d - (no data; responds with 001d)
[[#Get hardware version?|009e - Get hardware version?]]
[[#Get serial number|009f - Get serial number]]
00a1 - quiet (16-bit max sleep seconds)
[[#"Buffers"|00a2 - Request "buffers" (every 30 seconds; no data; triggers [0025] [0027] 0022 0023 [0029] [002b] 000c 002f)]]
[[#"Buffers"|00a3 - ACK to 002f (no data)]]
00a4 - set wakeup mask (16-bit data)
00b1 - button pressed/unpressed (no data)
00b3 - set humidity thresholds (32-bit data)
00b5 - set near pir threshold (16-bit data)
00b9 - set als thresholds (32-bit data)
00ba - set vergence mode (48-bit data)
00c2 - (48-bit data)
[[#Reset|00ff - Reset]]

==== Backplate to display ====
0001 - (message from backplate; ASCII)
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
[[#FET presence|0004 - FET presence]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
[[#FET presence|0009 - FET presence]]
000a - (every second; 2x(?) 16-bit data)
[[#Backplate state|000b - Backplate state]]
000c - (16-bit values: pir, px1, px1 divisor, px2, px2 divisor, alir, av; included in [[#"Buffers"|"buffers" data]])
0010 - (24-bit data)
[[#Backplate firmware upload|0011 - Backplate firmware upload (ACK)]]
0014 - "WakeVector" (16-bit data)
[[#Get TFE version|0018 - Get TFE version (response)]]
[[#Get build info|0019 - Get build info (response)]]
[[#Get BSL version|001b - Get BSL version (response)]]
001c - Response to 009c; always(?) "BSL"
001d - Response to 009d (16-bit data)
[[#Get hardware version?|001e - Get hardware version? (response)]]
[[#Get serial number|001f - Get serial number (response)]]
[[#"Buffers"|0022 - buffered temperature reading (possibly multiple times)]]
[[#"Buffers"|0023 - BufferedSourceTemperature (3x 16-bit data; possibly multiple times)]]
[[#"Buffers"|0025 - BufferedNearPir (16-bit data; possibly multiple times)]]
[[#"Buffers"|0027 - BufferedPassiveInfrared (64-bit data; possibly multiple times)]]
[[#"Buffers"|0029 - BufferedAmbientLightSensor (48-bit data; likely 3x 16-bit; possibly multiple times)]]
[[#"Buffers"|002b - BufferedPowerData (64-bit data; possibly multiple times)]]
[[#"Buffers"|002f - End of "buffers" (16-bit data)]]

=== Backplate firmware upload ===
For uploading the firmware, the following sequence is used:
Send 0091 data=0000<firmware type>
Recv 0011 data=0000
Send 0092 data=0100...
Recv 0011 data=0100
Send 0092 data=0200...
Recv 0011 data=0200
...
Send 0092 data=a901...
Recv 0011 data=a901
Send 0093 data=aa01
Recv 0011 data=aa01
Following the upload, the [[#Backplate initialisation|backplate initialisation process]] begins immediately (that is, without message 00ff being sent to order a reset).
Presumably the 0011 message is an ACK, and the first 16 bits of each message is the line number.
The format itself appears to be Motorola S-record (SREC).
Uploading the BSL firmware was followed by the TFE firmware, so it may be required (though uploading the TFE firmware does ''not'' require uploading the BSL).

Firmware type is either 4d for TFE or 42 for BSL.

=== Backplate state ===
Data:
* 8-bit "state"
* 8-bit "flags"
* 8-bit "px0" (may be wider?)
* 40-bit UNKNOWN (includes at least "p2" and "voc")
* 16-bit centi-volts "vi"
* 16-bit milli-volts "vo"
* 16-bit milli-volts "vb"
* 8-bit ("pins" or "wires")
* 8-bit ("wires" or "pins")
* 16-bit UNKNOWN

=== "Buffers" ===
The 00a2 message requests the backplate send the contents of various "buffers", which are returned in messages [0025], [0027], 0022, 0023, [0029], and [002b] (empty ones will NOT be sent; brackets infer commonly-empty buffers).
00a2 also triggers 000c immediately following these.
After all the buffers (including 000c) have been sent, the message 002f indicates "end of buffers".
The display is then expected to acknowledge it with message 00a3.

Buffers:
[[#Temperature reading|0022 - Temperature reading]]
0023 - BufferedSourceTemperature (not sure what that means)
0025 - BufferedNearPir
0027 - BufferedPassiveInfrared
0029 - BufferedAmbientLightSensor
002b - BufferedPowerData

=== FET control ===
Turn on W1: d5aa96 8200 0200 00 01 29a2
Turn off W1: d5aa96 8200 0200 00 00 08b2
Turn on Y1: d5aa96 8200 0200 01 01 1891
Turn off Y1: d5aa96 8200 0200 01 00 3981
Turn on G : d5aa96 8200 0200 02 01 4bc4
Turn off G : d5aa96 8200 0200 02 00 6ad4
Turn on OB: d5aa96 8200 0200 03 01 7af7
Turn off OB: d5aa96 8200 0200 03 00 5be7
Turn on W2: d5aa96 8200 0200 04 01 ed6e
Turn off W2: d5aa96 8200 0200 04 00 cc7e
Turn on Y2: d5aa96 8200 0200 07 01 be3b
Turn off Y2: d5aa96 8200 0200 07 00 9f2b
Turn on * : d5aa96 8200 0200 0b 01 d37e
Turn off * : d5aa96 8200 0200 0b 00 f26e

For the sake of documentation, we will refer to the unique id numbers for each wire as "wire id numbers".
So wire id 0 is W1, wire id 1 is Y1, wire id B is *, etc.

=== FET presence ===
The backplate will, at least upon connection, send information about which FETs have a wire present.
This data is received with command ids 0004 and 0009, in that order.
Each sensor is represented by one byte which is either 00 (not present) or 01 (present).

The content of 0004 is in order of the "wire id numbers" used for control:
W1, Y1, G, OB, W2, ?0, ?0, Y2, C, RC, ?0, *, ?0

The content of 0009 is arranged differently and has 2 more values:
W1, Y1, C, RC, ?0, G, OB, W2, ?0, Y2, ?0, *, ?0, ?0, ?0

0009 seems to indicate a wire is physically plugged in, while 0004 indicates that it is connected to something (?).

After these are received, the display sends back command 008f with the exact data from message 0004.
Message 008f does not itself receive any response.

In a power outage condition, 0004 will report all absent (including unknown ones), whereas 0009 will continue to report the same as when power is available.

=== Get build info ===
Message 0099 (no data) requests the backplate report information about its build.
The response will be message 0019 in ASCII (one line, no trailing newline).

=== Get hardware version? ===
Message 009e (no data) requests the backplate report a "Backplate-"X.Y version string.
Since the firmware file on the display CPU uses these strings as "MinApplicability" and "MaxApplicability" ranges, it is probable they refer to the hardware.

Witnessed versions:
"Backplate-2.8" - Florida Lowes

=== Get BSL version ===
Message 009b (no data) requests the backplate report its BSL version number.
The response will be message 001b in ASCII.

=== Get TFE version ===
Message 0098 (no data) requests the backplate report its TFE version number.
The response will be message 0018 in ASCII.

=== Get serial number ===
Message 009f (no data) requests the backplate report its serial number (a 64-bit hexadecimal value).
The response will be message 001f in uppercase ASCII.

=== Periodic status ===
Sending message 0083 (no data) will trigger various periodic messages:
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
000a - (every second; 16-bit data)

The Nest client sends 0083 every 30 seconds, but at least the periodic temperature status will continue on for an hour before stopping.

=== Temperature reading ===
The backplate will send message 0002 every 30 seconds.
The data contains two 16-bit numbers, which nlclient logs in decimal.
The first number is the temperature in centi-celcius.
The second number is the humidity in per-millis.

See also: [[#"Buffers"|"Buffers"]]

=== Reset ===
At least upon connection, the display sends message 00ff to the backplate to reset.

The backplate answers with:
0001 msg "<version> <build timestamp "YYYY-MM-DD HH:MM:SS"> K"
[[#FET presence|0004 FET presence]]
[[#FET presence|0009 FET presence]]
0001 msg "*sense 06d1 06d0 0001 0001 0000 0000 0000 0001 06d9 06d8 06d8; detect 09d3 065c"
0001 msg "BRK"

== Run BeagleBone/Debian programs ==
ln -s . /lib/arm-linux-gnueabihf
ln -s ld-2.11.1.so /lib/ld-linux-armhf.so.3

Nest Hacking

2014-08-08T18:40:32Z

Luke-Jr:

== Hardware ==

[https://www.ifixit.com/Teardown/Nest+Learning+Thermostat+2nd+Generation+Teardown/13818 Pictures]

=== Backplate ===
* ST Microelectronics STM32L151VB ultra-low-power 32 MHz ARM Cortex-M3 MCU
* Sensirion SHT20 humidity and temperature sensor
* Texas Instruments LW051A 8-channel CMOS analog multiplexer/demultiplexer

=== Display ===
* Texas Instruments AM3703CUS Sitara ARM Cortex A8 microprocessor
* Texas Instruments TPS65921B power management and USB single chip
* Samsung K4X51163PK 512 Mb mobile DRAM
* Ember EM357 integrated ZigBee/802.15.4 system-on-chip
* Micron MT29F2G16ABBEAH4 2 Gb NAND flash memory
* Skyworks 2436L high power 2.4 GHz 802.15.4 front-end module
* Texas Instruments WL1270B 802.11 b/g/n Wi-Fi solution
* Avago ADBM-A350 optical finger navigation module (knob movement sensor)

== Info ==
* /dev/event1 is the knob; /dev/event2 is the button
* /sys/class/hwmon/hwmon0/device/in0_battery_type * 0.003 is battery voltage
** Nest turns off wifi below 3.7 V, and waits until 3.8 V to automatically reconnect
* Display serial number is located in U-Boot environment variable "serial#"

== Nest software ==
/nestlabs/sbin/nlclient -config /nestlabs/etc/client.config -config /nestlabs/etc/Display/Display-2/client.config

=== Backplate communications ===
Backplate communications can be decoded from a (filtered) strace log using [http://luke.dashjr.org/programs/freeabode/kindling/NestDecode.pl NestDecode.pl], or decoded in real time using [http://luke.dashjr.org/programs/freeabode/kindling/nest-intercept.c nest-intercept.c].

nest-intercept.c requires one argument, the thread id reading from the backplate controller.
The easiest way to get this is to strace the nlclient process with -ff and look for a thread reading from fd 54.

Note that nest-intercept.c also has a "hack" variable which can be set to 0 (default is 2) in order to corrupt the TFE version response and trigger nlclient into uploading the firmware again.

=== Backplate firmware ===
Found in /nestlabs/share/bp/data/firmware/nlbpfirmware.plist

There are 12 different firmwares in the file:
* Test vs Production
* Backplate 2 vs Backplate 3
* TFE (BP_D2 for Bp2, AMBER_BP for Bp3) vs BSL
* For TFE firmwares, hex vs srec (which for some reason DO differ!)

Python script to extract them into individual files: [http://luke.dashjr.org/programs/freeabode/kindling/extract-fw.py extract-fw.py]

=== Backplate initialisation ===
When the backplate is first connected, the following sequence occurs:
tcflush(fd, TCIFLUSH)
Set baud to 115200 (-opost -isig -icanon -echo ...)
tcflush(fd, TCIOFLUSH)
tcsendbreak(fd, 1)
Send [[#Reset|00ff - Reset]]
Recv 0001 - (message from backplate; ASCII)
Recv [[#FET presence|0004 - FET presence]]
Recv [[#FET presence|0009 - FET presence]]
Send [[#FET presence|008f - FET presence]]
Send [[#Periodic status|0083 - Periodic status request]]
Send 0090 - (no data; response 0010 with 3 bytes)
Recv 0001 - (message from backplate; ASCII)
Recv 0001 - (message from backplate; ASCII)
Recv 0010 - (24-bit data)
Send [[#Get TFE version|0098 - Get TFE version]]
Recv 000a - (every second; 16-bit data)
Recv 0007 - (every second; 16-bit data)
Recv [[#Get TFE version|0018 - Get TFE version (response)]]
Send [[#Get build info|0099 - Get build info]]
Recv [[#Get build info|0019 - Get build info (response)]]
Sometimes:
Send 009d - (no data; responds with 001d)
Recv 001d - Response to 009d (16-bit data)
Sometimes:
Send [[#Get BSL version|009b - Get BSL version]]
Recv [[#Get BSL version|001b - Get BSL version (response)]]
Sometimes:
Send 009c - (no data; responds with 001c (constant?) data="BSL")
Recv 001c - Response to 009c; always(?) "BSL"
Send [[#Get serial number|009f - Get serial number]]
Recv [[#Get serial number|001f - Get serial number (response)]]
Send [[#Get hardware version?|009e - Get hardware version?]]
Recv [[#Get hardware version?|001e - Get hardware version? (response)]]

== Nest backplate interface ==
* Connected on /dev/ttyO2
* All communications with backplate begin with (d5)d5aa96 (d5 is doubled only for data FROM backplate)
* Everything is little endian
* 16-bit command
* 16-bit data length
* <data>
* 16-bit checksum

Monitor:
strace -ff -p $(pidof nlclient) -x -s9999 -e read,write 2>&1 | grep '(54'

NOTE: Most of this documentation is reverse engineered from firmware version BSL-2.1 and/or TFE_BP_D2-4.0.21 for Backplate-2.x.

=== Checksum ===
<Bytes-from-end>.<bit-value> <xor-with>
00.01 2110 (1021)
00.02 4220 (2042: 1021<<1)
00.04 8440 (4084: 2048<<1)
00.08 0881 (8108: 4084<<1)
00.10 3112 (1231: 8108<<1^1021)
00.20 6224 (2462: 1231<<1)
00.40 c448 (48c4: 2462<<1)
00.80 8891 (9188: 48c4<<1)
01.01 3133 (3313: 9188<<1^1021)
01.02 6266
01.04 c4cc
01.08 a989
01.10 7303
01.20 e606
01.40 cc0d
01.80 981b
02.01 3037
02.02 606e
...
03.01 b476
03.02 68ed
03.04 f1ca
03.08 c385
03.10 a71b
03.20 4e37
03.40 9c6e
03.80 38dd
...
07.20 687b

If you compute the contribution of the individual bit changes in the data you end up with the xor table above; byte offset from the end of the data, bit pattern, xor value. Correcting for little endianess in the output you end up with the hex values in parenthesis. The least significant bit is 0x1021 and each subsequent bit is a shift left, if the XOR value has the 0x8000 bit set then it is XORed with 0x1021. This is the CRC-CCITT polynomial.

8 7 6 5 4 3 2 1 0
d5 aa 96 82 00 02 00 00 00: 08b2
|| |
|| 68ed
|408b
20d4

08b2: 68ed ^ 408b ^ 20d4

Starting at the least significant bit and filling in the XOR values for each bit gives the above diagram; the diagram stops at the 20d4 XOR value because at that point it matches the final CRC. This tells us that the CRC covers the 6 bytes prior.

#!/usr/bin/env perl
use Digest::CRC qw(crc);
my $data = pack("H*", "820002000000");
printf("%04x\n", crc($data,16,0,0,0,0x1021,0,0));

We can also compute the same CRC in Perl; note the result will be byte swapped since the data encodes the number as little endian.

=== Command ids ===

==== Display to backplate ====
[[#FET control|0082 - FET control]]
[[#Periodic status|0083 - Periodic status request]]
[[#FET presence|008f - FET presence]]
0090 - (no data; response 0010 with 3 bytes)
[[#Backplate firmware upload|0091 - Backplate firmware upload (start)]]
[[#Backplate firmware upload|0092 - Backplate firmware upload]]
[[#Backplate firmware upload|0093 - Backplate firmware upload (finish)]]
[[#Get TFE version|0098 - Get TFE version]]
[[#Get build info|0099 - Get build info]]
[[#Get BSL version|009b - Get BSL version]]
009c - (no data; responds with 001c (constant?) data="BSL")
009d - (no data; responds with 001d)
[[#Get hardware version?|009e - Get hardware version?]]
[[#Get serial number|009f - Get serial number]]
00a1 - (16-bit data)
[[#"Buffers"|00a2 - Request "buffers" (every 30 seconds; no data; triggers [0025] [0027] 0022 0023 [0029] [002b] 000c 002f)]]
[[#"Buffers"|00a3 - ACK to 002f (no data)]]
00a4 - (16-bit data)
00b1 - button pressed/unpressed (no data)
00b3 - (32-bit data)
00b5 - (16-bit data)
00b9 - (32-bit data)
00ba - (48-bit data)
00c2 - (48-bit data)
[[#Reset|00ff - Reset]]

==== Backplate to display ====
0001 - (message from backplate; ASCII)
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
[[#FET presence|0004 - FET presence]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
[[#FET presence|0009 - FET presence]]
000a - (every second; 2x(?) 16-bit data)
[[#Backplate state|000b - Backplate state]]
000c - (16-bit values: pir, px1, px1 divisor, px2, px2 divisor, alir, av; included in [[#"Buffers"|"buffers" data]])
0010 - (24-bit data)
[[#Backplate firmware upload|0011 - Backplate firmware upload (ACK)]]
0014 - "WakeVector" (16-bit data)
[[#Get TFE version|0018 - Get TFE version (response)]]
[[#Get build info|0019 - Get build info (response)]]
[[#Get BSL version|001b - Get BSL version (response)]]
001c - Response to 009c; always(?) "BSL"
001d - Response to 009d (16-bit data)
[[#Get hardware version?|001e - Get hardware version? (response)]]
[[#Get serial number|001f - Get serial number (response)]]
[[#"Buffers"|0022 - buffered temperature reading (possibly multiple times)]]
[[#"Buffers"|0023 - BufferedSourceTemperature (3x 16-bit data; possibly multiple times)]]
[[#"Buffers"|0025 - BufferedNearPir (16-bit data; possibly multiple times)]]
[[#"Buffers"|0027 - BufferedPassiveInfrared (64-bit data; possibly multiple times)]]
[[#"Buffers"|0029 - BufferedAmbientLightSensor (48-bit data; likely 3x 16-bit; possibly multiple times)]]
[[#"Buffers"|002b - BufferedPowerData (64-bit data; possibly multiple times)]]
[[#"Buffers"|002f - End of "buffers" (16-bit data)]]

=== Backplate firmware upload ===
For uploading the firmware, the following sequence is used:
Send 0091 data=0000<firmware type>
Recv 0011 data=0000
Send 0092 data=0100...
Recv 0011 data=0100
Send 0092 data=0200...
Recv 0011 data=0200
...
Send 0092 data=a901...
Recv 0011 data=a901
Send 0093 data=aa01
Recv 0011 data=aa01
Following the upload, the [[#Backplate initialisation|backplate initialisation process]] begins immediately (that is, without message 00ff being sent to order a reset).
Presumably the 0011 message is an ACK, and the first 16 bits of each message is the line number.
The format itself appears to be Motorola S-record (SREC).
Uploading the BSL firmware was followed by the TFE firmware, so it may be required (though uploading the TFE firmware does ''not'' require uploading the BSL).

Firmware type is either 4d for TFE or 42 for BSL.

=== Backplate state ===
Data:
* 8-bit "state"
* 8-bit "flags"
* 8-bit "px0" (may be wider?)
* 40-bit UNKNOWN (includes at least "p2" and "voc")
* 16-bit centi-volts "vi"
* 16-bit milli-volts "vo"
* 16-bit milli-volts "vb"
* 8-bit ("pins" or "wires")
* 8-bit ("wires" or "pins")
* 16-bit UNKNOWN

=== "Buffers" ===
The 00a2 message requests the backplate send the contents of various "buffers", which are returned in messages [0025], [0027], 0022, 0023, [0029], and [002b] (empty ones will NOT be sent; brackets infer commonly-empty buffers).
00a2 also triggers 000c immediately following these.
After all the buffers (including 000c) have been sent, the message 002f indicates "end of buffers".
The display is then expected to acknowledge it with message 00a3.

Buffers:
[[#Temperature reading|0022 - Temperature reading]]
0023 - BufferedSourceTemperature (not sure what that means)
0025 - BufferedNearPir
0027 - BufferedPassiveInfrared
0029 - BufferedAmbientLightSensor
002b - BufferedPowerData

=== FET control ===
Turn on W1: d5aa96 8200 0200 00 01 29a2
Turn off W1: d5aa96 8200 0200 00 00 08b2
Turn on Y1: d5aa96 8200 0200 01 01 1891
Turn off Y1: d5aa96 8200 0200 01 00 3981
Turn on G : d5aa96 8200 0200 02 01 4bc4
Turn off G : d5aa96 8200 0200 02 00 6ad4
Turn on OB: d5aa96 8200 0200 03 01 7af7
Turn off OB: d5aa96 8200 0200 03 00 5be7
Turn on W2: d5aa96 8200 0200 04 01 ed6e
Turn off W2: d5aa96 8200 0200 04 00 cc7e
Turn on Y2: d5aa96 8200 0200 07 01 be3b
Turn off Y2: d5aa96 8200 0200 07 00 9f2b
Turn on * : d5aa96 8200 0200 0b 01 d37e
Turn off * : d5aa96 8200 0200 0b 00 f26e

For the sake of documentation, we will refer to the unique id numbers for each wire as "wire id numbers".
So wire id 0 is W1, wire id 1 is Y1, wire id B is *, etc.

=== FET presence ===
The backplate will, at least upon connection, send information about which FETs have a wire present.
This data is received with command ids 0004 and 0009, in that order.
Each sensor is represented by one byte which is either 00 (not present) or 01 (present).

The content of 0004 is in order of the "wire id numbers" used for control:
W1, Y1, G, OB, W2, ?0, ?0, Y2, C, RC, ?0, *, ?0

The content of 0009 is arranged differently and has 2 more values:
W1, Y1, C, RC, ?0, G, OB, W2, ?0, Y2, ?0, *, ?0, ?0, ?0

0009 seems to indicate a wire is physically plugged in, while 0004 indicates that it is connected to something (?).

After these are received, the display sends back command 008f with the exact data from message 0004.
Message 008f does not itself receive any response.

In a power outage condition, 0004 will report all absent (including unknown ones), whereas 0009 will continue to report the same as when power is available.

=== Get build info ===
Message 0099 (no data) requests the backplate report information about its build.
The response will be message 0019 in ASCII (one line, no trailing newline).

=== Get hardware version? ===
Message 009e (no data) requests the backplate report a "Backplate-"X.Y version string.
Since the firmware file on the display CPU uses these strings as "MinApplicability" and "MaxApplicability" ranges, it is probable they refer to the hardware.

Witnessed versions:
"Backplate-2.8" - Florida Lowes

=== Get BSL version ===
Message 009b (no data) requests the backplate report its BSL version number.
The response will be message 001b in ASCII.

=== Get TFE version ===
Message 0098 (no data) requests the backplate report its TFE version number.
The response will be message 0018 in ASCII.

=== Get serial number ===
Message 009f (no data) requests the backplate report its serial number (a 64-bit hexadecimal value).
The response will be message 001f in uppercase ASCII.

=== Periodic status ===
Sending message 0083 (no data) will trigger various periodic messages:
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
000a - (every second; 16-bit data)

The Nest client sends 0083 every 30 seconds, but at least the periodic temperature status will continue on for an hour before stopping.

=== Temperature reading ===
The backplate will send message 0002 every 30 seconds.
The data contains two 16-bit numbers, which nlclient logs in decimal.
The first number is the temperature in centi-celcius.
The second number is the humidity in per-millis.

See also: [[#"Buffers"|"Buffers"]]

=== Reset ===
At least upon connection, the display sends message 00ff to the backplate to reset.

The backplate answers with:
0001 msg "<version> <build timestamp "YYYY-MM-DD HH:MM:SS"> K"
[[#FET presence|0004 FET presence]]
[[#FET presence|0009 FET presence]]
0001 msg "*sense 06d1 06d0 0001 0001 0000 0000 0000 0001 06d9 06d8 06d8; detect 09d3 065c"
0001 msg "BRK"

== Run BeagleBone/Debian programs ==
ln -s . /lib/arm-linux-gnueabihf
ln -s ld-2.11.1.so /lib/ld-linux-armhf.so.3

Nest Hacking

2014-08-08T03:23:22Z

Luke-Jr:

== Hardware ==

[https://www.ifixit.com/Teardown/Nest+Learning+Thermostat+2nd+Generation+Teardown/13818 Pictures]

=== Backplate ===
* ST Microelectronics STM32L151VB ultra-low-power 32 MHz ARM Cortex-M3 MCU
* Sensirion SHT20 humidity and temperature sensor
* Texas Instruments LW051A 8-channel CMOS analog multiplexer/demultiplexer

=== Display ===
* Texas Instruments AM3703CUS Sitara ARM Cortex A8 microprocessor
* Texas Instruments TPS65921B power management and USB single chip
* Samsung K4X51163PK 512 Mb mobile DRAM
* Ember EM357 integrated ZigBee/802.15.4 system-on-chip
* Micron MT29F2G16ABBEAH4 2 Gb NAND flash memory
* Skyworks 2436L high power 2.4 GHz 802.15.4 front-end module
* Texas Instruments WL1270B 802.11 b/g/n Wi-Fi solution
* Avago ADBM-A350 optical finger navigation module (knob movement sensor)

== Info ==
* /dev/event1 is the knob; /dev/event2 is the button
* /sys/class/hwmon/hwmon0/device/in0_battery_type * 0.003 is battery voltage
** Nest turns off wifi below 3.7 V, and waits until 3.8 V to automatically reconnect
* Display serial number is located in U-Boot environment variable "serial#"

== Nest software ==
/nestlabs/sbin/nlclient -config /nestlabs/etc/client.config -config /nestlabs/etc/Display/Display-2/client.config

=== Backplate communications ===
Backplate communications can be decoded from a (filtered) strace log using [http://luke.dashjr.org/programs/freeabode/kindling/NestDecode.pl NestDecode.pl], or decoded in real time using [http://luke.dashjr.org/programs/freeabode/kindling/nest-intercept.c nest-intercept.c].

nest-intercept.c requires one argument, the thread id reading from the backplate controller.
The easiest way to get this is to strace the nlclient process with -ff and look for a thread reading from fd 54.

Note that nest-intercept.c also has a "hack" variable which can be set to 0 (default is 2) in order to corrupt the TFE version response and trigger nlclient into uploading the firmware again.

=== Backplate firmware ===
Found in /nestlabs/share/bp/data/firmware/nlbpfirmware.plist

There are 12 different firmwares in the file:
* Test vs Production
* Backplate 2 vs Backplate 3
* TFE (BP_D2 for Bp2, AMBER_BP for Bp3) vs BSL
* For TFE firmwares, hex vs srec (which for some reason DO differ!)

Python script to extract them into individual files: [http://luke.dashjr.org/programs/freeabode/kindling/extract-fw.py extract-fw.py]

=== Backplate initialisation ===
When the backplate is first connected, the following sequence occurs:
tcflush(fd, TCIFLUSH)
Set baud to 115200 (-opost -isig -icanon -echo ...)
tcflush(fd, TCIOFLUSH)
tcsendbreak(fd, 1)
Send [[#Reset|00ff - Reset]]
Recv 0001 - (message from backplate; ASCII)
Recv [[#FET presence|0004 - FET presence]]
Recv [[#FET presence|0009 - FET presence]]
Send [[#FET presence|008f - FET presence]]
Send [[#Periodic status|0083 - Periodic status request]]
Send 0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
Recv 0001 - (message from backplate; ASCII)
Recv 0001 - (message from backplate; ASCII)
Recv 0010 - (24-bit data)
Send [[#Get TFE version|0098 - Get TFE version]]
Recv 000a - (every second; 16-bit data)
Recv 0007 - (every second; 16-bit data)
Recv [[#Get TFE version|0018 - Get TFE version (response)]]
Send [[#Get build info|0099 - Get build info]]
Recv [[#Get build info|0019 - Get build info (response)]]
Sometimes:
Send 009d - (no data; responds with 001d (constant?) data=bbbb)
Recv 001d - Response to 009d; always(?) bbbb
Sometimes:
Send [[#Get BSL version|009b - Get BSL version]]
Recv [[#Get BSL version|001b - Get BSL version (response)]]
Sometimes:
Send 009c - (no data; responds with 001c (constant?) data="BSL")
Recv 001c - Response to 009c; always(?) "BSL"
Send [[#Get serial number|009f - Get serial number]]
Recv [[#Get serial number|001f - Get serial number (response)]]
Send [[#Get hardware version?|009e - Get hardware version?]]
Recv [[#Get hardware version?|001e - Get hardware version? (response)]]

== Nest backplate interface ==
* Connected on /dev/ttyO2
* All communications with backplate begin with (d5)d5aa96 (d5 is doubled only for data FROM backplate)
* Everything is little endian
* 16-bit command
* 16-bit data length
* <data>
* 16-bit checksum

Monitor:
strace -ff -p $(pidof nlclient) -x -s9999 -e read,write 2>&1 | grep '(54'

NOTE: Most of this documentation is reverse engineered from firmware version BSL-2.1 and/or TFE_BP_D2-4.0.21 for Backplate-2.x.

=== Checksum ===
<Bytes-from-end>.<bit-value> <xor-with>
00.01 2110 (1021)
00.02 4220 (2042: 1021<<1)
00.04 8440 (4084: 2048<<1)
00.08 0881 (8108: 4084<<1)
00.10 3112 (1231: 8108<<1^1021)
00.20 6224 (2462: 1231<<1)
00.40 c448 (48c4: 2462<<1)
00.80 8891 (9188: 48c4<<1)
01.01 3133 (3313: 9188<<1^1021)
01.02 6266
01.04 c4cc
01.08 a989
01.10 7303
01.20 e606
01.40 cc0d
01.80 981b
02.01 3037
02.02 606e
...
03.01 b476
03.02 68ed
03.04 f1ca
03.08 c385
03.10 a71b
03.20 4e37
03.40 9c6e
03.80 38dd
...
07.20 687b

If you compute the contribution of the individual bit changes in the data you end up with the xor table above; byte offset from the end of the data, bit pattern, xor value. Correcting for little endianess in the output you end up with the hex values in parenthesis. The least significant bit is 0x1021 and each subsequent bit is a shift left, if the XOR value has the 0x8000 bit set then it is XORed with 0x1021. This is the CRC-CCITT polynomial.

8 7 6 5 4 3 2 1 0
d5 aa 96 82 00 02 00 00 00: 08b2
|| |
|| 68ed
|408b
20d4

08b2: 68ed ^ 408b ^ 20d4

Starting at the least significant bit and filling in the XOR values for each bit gives the above diagram; the diagram stops at the 20d4 XOR value because at that point it matches the final CRC. This tells us that the CRC covers the 6 bytes prior.

#!/usr/bin/env perl
use Digest::CRC qw(crc);
my $data = pack("H*", "820002000000");
printf("%04x\n", crc($data,16,0,0,0,0x1021,0,0));

We can also compute the same CRC in Perl; note the result will be byte swapped since the data encodes the number as little endian.

=== Command ids ===

==== Display to backplate ====
[[#FET control|0082 - FET control]]
[[#Periodic status|0083 - Periodic status request]]
[[#FET presence|008f - FET presence]]
0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
[[#Backplate firmware upload|0091 - Backplate firmware upload (start)]]
[[#Backplate firmware upload|0092 - Backplate firmware upload]]
[[#Backplate firmware upload|0093 - Backplate firmware upload (finish)]]
[[#Get TFE version|0098 - Get TFE version]]
[[#Get build info|0099 - Get build info]]
[[#Get BSL version|009b - Get BSL version]]
009c - (no data; responds with 001c (constant?) data="BSL")
009d - (no data; responds with 001d (constant?) data=bbbb)
[[#Get hardware version?|009e - Get hardware version?]]
[[#Get serial number|009f - Get serial number]]
00a1 - (16-bit data)
[[#"Buffers"|00a2 - Request "buffers" (every 30 seconds; no data; triggers [0025] [0027] 0022 0023 [0029] [002b] 000c 002f)]]
[[#"Buffers"|00a3 - ACK to 002f (no data)]]
00a4 - (16-bit data)
00b1 - button pressed/unpressed (no data)
00b3 - (32-bit data; always ffffffff?)
00b5 - (16-bit data; always 0f00?)
00b9 - (32-bit data; always 0000ffff?)
00ba - (48-bit data; always 000000000000?)
00c2 - (48-bit data)
[[#Reset|00ff - Reset]]

==== Backplate to display ====
0001 - (message from backplate; ASCII)
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
[[#FET presence|0004 - FET presence]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
[[#FET presence|0009 - FET presence]]
000a - (every second; 2x(?) 16-bit data)
[[#Backplate state|000b - Backplate state]]
000c - (16-bit values: pir, px1, px1 divisor, px2, px2 divisor, alir, av; included in [[#"Buffers"|"buffers" data]])
0010 - (24-bit data)
[[#Backplate firmware upload|0011 - Backplate firmware upload (ACK)]]
0014 - "WakeVector" (16-bit data)
[[#Get TFE version|0018 - Get TFE version (response)]]
[[#Get build info|0019 - Get build info (response)]]
[[#Get BSL version|001b - Get BSL version (response)]]
001c - Response to 009c; always(?) "BSL"
001d - Response to 009d; always(?) bbbb
[[#Get hardware version?|001e - Get hardware version? (response)]]
[[#Get serial number|001f - Get serial number (response)]]
[[#"Buffers"|0022 - buffered temperature reading (possibly multiple times)]]
[[#"Buffers"|0023 - BufferedSourceTemperature (3x 16-bit data; possibly multiple times)]]
[[#"Buffers"|0025 - BufferedNearPir (16-bit data; possibly multiple times)]]
[[#"Buffers"|0027 - BufferedPassiveInfrared (64-bit data; possibly multiple times)]]
[[#"Buffers"|0029 - BufferedAmbientLightSensor (48-bit data; likely 3x 16-bit; possibly multiple times)]]
[[#"Buffers"|002b - BufferedPowerData (64-bit data; possibly multiple times)]]
[[#"Buffers"|002f - End of "buffers" (16-bit data)]]

=== Backplate firmware upload ===
For uploading the firmware, the following sequence is used:
Send 0091 data=0000<firmware type>
Recv 0011 data=0000
Send 0092 data=0100...
Recv 0011 data=0100
Send 0092 data=0200...
Recv 0011 data=0200
...
Send 0092 data=a901...
Recv 0011 data=a901
Send 0093 data=aa01
Recv 0011 data=aa01
Following the upload, the [[#Backplate initialisation|backplate initialisation process]] begins immediately (that is, without message 00ff being sent to order a reset).
Presumably the 0011 message is an ACK, and the first 16 bits of each message is the line number.
The format itself appears to be Motorola S-record (SREC).
Uploading the BSL firmware was followed by the TFE firmware, so it may be required (though uploading the TFE firmware does ''not'' require uploading the BSL).

Firmware type is either 4d for TFE or 42 for BSL.

=== Backplate state ===
Data:
* 8-bit "state"
* 8-bit "flags"
* 8-bit "px0" (may be wider?)
* 40-bit UNKNOWN (includes at least "p2" and "voc")
* 16-bit centi-volts "vi"
* 16-bit milli-volts "vo"
* 16-bit milli-volts "vb"
* 8-bit ("pins" or "wires")
* 8-bit ("wires" or "pins")
* 16-bit UNKNOWN

=== "Buffers" ===
The 00a2 message requests the backplate send the contents of various "buffers", which are returned in messages [0025], [0027], 0022, 0023, [0029], and [002b] (empty ones will NOT be sent; brackets infer commonly-empty buffers).
00a2 also triggers 000c immediately following these.
After all the buffers (including 000c) have been sent, the message 002f indicates "end of buffers".
The display is then expected to acknowledge it with message 00a3.

Buffers:
[[#Temperature reading|0022 - Temperature reading]]
0023 - BufferedSourceTemperature (not sure what that means)
0025 - BufferedNearPir
0027 - BufferedPassiveInfrared
0029 - BufferedAmbientLightSensor
002b - BufferedPowerData

=== FET control ===
Turn on W1: d5aa96 8200 0200 00 01 29a2
Turn off W1: d5aa96 8200 0200 00 00 08b2
Turn on Y1: d5aa96 8200 0200 01 01 1891
Turn off Y1: d5aa96 8200 0200 01 00 3981
Turn on G : d5aa96 8200 0200 02 01 4bc4
Turn off G : d5aa96 8200 0200 02 00 6ad4
Turn on OB: d5aa96 8200 0200 03 01 7af7
Turn off OB: d5aa96 8200 0200 03 00 5be7
Turn on W2: d5aa96 8200 0200 04 01 ed6e
Turn off W2: d5aa96 8200 0200 04 00 cc7e
Turn on Y2: d5aa96 8200 0200 07 01 be3b
Turn off Y2: d5aa96 8200 0200 07 00 9f2b
Turn on * : d5aa96 8200 0200 0b 01 d37e
Turn off * : d5aa96 8200 0200 0b 00 f26e

For the sake of documentation, we will refer to the unique id numbers for each wire as "wire id numbers".
So wire id 0 is W1, wire id 1 is Y1, wire id B is *, etc.

=== FET presence ===
The backplate will, at least upon connection, send information about which FETs have a wire present.
This data is received with command ids 0004 and 0009, in that order.
Each sensor is represented by one byte which is either 00 (not present) or 01 (present).

The content of 0004 is in order of the "wire id numbers" used for control:
W1, Y1, G, OB, W2, ?0, ?0, Y2, C, RC, ?0, *, ?0

The content of 0009 is arranged differently and has 2 more values:
W1, Y1, C, RC, ?0, G, OB, W2, ?0, Y2, ?0, *, ?0, ?0, ?0

0009 seems to indicate a wire is physically plugged in, while 0004 indicates that it is connected to something (?).

After these are received, the display sends back command 008f with the exact data from message 0004.
Message 008f does not itself receive any response.

In a power outage condition, 0004 will report all absent (including unknown ones), whereas 0009 will continue to report the same as when power is available.

=== Get build info ===
Message 0099 (no data) requests the backplate report information about its build.
The response will be message 0019 in ASCII (one line, no trailing newline).

=== Get hardware version? ===
Message 009e (no data) requests the backplate report a "Backplate-"X.Y version string.
Since the firmware file on the display CPU uses these strings as "MinApplicability" and "MaxApplicability" ranges, it is probable they refer to the hardware.

Witnessed versions:
"Backplate-2.8" - Florida Lowes

=== Get BSL version ===
Message 009b (no data) requests the backplate report its BSL version number.
The response will be message 001b in ASCII.

=== Get TFE version ===
Message 0098 (no data) requests the backplate report its TFE version number.
The response will be message 0018 in ASCII.

=== Get serial number ===
Message 009f (no data) requests the backplate report its serial number (a 64-bit hexadecimal value).
The response will be message 001f in uppercase ASCII.

=== Periodic status ===
Sending message 0083 (no data) will trigger various periodic messages:
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
000a - (every second; 16-bit data)

The Nest client sends 0083 every 30 seconds, but at least the periodic temperature status will continue on for an hour before stopping.

=== Temperature reading ===
The backplate will send message 0002 every 30 seconds.
The data contains two 16-bit numbers, which nlclient logs in decimal.
The first number is the temperature in centi-celcius.
The second number is the humidity in per-millis.

See also: [[#"Buffers"|"Buffers"]]

=== Reset ===
At least upon connection, the display sends message 00ff to the backplate to reset.

The backplate answers with:
0001 msg "<version> <build timestamp "YYYY-MM-DD HH:MM:SS"> K"
[[#FET presence|0004 FET presence]]
[[#FET presence|0009 FET presence]]
0001 msg "*sense 06d1 06d0 0001 0001 0000 0000 0000 0001 06d9 06d8 06d8; detect 09d3 065c"
0001 msg "BRK"

== Run BeagleBone/Debian programs ==
ln -s . /lib/arm-linux-gnueabihf
ln -s ld-2.11.1.so /lib/ld-linux-armhf.so.3

Nest Hacking

2014-08-08T03:10:36Z

Luke-Jr:

== Hardware ==

[https://www.ifixit.com/Teardown/Nest+Learning+Thermostat+2nd+Generation+Teardown/13818 Pictures]

=== Backplate ===
* ST Microelectronics STM32L151VB ultra-low-power 32 MHz ARM Cortex-M3 MCU
* Sensirion SHT20 humidity and temperature sensor
* Texas Instruments LW051A 8-channel CMOS analog multiplexer/demultiplexer

=== Display ===
* Texas Instruments AM3703CUS Sitara ARM Cortex A8 microprocessor
* Texas Instruments TPS65921B power management and USB single chip
* Samsung K4X51163PK 512 Mb mobile DRAM
* Ember EM357 integrated ZigBee/802.15.4 system-on-chip
* Micron MT29F2G16ABBEAH4 2 Gb NAND flash memory
* Skyworks 2436L high power 2.4 GHz 802.15.4 front-end module
* Texas Instruments WL1270B 802.11 b/g/n Wi-Fi solution
* Avago ADBM-A350 optical finger navigation module (knob movement sensor)

== Info ==
* /dev/event1 is the knob; /dev/event2 is the button
* /sys/class/hwmon/hwmon0/device/in0_battery_type * 0.003 is battery voltage
** Nest turns off wifi below 3.7 V, and waits until 3.8 V to automatically reconnect
* Display serial number is located in U-Boot environment variable "serial#"

== Nest software ==
/nestlabs/sbin/nlclient -config /nestlabs/etc/client.config -config /nestlabs/etc/Display/Display-2/client.config

=== Backplate communications ===
Backplate communications can be decoded from a (filtered) strace log using [http://luke.dashjr.org/programs/freeabode/kindling/NestDecode.pl NestDecode.pl], or decoded in real time using [http://luke.dashjr.org/programs/freeabode/kindling/nest-intercept.c nest-intercept.c].

nest-intercept.c requires one argument, the thread id reading from the backplate controller.
The easiest way to get this is to strace the nlclient process with -ff and look for a thread reading from fd 54.

Note that nest-intercept.c also has a "hack" variable which can be set to 0 (default is 2) in order to corrupt the TFE version response and trigger nlclient into uploading the firmware again.

=== Backplate firmware ===
Found in /nestlabs/share/bp/data/firmware/nlbpfirmware.plist

There are 12 different firmwares in the file:
* Test vs Production
* Backplate 2 vs Backplate 3
* TFE (BP_D2 for Bp2, AMBER_BP for Bp3) vs BSL
* For TFE firmwares, hex vs srec (which for some reason DO differ!)

Python script to extract them into individual files: [http://luke.dashjr.org/programs/freeabode/kindling/extract-fw.py extract-fw.py]

=== Backplate initialisation ===
When the backplate is first connected, the following sequence occurs:
tcflush(fd, TCIFLUSH)
Set baud to 115200 (-opost -isig -icanon -echo ...)
tcflush(fd, TCIOFLUSH)
tcsendbreak(fd, 1)
Send [[#Reset|00ff - Reset]]
Recv 0001 - (message from backplate; ASCII)
Recv [[#FET presence|0004 - FET presence]]
Recv [[#FET presence|0009 - FET presence]]
Send [[#FET presence|008f - FET presence]]
Send [[#Periodic status|0083 - Periodic status request]]
Send 0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
Recv 0001 - (message from backplate; ASCII)
Recv 0001 - (message from backplate; ASCII)
Recv 0010 - (24-bit data)
Send [[#Get TFE version|0098 - Get TFE version]]
Recv 000a - (every second; 16-bit data)
Recv 0007 - (every second; 16-bit data)
Recv [[#Get TFE version|0018 - Get TFE version (response)]]
Send [[#Get build info|0099 - Get build info]]
Recv [[#Get build info|0019 - Get build info (response)]]
Sometimes:
Send 009d - (no data; responds with 001d (constant?) data=bbbb)
Recv 001d - Response to 009d; always(?) bbbb
Sometimes:
Send [[#Get BSL version|009b - Get BSL version]]
Recv [[#Get BSL version|001b - Get BSL version (response)]]
Sometimes:
Send 009c - (no data; responds with 001c (constant?) data="BSL")
Recv 001c - Response to 009c; always(?) "BSL"
Send [[#Get serial number|009f - Get serial number]]
Recv [[#Get serial number|001f - Get serial number (response)]]
Send [[#Get hardware version?|009e - Get hardware version?]]
Recv [[#Get hardware version?|001e - Get hardware version? (response)]]

== Nest backplate interface ==
* Connected on /dev/ttyO2
* All communications with backplate begin with (d5)d5aa96 (d5 is doubled only for data FROM backplate)
* Everything is little endian
* 16-bit command
* 16-bit data length
* <data>
* 16-bit checksum

Monitor:
strace -ff -p $(pidof nlclient) -x -s9999 -e read,write 2>&1 | grep '(54'

NOTE: Most of this documentation is reverse engineered from firmware version BSL-2.1 and/or TFE_BP_D2-4.0.21 for Backplate-2.x.

=== Checksum ===
<Bytes-from-end>.<bit-value> <xor-with>
00.01 2110 (1021)
00.02 4220 (2042: 1021<<1)
00.04 8440 (4084: 2048<<1)
00.08 0881 (8108: 4084<<1)
00.10 3112 (1231: 8108<<1^1021)
00.20 6224 (2462: 1231<<1)
00.40 c448 (48c4: 2462<<1)
00.80 8891 (9188: 48c4<<1)
01.01 3133 (3313: 9188<<1^1021)
01.02 6266
01.04 c4cc
01.08 a989
01.10 7303
01.20 e606
01.40 cc0d
01.80 981b
02.01 3037
02.02 606e
...
03.01 b476
03.02 68ed
03.04 f1ca
03.08 c385
03.10 a71b
03.20 4e37
03.40 9c6e
03.80 38dd
...
07.20 687b

If you compute the contribution of the individual bit changes in the data you end up with the xor table above; byte offset from the end of the data, bit pattern, xor value. Correcting for little endianess in the output you end up with the hex values in parenthesis. The least significant bit is 0x1021 and each subsequent bit is a shift left, if the XOR value has the 0x8000 bit set then it is XORed with 0x1021. This is the CRC-CCITT polynomial.

8 7 6 5 4 3 2 1 0
d5 aa 96 82 00 02 00 00 00: 08b2
|| |
|| 68ed
|408b
20d4

08b2: 68ed ^ 408b ^ 20d4

Starting at the least significant bit and filling in the XOR values for each bit gives the above diagram; the diagram stops at the 20d4 XOR value because at that point it matches the final CRC. This tells us that the CRC covers the 6 bytes prior.

#!/usr/bin/env perl
use Digest::CRC qw(crc);
my $data = pack("H*", "820002000000");
printf("%04x\n", crc($data,16,0,0,0,0x1021,0,0));

We can also compute the same CRC in Perl; note the result will be byte swapped since the data encodes the number as little endian.

=== Command ids ===

==== Display to backplate ====
[[#FET control|0082 - FET control]]
[[#Periodic status|0083 - Periodic status request]]
[[#FET presence|008f - FET presence]]
0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
[[#Backplate firmware upload|0091 - Backplate firmware upload (start)]]
[[#Backplate firmware upload|0092 - Backplate firmware upload]]
[[#Backplate firmware upload|0093 - Backplate firmware upload (finish)]]
[[#Get TFE version|0098 - Get TFE version]]
[[#Get build info|0099 - Get build info]]
[[#Get BSL version|009b - Get BSL version]]
009c - (no data; responds with 001c (constant?) data="BSL")
009d - (no data; responds with 001d (constant?) data=bbbb)
[[#Get hardware version?|009e - Get hardware version?]]
[[#Get serial number|009f - Get serial number]]
00a1 - (16-bit data)
[[#"Buffers"|00a2 - Request "buffers" (every 30 seconds; no data; triggers [0025] [0027] 0022 0023 [0029] [002b] 000c 002f)]]
[[#"Buffers"|00a3 - ACK to 002f (no data)]]
00a4 - (16-bit data)
00b1 - button pressed/unpressed (no data)
00b3 - (32-bit data; always ffffffff?)
00b5 - (16-bit data; always 0f00?)
00b9 - (32-bit data; always 0000ffff?)
00ba - (48-bit data; always 000000000000?)
00c2 - (48-bit data)
[[#Reset|00ff - Reset]]

==== Backplate to display ====
0001 - (message from backplate; ASCII)
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
[[#FET presence|0004 - FET presence]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
[[#FET presence|0009 - FET presence]]
000a - (every second; 2x(?) 16-bit data)
[[#Backplate state|000b - Backplate state]]
000c - (16-bit values: pir, px1, px1 divisor, px2, px2 divisor, alir, av; included in [[#"Buffers"|"buffers" data]])
0010 - (24-bit data)
[[#Backplate firmware upload|0011 - Backplate firmware upload (ACK)]]
0014 - "WakeVector" (16-bit data)
[[#Get TFE version|0018 - Get TFE version (response)]]
[[#Get build info|0019 - Get build info (response)]]
[[#Get BSL version|001b - Get BSL version (response)]]
001c - Response to 009c; always(?) "BSL"
001d - Response to 009d; always(?) bbbb
[[#Get hardware version?|001e - Get hardware version? (response)]]
[[#Get serial number|001f - Get serial number (response)]]
[[#"Buffers"|0022 - buffered temperature reading (possibly multiple times)]]
[[#"Buffers"|0023 - 48-bit data (likely 3x 16-bit; possibly multiple times)]]
[[#"Buffers"|0025 - 16-bit data (possibly multiple times)]]
[[#"Buffers"|0027 - 64-bit data (possibly multiple times)]]
[[#"Buffers"|0029 - 48-bit data (likely 3x 16-bit; possibly multiple times)]]
[[#"Buffers"|002b - 64-bit data (possibly multiple times)]]
[[#"Buffers"|002f - End of "buffers" (16-bit data)]]

=== Backplate firmware upload ===
For uploading the firmware, the following sequence is used:
Send 0091 data=0000<firmware type>
Recv 0011 data=0000
Send 0092 data=0100...
Recv 0011 data=0100
Send 0092 data=0200...
Recv 0011 data=0200
...
Send 0092 data=a901...
Recv 0011 data=a901
Send 0093 data=aa01
Recv 0011 data=aa01
Following the upload, the [[#Backplate initialisation|backplate initialisation process]] begins immediately (that is, without message 00ff being sent to order a reset).
Presumably the 0011 message is an ACK, and the first 16 bits of each message is the line number.
The format itself appears to be Motorola S-record (SREC).
Uploading the BSL firmware was followed by the TFE firmware, so it may be required (though uploading the TFE firmware does ''not'' require uploading the BSL).

Firmware type is either 4d for TFE or 42 for BSL.

=== Backplate state ===
Data:
* 8-bit "state"
* 8-bit "flags"
* 8-bit "px0" (may be wider?)
* 40-bit UNKNOWN (includes at least "p2" and "voc")
* 16-bit centi-volts "vi"
* 16-bit milli-volts "vo"
* 16-bit milli-volts "vb"
* 8-bit ("pins" or "wires")
* 8-bit ("wires" or "pins")
* 16-bit UNKNOWN

=== "Buffers" ===
The 00a2 message requests the backplate send the contents of various "buffers", which are returned in messages [0025], [0027], 0022, 0023, [0029], and [002b] (empty ones will NOT be sent; brackets infer commonly-empty buffers).
00a2 also triggers 000c immediately following these.
After all the buffers (including 000c) have been sent, the message 002f indicates "end of buffers".
The display is then expected to acknowledge it with message 00a3.

Buffers:
[[#Temperature reading|0022 - Temperature reading]]
0023 - BufferedSourceTemperature (not sure what that means)
0025 - ? BufferedPassiveInfrared or BufferedNearPir
0027 - ? BufferedPassiveInfrared or BufferedNearPir
0029 - BufferedAmbientLightSensor
002b - BufferedPowerData

=== FET control ===
Turn on W1: d5aa96 8200 0200 00 01 29a2
Turn off W1: d5aa96 8200 0200 00 00 08b2
Turn on Y1: d5aa96 8200 0200 01 01 1891
Turn off Y1: d5aa96 8200 0200 01 00 3981
Turn on G : d5aa96 8200 0200 02 01 4bc4
Turn off G : d5aa96 8200 0200 02 00 6ad4
Turn on OB: d5aa96 8200 0200 03 01 7af7
Turn off OB: d5aa96 8200 0200 03 00 5be7
Turn on W2: d5aa96 8200 0200 04 01 ed6e
Turn off W2: d5aa96 8200 0200 04 00 cc7e
Turn on Y2: d5aa96 8200 0200 07 01 be3b
Turn off Y2: d5aa96 8200 0200 07 00 9f2b
Turn on * : d5aa96 8200 0200 0b 01 d37e
Turn off * : d5aa96 8200 0200 0b 00 f26e

For the sake of documentation, we will refer to the unique id numbers for each wire as "wire id numbers".
So wire id 0 is W1, wire id 1 is Y1, wire id B is *, etc.

=== FET presence ===
The backplate will, at least upon connection, send information about which FETs have a wire present.
This data is received with command ids 0004 and 0009, in that order.
Each sensor is represented by one byte which is either 00 (not present) or 01 (present).

The content of 0004 is in order of the "wire id numbers" used for control:
W1, Y1, G, OB, W2, ?0, ?0, Y2, C, RC, ?0, *, ?0

The content of 0009 is arranged differently and has 2 more values:
W1, Y1, C, RC, ?0, G, OB, W2, ?0, Y2, ?0, *, ?0, ?0, ?0

0009 seems to indicate a wire is physically plugged in, while 0004 indicates that it is connected to something (?).

After these are received, the display sends back command 008f with the exact data from message 0004.
Message 008f does not itself receive any response.

In a power outage condition, 0004 will report all absent (including unknown ones), whereas 0009 will continue to report the same as when power is available.

=== Get build info ===
Message 0099 (no data) requests the backplate report information about its build.
The response will be message 0019 in ASCII (one line, no trailing newline).

=== Get hardware version? ===
Message 009e (no data) requests the backplate report a "Backplate-"X.Y version string.
Since the firmware file on the display CPU uses these strings as "MinApplicability" and "MaxApplicability" ranges, it is probable they refer to the hardware.

Witnessed versions:
"Backplate-2.8" - Florida Lowes

=== Get BSL version ===
Message 009b (no data) requests the backplate report its BSL version number.
The response will be message 001b in ASCII.

=== Get TFE version ===
Message 0098 (no data) requests the backplate report its TFE version number.
The response will be message 0018 in ASCII.

=== Get serial number ===
Message 009f (no data) requests the backplate report its serial number (a 64-bit hexadecimal value).
The response will be message 001f in uppercase ASCII.

=== Periodic status ===
Sending message 0083 (no data) will trigger various periodic messages:
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
000a - (every second; 16-bit data)

The Nest client sends 0083 every 30 seconds, but at least the periodic temperature status will continue on for an hour before stopping.

=== Temperature reading ===
The backplate will send message 0002 every 30 seconds.
The data contains two 16-bit numbers, which nlclient logs in decimal.
The first number is the temperature in centi-celcius.
The second number is the humidity in per-millis.

See also: [[#"Buffers"|"Buffers"]]

=== Reset ===
At least upon connection, the display sends message 00ff to the backplate to reset.

The backplate answers with:
0001 msg "<version> <build timestamp "YYYY-MM-DD HH:MM:SS"> K"
[[#FET presence|0004 FET presence]]
[[#FET presence|0009 FET presence]]
0001 msg "*sense 06d1 06d0 0001 0001 0000 0000 0000 0001 06d9 06d8 06d8; detect 09d3 065c"
0001 msg "BRK"

== Run BeagleBone/Debian programs ==
ln -s . /lib/arm-linux-gnueabihf
ln -s ld-2.11.1.so /lib/ld-linux-armhf.so.3

Nest Hacking

2014-08-08T03:03:51Z

Luke-Jr: /* "Buffers" */

== Hardware ==

[https://www.ifixit.com/Teardown/Nest+Learning+Thermostat+2nd+Generation+Teardown/13818 Pictures]

=== Backplate ===
* ST Microelectronics STM32L151VB ultra-low-power 32 MHz ARM Cortex-M3 MCU
* Sensirion SHT20 humidity and temperature sensor
* Texas Instruments LW051A 8-channel CMOS analog multiplexer/demultiplexer

=== Display ===
* Texas Instruments AM3703CUS Sitara ARM Cortex A8 microprocessor
* Texas Instruments TPS65921B power management and USB single chip
* Samsung K4X51163PK 512 Mb mobile DRAM
* Ember EM357 integrated ZigBee/802.15.4 system-on-chip
* Micron MT29F2G16ABBEAH4 2 Gb NAND flash memory
* Skyworks 2436L high power 2.4 GHz 802.15.4 front-end module
* Texas Instruments WL1270B 802.11 b/g/n Wi-Fi solution
* Avago ADBM-A350 optical finger navigation module (knob movement sensor)

== Info ==
* /dev/event1 is the knob; /dev/event2 is the button
* /sys/class/hwmon/hwmon0/device/in0_battery_type * 0.003 is battery voltage
** Nest turns off wifi below 3.7 V, and waits until 3.8 V to automatically reconnect
* Display serial number is located in U-Boot environment variable "serial#"

== Nest software ==
/nestlabs/sbin/nlclient -config /nestlabs/etc/client.config -config /nestlabs/etc/Display/Display-2/client.config

=== Backplate communications ===
Backplate communications can be decoded from a (filtered) strace log using [http://luke.dashjr.org/programs/freeabode/kindling/NestDecode.pl NestDecode.pl], or decoded in real time using [http://luke.dashjr.org/programs/freeabode/kindling/nest-intercept.c nest-intercept.c].

nest-intercept.c requires one argument, the thread id reading from the backplate controller.
The easiest way to get this is to strace the nlclient process with -ff and look for a thread reading from fd 54.

Note that nest-intercept.c also has a "hack" variable which can be set to 0 (default is 2) in order to corrupt the TFE version response and trigger nlclient into uploading the firmware again.

=== Backplate firmware ===
Found in /nestlabs/share/bp/data/firmware/nlbpfirmware.plist

There are 12 different firmwares in the file:
* Test vs Production
* Backplate 2 vs Backplate 3
* TFE (BP_D2 for Bp2, AMBER_BP for Bp3) vs BSL
* For TFE firmwares, hex vs srec (which for some reason DO differ!)

Python script to extract them into individual files: [http://luke.dashjr.org/programs/freeabode/kindling/extract-fw.py extract-fw.py]

=== Backplate initialisation ===
When the backplate is first connected, the following sequence occurs:
tcflush(fd, TCIFLUSH)
Set baud to 115200 (-opost -isig -icanon -echo ...)
tcflush(fd, TCIOFLUSH)
tcsendbreak(fd, 1)
Send [[#Reset|00ff - Reset]]
Recv 0001 - (message from backplate; ASCII)
Recv [[#FET presence|0004 - FET presence]]
Recv [[#FET presence|0009 - FET presence]]
Send [[#FET presence|008f - FET presence]]
Send [[#Periodic status|0083 - Periodic status request]]
Send 0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
Recv 0001 - (message from backplate; ASCII)
Recv 0001 - (message from backplate; ASCII)
Recv 0010 - (24-bit data)
Send [[#Get TFE version|0098 - Get TFE version]]
Recv 000a - (every second; 16-bit data)
Recv 0007 - (every second; 16-bit data)
Recv [[#Get TFE version|0018 - Get TFE version (response)]]
Send [[#Get build info|0099 - Get build info]]
Recv [[#Get build info|0019 - Get build info (response)]]
Sometimes:
Send 009d - (no data; responds with 001d (constant?) data=bbbb)
Recv 001d - Response to 009d; always(?) bbbb
Sometimes:
Send [[#Get BSL version|009b - Get BSL version]]
Recv [[#Get BSL version|001b - Get BSL version (response)]]
Sometimes:
Send 009c - (no data; responds with 001c (constant?) data="BSL")
Recv 001c - Response to 009c; always(?) "BSL"
Send [[#Get serial number|009f - Get serial number]]
Recv [[#Get serial number|001f - Get serial number (response)]]
Send [[#Get hardware version?|009e - Get hardware version?]]
Recv [[#Get hardware version?|001e - Get hardware version? (response)]]

== Nest backplate interface ==
* Connected on /dev/ttyO2
* All communications with backplate begin with (d5)d5aa96 (d5 is doubled only for data FROM backplate)
* Everything is little endian
* 16-bit command
* 16-bit data length
* <data>
* 16-bit checksum

Monitor:
strace -ff -p $(pidof nlclient) -x -s9999 -e read,write 2>&1 | grep '(54'

NOTE: Most of this documentation is reverse engineered from firmware version BSL-2.1 and/or TFE_BP_D2-4.0.21 for Backplate-2.x.

=== Checksum ===
<Bytes-from-end>.<bit-value> <xor-with>
00.01 2110 (1021)
00.02 4220 (2042: 1021<<1)
00.04 8440 (4084: 2048<<1)
00.08 0881 (8108: 4084<<1)
00.10 3112 (1231: 8108<<1^1021)
00.20 6224 (2462: 1231<<1)
00.40 c448 (48c4: 2462<<1)
00.80 8891 (9188: 48c4<<1)
01.01 3133 (3313: 9188<<1^1021)
01.02 6266
01.04 c4cc
01.08 a989
01.10 7303
01.20 e606
01.40 cc0d
01.80 981b
02.01 3037
02.02 606e
...
03.01 b476
03.02 68ed
03.04 f1ca
03.08 c385
03.10 a71b
03.20 4e37
03.40 9c6e
03.80 38dd
...
07.20 687b

If you compute the contribution of the individual bit changes in the data you end up with the xor table above; byte offset from the end of the data, bit pattern, xor value. Correcting for little endianess in the output you end up with the hex values in parenthesis. The least significant bit is 0x1021 and each subsequent bit is a shift left, if the XOR value has the 0x8000 bit set then it is XORed with 0x1021. This is the CRC-CCITT polynomial.

8 7 6 5 4 3 2 1 0
d5 aa 96 82 00 02 00 00 00: 08b2
|| |
|| 68ed
|408b
20d4

08b2: 68ed ^ 408b ^ 20d4

Starting at the least significant bit and filling in the XOR values for each bit gives the above diagram; the diagram stops at the 20d4 XOR value because at that point it matches the final CRC. This tells us that the CRC covers the 6 bytes prior.

#!/usr/bin/env perl
use Digest::CRC qw(crc);
my $data = pack("H*", "820002000000");
printf("%04x\n", crc($data,16,0,0,0,0x1021,0,0));

We can also compute the same CRC in Perl; note the result will be byte swapped since the data encodes the number as little endian.

=== Command ids ===

==== Display to backplate ====
[[#FET control|0082 - FET control]]
[[#Periodic status|0083 - Periodic status request]]
[[#FET presence|008f - FET presence]]
0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
[[#Backplate firmware upload|0091 - Backplate firmware upload (start)]]
[[#Backplate firmware upload|0092 - Backplate firmware upload]]
[[#Backplate firmware upload|0093 - Backplate firmware upload (finish)]]
[[#Get TFE version|0098 - Get TFE version]]
[[#Get build info|0099 - Get build info]]
[[#Get BSL version|009b - Get BSL version]]
009c - (no data; responds with 001c (constant?) data="BSL")
009d - (no data; responds with 001d (constant?) data=bbbb)
[[#Get hardware version?|009e - Get hardware version?]]
[[#Get serial number|009f - Get serial number]]
00a1 - (16-bit data)
[[#"Buffers"|00a2 - Request "buffers" (every 30 seconds; no data; triggers [0025] [0027] 0022 0023 [0029] [002b] 000c 002f)]]
[[#"Buffers"|00a3 - ACK to 002f (no data)]]
00a4 - (16-bit data)
00b1 - button pressed/unpressed (no data)
00b3 - (32-bit data; always ffffffff?)
00b5 - (16-bit data; always 0f00?)
00b9 - (32-bit data; always 0000ffff?)
00ba - (48-bit data; always 000000000000?)
00c2 - (48-bit data)
[[#Reset|00ff - Reset]]

==== Backplate to display ====
0001 - (message from backplate; ASCII)
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
[[#FET presence|0004 - FET presence]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
[[#FET presence|0009 - FET presence]]
000a - (every second; 2x(?) 16-bit data)
[[#Backplate state|000b - Backplate state]]
000c - (16-bit values: pir, px1, px1 divisor, px2, px2 divisor, alir, av; included in [[#"Buffers"|"buffers" data]])
0010 - (24-bit data)
[[#Backplate firmware upload|0011 - Backplate firmware upload (ACK)]]
0014 - (16-bit data)
[[#Get TFE version|0018 - Get TFE version (response)]]
[[#Get build info|0019 - Get build info (response)]]
[[#Get BSL version|001b - Get BSL version (response)]]
001c - Response to 009c; always(?) "BSL"
001d - Response to 009d; always(?) bbbb
[[#Get hardware version?|001e - Get hardware version? (response)]]
[[#Get serial number|001f - Get serial number (response)]]
[[#"Buffers"|0022 - buffered temperature reading (possibly multiple times)]]
[[#"Buffers"|0023 - 48-bit data (likely 3x 16-bit; possibly multiple times)]]
[[#"Buffers"|0025 - 16-bit data (possibly multiple times)]]
[[#"Buffers"|0027 - 64-bit data (possibly multiple times)]]
[[#"Buffers"|0029 - 48-bit data (likely 3x 16-bit; possibly multiple times)]]
[[#"Buffers"|002b - 64-bit data (possibly multiple times)]]
[[#"Buffers"|002f - End of "buffers" (16-bit data)]]

=== Backplate firmware upload ===
For uploading the firmware, the following sequence is used:
Send 0091 data=0000<firmware type>
Recv 0011 data=0000
Send 0092 data=0100...
Recv 0011 data=0100
Send 0092 data=0200...
Recv 0011 data=0200
...
Send 0092 data=a901...
Recv 0011 data=a901
Send 0093 data=aa01
Recv 0011 data=aa01
Following the upload, the [[#Backplate initialisation|backplate initialisation process]] begins immediately (that is, without message 00ff being sent to order a reset).
Presumably the 0011 message is an ACK, and the first 16 bits of each message is the line number.
The format itself appears to be Motorola S-record (SREC).
Uploading the BSL firmware was followed by the TFE firmware, so it may be required (though uploading the TFE firmware does ''not'' require uploading the BSL).

Firmware type is either 4d for TFE or 42 for BSL.

=== Backplate state ===
Data:
* 8-bit "state"
* 8-bit "flags"
* 8-bit "px0" (may be wider?)
* 40-bit UNKNOWN (includes at least "p2" and "voc")
* 16-bit centi-volts "vi"
* 16-bit milli-volts "vo"
* 16-bit milli-volts "vb"
* 8-bit ("pins" or "wires")
* 8-bit ("wires" or "pins")
* 16-bit UNKNOWN

=== "Buffers" ===
The 00a2 message requests the backplate send the contents of various "buffers", which are returned in messages [0025], [0027], 0022, 0023, [0029], and [002b] (empty ones will NOT be sent; brackets infer commonly-empty buffers).
00a2 also triggers 000c immediately following these.
After all the buffers (including 000c) have been sent, the message 002f indicates "end of buffers".
The display is then expected to acknowledge it with message 00a3.

Buffers:
[[#Temperature reading|0022 - Temperature reading]]
0023 - BufferedSourceTemperature (not sure what that means)
0025 - ? BufferedPassiveInfrared or BufferedNearPir
0027 - ? BufferedPassiveInfrared or BufferedNearPir
0029 - BufferedAmbientLightSensor
002b - BufferedPowerData

=== FET control ===
Turn on W1: d5aa96 8200 0200 00 01 29a2
Turn off W1: d5aa96 8200 0200 00 00 08b2
Turn on Y1: d5aa96 8200 0200 01 01 1891
Turn off Y1: d5aa96 8200 0200 01 00 3981
Turn on G : d5aa96 8200 0200 02 01 4bc4
Turn off G : d5aa96 8200 0200 02 00 6ad4
Turn on OB: d5aa96 8200 0200 03 01 7af7
Turn off OB: d5aa96 8200 0200 03 00 5be7
Turn on W2: d5aa96 8200 0200 04 01 ed6e
Turn off W2: d5aa96 8200 0200 04 00 cc7e
Turn on Y2: d5aa96 8200 0200 07 01 be3b
Turn off Y2: d5aa96 8200 0200 07 00 9f2b
Turn on * : d5aa96 8200 0200 0b 01 d37e
Turn off * : d5aa96 8200 0200 0b 00 f26e

For the sake of documentation, we will refer to the unique id numbers for each wire as "wire id numbers".
So wire id 0 is W1, wire id 1 is Y1, wire id B is *, etc.

=== FET presence ===
The backplate will, at least upon connection, send information about which FETs have a wire present.
This data is received with command ids 0004 and 0009, in that order.
Each sensor is represented by one byte which is either 00 (not present) or 01 (present).

The content of 0004 is in order of the "wire id numbers" used for control:
W1, Y1, G, OB, W2, ?0, ?0, Y2, C, RC, ?0, *, ?0

The content of 0009 is arranged differently and has 2 more values:
W1, Y1, C, RC, ?0, G, OB, W2, ?0, Y2, ?0, *, ?0, ?0, ?0

0009 seems to indicate a wire is physically plugged in, while 0004 indicates that it is connected to something (?).

After these are received, the display sends back command 008f with the exact data from message 0004.
Message 008f does not itself receive any response.

In a power outage condition, 0004 will report all absent (including unknown ones), whereas 0009 will continue to report the same as when power is available.

=== Get build info ===
Message 0099 (no data) requests the backplate report information about its build.
The response will be message 0019 in ASCII (one line, no trailing newline).

=== Get hardware version? ===
Message 009e (no data) requests the backplate report a "Backplate-"X.Y version string.
Since the firmware file on the display CPU uses these strings as "MinApplicability" and "MaxApplicability" ranges, it is probable they refer to the hardware.

Witnessed versions:
"Backplate-2.8" - Florida Lowes

=== Get BSL version ===
Message 009b (no data) requests the backplate report its BSL version number.
The response will be message 001b in ASCII.

=== Get TFE version ===
Message 0098 (no data) requests the backplate report its TFE version number.
The response will be message 0018 in ASCII.

=== Get serial number ===
Message 009f (no data) requests the backplate report its serial number (a 64-bit hexadecimal value).
The response will be message 001f in uppercase ASCII.

=== Periodic status ===
Sending message 0083 (no data) will trigger various periodic messages:
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
000a - (every second; 16-bit data)

The Nest client sends 0083 every 30 seconds, but at least the periodic temperature status will continue on for an hour before stopping.

=== Temperature reading ===
The backplate will send message 0002 every 30 seconds.
The data contains two 16-bit numbers, which nlclient logs in decimal.
The first number is the temperature in centi-celcius.
The second number is the humidity in per-millis.

See also: [[#"Buffers"|"Buffers"]]

=== Reset ===
At least upon connection, the display sends message 00ff to the backplate to reset.

The backplate answers with:
0001 msg "<version> <build timestamp "YYYY-MM-DD HH:MM:SS"> K"
[[#FET presence|0004 FET presence]]
[[#FET presence|0009 FET presence]]
0001 msg "*sense 06d1 06d0 0001 0001 0000 0000 0000 0001 06d9 06d8 06d8; detect 09d3 065c"
0001 msg "BRK"

== Run BeagleBone/Debian programs ==
ln -s . /lib/arm-linux-gnueabihf
ln -s ld-2.11.1.so /lib/ld-linux-armhf.so.3

Nest Hacking

2014-08-08T02:51:56Z

Luke-Jr: /* "Buffers" */

== Hardware ==

[https://www.ifixit.com/Teardown/Nest+Learning+Thermostat+2nd+Generation+Teardown/13818 Pictures]

=== Backplate ===
* ST Microelectronics STM32L151VB ultra-low-power 32 MHz ARM Cortex-M3 MCU
* Sensirion SHT20 humidity and temperature sensor
* Texas Instruments LW051A 8-channel CMOS analog multiplexer/demultiplexer

=== Display ===
* Texas Instruments AM3703CUS Sitara ARM Cortex A8 microprocessor
* Texas Instruments TPS65921B power management and USB single chip
* Samsung K4X51163PK 512 Mb mobile DRAM
* Ember EM357 integrated ZigBee/802.15.4 system-on-chip
* Micron MT29F2G16ABBEAH4 2 Gb NAND flash memory
* Skyworks 2436L high power 2.4 GHz 802.15.4 front-end module
* Texas Instruments WL1270B 802.11 b/g/n Wi-Fi solution
* Avago ADBM-A350 optical finger navigation module (knob movement sensor)

== Info ==
* /dev/event1 is the knob; /dev/event2 is the button
* /sys/class/hwmon/hwmon0/device/in0_battery_type * 0.003 is battery voltage
** Nest turns off wifi below 3.7 V, and waits until 3.8 V to automatically reconnect
* Display serial number is located in U-Boot environment variable "serial#"

== Nest software ==
/nestlabs/sbin/nlclient -config /nestlabs/etc/client.config -config /nestlabs/etc/Display/Display-2/client.config

=== Backplate communications ===
Backplate communications can be decoded from a (filtered) strace log using [http://luke.dashjr.org/programs/freeabode/kindling/NestDecode.pl NestDecode.pl], or decoded in real time using [http://luke.dashjr.org/programs/freeabode/kindling/nest-intercept.c nest-intercept.c].

nest-intercept.c requires one argument, the thread id reading from the backplate controller.
The easiest way to get this is to strace the nlclient process with -ff and look for a thread reading from fd 54.

Note that nest-intercept.c also has a "hack" variable which can be set to 0 (default is 2) in order to corrupt the TFE version response and trigger nlclient into uploading the firmware again.

=== Backplate firmware ===
Found in /nestlabs/share/bp/data/firmware/nlbpfirmware.plist

There are 12 different firmwares in the file:
* Test vs Production
* Backplate 2 vs Backplate 3
* TFE (BP_D2 for Bp2, AMBER_BP for Bp3) vs BSL
* For TFE firmwares, hex vs srec (which for some reason DO differ!)

Python script to extract them into individual files: [http://luke.dashjr.org/programs/freeabode/kindling/extract-fw.py extract-fw.py]

=== Backplate initialisation ===
When the backplate is first connected, the following sequence occurs:
tcflush(fd, TCIFLUSH)
Set baud to 115200 (-opost -isig -icanon -echo ...)
tcflush(fd, TCIOFLUSH)
tcsendbreak(fd, 1)
Send [[#Reset|00ff - Reset]]
Recv 0001 - (message from backplate; ASCII)
Recv [[#FET presence|0004 - FET presence]]
Recv [[#FET presence|0009 - FET presence]]
Send [[#FET presence|008f - FET presence]]
Send [[#Periodic status|0083 - Periodic status request]]
Send 0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
Recv 0001 - (message from backplate; ASCII)
Recv 0001 - (message from backplate; ASCII)
Recv 0010 - (24-bit data)
Send [[#Get TFE version|0098 - Get TFE version]]
Recv 000a - (every second; 16-bit data)
Recv 0007 - (every second; 16-bit data)
Recv [[#Get TFE version|0018 - Get TFE version (response)]]
Send [[#Get build info|0099 - Get build info]]
Recv [[#Get build info|0019 - Get build info (response)]]
Sometimes:
Send 009d - (no data; responds with 001d (constant?) data=bbbb)
Recv 001d - Response to 009d; always(?) bbbb
Sometimes:
Send [[#Get BSL version|009b - Get BSL version]]
Recv [[#Get BSL version|001b - Get BSL version (response)]]
Sometimes:
Send 009c - (no data; responds with 001c (constant?) data="BSL")
Recv 001c - Response to 009c; always(?) "BSL"
Send [[#Get serial number|009f - Get serial number]]
Recv [[#Get serial number|001f - Get serial number (response)]]
Send [[#Get hardware version?|009e - Get hardware version?]]
Recv [[#Get hardware version?|001e - Get hardware version? (response)]]

== Nest backplate interface ==
* Connected on /dev/ttyO2
* All communications with backplate begin with (d5)d5aa96 (d5 is doubled only for data FROM backplate)
* Everything is little endian
* 16-bit command
* 16-bit data length
* <data>
* 16-bit checksum

Monitor:
strace -ff -p $(pidof nlclient) -x -s9999 -e read,write 2>&1 | grep '(54'

NOTE: Most of this documentation is reverse engineered from firmware version BSL-2.1 and/or TFE_BP_D2-4.0.21 for Backplate-2.x.

=== Checksum ===
<Bytes-from-end>.<bit-value> <xor-with>
00.01 2110 (1021)
00.02 4220 (2042: 1021<<1)
00.04 8440 (4084: 2048<<1)
00.08 0881 (8108: 4084<<1)
00.10 3112 (1231: 8108<<1^1021)
00.20 6224 (2462: 1231<<1)
00.40 c448 (48c4: 2462<<1)
00.80 8891 (9188: 48c4<<1)
01.01 3133 (3313: 9188<<1^1021)
01.02 6266
01.04 c4cc
01.08 a989
01.10 7303
01.20 e606
01.40 cc0d
01.80 981b
02.01 3037
02.02 606e
...
03.01 b476
03.02 68ed
03.04 f1ca
03.08 c385
03.10 a71b
03.20 4e37
03.40 9c6e
03.80 38dd
...
07.20 687b

If you compute the contribution of the individual bit changes in the data you end up with the xor table above; byte offset from the end of the data, bit pattern, xor value. Correcting for little endianess in the output you end up with the hex values in parenthesis. The least significant bit is 0x1021 and each subsequent bit is a shift left, if the XOR value has the 0x8000 bit set then it is XORed with 0x1021. This is the CRC-CCITT polynomial.

8 7 6 5 4 3 2 1 0
d5 aa 96 82 00 02 00 00 00: 08b2
|| |
|| 68ed
|408b
20d4

08b2: 68ed ^ 408b ^ 20d4

Starting at the least significant bit and filling in the XOR values for each bit gives the above diagram; the diagram stops at the 20d4 XOR value because at that point it matches the final CRC. This tells us that the CRC covers the 6 bytes prior.

#!/usr/bin/env perl
use Digest::CRC qw(crc);
my $data = pack("H*", "820002000000");
printf("%04x\n", crc($data,16,0,0,0,0x1021,0,0));

We can also compute the same CRC in Perl; note the result will be byte swapped since the data encodes the number as little endian.

=== Command ids ===

==== Display to backplate ====
[[#FET control|0082 - FET control]]
[[#Periodic status|0083 - Periodic status request]]
[[#FET presence|008f - FET presence]]
0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
[[#Backplate firmware upload|0091 - Backplate firmware upload (start)]]
[[#Backplate firmware upload|0092 - Backplate firmware upload]]
[[#Backplate firmware upload|0093 - Backplate firmware upload (finish)]]
[[#Get TFE version|0098 - Get TFE version]]
[[#Get build info|0099 - Get build info]]
[[#Get BSL version|009b - Get BSL version]]
009c - (no data; responds with 001c (constant?) data="BSL")
009d - (no data; responds with 001d (constant?) data=bbbb)
[[#Get hardware version?|009e - Get hardware version?]]
[[#Get serial number|009f - Get serial number]]
00a1 - (16-bit data)
[[#"Buffers"|00a2 - Request "buffers" (every 30 seconds; no data; triggers [0025] [0027] 0022 0023 [0029] [002b] 000c 002f)]]
[[#"Buffers"|00a3 - ACK to 002f (no data)]]
00a4 - (16-bit data)
00b1 - button pressed/unpressed (no data)
00b3 - (32-bit data; always ffffffff?)
00b5 - (16-bit data; always 0f00?)
00b9 - (32-bit data; always 0000ffff?)
00ba - (48-bit data; always 000000000000?)
00c2 - (48-bit data)
[[#Reset|00ff - Reset]]

==== Backplate to display ====
0001 - (message from backplate; ASCII)
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
[[#FET presence|0004 - FET presence]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
[[#FET presence|0009 - FET presence]]
000a - (every second; 2x(?) 16-bit data)
[[#Backplate state|000b - Backplate state]]
000c - (16-bit values: pir, px1, px1 divisor, px2, px2 divisor, alir, av; included in [[#"Buffers"|"buffers" data]])
0010 - (24-bit data)
[[#Backplate firmware upload|0011 - Backplate firmware upload (ACK)]]
0014 - (16-bit data)
[[#Get TFE version|0018 - Get TFE version (response)]]
[[#Get build info|0019 - Get build info (response)]]
[[#Get BSL version|001b - Get BSL version (response)]]
001c - Response to 009c; always(?) "BSL"
001d - Response to 009d; always(?) bbbb
[[#Get hardware version?|001e - Get hardware version? (response)]]
[[#Get serial number|001f - Get serial number (response)]]
[[#"Buffers"|0022 - buffered temperature reading (possibly multiple times)]]
[[#"Buffers"|0023 - 48-bit data (likely 3x 16-bit; possibly multiple times)]]
[[#"Buffers"|0025 - 16-bit data (possibly multiple times)]]
[[#"Buffers"|0027 - 64-bit data (possibly multiple times)]]
[[#"Buffers"|0029 - 48-bit data (likely 3x 16-bit; possibly multiple times)]]
[[#"Buffers"|002b - 64-bit data (possibly multiple times)]]
[[#"Buffers"|002f - End of "buffers" (16-bit data)]]

=== Backplate firmware upload ===
For uploading the firmware, the following sequence is used:
Send 0091 data=0000<firmware type>
Recv 0011 data=0000
Send 0092 data=0100...
Recv 0011 data=0100
Send 0092 data=0200...
Recv 0011 data=0200
...
Send 0092 data=a901...
Recv 0011 data=a901
Send 0093 data=aa01
Recv 0011 data=aa01
Following the upload, the [[#Backplate initialisation|backplate initialisation process]] begins immediately (that is, without message 00ff being sent to order a reset).
Presumably the 0011 message is an ACK, and the first 16 bits of each message is the line number.
The format itself appears to be Motorola S-record (SREC).
Uploading the BSL firmware was followed by the TFE firmware, so it may be required (though uploading the TFE firmware does ''not'' require uploading the BSL).

Firmware type is either 4d for TFE or 42 for BSL.

=== Backplate state ===
Data:
* 8-bit "state"
* 8-bit "flags"
* 8-bit "px0" (may be wider?)
* 40-bit UNKNOWN (includes at least "p2" and "voc")
* 16-bit centi-volts "vi"
* 16-bit milli-volts "vo"
* 16-bit milli-volts "vb"
* 8-bit ("pins" or "wires")
* 8-bit ("wires" or "pins")
* 16-bit UNKNOWN

=== "Buffers" ===
The 00a2 message requests the backplate send the contents of various "buffers", which are returned in messages [0025], [0027], 0022, 0023, [0029], and [002b] (empty ones will NOT be sent; brackets infer commonly-empty buffers).
00a2 also triggers 000c immediately following these.
After all the buffers (including 000c) have been sent, the message 002f indicates "end of buffers".
The display is then expected to acknowledge it with message 00a3.

Buffers:
[[#Temperature reading|0022 - Temperature reading]]
0023 - BufferedSourceTemperature (not sure what that means)
0025 - ?
0027 - ?
0029 - ?
002b - ?

=== FET control ===
Turn on W1: d5aa96 8200 0200 00 01 29a2
Turn off W1: d5aa96 8200 0200 00 00 08b2
Turn on Y1: d5aa96 8200 0200 01 01 1891
Turn off Y1: d5aa96 8200 0200 01 00 3981
Turn on G : d5aa96 8200 0200 02 01 4bc4
Turn off G : d5aa96 8200 0200 02 00 6ad4
Turn on OB: d5aa96 8200 0200 03 01 7af7
Turn off OB: d5aa96 8200 0200 03 00 5be7
Turn on W2: d5aa96 8200 0200 04 01 ed6e
Turn off W2: d5aa96 8200 0200 04 00 cc7e
Turn on Y2: d5aa96 8200 0200 07 01 be3b
Turn off Y2: d5aa96 8200 0200 07 00 9f2b
Turn on * : d5aa96 8200 0200 0b 01 d37e
Turn off * : d5aa96 8200 0200 0b 00 f26e

For the sake of documentation, we will refer to the unique id numbers for each wire as "wire id numbers".
So wire id 0 is W1, wire id 1 is Y1, wire id B is *, etc.

=== FET presence ===
The backplate will, at least upon connection, send information about which FETs have a wire present.
This data is received with command ids 0004 and 0009, in that order.
Each sensor is represented by one byte which is either 00 (not present) or 01 (present).

The content of 0004 is in order of the "wire id numbers" used for control:
W1, Y1, G, OB, W2, ?0, ?0, Y2, C, RC, ?0, *, ?0

The content of 0009 is arranged differently and has 2 more values:
W1, Y1, C, RC, ?0, G, OB, W2, ?0, Y2, ?0, *, ?0, ?0, ?0

0009 seems to indicate a wire is physically plugged in, while 0004 indicates that it is connected to something (?).

After these are received, the display sends back command 008f with the exact data from message 0004.
Message 008f does not itself receive any response.

In a power outage condition, 0004 will report all absent (including unknown ones), whereas 0009 will continue to report the same as when power is available.

=== Get build info ===
Message 0099 (no data) requests the backplate report information about its build.
The response will be message 0019 in ASCII (one line, no trailing newline).

=== Get hardware version? ===
Message 009e (no data) requests the backplate report a "Backplate-"X.Y version string.
Since the firmware file on the display CPU uses these strings as "MinApplicability" and "MaxApplicability" ranges, it is probable they refer to the hardware.

Witnessed versions:
"Backplate-2.8" - Florida Lowes

=== Get BSL version ===
Message 009b (no data) requests the backplate report its BSL version number.
The response will be message 001b in ASCII.

=== Get TFE version ===
Message 0098 (no data) requests the backplate report its TFE version number.
The response will be message 0018 in ASCII.

=== Get serial number ===
Message 009f (no data) requests the backplate report its serial number (a 64-bit hexadecimal value).
The response will be message 001f in uppercase ASCII.

=== Periodic status ===
Sending message 0083 (no data) will trigger various periodic messages:
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
000a - (every second; 16-bit data)

The Nest client sends 0083 every 30 seconds, but at least the periodic temperature status will continue on for an hour before stopping.

=== Temperature reading ===
The backplate will send message 0002 every 30 seconds.
The data contains two 16-bit numbers, which nlclient logs in decimal.
The first number is the temperature in centi-celcius.
The second number is the humidity in per-millis.

See also: [[#"Buffers"|"Buffers"]]

=== Reset ===
At least upon connection, the display sends message 00ff to the backplate to reset.

The backplate answers with:
0001 msg "<version> <build timestamp "YYYY-MM-DD HH:MM:SS"> K"
[[#FET presence|0004 FET presence]]
[[#FET presence|0009 FET presence]]
0001 msg "*sense 06d1 06d0 0001 0001 0000 0000 0000 0001 06d9 06d8 06d8; detect 09d3 065c"
0001 msg "BRK"

== Run BeagleBone/Debian programs ==
ln -s . /lib/arm-linux-gnueabihf
ln -s ld-2.11.1.so /lib/ld-linux-armhf.so.3

Nest Hacking

2014-08-08T02:50:38Z

Luke-Jr: Temperature buffer

== Hardware ==

[https://www.ifixit.com/Teardown/Nest+Learning+Thermostat+2nd+Generation+Teardown/13818 Pictures]

=== Backplate ===
* ST Microelectronics STM32L151VB ultra-low-power 32 MHz ARM Cortex-M3 MCU
* Sensirion SHT20 humidity and temperature sensor
* Texas Instruments LW051A 8-channel CMOS analog multiplexer/demultiplexer

=== Display ===
* Texas Instruments AM3703CUS Sitara ARM Cortex A8 microprocessor
* Texas Instruments TPS65921B power management and USB single chip
* Samsung K4X51163PK 512 Mb mobile DRAM
* Ember EM357 integrated ZigBee/802.15.4 system-on-chip
* Micron MT29F2G16ABBEAH4 2 Gb NAND flash memory
* Skyworks 2436L high power 2.4 GHz 802.15.4 front-end module
* Texas Instruments WL1270B 802.11 b/g/n Wi-Fi solution
* Avago ADBM-A350 optical finger navigation module (knob movement sensor)

== Info ==
* /dev/event1 is the knob; /dev/event2 is the button
* /sys/class/hwmon/hwmon0/device/in0_battery_type * 0.003 is battery voltage
** Nest turns off wifi below 3.7 V, and waits until 3.8 V to automatically reconnect
* Display serial number is located in U-Boot environment variable "serial#"

== Nest software ==
/nestlabs/sbin/nlclient -config /nestlabs/etc/client.config -config /nestlabs/etc/Display/Display-2/client.config

=== Backplate communications ===
Backplate communications can be decoded from a (filtered) strace log using [http://luke.dashjr.org/programs/freeabode/kindling/NestDecode.pl NestDecode.pl], or decoded in real time using [http://luke.dashjr.org/programs/freeabode/kindling/nest-intercept.c nest-intercept.c].

nest-intercept.c requires one argument, the thread id reading from the backplate controller.
The easiest way to get this is to strace the nlclient process with -ff and look for a thread reading from fd 54.

Note that nest-intercept.c also has a "hack" variable which can be set to 0 (default is 2) in order to corrupt the TFE version response and trigger nlclient into uploading the firmware again.

=== Backplate firmware ===
Found in /nestlabs/share/bp/data/firmware/nlbpfirmware.plist

There are 12 different firmwares in the file:
* Test vs Production
* Backplate 2 vs Backplate 3
* TFE (BP_D2 for Bp2, AMBER_BP for Bp3) vs BSL
* For TFE firmwares, hex vs srec (which for some reason DO differ!)

Python script to extract them into individual files: [http://luke.dashjr.org/programs/freeabode/kindling/extract-fw.py extract-fw.py]

=== Backplate initialisation ===
When the backplate is first connected, the following sequence occurs:
tcflush(fd, TCIFLUSH)
Set baud to 115200 (-opost -isig -icanon -echo ...)
tcflush(fd, TCIOFLUSH)
tcsendbreak(fd, 1)
Send [[#Reset|00ff - Reset]]
Recv 0001 - (message from backplate; ASCII)
Recv [[#FET presence|0004 - FET presence]]
Recv [[#FET presence|0009 - FET presence]]
Send [[#FET presence|008f - FET presence]]
Send [[#Periodic status|0083 - Periodic status request]]
Send 0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
Recv 0001 - (message from backplate; ASCII)
Recv 0001 - (message from backplate; ASCII)
Recv 0010 - (24-bit data)
Send [[#Get TFE version|0098 - Get TFE version]]
Recv 000a - (every second; 16-bit data)
Recv 0007 - (every second; 16-bit data)
Recv [[#Get TFE version|0018 - Get TFE version (response)]]
Send [[#Get build info|0099 - Get build info]]
Recv [[#Get build info|0019 - Get build info (response)]]
Sometimes:
Send 009d - (no data; responds with 001d (constant?) data=bbbb)
Recv 001d - Response to 009d; always(?) bbbb
Sometimes:
Send [[#Get BSL version|009b - Get BSL version]]
Recv [[#Get BSL version|001b - Get BSL version (response)]]
Sometimes:
Send 009c - (no data; responds with 001c (constant?) data="BSL")
Recv 001c - Response to 009c; always(?) "BSL"
Send [[#Get serial number|009f - Get serial number]]
Recv [[#Get serial number|001f - Get serial number (response)]]
Send [[#Get hardware version?|009e - Get hardware version?]]
Recv [[#Get hardware version?|001e - Get hardware version? (response)]]

== Nest backplate interface ==
* Connected on /dev/ttyO2
* All communications with backplate begin with (d5)d5aa96 (d5 is doubled only for data FROM backplate)
* Everything is little endian
* 16-bit command
* 16-bit data length
* <data>
* 16-bit checksum

Monitor:
strace -ff -p $(pidof nlclient) -x -s9999 -e read,write 2>&1 | grep '(54'

NOTE: Most of this documentation is reverse engineered from firmware version BSL-2.1 and/or TFE_BP_D2-4.0.21 for Backplate-2.x.

=== Checksum ===
<Bytes-from-end>.<bit-value> <xor-with>
00.01 2110 (1021)
00.02 4220 (2042: 1021<<1)
00.04 8440 (4084: 2048<<1)
00.08 0881 (8108: 4084<<1)
00.10 3112 (1231: 8108<<1^1021)
00.20 6224 (2462: 1231<<1)
00.40 c448 (48c4: 2462<<1)
00.80 8891 (9188: 48c4<<1)
01.01 3133 (3313: 9188<<1^1021)
01.02 6266
01.04 c4cc
01.08 a989
01.10 7303
01.20 e606
01.40 cc0d
01.80 981b
02.01 3037
02.02 606e
...
03.01 b476
03.02 68ed
03.04 f1ca
03.08 c385
03.10 a71b
03.20 4e37
03.40 9c6e
03.80 38dd
...
07.20 687b

If you compute the contribution of the individual bit changes in the data you end up with the xor table above; byte offset from the end of the data, bit pattern, xor value. Correcting for little endianess in the output you end up with the hex values in parenthesis. The least significant bit is 0x1021 and each subsequent bit is a shift left, if the XOR value has the 0x8000 bit set then it is XORed with 0x1021. This is the CRC-CCITT polynomial.

8 7 6 5 4 3 2 1 0
d5 aa 96 82 00 02 00 00 00: 08b2
|| |
|| 68ed
|408b
20d4

08b2: 68ed ^ 408b ^ 20d4

Starting at the least significant bit and filling in the XOR values for each bit gives the above diagram; the diagram stops at the 20d4 XOR value because at that point it matches the final CRC. This tells us that the CRC covers the 6 bytes prior.

#!/usr/bin/env perl
use Digest::CRC qw(crc);
my $data = pack("H*", "820002000000");
printf("%04x\n", crc($data,16,0,0,0,0x1021,0,0));

We can also compute the same CRC in Perl; note the result will be byte swapped since the data encodes the number as little endian.

=== Command ids ===

==== Display to backplate ====
[[#FET control|0082 - FET control]]
[[#Periodic status|0083 - Periodic status request]]
[[#FET presence|008f - FET presence]]
0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
[[#Backplate firmware upload|0091 - Backplate firmware upload (start)]]
[[#Backplate firmware upload|0092 - Backplate firmware upload]]
[[#Backplate firmware upload|0093 - Backplate firmware upload (finish)]]
[[#Get TFE version|0098 - Get TFE version]]
[[#Get build info|0099 - Get build info]]
[[#Get BSL version|009b - Get BSL version]]
009c - (no data; responds with 001c (constant?) data="BSL")
009d - (no data; responds with 001d (constant?) data=bbbb)
[[#Get hardware version?|009e - Get hardware version?]]
[[#Get serial number|009f - Get serial number]]
00a1 - (16-bit data)
[[#"Buffers"|00a2 - Request "buffers" (every 30 seconds; no data; triggers [0025] [0027] 0022 0023 [0029] [002b] 000c 002f)]]
[[#"Buffers"|00a3 - ACK to 002f (no data)]]
00a4 - (16-bit data)
00b1 - button pressed/unpressed (no data)
00b3 - (32-bit data; always ffffffff?)
00b5 - (16-bit data; always 0f00?)
00b9 - (32-bit data; always 0000ffff?)
00ba - (48-bit data; always 000000000000?)
00c2 - (48-bit data)
[[#Reset|00ff - Reset]]

==== Backplate to display ====
0001 - (message from backplate; ASCII)
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
[[#FET presence|0004 - FET presence]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
[[#FET presence|0009 - FET presence]]
000a - (every second; 2x(?) 16-bit data)
[[#Backplate state|000b - Backplate state]]
000c - (16-bit values: pir, px1, px1 divisor, px2, px2 divisor, alir, av; included in [[#"Buffers"|"buffers" data]])
0010 - (24-bit data)
[[#Backplate firmware upload|0011 - Backplate firmware upload (ACK)]]
0014 - (16-bit data)
[[#Get TFE version|0018 - Get TFE version (response)]]
[[#Get build info|0019 - Get build info (response)]]
[[#Get BSL version|001b - Get BSL version (response)]]
001c - Response to 009c; always(?) "BSL"
001d - Response to 009d; always(?) bbbb
[[#Get hardware version?|001e - Get hardware version? (response)]]
[[#Get serial number|001f - Get serial number (response)]]
[[#"Buffers"|0022 - buffered temperature reading (possibly multiple times)]]
[[#"Buffers"|0023 - 48-bit data (likely 3x 16-bit; possibly multiple times)]]
[[#"Buffers"|0025 - 16-bit data (possibly multiple times)]]
[[#"Buffers"|0027 - 64-bit data (possibly multiple times)]]
[[#"Buffers"|0029 - 48-bit data (likely 3x 16-bit; possibly multiple times)]]
[[#"Buffers"|002b - 64-bit data (possibly multiple times)]]
[[#"Buffers"|002f - End of "buffers" (16-bit data)]]

=== Backplate firmware upload ===
For uploading the firmware, the following sequence is used:
Send 0091 data=0000<firmware type>
Recv 0011 data=0000
Send 0092 data=0100...
Recv 0011 data=0100
Send 0092 data=0200...
Recv 0011 data=0200
...
Send 0092 data=a901...
Recv 0011 data=a901
Send 0093 data=aa01
Recv 0011 data=aa01
Following the upload, the [[#Backplate initialisation|backplate initialisation process]] begins immediately (that is, without message 00ff being sent to order a reset).
Presumably the 0011 message is an ACK, and the first 16 bits of each message is the line number.
The format itself appears to be Motorola S-record (SREC).
Uploading the BSL firmware was followed by the TFE firmware, so it may be required (though uploading the TFE firmware does ''not'' require uploading the BSL).

Firmware type is either 4d for TFE or 42 for BSL.

=== Backplate state ===
Data:
* 8-bit "state"
* 8-bit "flags"
* 8-bit "px0" (may be wider?)
* 40-bit UNKNOWN (includes at least "p2" and "voc")
* 16-bit centi-volts "vi"
* 16-bit milli-volts "vo"
* 16-bit milli-volts "vb"
* 8-bit ("pins" or "wires")
* 8-bit ("wires" or "pins")
* 16-bit UNKNOWN

=== "Buffers" ===
The 00a2 message requests the backplate send the contents of various "buffers", which are returned in messages [0025], [0027], 0022, 0023, [0029], and [002b] (empty ones will NOT be sent; brackets infer commonly-empty buffers).
00a2 also triggers 000c immediately following these.
After all the buffers (including 000c) have been sent, the message 002f indicates "end of buffers".
The display is then expected to acknowledge it with message 00a3.

Buffers:
[[#Temperature reading|0022 - Temperature reading]]
0023 - ?
0025 - ?
0027 - ?
0029 - ?
002b - ?

=== FET control ===
Turn on W1: d5aa96 8200 0200 00 01 29a2
Turn off W1: d5aa96 8200 0200 00 00 08b2
Turn on Y1: d5aa96 8200 0200 01 01 1891
Turn off Y1: d5aa96 8200 0200 01 00 3981
Turn on G : d5aa96 8200 0200 02 01 4bc4
Turn off G : d5aa96 8200 0200 02 00 6ad4
Turn on OB: d5aa96 8200 0200 03 01 7af7
Turn off OB: d5aa96 8200 0200 03 00 5be7
Turn on W2: d5aa96 8200 0200 04 01 ed6e
Turn off W2: d5aa96 8200 0200 04 00 cc7e
Turn on Y2: d5aa96 8200 0200 07 01 be3b
Turn off Y2: d5aa96 8200 0200 07 00 9f2b
Turn on * : d5aa96 8200 0200 0b 01 d37e
Turn off * : d5aa96 8200 0200 0b 00 f26e

For the sake of documentation, we will refer to the unique id numbers for each wire as "wire id numbers".
So wire id 0 is W1, wire id 1 is Y1, wire id B is *, etc.

=== FET presence ===
The backplate will, at least upon connection, send information about which FETs have a wire present.
This data is received with command ids 0004 and 0009, in that order.
Each sensor is represented by one byte which is either 00 (not present) or 01 (present).

The content of 0004 is in order of the "wire id numbers" used for control:
W1, Y1, G, OB, W2, ?0, ?0, Y2, C, RC, ?0, *, ?0

The content of 0009 is arranged differently and has 2 more values:
W1, Y1, C, RC, ?0, G, OB, W2, ?0, Y2, ?0, *, ?0, ?0, ?0

0009 seems to indicate a wire is physically plugged in, while 0004 indicates that it is connected to something (?).

After these are received, the display sends back command 008f with the exact data from message 0004.
Message 008f does not itself receive any response.

In a power outage condition, 0004 will report all absent (including unknown ones), whereas 0009 will continue to report the same as when power is available.

=== Get build info ===
Message 0099 (no data) requests the backplate report information about its build.
The response will be message 0019 in ASCII (one line, no trailing newline).

=== Get hardware version? ===
Message 009e (no data) requests the backplate report a "Backplate-"X.Y version string.
Since the firmware file on the display CPU uses these strings as "MinApplicability" and "MaxApplicability" ranges, it is probable they refer to the hardware.

Witnessed versions:
"Backplate-2.8" - Florida Lowes

=== Get BSL version ===
Message 009b (no data) requests the backplate report its BSL version number.
The response will be message 001b in ASCII.

=== Get TFE version ===
Message 0098 (no data) requests the backplate report its TFE version number.
The response will be message 0018 in ASCII.

=== Get serial number ===
Message 009f (no data) requests the backplate report its serial number (a 64-bit hexadecimal value).
The response will be message 001f in uppercase ASCII.

=== Periodic status ===
Sending message 0083 (no data) will trigger various periodic messages:
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
000a - (every second; 16-bit data)

The Nest client sends 0083 every 30 seconds, but at least the periodic temperature status will continue on for an hour before stopping.

=== Temperature reading ===
The backplate will send message 0002 every 30 seconds.
The data contains two 16-bit numbers, which nlclient logs in decimal.
The first number is the temperature in centi-celcius.
The second number is the humidity in per-millis.

See also: [[#"Buffers"|"Buffers"]]

=== Reset ===
At least upon connection, the display sends message 00ff to the backplate to reset.

The backplate answers with:
0001 msg "<version> <build timestamp "YYYY-MM-DD HH:MM:SS"> K"
[[#FET presence|0004 FET presence]]
[[#FET presence|0009 FET presence]]
0001 msg "*sense 06d1 06d0 0001 0001 0000 0000 0000 0001 06d9 06d8 06d8; detect 09d3 065c"
0001 msg "BRK"

== Run BeagleBone/Debian programs ==
ln -s . /lib/arm-linux-gnueabihf
ln -s ld-2.11.1.so /lib/ld-linux-armhf.so.3

Nest Hacking

2014-08-08T02:28:48Z

Luke-Jr: /* FET presence */

== Hardware ==

[https://www.ifixit.com/Teardown/Nest+Learning+Thermostat+2nd+Generation+Teardown/13818 Pictures]

=== Backplate ===
* ST Microelectronics STM32L151VB ultra-low-power 32 MHz ARM Cortex-M3 MCU
* Sensirion SHT20 humidity and temperature sensor
* Texas Instruments LW051A 8-channel CMOS analog multiplexer/demultiplexer

=== Display ===
* Texas Instruments AM3703CUS Sitara ARM Cortex A8 microprocessor
* Texas Instruments TPS65921B power management and USB single chip
* Samsung K4X51163PK 512 Mb mobile DRAM
* Ember EM357 integrated ZigBee/802.15.4 system-on-chip
* Micron MT29F2G16ABBEAH4 2 Gb NAND flash memory
* Skyworks 2436L high power 2.4 GHz 802.15.4 front-end module
* Texas Instruments WL1270B 802.11 b/g/n Wi-Fi solution
* Avago ADBM-A350 optical finger navigation module (knob movement sensor)

== Info ==
* /dev/event1 is the knob; /dev/event2 is the button
* /sys/class/hwmon/hwmon0/device/in0_battery_type * 0.003 is battery voltage
** Nest turns off wifi below 3.7 V, and waits until 3.8 V to automatically reconnect
* Display serial number is located in U-Boot environment variable "serial#"

== Nest software ==
/nestlabs/sbin/nlclient -config /nestlabs/etc/client.config -config /nestlabs/etc/Display/Display-2/client.config

=== Backplate communications ===
Backplate communications can be decoded from a (filtered) strace log using [http://luke.dashjr.org/programs/freeabode/kindling/NestDecode.pl NestDecode.pl], or decoded in real time using [http://luke.dashjr.org/programs/freeabode/kindling/nest-intercept.c nest-intercept.c].

nest-intercept.c requires one argument, the thread id reading from the backplate controller.
The easiest way to get this is to strace the nlclient process with -ff and look for a thread reading from fd 54.

Note that nest-intercept.c also has a "hack" variable which can be set to 0 (default is 2) in order to corrupt the TFE version response and trigger nlclient into uploading the firmware again.

=== Backplate firmware ===
Found in /nestlabs/share/bp/data/firmware/nlbpfirmware.plist

There are 12 different firmwares in the file:
* Test vs Production
* Backplate 2 vs Backplate 3
* TFE (BP_D2 for Bp2, AMBER_BP for Bp3) vs BSL
* For TFE firmwares, hex vs srec (which for some reason DO differ!)

Python script to extract them into individual files: [http://luke.dashjr.org/programs/freeabode/kindling/extract-fw.py extract-fw.py]

=== Backplate initialisation ===
When the backplate is first connected, the following sequence occurs:
tcflush(fd, TCIFLUSH)
Set baud to 115200 (-opost -isig -icanon -echo ...)
tcflush(fd, TCIOFLUSH)
tcsendbreak(fd, 1)
Send [[#Reset|00ff - Reset]]
Recv 0001 - (message from backplate; ASCII)
Recv [[#FET presence|0004 - FET presence]]
Recv [[#FET presence|0009 - FET presence]]
Send [[#FET presence|008f - FET presence]]
Send [[#Periodic status|0083 - Periodic status request]]
Send 0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
Recv 0001 - (message from backplate; ASCII)
Recv 0001 - (message from backplate; ASCII)
Recv 0010 - (24-bit data)
Send [[#Get TFE version|0098 - Get TFE version]]
Recv 000a - (every second; 16-bit data)
Recv 0007 - (every second; 16-bit data)
Recv [[#Get TFE version|0018 - Get TFE version (response)]]
Send [[#Get build info|0099 - Get build info]]
Recv [[#Get build info|0019 - Get build info (response)]]
Sometimes:
Send 009d - (no data; responds with 001d (constant?) data=bbbb)
Recv 001d - Response to 009d; always(?) bbbb
Sometimes:
Send [[#Get BSL version|009b - Get BSL version]]
Recv [[#Get BSL version|001b - Get BSL version (response)]]
Sometimes:
Send 009c - (no data; responds with 001c (constant?) data="BSL")
Recv 001c - Response to 009c; always(?) "BSL"
Send [[#Get serial number|009f - Get serial number]]
Recv [[#Get serial number|001f - Get serial number (response)]]
Send [[#Get hardware version?|009e - Get hardware version?]]
Recv [[#Get hardware version?|001e - Get hardware version? (response)]]

== Nest backplate interface ==
* Connected on /dev/ttyO2
* All communications with backplate begin with (d5)d5aa96 (d5 is doubled only for data FROM backplate)
* Everything is little endian
* 16-bit command
* 16-bit data length
* <data>
* 16-bit checksum

Monitor:
strace -ff -p $(pidof nlclient) -x -s9999 -e read,write 2>&1 | grep '(54'

NOTE: Most of this documentation is reverse engineered from firmware version BSL-2.1 and/or TFE_BP_D2-4.0.21 for Backplate-2.x.

=== Checksum ===
<Bytes-from-end>.<bit-value> <xor-with>
00.01 2110 (1021)
00.02 4220 (2042: 1021<<1)
00.04 8440 (4084: 2048<<1)
00.08 0881 (8108: 4084<<1)
00.10 3112 (1231: 8108<<1^1021)
00.20 6224 (2462: 1231<<1)
00.40 c448 (48c4: 2462<<1)
00.80 8891 (9188: 48c4<<1)
01.01 3133 (3313: 9188<<1^1021)
01.02 6266
01.04 c4cc
01.08 a989
01.10 7303
01.20 e606
01.40 cc0d
01.80 981b
02.01 3037
02.02 606e
...
03.01 b476
03.02 68ed
03.04 f1ca
03.08 c385
03.10 a71b
03.20 4e37
03.40 9c6e
03.80 38dd
...
07.20 687b

If you compute the contribution of the individual bit changes in the data you end up with the xor table above; byte offset from the end of the data, bit pattern, xor value. Correcting for little endianess in the output you end up with the hex values in parenthesis. The least significant bit is 0x1021 and each subsequent bit is a shift left, if the XOR value has the 0x8000 bit set then it is XORed with 0x1021. This is the CRC-CCITT polynomial.

8 7 6 5 4 3 2 1 0
d5 aa 96 82 00 02 00 00 00: 08b2
|| |
|| 68ed
|408b
20d4

08b2: 68ed ^ 408b ^ 20d4

Starting at the least significant bit and filling in the XOR values for each bit gives the above diagram; the diagram stops at the 20d4 XOR value because at that point it matches the final CRC. This tells us that the CRC covers the 6 bytes prior.

#!/usr/bin/env perl
use Digest::CRC qw(crc);
my $data = pack("H*", "820002000000");
printf("%04x\n", crc($data,16,0,0,0,0x1021,0,0));

We can also compute the same CRC in Perl; note the result will be byte swapped since the data encodes the number as little endian.

=== Command ids ===

==== Display to backplate ====
[[#FET control|0082 - FET control]]
[[#Periodic status|0083 - Periodic status request]]
[[#FET presence|008f - FET presence]]
0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
[[#Backplate firmware upload|0091 - Backplate firmware upload (start)]]
[[#Backplate firmware upload|0092 - Backplate firmware upload]]
[[#Backplate firmware upload|0093 - Backplate firmware upload (finish)]]
[[#Get TFE version|0098 - Get TFE version]]
[[#Get build info|0099 - Get build info]]
[[#Get BSL version|009b - Get BSL version]]
009c - (no data; responds with 001c (constant?) data="BSL")
009d - (no data; responds with 001d (constant?) data=bbbb)
[[#Get hardware version?|009e - Get hardware version?]]
[[#Get serial number|009f - Get serial number]]
00a1 - (16-bit data)
[[#"Buffers"|00a2 - Request "buffers" (every 30 seconds; no data; triggers [0025] [0027] 0022 0023 [0029] [002b] 000c 002f)]]
[[#"Buffers"|00a3 - ACK to 002f (no data)]]
00a4 - (16-bit data)
00b1 - button pressed/unpressed (no data)
00b3 - (32-bit data; always ffffffff?)
00b5 - (16-bit data; always 0f00?)
00b9 - (32-bit data; always 0000ffff?)
00ba - (48-bit data; always 000000000000?)
00c2 - (48-bit data)
[[#Reset|00ff - Reset]]

==== Backplate to display ====
0001 - (message from backplate; ASCII)
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
[[#FET presence|0004 - FET presence]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
[[#FET presence|0009 - FET presence]]
000a - (every second; 2x(?) 16-bit data)
[[#Backplate state|000b - Backplate state]]
000c - (16-bit values: pir, px1, px1 divisor, px2, px2 divisor, alir, av; included in [[#"Buffers"|"buffers" data]])
0010 - (24-bit data)
[[#Backplate firmware upload|0011 - Backplate firmware upload (ACK)]]
0014 - (16-bit data)
[[#Get TFE version|0018 - Get TFE version (response)]]
[[#Get build info|0019 - Get build info (response)]]
[[#Get BSL version|001b - Get BSL version (response)]]
001c - Response to 009c; always(?) "BSL"
001d - Response to 009d; always(?) bbbb
[[#Get hardware version?|001e - Get hardware version? (response)]]
[[#Get serial number|001f - Get serial number (response)]]
[[#"Buffers"|0022 - 32-bit data (likely 2x 16-bit; possibly multiple times)]]
[[#"Buffers"|0023 - 48-bit data (likely 3x 16-bit; possibly multiple times)]]
[[#"Buffers"|0025 - 16-bit data (possibly multiple times)]]
[[#"Buffers"|0027 - 64-bit data (possibly multiple times)]]
[[#"Buffers"|0029 - 48-bit data (likely 3x 16-bit; possibly multiple times)]]
[[#"Buffers"|002b - 64-bit data (possibly multiple times)]]
[[#"Buffers"|002f - End of "buffers" (16-bit data)]]

=== Backplate firmware upload ===
For uploading the firmware, the following sequence is used:
Send 0091 data=0000<firmware type>
Recv 0011 data=0000
Send 0092 data=0100...
Recv 0011 data=0100
Send 0092 data=0200...
Recv 0011 data=0200
...
Send 0092 data=a901...
Recv 0011 data=a901
Send 0093 data=aa01
Recv 0011 data=aa01
Following the upload, the [[#Backplate initialisation|backplate initialisation process]] begins immediately (that is, without message 00ff being sent to order a reset).
Presumably the 0011 message is an ACK, and the first 16 bits of each message is the line number.
The format itself appears to be Motorola S-record (SREC).
Uploading the BSL firmware was followed by the TFE firmware, so it may be required (though uploading the TFE firmware does ''not'' require uploading the BSL).

Firmware type is either 4d for TFE or 42 for BSL.

=== Backplate state ===
Data:
* 8-bit "state"
* 8-bit "flags"
* 8-bit "px0" (may be wider?)
* 40-bit UNKNOWN (includes at least "p2" and "voc")
* 16-bit centi-volts "vi"
* 16-bit milli-volts "vo"
* 16-bit milli-volts "vb"
* 8-bit ("pins" or "wires")
* 8-bit ("wires" or "pins")
* 16-bit UNKNOWN

=== "Buffers" ===
The 00a2 message requests the backplate send the contents of various "buffers", which are returned in messages [0025], [0027], 0022, 0023, [0029], and [002b] (empty ones will NOT be sent; brackets infer commonly-empty buffers).
00a2 also triggers 000c immediately following these.
After all the buffers (including 000c) have been sent, the message 002f indicates "end of buffers".
The display is then expected to acknowledge it with message 00a3.

=== FET control ===
Turn on W1: d5aa96 8200 0200 00 01 29a2
Turn off W1: d5aa96 8200 0200 00 00 08b2
Turn on Y1: d5aa96 8200 0200 01 01 1891
Turn off Y1: d5aa96 8200 0200 01 00 3981
Turn on G : d5aa96 8200 0200 02 01 4bc4
Turn off G : d5aa96 8200 0200 02 00 6ad4
Turn on OB: d5aa96 8200 0200 03 01 7af7
Turn off OB: d5aa96 8200 0200 03 00 5be7
Turn on W2: d5aa96 8200 0200 04 01 ed6e
Turn off W2: d5aa96 8200 0200 04 00 cc7e
Turn on Y2: d5aa96 8200 0200 07 01 be3b
Turn off Y2: d5aa96 8200 0200 07 00 9f2b
Turn on * : d5aa96 8200 0200 0b 01 d37e
Turn off * : d5aa96 8200 0200 0b 00 f26e

For the sake of documentation, we will refer to the unique id numbers for each wire as "wire id numbers".
So wire id 0 is W1, wire id 1 is Y1, wire id B is *, etc.

=== FET presence ===
The backplate will, at least upon connection, send information about which FETs have a wire present.
This data is received with command ids 0004 and 0009, in that order.
Each sensor is represented by one byte which is either 00 (not present) or 01 (present).

The content of 0004 is in order of the "wire id numbers" used for control:
W1, Y1, G, OB, W2, ?0, ?0, Y2, C, RC, ?0, *, ?0

The content of 0009 is arranged differently and has 2 more values:
W1, Y1, C, RC, ?0, G, OB, W2, ?0, Y2, ?0, *, ?0, ?0, ?0

0009 seems to indicate a wire is physically plugged in, while 0004 indicates that it is connected to something (?).

After these are received, the display sends back command 008f with the exact data from message 0004.
Message 008f does not itself receive any response.

In a power outage condition, 0004 will report all absent (including unknown ones), whereas 0009 will continue to report the same as when power is available.

=== Get build info ===
Message 0099 (no data) requests the backplate report information about its build.
The response will be message 0019 in ASCII (one line, no trailing newline).

=== Get hardware version? ===
Message 009e (no data) requests the backplate report a "Backplate-"X.Y version string.
Since the firmware file on the display CPU uses these strings as "MinApplicability" and "MaxApplicability" ranges, it is probable they refer to the hardware.

Witnessed versions:
"Backplate-2.8" - Florida Lowes

=== Get BSL version ===
Message 009b (no data) requests the backplate report its BSL version number.
The response will be message 001b in ASCII.

=== Get TFE version ===
Message 0098 (no data) requests the backplate report its TFE version number.
The response will be message 0018 in ASCII.

=== Get serial number ===
Message 009f (no data) requests the backplate report its serial number (a 64-bit hexadecimal value).
The response will be message 001f in uppercase ASCII.

=== Periodic status ===
Sending message 0083 (no data) will trigger various periodic messages:
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
000a - (every second; 16-bit data)

The Nest client sends 0083 every 30 seconds, but at least the periodic temperature status will continue on for an hour before stopping.

=== Temperature reading ===
The backplate will send message 0002 every 30 seconds.
The data contains two 16-bit numbers, which nlclient logs in decimal.
The first number is the temperature in centi-celcius.
The second number is the humidity in per-millis.

=== Reset ===
At least upon connection, the display sends message 00ff to the backplate to reset.

The backplate answers with:
0001 msg "<version> <build timestamp "YYYY-MM-DD HH:MM:SS"> K"
[[#FET presence|0004 FET presence]]
[[#FET presence|0009 FET presence]]
0001 msg "*sense 06d1 06d0 0001 0001 0000 0000 0000 0001 06d9 06d8 06d8; detect 09d3 065c"
0001 msg "BRK"

== Run BeagleBone/Debian programs ==
ln -s . /lib/arm-linux-gnueabihf
ln -s ld-2.11.1.so /lib/ld-linux-armhf.so.3

Nest Hacking

2014-08-07T02:50:07Z

Luke-Jr: /* Nest backplate interface */

== Hardware ==

[https://www.ifixit.com/Teardown/Nest+Learning+Thermostat+2nd+Generation+Teardown/13818 Pictures]

=== Backplate ===
* ST Microelectronics STM32L151VB ultra-low-power 32 MHz ARM Cortex-M3 MCU
* Sensirion SHT20 humidity and temperature sensor
* Texas Instruments LW051A 8-channel CMOS analog multiplexer/demultiplexer

=== Display ===
* Texas Instruments AM3703CUS Sitara ARM Cortex A8 microprocessor
* Texas Instruments TPS65921B power management and USB single chip
* Samsung K4X51163PK 512 Mb mobile DRAM
* Ember EM357 integrated ZigBee/802.15.4 system-on-chip
* Micron MT29F2G16ABBEAH4 2 Gb NAND flash memory
* Skyworks 2436L high power 2.4 GHz 802.15.4 front-end module
* Texas Instruments WL1270B 802.11 b/g/n Wi-Fi solution
* Avago ADBM-A350 optical finger navigation module (knob movement sensor)

== Info ==
* /dev/event1 is the knob; /dev/event2 is the button
* /sys/class/hwmon/hwmon0/device/in0_battery_type * 0.003 is battery voltage
** Nest turns off wifi below 3.7 V, and waits until 3.8 V to automatically reconnect
* Display serial number is located in U-Boot environment variable "serial#"

== Nest software ==
/nestlabs/sbin/nlclient -config /nestlabs/etc/client.config -config /nestlabs/etc/Display/Display-2/client.config

=== Backplate communications ===
Backplate communications can be decoded from a (filtered) strace log using [http://luke.dashjr.org/programs/freeabode/kindling/NestDecode.pl NestDecode.pl], or decoded in real time using [http://luke.dashjr.org/programs/freeabode/kindling/nest-intercept.c nest-intercept.c].

nest-intercept.c requires one argument, the thread id reading from the backplate controller.
The easiest way to get this is to strace the nlclient process with -ff and look for a thread reading from fd 54.

Note that nest-intercept.c also has a "hack" variable which can be set to 0 (default is 2) in order to corrupt the TFE version response and trigger nlclient into uploading the firmware again.

=== Backplate firmware ===
Found in /nestlabs/share/bp/data/firmware/nlbpfirmware.plist

There are 12 different firmwares in the file:
* Test vs Production
* Backplate 2 vs Backplate 3
* TFE (BP_D2 for Bp2, AMBER_BP for Bp3) vs BSL
* For TFE firmwares, hex vs srec (which for some reason DO differ!)

Python script to extract them into individual files: [http://luke.dashjr.org/programs/freeabode/kindling/extract-fw.py extract-fw.py]

=== Backplate initialisation ===
When the backplate is first connected, the following sequence occurs:
tcflush(fd, TCIFLUSH)
Set baud to 115200 (-opost -isig -icanon -echo ...)
tcflush(fd, TCIOFLUSH)
tcsendbreak(fd, 1)
Send [[#Reset|00ff - Reset]]
Recv 0001 - (message from backplate; ASCII)
Recv [[#FET presence|0004 - FET presence]]
Recv [[#FET presence|0009 - FET presence]]
Send [[#FET presence|008f - FET presence]]
Send [[#Periodic status|0083 - Periodic status request]]
Send 0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
Recv 0001 - (message from backplate; ASCII)
Recv 0001 - (message from backplate; ASCII)
Recv 0010 - (24-bit data)
Send [[#Get TFE version|0098 - Get TFE version]]
Recv 000a - (every second; 16-bit data)
Recv 0007 - (every second; 16-bit data)
Recv [[#Get TFE version|0018 - Get TFE version (response)]]
Send [[#Get build info|0099 - Get build info]]
Recv [[#Get build info|0019 - Get build info (response)]]
Sometimes:
Send 009d - (no data; responds with 001d (constant?) data=bbbb)
Recv 001d - Response to 009d; always(?) bbbb
Sometimes:
Send [[#Get BSL version|009b - Get BSL version]]
Recv [[#Get BSL version|001b - Get BSL version (response)]]
Sometimes:
Send 009c - (no data; responds with 001c (constant?) data="BSL")
Recv 001c - Response to 009c; always(?) "BSL"
Send [[#Get serial number|009f - Get serial number]]
Recv [[#Get serial number|001f - Get serial number (response)]]
Send [[#Get hardware version?|009e - Get hardware version?]]
Recv [[#Get hardware version?|001e - Get hardware version? (response)]]

== Nest backplate interface ==
* Connected on /dev/ttyO2
* All communications with backplate begin with (d5)d5aa96 (d5 is doubled only for data FROM backplate)
* Everything is little endian
* 16-bit command
* 16-bit data length
* <data>
* 16-bit checksum

Monitor:
strace -ff -p $(pidof nlclient) -x -s9999 -e read,write 2>&1 | grep '(54'

NOTE: Most of this documentation is reverse engineered from firmware version BSL-2.1 and/or TFE_BP_D2-4.0.21 for Backplate-2.x.

=== Checksum ===
<Bytes-from-end>.<bit-value> <xor-with>
00.01 2110 (1021)
00.02 4220 (2042: 1021<<1)
00.04 8440 (4084: 2048<<1)
00.08 0881 (8108: 4084<<1)
00.10 3112 (1231: 8108<<1^1021)
00.20 6224 (2462: 1231<<1)
00.40 c448 (48c4: 2462<<1)
00.80 8891 (9188: 48c4<<1)
01.01 3133 (3313: 9188<<1^1021)
01.02 6266
01.04 c4cc
01.08 a989
01.10 7303
01.20 e606
01.40 cc0d
01.80 981b
02.01 3037
02.02 606e
...
03.01 b476
03.02 68ed
03.04 f1ca
03.08 c385
03.10 a71b
03.20 4e37
03.40 9c6e
03.80 38dd
...
07.20 687b

If you compute the contribution of the individual bit changes in the data you end up with the xor table above; byte offset from the end of the data, bit pattern, xor value. Correcting for little endianess in the output you end up with the hex values in parenthesis. The least significant bit is 0x1021 and each subsequent bit is a shift left, if the XOR value has the 0x8000 bit set then it is XORed with 0x1021. This is the CRC-CCITT polynomial.

8 7 6 5 4 3 2 1 0
d5 aa 96 82 00 02 00 00 00: 08b2
|| |
|| 68ed
|408b
20d4

08b2: 68ed ^ 408b ^ 20d4

Starting at the least significant bit and filling in the XOR values for each bit gives the above diagram; the diagram stops at the 20d4 XOR value because at that point it matches the final CRC. This tells us that the CRC covers the 6 bytes prior.

#!/usr/bin/env perl
use Digest::CRC qw(crc);
my $data = pack("H*", "820002000000");
printf("%04x\n", crc($data,16,0,0,0,0x1021,0,0));

We can also compute the same CRC in Perl; note the result will be byte swapped since the data encodes the number as little endian.

=== Command ids ===

==== Display to backplate ====
[[#FET control|0082 - FET control]]
[[#Periodic status|0083 - Periodic status request]]
[[#FET presence|008f - FET presence]]
0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
[[#Backplate firmware upload|0091 - Backplate firmware upload (start)]]
[[#Backplate firmware upload|0092 - Backplate firmware upload]]
[[#Backplate firmware upload|0093 - Backplate firmware upload (finish)]]
[[#Get TFE version|0098 - Get TFE version]]
[[#Get build info|0099 - Get build info]]
[[#Get BSL version|009b - Get BSL version]]
009c - (no data; responds with 001c (constant?) data="BSL")
009d - (no data; responds with 001d (constant?) data=bbbb)
[[#Get hardware version?|009e - Get hardware version?]]
[[#Get serial number|009f - Get serial number]]
00a1 - (16-bit data)
[[#"Buffers"|00a2 - Request "buffers" (every 30 seconds; no data; triggers [0025] [0027] 0022 0023 [0029] [002b] 000c 002f)]]
[[#"Buffers"|00a3 - ACK to 002f (no data)]]
00a4 - (16-bit data)
00b1 - button pressed/unpressed (no data)
00b3 - (32-bit data; always ffffffff?)
00b5 - (16-bit data; always 0f00?)
00b9 - (32-bit data; always 0000ffff?)
00ba - (48-bit data; always 000000000000?)
00c2 - (48-bit data)
[[#Reset|00ff - Reset]]

==== Backplate to display ====
0001 - (message from backplate; ASCII)
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
[[#FET presence|0004 - FET presence]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
[[#FET presence|0009 - FET presence]]
000a - (every second; 2x(?) 16-bit data)
[[#Backplate state|000b - Backplate state]]
000c - (16-bit values: pir, px1, px1 divisor, px2, px2 divisor, alir, av; included in [[#"Buffers"|"buffers" data]])
0010 - (24-bit data)
[[#Backplate firmware upload|0011 - Backplate firmware upload (ACK)]]
0014 - (16-bit data)
[[#Get TFE version|0018 - Get TFE version (response)]]
[[#Get build info|0019 - Get build info (response)]]
[[#Get BSL version|001b - Get BSL version (response)]]
001c - Response to 009c; always(?) "BSL"
001d - Response to 009d; always(?) bbbb
[[#Get hardware version?|001e - Get hardware version? (response)]]
[[#Get serial number|001f - Get serial number (response)]]
[[#"Buffers"|0022 - 32-bit data (likely 2x 16-bit; possibly multiple times)]]
[[#"Buffers"|0023 - 48-bit data (likely 3x 16-bit; possibly multiple times)]]
[[#"Buffers"|0025 - 16-bit data (possibly multiple times)]]
[[#"Buffers"|0027 - 64-bit data (possibly multiple times)]]
[[#"Buffers"|0029 - 48-bit data (likely 3x 16-bit; possibly multiple times)]]
[[#"Buffers"|002b - 64-bit data (possibly multiple times)]]
[[#"Buffers"|002f - End of "buffers" (16-bit data)]]

=== Backplate firmware upload ===
For uploading the firmware, the following sequence is used:
Send 0091 data=0000<firmware type>
Recv 0011 data=0000
Send 0092 data=0100...
Recv 0011 data=0100
Send 0092 data=0200...
Recv 0011 data=0200
...
Send 0092 data=a901...
Recv 0011 data=a901
Send 0093 data=aa01
Recv 0011 data=aa01
Following the upload, the [[#Backplate initialisation|backplate initialisation process]] begins immediately (that is, without message 00ff being sent to order a reset).
Presumably the 0011 message is an ACK, and the first 16 bits of each message is the line number.
The format itself appears to be Motorola S-record (SREC).
Uploading the BSL firmware was followed by the TFE firmware, so it may be required (though uploading the TFE firmware does ''not'' require uploading the BSL).

Firmware type is either 4d for TFE or 42 for BSL.

=== Backplate state ===
Data:
* 8-bit "state"
* 8-bit "flags"
* 8-bit "px0" (may be wider?)
* 40-bit UNKNOWN (includes at least "p2" and "voc")
* 16-bit centi-volts "vi"
* 16-bit milli-volts "vo"
* 16-bit milli-volts "vb"
* 8-bit ("pins" or "wires")
* 8-bit ("wires" or "pins")
* 16-bit UNKNOWN

=== "Buffers" ===
The 00a2 message requests the backplate send the contents of various "buffers", which are returned in messages [0025], [0027], 0022, 0023, [0029], and [002b] (empty ones will NOT be sent; brackets infer commonly-empty buffers).
00a2 also triggers 000c immediately following these.
After all the buffers (including 000c) have been sent, the message 002f indicates "end of buffers".
The display is then expected to acknowledge it with message 00a3.

=== FET control ===
Turn on W1: d5aa96 8200 0200 00 01 29a2
Turn off W1: d5aa96 8200 0200 00 00 08b2
Turn on Y1: d5aa96 8200 0200 01 01 1891
Turn off Y1: d5aa96 8200 0200 01 00 3981
Turn on G : d5aa96 8200 0200 02 01 4bc4
Turn off G : d5aa96 8200 0200 02 00 6ad4
Turn on OB: d5aa96 8200 0200 03 01 7af7
Turn off OB: d5aa96 8200 0200 03 00 5be7
Turn on W2: d5aa96 8200 0200 04 01 ed6e
Turn off W2: d5aa96 8200 0200 04 00 cc7e
Turn on Y2: d5aa96 8200 0200 07 01 be3b
Turn off Y2: d5aa96 8200 0200 07 00 9f2b
Turn on * : d5aa96 8200 0200 0b 01 d37e
Turn off * : d5aa96 8200 0200 0b 00 f26e

For the sake of documentation, we will refer to the unique id numbers for each wire as "wire id numbers".
So wire id 0 is W1, wire id 1 is Y1, wire id B is *, etc.

=== FET presence ===
The backplate will, at least upon connection, send information about which FETs have a wire present.
This data is received with command ids 0004 and 0009, in that order.
Each sensor is represented by one byte which is either 00 (not present) or 01 (present).

The content of 0004 is in order of the "wire id numbers" used for control:
W1, Y1, G, OB, W2, ?0, ?0, Y2, ?1, ?1, ?0, *, ?0

The content of 0009 is arranged differently and has 2 more values:
W1, Y1, ?1, ?1, ?0, G, OB, W2, ?0, Y2, ?0, *, ?0, ?0, ?0

After these are received, the display sends back command 008f with the exact data from message 0004.
Message 008f does not itself receive any response.

In a power outage condition, 0004 will report all absent (including unknown ones), whereas 0009 will continue to report the same as when power is available.

=== Get build info ===
Message 0099 (no data) requests the backplate report information about its build.
The response will be message 0019 in ASCII (one line, no trailing newline).

=== Get hardware version? ===
Message 009e (no data) requests the backplate report a "Backplate-"X.Y version string.
Since the firmware file on the display CPU uses these strings as "MinApplicability" and "MaxApplicability" ranges, it is probable they refer to the hardware.

Witnessed versions:
"Backplate-2.8" - Florida Lowes

=== Get BSL version ===
Message 009b (no data) requests the backplate report its BSL version number.
The response will be message 001b in ASCII.

=== Get TFE version ===
Message 0098 (no data) requests the backplate report its TFE version number.
The response will be message 0018 in ASCII.

=== Get serial number ===
Message 009f (no data) requests the backplate report its serial number (a 64-bit hexadecimal value).
The response will be message 001f in uppercase ASCII.

=== Periodic status ===
Sending message 0083 (no data) will trigger various periodic messages:
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
000a - (every second; 16-bit data)

The Nest client sends 0083 every 30 seconds, but at least the periodic temperature status will continue on for an hour before stopping.

=== Temperature reading ===
The backplate will send message 0002 every 30 seconds.
The data contains two 16-bit numbers, which nlclient logs in decimal.
The first number is the temperature in centi-celcius.
The second number is the humidity in per-millis.

=== Reset ===
At least upon connection, the display sends message 00ff to the backplate to reset.

The backplate answers with:
0001 msg "<version> <build timestamp "YYYY-MM-DD HH:MM:SS"> K"
[[#FET presence|0004 FET presence]]
[[#FET presence|0009 FET presence]]
0001 msg "*sense 06d1 06d0 0001 0001 0000 0000 0000 0001 06d9 06d8 06d8; detect 09d3 065c"
0001 msg "BRK"

== Run BeagleBone/Debian programs ==
ln -s . /lib/arm-linux-gnueabihf
ln -s ld-2.11.1.so /lib/ld-linux-armhf.so.3

Nest Hacking

2014-08-07T02:48:34Z

Luke-Jr: /* Info */

== Hardware ==

[https://www.ifixit.com/Teardown/Nest+Learning+Thermostat+2nd+Generation+Teardown/13818 Pictures]

=== Backplate ===
* ST Microelectronics STM32L151VB ultra-low-power 32 MHz ARM Cortex-M3 MCU
* Sensirion SHT20 humidity and temperature sensor
* Texas Instruments LW051A 8-channel CMOS analog multiplexer/demultiplexer

=== Display ===
* Texas Instruments AM3703CUS Sitara ARM Cortex A8 microprocessor
* Texas Instruments TPS65921B power management and USB single chip
* Samsung K4X51163PK 512 Mb mobile DRAM
* Ember EM357 integrated ZigBee/802.15.4 system-on-chip
* Micron MT29F2G16ABBEAH4 2 Gb NAND flash memory
* Skyworks 2436L high power 2.4 GHz 802.15.4 front-end module
* Texas Instruments WL1270B 802.11 b/g/n Wi-Fi solution
* Avago ADBM-A350 optical finger navigation module (knob movement sensor)

== Info ==
* /dev/event1 is the knob; /dev/event2 is the button
* /sys/class/hwmon/hwmon0/device/in0_battery_type * 0.003 is battery voltage
** Nest turns off wifi below 3.7 V, and waits until 3.8 V to automatically reconnect
* Display serial number is located in U-Boot environment variable "serial#"

== Nest software ==
/nestlabs/sbin/nlclient -config /nestlabs/etc/client.config -config /nestlabs/etc/Display/Display-2/client.config

=== Backplate communications ===
Backplate communications can be decoded from a (filtered) strace log using [http://luke.dashjr.org/programs/freeabode/kindling/NestDecode.pl NestDecode.pl], or decoded in real time using [http://luke.dashjr.org/programs/freeabode/kindling/nest-intercept.c nest-intercept.c].

nest-intercept.c requires one argument, the thread id reading from the backplate controller.
The easiest way to get this is to strace the nlclient process with -ff and look for a thread reading from fd 54.

Note that nest-intercept.c also has a "hack" variable which can be set to 0 (default is 2) in order to corrupt the TFE version response and trigger nlclient into uploading the firmware again.

=== Backplate firmware ===
Found in /nestlabs/share/bp/data/firmware/nlbpfirmware.plist

There are 12 different firmwares in the file:
* Test vs Production
* Backplate 2 vs Backplate 3
* TFE (BP_D2 for Bp2, AMBER_BP for Bp3) vs BSL
* For TFE firmwares, hex vs srec (which for some reason DO differ!)

Python script to extract them into individual files: [http://luke.dashjr.org/programs/freeabode/kindling/extract-fw.py extract-fw.py]

=== Backplate initialisation ===
When the backplate is first connected, the following sequence occurs:
tcflush(fd, TCIFLUSH)
Set baud to 115200 (-opost -isig -icanon -echo ...)
tcflush(fd, TCIOFLUSH)
tcsendbreak(fd, 1)
Send [[#Reset|00ff - Reset]]
Recv 0001 - (message from backplate; ASCII)
Recv [[#FET presence|0004 - FET presence]]
Recv [[#FET presence|0009 - FET presence]]
Send [[#FET presence|008f - FET presence]]
Send [[#Periodic status|0083 - Periodic status request]]
Send 0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
Recv 0001 - (message from backplate; ASCII)
Recv 0001 - (message from backplate; ASCII)
Recv 0010 - (24-bit data)
Send [[#Get TFE version|0098 - Get TFE version]]
Recv 000a - (every second; 16-bit data)
Recv 0007 - (every second; 16-bit data)
Recv [[#Get TFE version|0018 - Get TFE version (response)]]
Send [[#Get build info|0099 - Get build info]]
Recv [[#Get build info|0019 - Get build info (response)]]
Sometimes:
Send 009d - (no data; responds with 001d (constant?) data=bbbb)
Recv 001d - Response to 009d; always(?) bbbb
Sometimes:
Send [[#Get BSL version|009b - Get BSL version]]
Recv [[#Get BSL version|001b - Get BSL version (response)]]
Sometimes:
Send 009c - (no data; responds with 001c (constant?) data="BSL")
Recv 001c - Response to 009c; always(?) "BSL"
Send [[#Get serial number|009f - Get serial number]]
Recv [[#Get serial number|001f - Get serial number (response)]]
Send [[#Get hardware version?|009e - Get hardware version?]]
Recv [[#Get hardware version?|001e - Get hardware version? (response)]]

== Nest backplate interface ==
* Connected on /dev/ttyO2
* All communications with backplate begin with (d5)d5aa96 (d5 is doubled only for data FROM backplate)
* Everything is little endian
* 16-bit command
* 16-bit data length
* <data>
* 16-bit checksum

Monitor:
strace -ff -p $(pidof nlclient) -x -s9999 -e read,write 2>&1 | grep '(54'

=== Checksum ===
<Bytes-from-end>.<bit-value> <xor-with>
00.01 2110 (1021)
00.02 4220 (2042: 1021<<1)
00.04 8440 (4084: 2048<<1)
00.08 0881 (8108: 4084<<1)
00.10 3112 (1231: 8108<<1^1021)
00.20 6224 (2462: 1231<<1)
00.40 c448 (48c4: 2462<<1)
00.80 8891 (9188: 48c4<<1)
01.01 3133 (3313: 9188<<1^1021)
01.02 6266
01.04 c4cc
01.08 a989
01.10 7303
01.20 e606
01.40 cc0d
01.80 981b
02.01 3037
02.02 606e
...
03.01 b476
03.02 68ed
03.04 f1ca
03.08 c385
03.10 a71b
03.20 4e37
03.40 9c6e
03.80 38dd
...
07.20 687b

If you compute the contribution of the individual bit changes in the data you end up with the xor table above; byte offset from the end of the data, bit pattern, xor value. Correcting for little endianess in the output you end up with the hex values in parenthesis. The least significant bit is 0x1021 and each subsequent bit is a shift left, if the XOR value has the 0x8000 bit set then it is XORed with 0x1021. This is the CRC-CCITT polynomial.

8 7 6 5 4 3 2 1 0
d5 aa 96 82 00 02 00 00 00: 08b2
|| |
|| 68ed
|408b
20d4

08b2: 68ed ^ 408b ^ 20d4

Starting at the least significant bit and filling in the XOR values for each bit gives the above diagram; the diagram stops at the 20d4 XOR value because at that point it matches the final CRC. This tells us that the CRC covers the 6 bytes prior.

#!/usr/bin/env perl
use Digest::CRC qw(crc);
my $data = pack("H*", "820002000000");
printf("%04x\n", crc($data,16,0,0,0,0x1021,0,0));

We can also compute the same CRC in Perl; note the result will be byte swapped since the data encodes the number as little endian.

=== Command ids ===

==== Display to backplate ====
[[#FET control|0082 - FET control]]
[[#Periodic status|0083 - Periodic status request]]
[[#FET presence|008f - FET presence]]
0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
[[#Backplate firmware upload|0091 - Backplate firmware upload (start)]]
[[#Backplate firmware upload|0092 - Backplate firmware upload]]
[[#Backplate firmware upload|0093 - Backplate firmware upload (finish)]]
[[#Get TFE version|0098 - Get TFE version]]
[[#Get build info|0099 - Get build info]]
[[#Get BSL version|009b - Get BSL version]]
009c - (no data; responds with 001c (constant?) data="BSL")
009d - (no data; responds with 001d (constant?) data=bbbb)
[[#Get hardware version?|009e - Get hardware version?]]
[[#Get serial number|009f - Get serial number]]
00a1 - (16-bit data)
[[#"Buffers"|00a2 - Request "buffers" (every 30 seconds; no data; triggers [0025] [0027] 0022 0023 [0029] [002b] 000c 002f)]]
[[#"Buffers"|00a3 - ACK to 002f (no data)]]
00a4 - (16-bit data)
00b1 - button pressed/unpressed (no data)
00b3 - (32-bit data; always ffffffff?)
00b5 - (16-bit data; always 0f00?)
00b9 - (32-bit data; always 0000ffff?)
00ba - (48-bit data; always 000000000000?)
00c2 - (48-bit data)
[[#Reset|00ff - Reset]]

==== Backplate to display ====
0001 - (message from backplate; ASCII)
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
[[#FET presence|0004 - FET presence]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
[[#FET presence|0009 - FET presence]]
000a - (every second; 2x(?) 16-bit data)
[[#Backplate state|000b - Backplate state]]
000c - (16-bit values: pir, px1, px1 divisor, px2, px2 divisor, alir, av; included in [[#"Buffers"|"buffers" data]])
0010 - (24-bit data)
[[#Backplate firmware upload|0011 - Backplate firmware upload (ACK)]]
0014 - (16-bit data)
[[#Get TFE version|0018 - Get TFE version (response)]]
[[#Get build info|0019 - Get build info (response)]]
[[#Get BSL version|001b - Get BSL version (response)]]
001c - Response to 009c; always(?) "BSL"
001d - Response to 009d; always(?) bbbb
[[#Get hardware version?|001e - Get hardware version? (response)]]
[[#Get serial number|001f - Get serial number (response)]]
[[#"Buffers"|0022 - 32-bit data (likely 2x 16-bit; possibly multiple times)]]
[[#"Buffers"|0023 - 48-bit data (likely 3x 16-bit; possibly multiple times)]]
[[#"Buffers"|0025 - 16-bit data (possibly multiple times)]]
[[#"Buffers"|0027 - 64-bit data (possibly multiple times)]]
[[#"Buffers"|0029 - 48-bit data (likely 3x 16-bit; possibly multiple times)]]
[[#"Buffers"|002b - 64-bit data (possibly multiple times)]]
[[#"Buffers"|002f - End of "buffers" (16-bit data)]]

=== Backplate firmware upload ===
For uploading the firmware, the following sequence is used:
Send 0091 data=0000<firmware type>
Recv 0011 data=0000
Send 0092 data=0100...
Recv 0011 data=0100
Send 0092 data=0200...
Recv 0011 data=0200
...
Send 0092 data=a901...
Recv 0011 data=a901
Send 0093 data=aa01
Recv 0011 data=aa01
Following the upload, the [[#Backplate initialisation|backplate initialisation process]] begins immediately (that is, without message 00ff being sent to order a reset).
Presumably the 0011 message is an ACK, and the first 16 bits of each message is the line number.
The format itself appears to be Motorola S-record (SREC).
Uploading the BSL firmware was followed by the TFE firmware, so it may be required (though uploading the TFE firmware does ''not'' require uploading the BSL).

Firmware type is either 4d for TFE or 42 for BSL.

=== Backplate state ===
Data:
* 8-bit "state"
* 8-bit "flags"
* 8-bit "px0" (may be wider?)
* 40-bit UNKNOWN (includes at least "p2" and "voc")
* 16-bit centi-volts "vi"
* 16-bit milli-volts "vo"
* 16-bit milli-volts "vb"
* 8-bit ("pins" or "wires")
* 8-bit ("wires" or "pins")
* 16-bit UNKNOWN

=== "Buffers" ===
The 00a2 message requests the backplate send the contents of various "buffers", which are returned in messages [0025], [0027], 0022, 0023, [0029], and [002b] (empty ones will NOT be sent; brackets infer commonly-empty buffers).
00a2 also triggers 000c immediately following these.
After all the buffers (including 000c) have been sent, the message 002f indicates "end of buffers".
The display is then expected to acknowledge it with message 00a3.

=== FET control ===
Turn on W1: d5aa96 8200 0200 00 01 29a2
Turn off W1: d5aa96 8200 0200 00 00 08b2
Turn on Y1: d5aa96 8200 0200 01 01 1891
Turn off Y1: d5aa96 8200 0200 01 00 3981
Turn on G : d5aa96 8200 0200 02 01 4bc4
Turn off G : d5aa96 8200 0200 02 00 6ad4
Turn on OB: d5aa96 8200 0200 03 01 7af7
Turn off OB: d5aa96 8200 0200 03 00 5be7
Turn on W2: d5aa96 8200 0200 04 01 ed6e
Turn off W2: d5aa96 8200 0200 04 00 cc7e
Turn on Y2: d5aa96 8200 0200 07 01 be3b
Turn off Y2: d5aa96 8200 0200 07 00 9f2b
Turn on * : d5aa96 8200 0200 0b 01 d37e
Turn off * : d5aa96 8200 0200 0b 00 f26e

For the sake of documentation, we will refer to the unique id numbers for each wire as "wire id numbers".
So wire id 0 is W1, wire id 1 is Y1, wire id B is *, etc.

=== FET presence ===
The backplate will, at least upon connection, send information about which FETs have a wire present.
This data is received with command ids 0004 and 0009, in that order.
Each sensor is represented by one byte which is either 00 (not present) or 01 (present).

The content of 0004 is in order of the "wire id numbers" used for control:
W1, Y1, G, OB, W2, ?0, ?0, Y2, ?1, ?1, ?0, *, ?0

The content of 0009 is arranged differently and has 2 more values:
W1, Y1, ?1, ?1, ?0, G, OB, W2, ?0, Y2, ?0, *, ?0, ?0, ?0

After these are received, the display sends back command 008f with the exact data from message 0004.
Message 008f does not itself receive any response.

In a power outage condition, 0004 will report all absent (including unknown ones), whereas 0009 will continue to report the same as when power is available.

=== Get build info ===
Message 0099 (no data) requests the backplate report information about its build.
The response will be message 0019 in ASCII (one line, no trailing newline).

=== Get hardware version? ===
Message 009e (no data) requests the backplate report a "Backplate-"X.Y version string.
Since the firmware file on the display CPU uses these strings as "MinApplicability" and "MaxApplicability" ranges, it is probable they refer to the hardware.

Witnessed versions:
"Backplate-2.8" - Florida Lowes

=== Get BSL version ===
Message 009b (no data) requests the backplate report its BSL version number.
The response will be message 001b in ASCII.

=== Get TFE version ===
Message 0098 (no data) requests the backplate report its TFE version number.
The response will be message 0018 in ASCII.

=== Get serial number ===
Message 009f (no data) requests the backplate report its serial number (a 64-bit hexadecimal value).
The response will be message 001f in uppercase ASCII.

=== Periodic status ===
Sending message 0083 (no data) will trigger various periodic messages:
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
000a - (every second; 16-bit data)

The Nest client sends 0083 every 30 seconds, but at least the periodic temperature status will continue on for an hour before stopping.

=== Temperature reading ===
The backplate will send message 0002 every 30 seconds.
The data contains two 16-bit numbers, which nlclient logs in decimal.
The first number is the temperature in centi-celcius.
The second number is the humidity in per-millis.

=== Reset ===
At least upon connection, the display sends message 00ff to the backplate to reset.

The backplate answers with:
0001 msg "<version> <build timestamp "YYYY-MM-DD HH:MM:SS"> K"
[[#FET presence|0004 FET presence]]
[[#FET presence|0009 FET presence]]
0001 msg "*sense 06d1 06d0 0001 0001 0000 0000 0000 0001 06d9 06d8 06d8; detect 09d3 065c"
0001 msg "BRK"

== Run BeagleBone/Debian programs ==
ln -s . /lib/arm-linux-gnueabihf
ln -s ld-2.11.1.so /lib/ld-linux-armhf.so.3

Nest Hacking

2014-08-07T02:33:56Z

Luke-Jr: /* Nest backplate interface */ ABC order

== Hardware ==

[https://www.ifixit.com/Teardown/Nest+Learning+Thermostat+2nd+Generation+Teardown/13818 Pictures]

=== Backplate ===
* ST Microelectronics STM32L151VB ultra-low-power 32 MHz ARM Cortex-M3 MCU
* Sensirion SHT20 humidity and temperature sensor
* Texas Instruments LW051A 8-channel CMOS analog multiplexer/demultiplexer

=== Display ===
* Texas Instruments AM3703CUS Sitara ARM Cortex A8 microprocessor
* Texas Instruments TPS65921B power management and USB single chip
* Samsung K4X51163PK 512 Mb mobile DRAM
* Ember EM357 integrated ZigBee/802.15.4 system-on-chip
* Micron MT29F2G16ABBEAH4 2 Gb NAND flash memory
* Skyworks 2436L high power 2.4 GHz 802.15.4 front-end module
* Texas Instruments WL1270B 802.11 b/g/n Wi-Fi solution
* Avago ADBM-A350 optical finger navigation module (knob movement sensor)

== Info ==
* /dev/event1 is the knob; /dev/event2 is the button
* /sys/class/hwmon/hwmon0/device/in0_battery_type * 0.003 is battery voltage
** Nest turns off wifi below 3.7 V, and waits until 3.8 V to automatically reconnect

== Nest software ==
/nestlabs/sbin/nlclient -config /nestlabs/etc/client.config -config /nestlabs/etc/Display/Display-2/client.config

=== Backplate communications ===
Backplate communications can be decoded from a (filtered) strace log using [http://luke.dashjr.org/programs/freeabode/kindling/NestDecode.pl NestDecode.pl], or decoded in real time using [http://luke.dashjr.org/programs/freeabode/kindling/nest-intercept.c nest-intercept.c].

nest-intercept.c requires one argument, the thread id reading from the backplate controller.
The easiest way to get this is to strace the nlclient process with -ff and look for a thread reading from fd 54.

Note that nest-intercept.c also has a "hack" variable which can be set to 0 (default is 2) in order to corrupt the TFE version response and trigger nlclient into uploading the firmware again.

=== Backplate firmware ===
Found in /nestlabs/share/bp/data/firmware/nlbpfirmware.plist

There are 12 different firmwares in the file:
* Test vs Production
* Backplate 2 vs Backplate 3
* TFE (BP_D2 for Bp2, AMBER_BP for Bp3) vs BSL
* For TFE firmwares, hex vs srec (which for some reason DO differ!)

Python script to extract them into individual files: [http://luke.dashjr.org/programs/freeabode/kindling/extract-fw.py extract-fw.py]

=== Backplate initialisation ===
When the backplate is first connected, the following sequence occurs:
tcflush(fd, TCIFLUSH)
Set baud to 115200 (-opost -isig -icanon -echo ...)
tcflush(fd, TCIOFLUSH)
tcsendbreak(fd, 1)
Send [[#Reset|00ff - Reset]]
Recv 0001 - (message from backplate; ASCII)
Recv [[#FET presence|0004 - FET presence]]
Recv [[#FET presence|0009 - FET presence]]
Send [[#FET presence|008f - FET presence]]
Send [[#Periodic status|0083 - Periodic status request]]
Send 0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
Recv 0001 - (message from backplate; ASCII)
Recv 0001 - (message from backplate; ASCII)
Recv 0010 - (24-bit data)
Send [[#Get TFE version|0098 - Get TFE version]]
Recv 000a - (every second; 16-bit data)
Recv 0007 - (every second; 16-bit data)
Recv [[#Get TFE version|0018 - Get TFE version (response)]]
Send [[#Get build info|0099 - Get build info]]
Recv [[#Get build info|0019 - Get build info (response)]]
Sometimes:
Send 009d - (no data; responds with 001d (constant?) data=bbbb)
Recv 001d - Response to 009d; always(?) bbbb
Sometimes:
Send [[#Get BSL version|009b - Get BSL version]]
Recv [[#Get BSL version|001b - Get BSL version (response)]]
Sometimes:
Send 009c - (no data; responds with 001c (constant?) data="BSL")
Recv 001c - Response to 009c; always(?) "BSL"
Send [[#Get serial number|009f - Get serial number]]
Recv [[#Get serial number|001f - Get serial number (response)]]
Send [[#Get hardware version?|009e - Get hardware version?]]
Recv [[#Get hardware version?|001e - Get hardware version? (response)]]

== Nest backplate interface ==
* Connected on /dev/ttyO2
* All communications with backplate begin with (d5)d5aa96 (d5 is doubled only for data FROM backplate)
* Everything is little endian
* 16-bit command
* 16-bit data length
* <data>
* 16-bit checksum

Monitor:
strace -ff -p $(pidof nlclient) -x -s9999 -e read,write 2>&1 | grep '(54'

=== Checksum ===
<Bytes-from-end>.<bit-value> <xor-with>
00.01 2110 (1021)
00.02 4220 (2042: 1021<<1)
00.04 8440 (4084: 2048<<1)
00.08 0881 (8108: 4084<<1)
00.10 3112 (1231: 8108<<1^1021)
00.20 6224 (2462: 1231<<1)
00.40 c448 (48c4: 2462<<1)
00.80 8891 (9188: 48c4<<1)
01.01 3133 (3313: 9188<<1^1021)
01.02 6266
01.04 c4cc
01.08 a989
01.10 7303
01.20 e606
01.40 cc0d
01.80 981b
02.01 3037
02.02 606e
...
03.01 b476
03.02 68ed
03.04 f1ca
03.08 c385
03.10 a71b
03.20 4e37
03.40 9c6e
03.80 38dd
...
07.20 687b

If you compute the contribution of the individual bit changes in the data you end up with the xor table above; byte offset from the end of the data, bit pattern, xor value. Correcting for little endianess in the output you end up with the hex values in parenthesis. The least significant bit is 0x1021 and each subsequent bit is a shift left, if the XOR value has the 0x8000 bit set then it is XORed with 0x1021. This is the CRC-CCITT polynomial.

8 7 6 5 4 3 2 1 0
d5 aa 96 82 00 02 00 00 00: 08b2
|| |
|| 68ed
|408b
20d4

08b2: 68ed ^ 408b ^ 20d4

Starting at the least significant bit and filling in the XOR values for each bit gives the above diagram; the diagram stops at the 20d4 XOR value because at that point it matches the final CRC. This tells us that the CRC covers the 6 bytes prior.

#!/usr/bin/env perl
use Digest::CRC qw(crc);
my $data = pack("H*", "820002000000");
printf("%04x\n", crc($data,16,0,0,0,0x1021,0,0));

We can also compute the same CRC in Perl; note the result will be byte swapped since the data encodes the number as little endian.

=== Command ids ===

==== Display to backplate ====
[[#FET control|0082 - FET control]]
[[#Periodic status|0083 - Periodic status request]]
[[#FET presence|008f - FET presence]]
0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
[[#Backplate firmware upload|0091 - Backplate firmware upload (start)]]
[[#Backplate firmware upload|0092 - Backplate firmware upload]]
[[#Backplate firmware upload|0093 - Backplate firmware upload (finish)]]
[[#Get TFE version|0098 - Get TFE version]]
[[#Get build info|0099 - Get build info]]
[[#Get BSL version|009b - Get BSL version]]
009c - (no data; responds with 001c (constant?) data="BSL")
009d - (no data; responds with 001d (constant?) data=bbbb)
[[#Get hardware version?|009e - Get hardware version?]]
[[#Get serial number|009f - Get serial number]]
00a1 - (16-bit data)
[[#"Buffers"|00a2 - Request "buffers" (every 30 seconds; no data; triggers [0025] [0027] 0022 0023 [0029] [002b] 000c 002f)]]
[[#"Buffers"|00a3 - ACK to 002f (no data)]]
00a4 - (16-bit data)
00b1 - button pressed/unpressed (no data)
00b3 - (32-bit data; always ffffffff?)
00b5 - (16-bit data; always 0f00?)
00b9 - (32-bit data; always 0000ffff?)
00ba - (48-bit data; always 000000000000?)
00c2 - (48-bit data)
[[#Reset|00ff - Reset]]

==== Backplate to display ====
0001 - (message from backplate; ASCII)
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
[[#FET presence|0004 - FET presence]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
[[#FET presence|0009 - FET presence]]
000a - (every second; 2x(?) 16-bit data)
[[#Backplate state|000b - Backplate state]]
000c - (16-bit values: pir, px1, px1 divisor, px2, px2 divisor, alir, av; included in [[#"Buffers"|"buffers" data]])
0010 - (24-bit data)
[[#Backplate firmware upload|0011 - Backplate firmware upload (ACK)]]
0014 - (16-bit data)
[[#Get TFE version|0018 - Get TFE version (response)]]
[[#Get build info|0019 - Get build info (response)]]
[[#Get BSL version|001b - Get BSL version (response)]]
001c - Response to 009c; always(?) "BSL"
001d - Response to 009d; always(?) bbbb
[[#Get hardware version?|001e - Get hardware version? (response)]]
[[#Get serial number|001f - Get serial number (response)]]
[[#"Buffers"|0022 - 32-bit data (likely 2x 16-bit; possibly multiple times)]]
[[#"Buffers"|0023 - 48-bit data (likely 3x 16-bit; possibly multiple times)]]
[[#"Buffers"|0025 - 16-bit data (possibly multiple times)]]
[[#"Buffers"|0027 - 64-bit data (possibly multiple times)]]
[[#"Buffers"|0029 - 48-bit data (likely 3x 16-bit; possibly multiple times)]]
[[#"Buffers"|002b - 64-bit data (possibly multiple times)]]
[[#"Buffers"|002f - End of "buffers" (16-bit data)]]

=== Backplate firmware upload ===
For uploading the firmware, the following sequence is used:
Send 0091 data=0000<firmware type>
Recv 0011 data=0000
Send 0092 data=0100...
Recv 0011 data=0100
Send 0092 data=0200...
Recv 0011 data=0200
...
Send 0092 data=a901...
Recv 0011 data=a901
Send 0093 data=aa01
Recv 0011 data=aa01
Following the upload, the [[#Backplate initialisation|backplate initialisation process]] begins immediately (that is, without message 00ff being sent to order a reset).
Presumably the 0011 message is an ACK, and the first 16 bits of each message is the line number.
The format itself appears to be Motorola S-record (SREC).
Uploading the BSL firmware was followed by the TFE firmware, so it may be required (though uploading the TFE firmware does ''not'' require uploading the BSL).

Firmware type is either 4d for TFE or 42 for BSL.

=== Backplate state ===
Data:
* 8-bit "state"
* 8-bit "flags"
* 8-bit "px0" (may be wider?)
* 40-bit UNKNOWN (includes at least "p2" and "voc")
* 16-bit centi-volts "vi"
* 16-bit milli-volts "vo"
* 16-bit milli-volts "vb"
* 8-bit ("pins" or "wires")
* 8-bit ("wires" or "pins")
* 16-bit UNKNOWN

=== "Buffers" ===
The 00a2 message requests the backplate send the contents of various "buffers", which are returned in messages [0025], [0027], 0022, 0023, [0029], and [002b] (empty ones will NOT be sent; brackets infer commonly-empty buffers).
00a2 also triggers 000c immediately following these.
After all the buffers (including 000c) have been sent, the message 002f indicates "end of buffers".
The display is then expected to acknowledge it with message 00a3.

=== FET control ===
Turn on W1: d5aa96 8200 0200 00 01 29a2
Turn off W1: d5aa96 8200 0200 00 00 08b2
Turn on Y1: d5aa96 8200 0200 01 01 1891
Turn off Y1: d5aa96 8200 0200 01 00 3981
Turn on G : d5aa96 8200 0200 02 01 4bc4
Turn off G : d5aa96 8200 0200 02 00 6ad4
Turn on OB: d5aa96 8200 0200 03 01 7af7
Turn off OB: d5aa96 8200 0200 03 00 5be7
Turn on W2: d5aa96 8200 0200 04 01 ed6e
Turn off W2: d5aa96 8200 0200 04 00 cc7e
Turn on Y2: d5aa96 8200 0200 07 01 be3b
Turn off Y2: d5aa96 8200 0200 07 00 9f2b
Turn on * : d5aa96 8200 0200 0b 01 d37e
Turn off * : d5aa96 8200 0200 0b 00 f26e

For the sake of documentation, we will refer to the unique id numbers for each wire as "wire id numbers".
So wire id 0 is W1, wire id 1 is Y1, wire id B is *, etc.

=== FET presence ===
The backplate will, at least upon connection, send information about which FETs have a wire present.
This data is received with command ids 0004 and 0009, in that order.
Each sensor is represented by one byte which is either 00 (not present) or 01 (present).

The content of 0004 is in order of the "wire id numbers" used for control:
W1, Y1, G, OB, W2, ?0, ?0, Y2, ?1, ?1, ?0, *, ?0

The content of 0009 is arranged differently and has 2 more values:
W1, Y1, ?1, ?1, ?0, G, OB, W2, ?0, Y2, ?0, *, ?0, ?0, ?0

After these are received, the display sends back command 008f with the exact data from message 0004.
Message 008f does not itself receive any response.

In a power outage condition, 0004 will report all absent (including unknown ones), whereas 0009 will continue to report the same as when power is available.

=== Get build info ===
Message 0099 (no data) requests the backplate report information about its build.
The response will be message 0019 in ASCII (one line, no trailing newline).

=== Get hardware version? ===
Message 009e (no data) requests the backplate report a "Backplate-"X.Y version string.
Since the firmware file on the display CPU uses these strings as "MinApplicability" and "MaxApplicability" ranges, it is probable they refer to the hardware.

Witnessed versions:
"Backplate-2.8" - Florida Lowes

=== Get BSL version ===
Message 009b (no data) requests the backplate report its BSL version number.
The response will be message 001b in ASCII.

=== Get TFE version ===
Message 0098 (no data) requests the backplate report its TFE version number.
The response will be message 0018 in ASCII.

=== Get serial number ===
Message 009f (no data) requests the backplate report its serial number (a 64-bit hexadecimal value).
The response will be message 001f in uppercase ASCII.

=== Periodic status ===
Sending message 0083 (no data) will trigger various periodic messages:
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
000a - (every second; 16-bit data)

The Nest client sends 0083 every 30 seconds, but at least the periodic temperature status will continue on for an hour before stopping.

=== Temperature reading ===
The backplate will send message 0002 every 30 seconds.
The data contains two 16-bit numbers, which nlclient logs in decimal.
The first number is the temperature in centi-celcius.
The second number is the humidity in per-millis.

=== Reset ===
At least upon connection, the display sends message 00ff to the backplate to reset.

The backplate answers with:
0001 msg "<version> <build timestamp "YYYY-MM-DD HH:MM:SS"> K"
[[#FET presence|0004 FET presence]]
[[#FET presence|0009 FET presence]]
0001 msg "*sense 06d1 06d0 0001 0001 0000 0000 0000 0001 06d9 06d8 06d8; detect 09d3 065c"
0001 msg "BRK"

== Run BeagleBone/Debian programs ==
ln -s . /lib/arm-linux-gnueabihf
ln -s ld-2.11.1.so /lib/ld-linux-armhf.so.3

Nest Hacking

2014-08-07T02:33:00Z

Luke-Jr: /* FET control */

== Hardware ==

[https://www.ifixit.com/Teardown/Nest+Learning+Thermostat+2nd+Generation+Teardown/13818 Pictures]

=== Backplate ===
* ST Microelectronics STM32L151VB ultra-low-power 32 MHz ARM Cortex-M3 MCU
* Sensirion SHT20 humidity and temperature sensor
* Texas Instruments LW051A 8-channel CMOS analog multiplexer/demultiplexer

=== Display ===
* Texas Instruments AM3703CUS Sitara ARM Cortex A8 microprocessor
* Texas Instruments TPS65921B power management and USB single chip
* Samsung K4X51163PK 512 Mb mobile DRAM
* Ember EM357 integrated ZigBee/802.15.4 system-on-chip
* Micron MT29F2G16ABBEAH4 2 Gb NAND flash memory
* Skyworks 2436L high power 2.4 GHz 802.15.4 front-end module
* Texas Instruments WL1270B 802.11 b/g/n Wi-Fi solution
* Avago ADBM-A350 optical finger navigation module (knob movement sensor)

== Info ==
* /dev/event1 is the knob; /dev/event2 is the button
* /sys/class/hwmon/hwmon0/device/in0_battery_type * 0.003 is battery voltage
** Nest turns off wifi below 3.7 V, and waits until 3.8 V to automatically reconnect

== Nest software ==
/nestlabs/sbin/nlclient -config /nestlabs/etc/client.config -config /nestlabs/etc/Display/Display-2/client.config

=== Backplate communications ===
Backplate communications can be decoded from a (filtered) strace log using [http://luke.dashjr.org/programs/freeabode/kindling/NestDecode.pl NestDecode.pl], or decoded in real time using [http://luke.dashjr.org/programs/freeabode/kindling/nest-intercept.c nest-intercept.c].

nest-intercept.c requires one argument, the thread id reading from the backplate controller.
The easiest way to get this is to strace the nlclient process with -ff and look for a thread reading from fd 54.

Note that nest-intercept.c also has a "hack" variable which can be set to 0 (default is 2) in order to corrupt the TFE version response and trigger nlclient into uploading the firmware again.

=== Backplate firmware ===
Found in /nestlabs/share/bp/data/firmware/nlbpfirmware.plist

There are 12 different firmwares in the file:
* Test vs Production
* Backplate 2 vs Backplate 3
* TFE (BP_D2 for Bp2, AMBER_BP for Bp3) vs BSL
* For TFE firmwares, hex vs srec (which for some reason DO differ!)

Python script to extract them into individual files: [http://luke.dashjr.org/programs/freeabode/kindling/extract-fw.py extract-fw.py]

=== Backplate initialisation ===
When the backplate is first connected, the following sequence occurs:
tcflush(fd, TCIFLUSH)
Set baud to 115200 (-opost -isig -icanon -echo ...)
tcflush(fd, TCIOFLUSH)
tcsendbreak(fd, 1)
Send [[#Reset|00ff - Reset]]
Recv 0001 - (message from backplate; ASCII)
Recv [[#FET presence|0004 - FET presence]]
Recv [[#FET presence|0009 - FET presence]]
Send [[#FET presence|008f - FET presence]]
Send [[#Periodic status|0083 - Periodic status request]]
Send 0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
Recv 0001 - (message from backplate; ASCII)
Recv 0001 - (message from backplate; ASCII)
Recv 0010 - (24-bit data)
Send [[#Get TFE version|0098 - Get TFE version]]
Recv 000a - (every second; 16-bit data)
Recv 0007 - (every second; 16-bit data)
Recv [[#Get TFE version|0018 - Get TFE version (response)]]
Send [[#Get build info|0099 - Get build info]]
Recv [[#Get build info|0019 - Get build info (response)]]
Sometimes:
Send 009d - (no data; responds with 001d (constant?) data=bbbb)
Recv 001d - Response to 009d; always(?) bbbb
Sometimes:
Send [[#Get BSL version|009b - Get BSL version]]
Recv [[#Get BSL version|001b - Get BSL version (response)]]
Sometimes:
Send 009c - (no data; responds with 001c (constant?) data="BSL")
Recv 001c - Response to 009c; always(?) "BSL"
Send [[#Get serial number|009f - Get serial number]]
Recv [[#Get serial number|001f - Get serial number (response)]]
Send [[#Get hardware version?|009e - Get hardware version?]]
Recv [[#Get hardware version?|001e - Get hardware version? (response)]]

== Nest backplate interface ==
* Connected on /dev/ttyO2
* All communications with backplate begin with (d5)d5aa96 (d5 is doubled only for data FROM backplate)
* Everything is little endian
* 16-bit command
* 16-bit data length
* <data>
* 16-bit checksum

Monitor:
strace -ff -p $(pidof nlclient) -x -s9999 -e read,write 2>&1 | grep '(54'

=== Checksum ===
<Bytes-from-end>.<bit-value> <xor-with>
00.01 2110 (1021)
00.02 4220 (2042: 1021<<1)
00.04 8440 (4084: 2048<<1)
00.08 0881 (8108: 4084<<1)
00.10 3112 (1231: 8108<<1^1021)
00.20 6224 (2462: 1231<<1)
00.40 c448 (48c4: 2462<<1)
00.80 8891 (9188: 48c4<<1)
01.01 3133 (3313: 9188<<1^1021)
01.02 6266
01.04 c4cc
01.08 a989
01.10 7303
01.20 e606
01.40 cc0d
01.80 981b
02.01 3037
02.02 606e
...
03.01 b476
03.02 68ed
03.04 f1ca
03.08 c385
03.10 a71b
03.20 4e37
03.40 9c6e
03.80 38dd
...
07.20 687b

If you compute the contribution of the individual bit changes in the data you end up with the xor table above; byte offset from the end of the data, bit pattern, xor value. Correcting for little endianess in the output you end up with the hex values in parenthesis. The least significant bit is 0x1021 and each subsequent bit is a shift left, if the XOR value has the 0x8000 bit set then it is XORed with 0x1021. This is the CRC-CCITT polynomial.

8 7 6 5 4 3 2 1 0
d5 aa 96 82 00 02 00 00 00: 08b2
|| |
|| 68ed
|408b
20d4

08b2: 68ed ^ 408b ^ 20d4

Starting at the least significant bit and filling in the XOR values for each bit gives the above diagram; the diagram stops at the 20d4 XOR value because at that point it matches the final CRC. This tells us that the CRC covers the 6 bytes prior.

#!/usr/bin/env perl
use Digest::CRC qw(crc);
my $data = pack("H*", "820002000000");
printf("%04x\n", crc($data,16,0,0,0,0x1021,0,0));

We can also compute the same CRC in Perl; note the result will be byte swapped since the data encodes the number as little endian.

=== Command ids ===

==== Display to backplate ====
[[#FET control|0082 - FET control]]
[[#Periodic status|0083 - Periodic status request]]
[[#FET presence|008f - FET presence]]
0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
[[#Backplate firmware upload|0091 - Backplate firmware upload (start)]]
[[#Backplate firmware upload|0092 - Backplate firmware upload]]
[[#Backplate firmware upload|0093 - Backplate firmware upload (finish)]]
[[#Get TFE version|0098 - Get TFE version]]
[[#Get build info|0099 - Get build info]]
[[#Get BSL version|009b - Get BSL version]]
009c - (no data; responds with 001c (constant?) data="BSL")
009d - (no data; responds with 001d (constant?) data=bbbb)
[[#Get hardware version?|009e - Get hardware version?]]
[[#Get serial number|009f - Get serial number]]
00a1 - (16-bit data)
[[#"Buffers"|00a2 - Request "buffers" (every 30 seconds; no data; triggers [0025] [0027] 0022 0023 [0029] [002b] 000c 002f)]]
[[#"Buffers"|00a3 - ACK to 002f (no data)]]
00a4 - (16-bit data)
00b1 - button pressed/unpressed (no data)
00b3 - (32-bit data; always ffffffff?)
00b5 - (16-bit data; always 0f00?)
00b9 - (32-bit data; always 0000ffff?)
00ba - (48-bit data; always 000000000000?)
00c2 - (48-bit data)
[[#Reset|00ff - Reset]]

==== Backplate to display ====
0001 - (message from backplate; ASCII)
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
[[#FET presence|0004 - FET presence]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
[[#FET presence|0009 - FET presence]]
000a - (every second; 2x(?) 16-bit data)
[[#Backplate state|000b - Backplate state]]
000c - (16-bit values: pir, px1, px1 divisor, px2, px2 divisor, alir, av; included in [[#"Buffers"|"buffers" data]])
0010 - (24-bit data)
[[#Backplate firmware upload|0011 - Backplate firmware upload (ACK)]]
0014 - (16-bit data)
[[#Get TFE version|0018 - Get TFE version (response)]]
[[#Get build info|0019 - Get build info (response)]]
[[#Get BSL version|001b - Get BSL version (response)]]
001c - Response to 009c; always(?) "BSL"
001d - Response to 009d; always(?) bbbb
[[#Get hardware version?|001e - Get hardware version? (response)]]
[[#Get serial number|001f - Get serial number (response)]]
[[#"Buffers"|0022 - 32-bit data (likely 2x 16-bit; possibly multiple times)]]
[[#"Buffers"|0023 - 48-bit data (likely 3x 16-bit; possibly multiple times)]]
[[#"Buffers"|0025 - 16-bit data (possibly multiple times)]]
[[#"Buffers"|0027 - 64-bit data (possibly multiple times)]]
[[#"Buffers"|0029 - 48-bit data (likely 3x 16-bit; possibly multiple times)]]
[[#"Buffers"|002b - 64-bit data (possibly multiple times)]]
[[#"Buffers"|002f - End of "buffers" (16-bit data)]]

=== Backplate firmware upload ===
For uploading the firmware, the following sequence is used:
Send 0091 data=0000<firmware type>
Recv 0011 data=0000
Send 0092 data=0100...
Recv 0011 data=0100
Send 0092 data=0200...
Recv 0011 data=0200
...
Send 0092 data=a901...
Recv 0011 data=a901
Send 0093 data=aa01
Recv 0011 data=aa01
Following the upload, the [[#Backplate initialisation|backplate initialisation process]] begins immediately (that is, without message 00ff being sent to order a reset).
Presumably the 0011 message is an ACK, and the first 16 bits of each message is the line number.
The format itself appears to be Motorola S-record (SREC).
Uploading the BSL firmware was followed by the TFE firmware, so it may be required (though uploading the TFE firmware does ''not'' require uploading the BSL).

Firmware type is either 4d for TFE or 42 for BSL.

=== Backplate state ===
Data:
* 8-bit "state"
* 8-bit "flags"
* 8-bit "px0" (may be wider?)
* 40-bit UNKNOWN (includes at least "p2" and "voc")
* 16-bit centi-volts "vi"
* 16-bit milli-volts "vo"
* 16-bit milli-volts "vb"
* 8-bit ("pins" or "wires")
* 8-bit ("wires" or "pins")
* 16-bit UNKNOWN

=== "Buffers" ===
The 00a2 message requests the backplate send the contents of various "buffers", which are returned in messages [0025], [0027], 0022, 0023, [0029], and [002b] (empty ones will NOT be sent; brackets infer commonly-empty buffers).
00a2 also triggers 000c immediately following these.
After all the buffers (including 000c) have been sent, the message 002f indicates "end of buffers".
The display is then expected to acknowledge it with message 00a3.

=== FET control ===
Turn on W1: d5aa96 8200 0200 00 01 29a2
Turn off W1: d5aa96 8200 0200 00 00 08b2
Turn on Y1: d5aa96 8200 0200 01 01 1891
Turn off Y1: d5aa96 8200 0200 01 00 3981
Turn on G : d5aa96 8200 0200 02 01 4bc4
Turn off G : d5aa96 8200 0200 02 00 6ad4
Turn on OB: d5aa96 8200 0200 03 01 7af7
Turn off OB: d5aa96 8200 0200 03 00 5be7
Turn on W2: d5aa96 8200 0200 04 01 ed6e
Turn off W2: d5aa96 8200 0200 04 00 cc7e
Turn on Y2: d5aa96 8200 0200 07 01 be3b
Turn off Y2: d5aa96 8200 0200 07 00 9f2b
Turn on * : d5aa96 8200 0200 0b 01 d37e
Turn off * : d5aa96 8200 0200 0b 00 f26e

For the sake of documentation, we will refer to the unique id numbers for each wire as "wire id numbers".
So wire id 0 is W1, wire id 1 is Y1, wire id B is *, etc.

=== FET presence ===
The backplate will, at least upon connection, send information about which FETs have a wire present.
This data is received with command ids 0004 and 0009, in that order.
Each sensor is represented by one byte which is either 00 (not present) or 01 (present).

The content of 0004 is in order of the "wire id numbers" used for control:
W1, Y1, G, OB, W2, ?0, ?0, Y2, ?1, ?1, ?0, *, ?0

The content of 0009 is arranged differently and has 2 more values:
W1, Y1, ?1, ?1, ?0, G, OB, W2, ?0, Y2, ?0, *, ?0, ?0, ?0

After these are received, the display sends back command 008f with the exact data from message 0004.
Message 008f does not itself receive any response.

In a power outage condition, 0004 will report all absent (including unknown ones), whereas 0009 will continue to report the same as when power is available.

=== Get build info ===
Message 0099 (no data) requests the backplate report information about its build.
The response will be message 0019 in ASCII (one line, no trailing newline).

=== Get serial number ===
Message 009f (no data) requests the backplate report its serial number (a 64-bit hexadecimal value).
The response will be message 001f in uppercase ASCII.

=== Get hardware version? ===
Message 009e (no data) requests the backplate report a "Backplate-"X.Y version string.
Since the firmware file on the display CPU uses these strings as "MinApplicability" and "MaxApplicability" ranges, it is probable they refer to the hardware.

Witnessed versions:
"Backplate-2.8" - Florida Lowes

=== Get BSL version ===
Message 009b (no data) requests the backplate report its BSL version number.
The response will be message 001b in ASCII.

=== Get TFE version ===
Message 0098 (no data) requests the backplate report its TFE version number.
The response will be message 0018 in ASCII.

=== Periodic status ===
Sending message 0083 (no data) will trigger various periodic messages:
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
000a - (every second; 16-bit data)

The Nest client sends 0083 every 30 seconds, but at least the periodic temperature status will continue on for an hour before stopping.

=== Temperature reading ===
The backplate will send message 0002 every 30 seconds.
The data contains two 16-bit numbers, which nlclient logs in decimal.
The first number is the temperature in centi-celcius.
The second number is the humidity in per-millis.

=== Reset ===
At least upon connection, the display sends message 00ff to the backplate to reset.

The backplate answers with:
0001 msg "<version> <build timestamp "YYYY-MM-DD HH:MM:SS"> K"
[[#FET presence|0004 FET presence]]
[[#FET presence|0009 FET presence]]
0001 msg "*sense 06d1 06d0 0001 0001 0000 0000 0000 0001 06d9 06d8 06d8; detect 09d3 065c"
0001 msg "BRK"

== Run BeagleBone/Debian programs ==
ln -s . /lib/arm-linux-gnueabihf
ln -s ld-2.11.1.so /lib/ld-linux-armhf.so.3

Nest Hacking

2014-08-07T02:29:58Z

Luke-Jr: /* Display to backplate */

== Hardware ==

[https://www.ifixit.com/Teardown/Nest+Learning+Thermostat+2nd+Generation+Teardown/13818 Pictures]

=== Backplate ===
* ST Microelectronics STM32L151VB ultra-low-power 32 MHz ARM Cortex-M3 MCU
* Sensirion SHT20 humidity and temperature sensor
* Texas Instruments LW051A 8-channel CMOS analog multiplexer/demultiplexer

=== Display ===
* Texas Instruments AM3703CUS Sitara ARM Cortex A8 microprocessor
* Texas Instruments TPS65921B power management and USB single chip
* Samsung K4X51163PK 512 Mb mobile DRAM
* Ember EM357 integrated ZigBee/802.15.4 system-on-chip
* Micron MT29F2G16ABBEAH4 2 Gb NAND flash memory
* Skyworks 2436L high power 2.4 GHz 802.15.4 front-end module
* Texas Instruments WL1270B 802.11 b/g/n Wi-Fi solution
* Avago ADBM-A350 optical finger navigation module (knob movement sensor)

== Info ==
* /dev/event1 is the knob; /dev/event2 is the button
* /sys/class/hwmon/hwmon0/device/in0_battery_type * 0.003 is battery voltage
** Nest turns off wifi below 3.7 V, and waits until 3.8 V to automatically reconnect

== Nest software ==
/nestlabs/sbin/nlclient -config /nestlabs/etc/client.config -config /nestlabs/etc/Display/Display-2/client.config

=== Backplate communications ===
Backplate communications can be decoded from a (filtered) strace log using [http://luke.dashjr.org/programs/freeabode/kindling/NestDecode.pl NestDecode.pl], or decoded in real time using [http://luke.dashjr.org/programs/freeabode/kindling/nest-intercept.c nest-intercept.c].

nest-intercept.c requires one argument, the thread id reading from the backplate controller.
The easiest way to get this is to strace the nlclient process with -ff and look for a thread reading from fd 54.

Note that nest-intercept.c also has a "hack" variable which can be set to 0 (default is 2) in order to corrupt the TFE version response and trigger nlclient into uploading the firmware again.

=== Backplate firmware ===
Found in /nestlabs/share/bp/data/firmware/nlbpfirmware.plist

There are 12 different firmwares in the file:
* Test vs Production
* Backplate 2 vs Backplate 3
* TFE (BP_D2 for Bp2, AMBER_BP for Bp3) vs BSL
* For TFE firmwares, hex vs srec (which for some reason DO differ!)

Python script to extract them into individual files: [http://luke.dashjr.org/programs/freeabode/kindling/extract-fw.py extract-fw.py]

=== Backplate initialisation ===
When the backplate is first connected, the following sequence occurs:
tcflush(fd, TCIFLUSH)
Set baud to 115200 (-opost -isig -icanon -echo ...)
tcflush(fd, TCIOFLUSH)
tcsendbreak(fd, 1)
Send [[#Reset|00ff - Reset]]
Recv 0001 - (message from backplate; ASCII)
Recv [[#FET presence|0004 - FET presence]]
Recv [[#FET presence|0009 - FET presence]]
Send [[#FET presence|008f - FET presence]]
Send [[#Periodic status|0083 - Periodic status request]]
Send 0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
Recv 0001 - (message from backplate; ASCII)
Recv 0001 - (message from backplate; ASCII)
Recv 0010 - (24-bit data)
Send [[#Get TFE version|0098 - Get TFE version]]
Recv 000a - (every second; 16-bit data)
Recv 0007 - (every second; 16-bit data)
Recv [[#Get TFE version|0018 - Get TFE version (response)]]
Send [[#Get build info|0099 - Get build info]]
Recv [[#Get build info|0019 - Get build info (response)]]
Sometimes:
Send 009d - (no data; responds with 001d (constant?) data=bbbb)
Recv 001d - Response to 009d; always(?) bbbb
Sometimes:
Send [[#Get BSL version|009b - Get BSL version]]
Recv [[#Get BSL version|001b - Get BSL version (response)]]
Sometimes:
Send 009c - (no data; responds with 001c (constant?) data="BSL")
Recv 001c - Response to 009c; always(?) "BSL"
Send [[#Get serial number|009f - Get serial number]]
Recv [[#Get serial number|001f - Get serial number (response)]]
Send [[#Get hardware version?|009e - Get hardware version?]]
Recv [[#Get hardware version?|001e - Get hardware version? (response)]]

== Nest backplate interface ==
* Connected on /dev/ttyO2
* All communications with backplate begin with (d5)d5aa96 (d5 is doubled only for data FROM backplate)
* Everything is little endian
* 16-bit command
* 16-bit data length
* <data>
* 16-bit checksum

Monitor:
strace -ff -p $(pidof nlclient) -x -s9999 -e read,write 2>&1 | grep '(54'

=== Checksum ===
<Bytes-from-end>.<bit-value> <xor-with>
00.01 2110 (1021)
00.02 4220 (2042: 1021<<1)
00.04 8440 (4084: 2048<<1)
00.08 0881 (8108: 4084<<1)
00.10 3112 (1231: 8108<<1^1021)
00.20 6224 (2462: 1231<<1)
00.40 c448 (48c4: 2462<<1)
00.80 8891 (9188: 48c4<<1)
01.01 3133 (3313: 9188<<1^1021)
01.02 6266
01.04 c4cc
01.08 a989
01.10 7303
01.20 e606
01.40 cc0d
01.80 981b
02.01 3037
02.02 606e
...
03.01 b476
03.02 68ed
03.04 f1ca
03.08 c385
03.10 a71b
03.20 4e37
03.40 9c6e
03.80 38dd
...
07.20 687b

If you compute the contribution of the individual bit changes in the data you end up with the xor table above; byte offset from the end of the data, bit pattern, xor value. Correcting for little endianess in the output you end up with the hex values in parenthesis. The least significant bit is 0x1021 and each subsequent bit is a shift left, if the XOR value has the 0x8000 bit set then it is XORed with 0x1021. This is the CRC-CCITT polynomial.

8 7 6 5 4 3 2 1 0
d5 aa 96 82 00 02 00 00 00: 08b2
|| |
|| 68ed
|408b
20d4

08b2: 68ed ^ 408b ^ 20d4

Starting at the least significant bit and filling in the XOR values for each bit gives the above diagram; the diagram stops at the 20d4 XOR value because at that point it matches the final CRC. This tells us that the CRC covers the 6 bytes prior.

#!/usr/bin/env perl
use Digest::CRC qw(crc);
my $data = pack("H*", "820002000000");
printf("%04x\n", crc($data,16,0,0,0,0x1021,0,0));

We can also compute the same CRC in Perl; note the result will be byte swapped since the data encodes the number as little endian.

=== Command ids ===

==== Display to backplate ====
[[#FET control|0082 - FET control]]
[[#Periodic status|0083 - Periodic status request]]
[[#FET presence|008f - FET presence]]
0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
[[#Backplate firmware upload|0091 - Backplate firmware upload (start)]]
[[#Backplate firmware upload|0092 - Backplate firmware upload]]
[[#Backplate firmware upload|0093 - Backplate firmware upload (finish)]]
[[#Get TFE version|0098 - Get TFE version]]
[[#Get build info|0099 - Get build info]]
[[#Get BSL version|009b - Get BSL version]]
009c - (no data; responds with 001c (constant?) data="BSL")
009d - (no data; responds with 001d (constant?) data=bbbb)
[[#Get hardware version?|009e - Get hardware version?]]
[[#Get serial number|009f - Get serial number]]
00a1 - (16-bit data)
[[#"Buffers"|00a2 - Request "buffers" (every 30 seconds; no data; triggers [0025] [0027] 0022 0023 [0029] [002b] 000c 002f)]]
[[#"Buffers"|00a3 - ACK to 002f (no data)]]
00a4 - (16-bit data)
00b1 - button pressed/unpressed (no data)
00b3 - (32-bit data; always ffffffff?)
00b5 - (16-bit data; always 0f00?)
00b9 - (32-bit data; always 0000ffff?)
00ba - (48-bit data; always 000000000000?)
00c2 - (48-bit data)
[[#Reset|00ff - Reset]]

==== Backplate to display ====
0001 - (message from backplate; ASCII)
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
[[#FET presence|0004 - FET presence]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
[[#FET presence|0009 - FET presence]]
000a - (every second; 2x(?) 16-bit data)
[[#Backplate state|000b - Backplate state]]
000c - (16-bit values: pir, px1, px1 divisor, px2, px2 divisor, alir, av; included in [[#"Buffers"|"buffers" data]])
0010 - (24-bit data)
[[#Backplate firmware upload|0011 - Backplate firmware upload (ACK)]]
0014 - (16-bit data)
[[#Get TFE version|0018 - Get TFE version (response)]]
[[#Get build info|0019 - Get build info (response)]]
[[#Get BSL version|001b - Get BSL version (response)]]
001c - Response to 009c; always(?) "BSL"
001d - Response to 009d; always(?) bbbb
[[#Get hardware version?|001e - Get hardware version? (response)]]
[[#Get serial number|001f - Get serial number (response)]]
[[#"Buffers"|0022 - 32-bit data (likely 2x 16-bit; possibly multiple times)]]
[[#"Buffers"|0023 - 48-bit data (likely 3x 16-bit; possibly multiple times)]]
[[#"Buffers"|0025 - 16-bit data (possibly multiple times)]]
[[#"Buffers"|0027 - 64-bit data (possibly multiple times)]]
[[#"Buffers"|0029 - 48-bit data (likely 3x 16-bit; possibly multiple times)]]
[[#"Buffers"|002b - 64-bit data (possibly multiple times)]]
[[#"Buffers"|002f - End of "buffers" (16-bit data)]]

=== Backplate firmware upload ===
For uploading the firmware, the following sequence is used:
Send 0091 data=0000<firmware type>
Recv 0011 data=0000
Send 0092 data=0100...
Recv 0011 data=0100
Send 0092 data=0200...
Recv 0011 data=0200
...
Send 0092 data=a901...
Recv 0011 data=a901
Send 0093 data=aa01
Recv 0011 data=aa01
Following the upload, the [[#Backplate initialisation|backplate initialisation process]] begins immediately (that is, without message 00ff being sent to order a reset).
Presumably the 0011 message is an ACK, and the first 16 bits of each message is the line number.
The format itself appears to be Motorola S-record (SREC).
Uploading the BSL firmware was followed by the TFE firmware, so it may be required (though uploading the TFE firmware does ''not'' require uploading the BSL).

Firmware type is either 4d for TFE or 42 for BSL.

=== Backplate state ===
Data:
* 8-bit "state"
* 8-bit "flags"
* 8-bit "px0" (may be wider?)
* 40-bit UNKNOWN (includes at least "p2" and "voc")
* 16-bit centi-volts "vi"
* 16-bit milli-volts "vo"
* 16-bit milli-volts "vb"
* 8-bit ("pins" or "wires")
* 8-bit ("wires" or "pins")
* 16-bit UNKNOWN

=== FET control ===
Turn on W1: d5aa96 8200 0200 00 01 29a2
Turn off W1: d5aa96 8200 0200 00 00 08b2
Turn on Y1: d5aa96 8200 0200 01 01 1891
Turn off Y1: d5aa96 8200 0200 01 00 3981
Turn on G : d5aa96 8200 0200 02 01 4bc4
Turn off G : d5aa96 8200 0200 02 00 6ad4
Turn on OB: d5aa96 8200 0200 03 01 7af7
Turn off OB: d5aa96 8200 0200 03 00 5be7
Turn on W2: d5aa96 8200 0200 04 01 ed6e
Turn off W2: d5aa96 8200 0200 04 00 cc7e
Turn on Y2: d5aa96 8200 0200 07 01 be3b
Turn off Y2: d5aa96 8200 0200 07 00 9f2b
Turn on * : d5aa96 8200 0200 0b 01 d37e
Turn off * : d5aa96 8200 0200 0b 00 f26e

For the sake of documentation, we will refer to the unique id numbers for each wire as "wire id numbers".
So wire id 0 is W1, wire id 1 is Y1, wire id B is *, etc.

=== FET presence ===
The backplate will, at least upon connection, send information about which FETs have a wire present.
This data is received with command ids 0004 and 0009, in that order.
Each sensor is represented by one byte which is either 00 (not present) or 01 (present).

The content of 0004 is in order of the "wire id numbers" used for control:
W1, Y1, G, OB, W2, ?0, ?0, Y2, ?1, ?1, ?0, *, ?0

The content of 0009 is arranged differently and has 2 more values:
W1, Y1, ?1, ?1, ?0, G, OB, W2, ?0, Y2, ?0, *, ?0, ?0, ?0

After these are received, the display sends back command 008f with the exact data from message 0004.
Message 008f does not itself receive any response.

In a power outage condition, 0004 will report all absent (including unknown ones), whereas 0009 will continue to report the same as when power is available.

=== Get build info ===
Message 0099 (no data) requests the backplate report information about its build.
The response will be message 0019 in ASCII (one line, no trailing newline).

=== Get serial number ===
Message 009f (no data) requests the backplate report its serial number (a 64-bit hexadecimal value).
The response will be message 001f in uppercase ASCII.

=== Get hardware version? ===
Message 009e (no data) requests the backplate report a "Backplate-"X.Y version string.
Since the firmware file on the display CPU uses these strings as "MinApplicability" and "MaxApplicability" ranges, it is probable they refer to the hardware.

Witnessed versions:
"Backplate-2.8" - Florida Lowes

=== Get BSL version ===
Message 009b (no data) requests the backplate report its BSL version number.
The response will be message 001b in ASCII.

=== Get TFE version ===
Message 0098 (no data) requests the backplate report its TFE version number.
The response will be message 0018 in ASCII.

=== Periodic status ===
Sending message 0083 (no data) will trigger various periodic messages:
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
000a - (every second; 16-bit data)

The Nest client sends 0083 every 30 seconds, but at least the periodic temperature status will continue on for an hour before stopping.

=== Temperature reading ===
The backplate will send message 0002 every 30 seconds.
The data contains two 16-bit numbers, which nlclient logs in decimal.
The first number is the temperature in centi-celcius.
The second number is the humidity in per-millis.

=== Reset ===
At least upon connection, the display sends message 00ff to the backplate to reset.

The backplate answers with:
0001 msg "<version> <build timestamp "YYYY-MM-DD HH:MM:SS"> K"
[[#FET presence|0004 FET presence]]
[[#FET presence|0009 FET presence]]
0001 msg "*sense 06d1 06d0 0001 0001 0000 0000 0000 0001 06d9 06d8 06d8; detect 09d3 065c"
0001 msg "BRK"

== Run BeagleBone/Debian programs ==
ln -s . /lib/arm-linux-gnueabihf
ln -s ld-2.11.1.so /lib/ld-linux-armhf.so.3

Nest Hacking

2014-08-07T02:29:26Z

Luke-Jr: /* Command ids */ Group "buffers" together

== Hardware ==

[https://www.ifixit.com/Teardown/Nest+Learning+Thermostat+2nd+Generation+Teardown/13818 Pictures]

=== Backplate ===
* ST Microelectronics STM32L151VB ultra-low-power 32 MHz ARM Cortex-M3 MCU
* Sensirion SHT20 humidity and temperature sensor
* Texas Instruments LW051A 8-channel CMOS analog multiplexer/demultiplexer

=== Display ===
* Texas Instruments AM3703CUS Sitara ARM Cortex A8 microprocessor
* Texas Instruments TPS65921B power management and USB single chip
* Samsung K4X51163PK 512 Mb mobile DRAM
* Ember EM357 integrated ZigBee/802.15.4 system-on-chip
* Micron MT29F2G16ABBEAH4 2 Gb NAND flash memory
* Skyworks 2436L high power 2.4 GHz 802.15.4 front-end module
* Texas Instruments WL1270B 802.11 b/g/n Wi-Fi solution
* Avago ADBM-A350 optical finger navigation module (knob movement sensor)

== Info ==
* /dev/event1 is the knob; /dev/event2 is the button
* /sys/class/hwmon/hwmon0/device/in0_battery_type * 0.003 is battery voltage
** Nest turns off wifi below 3.7 V, and waits until 3.8 V to automatically reconnect

== Nest software ==
/nestlabs/sbin/nlclient -config /nestlabs/etc/client.config -config /nestlabs/etc/Display/Display-2/client.config

=== Backplate communications ===
Backplate communications can be decoded from a (filtered) strace log using [http://luke.dashjr.org/programs/freeabode/kindling/NestDecode.pl NestDecode.pl], or decoded in real time using [http://luke.dashjr.org/programs/freeabode/kindling/nest-intercept.c nest-intercept.c].

nest-intercept.c requires one argument, the thread id reading from the backplate controller.
The easiest way to get this is to strace the nlclient process with -ff and look for a thread reading from fd 54.

Note that nest-intercept.c also has a "hack" variable which can be set to 0 (default is 2) in order to corrupt the TFE version response and trigger nlclient into uploading the firmware again.

=== Backplate firmware ===
Found in /nestlabs/share/bp/data/firmware/nlbpfirmware.plist

There are 12 different firmwares in the file:
* Test vs Production
* Backplate 2 vs Backplate 3
* TFE (BP_D2 for Bp2, AMBER_BP for Bp3) vs BSL
* For TFE firmwares, hex vs srec (which for some reason DO differ!)

Python script to extract them into individual files: [http://luke.dashjr.org/programs/freeabode/kindling/extract-fw.py extract-fw.py]

=== Backplate initialisation ===
When the backplate is first connected, the following sequence occurs:
tcflush(fd, TCIFLUSH)
Set baud to 115200 (-opost -isig -icanon -echo ...)
tcflush(fd, TCIOFLUSH)
tcsendbreak(fd, 1)
Send [[#Reset|00ff - Reset]]
Recv 0001 - (message from backplate; ASCII)
Recv [[#FET presence|0004 - FET presence]]
Recv [[#FET presence|0009 - FET presence]]
Send [[#FET presence|008f - FET presence]]
Send [[#Periodic status|0083 - Periodic status request]]
Send 0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
Recv 0001 - (message from backplate; ASCII)
Recv 0001 - (message from backplate; ASCII)
Recv 0010 - (24-bit data)
Send [[#Get TFE version|0098 - Get TFE version]]
Recv 000a - (every second; 16-bit data)
Recv 0007 - (every second; 16-bit data)
Recv [[#Get TFE version|0018 - Get TFE version (response)]]
Send [[#Get build info|0099 - Get build info]]
Recv [[#Get build info|0019 - Get build info (response)]]
Sometimes:
Send 009d - (no data; responds with 001d (constant?) data=bbbb)
Recv 001d - Response to 009d; always(?) bbbb
Sometimes:
Send [[#Get BSL version|009b - Get BSL version]]
Recv [[#Get BSL version|001b - Get BSL version (response)]]
Sometimes:
Send 009c - (no data; responds with 001c (constant?) data="BSL")
Recv 001c - Response to 009c; always(?) "BSL"
Send [[#Get serial number|009f - Get serial number]]
Recv [[#Get serial number|001f - Get serial number (response)]]
Send [[#Get hardware version?|009e - Get hardware version?]]
Recv [[#Get hardware version?|001e - Get hardware version? (response)]]

== Nest backplate interface ==
* Connected on /dev/ttyO2
* All communications with backplate begin with (d5)d5aa96 (d5 is doubled only for data FROM backplate)
* Everything is little endian
* 16-bit command
* 16-bit data length
* <data>
* 16-bit checksum

Monitor:
strace -ff -p $(pidof nlclient) -x -s9999 -e read,write 2>&1 | grep '(54'

=== Checksum ===
<Bytes-from-end>.<bit-value> <xor-with>
00.01 2110 (1021)
00.02 4220 (2042: 1021<<1)
00.04 8440 (4084: 2048<<1)
00.08 0881 (8108: 4084<<1)
00.10 3112 (1231: 8108<<1^1021)
00.20 6224 (2462: 1231<<1)
00.40 c448 (48c4: 2462<<1)
00.80 8891 (9188: 48c4<<1)
01.01 3133 (3313: 9188<<1^1021)
01.02 6266
01.04 c4cc
01.08 a989
01.10 7303
01.20 e606
01.40 cc0d
01.80 981b
02.01 3037
02.02 606e
...
03.01 b476
03.02 68ed
03.04 f1ca
03.08 c385
03.10 a71b
03.20 4e37
03.40 9c6e
03.80 38dd
...
07.20 687b

If you compute the contribution of the individual bit changes in the data you end up with the xor table above; byte offset from the end of the data, bit pattern, xor value. Correcting for little endianess in the output you end up with the hex values in parenthesis. The least significant bit is 0x1021 and each subsequent bit is a shift left, if the XOR value has the 0x8000 bit set then it is XORed with 0x1021. This is the CRC-CCITT polynomial.

8 7 6 5 4 3 2 1 0
d5 aa 96 82 00 02 00 00 00: 08b2
|| |
|| 68ed
|408b
20d4

08b2: 68ed ^ 408b ^ 20d4

Starting at the least significant bit and filling in the XOR values for each bit gives the above diagram; the diagram stops at the 20d4 XOR value because at that point it matches the final CRC. This tells us that the CRC covers the 6 bytes prior.

#!/usr/bin/env perl
use Digest::CRC qw(crc);
my $data = pack("H*", "820002000000");
printf("%04x\n", crc($data,16,0,0,0,0x1021,0,0));

We can also compute the same CRC in Perl; note the result will be byte swapped since the data encodes the number as little endian.

=== Command ids ===

==== Display to backplate ====
[[#FET control|0082 - FET control]]
[[#Periodic status|0083 - Periodic status request]]
[[#FET presence|008f - FET presence]]
0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
[[#Backplate firmware upload|0091 - Backplate firmware upload (start)]]
[[#Backplate firmware upload|0092 - Backplate firmware upload]]
[[#Backplate firmware upload|0093 - Backplate firmware upload (finish)]]
[[#Get TFE version|0098 - Get TFE version]]
[[#Get build info|0099 - Get build info]]
[[#Get BSL version|009b - Get BSL version]]
009c - (no data; responds with 001c (constant?) data="BSL")
009d - (no data; responds with 001d (constant?) data=bbbb)
[[#Get hardware version?|009e - Get hardware version?]]
[[#Get serial number|009f - Get serial number]]
00a1 - (16-bit data)
[[#"Buffers"|00a2 - Request "buffers" (every 30 seconds; no data; triggers [0025] [0027] 0022 0023 [0029] [002b] 000c 002f)]]
00a3 - (every 30 seconds; no data; likely ACK to 002f)
00a4 - (16-bit data)
00b1 - button pressed/unpressed (no data)
00b3 - (32-bit data; always ffffffff?)
00b5 - (16-bit data; always 0f00?)
00b9 - (32-bit data; always 0000ffff?)
00ba - (48-bit data; always 000000000000?)
00c2 - (48-bit data)
[[#Reset|00ff - Reset]]

==== Backplate to display ====
0001 - (message from backplate; ASCII)
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
[[#FET presence|0004 - FET presence]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
[[#FET presence|0009 - FET presence]]
000a - (every second; 2x(?) 16-bit data)
[[#Backplate state|000b - Backplate state]]
000c - (16-bit values: pir, px1, px1 divisor, px2, px2 divisor, alir, av; included in [[#"Buffers"|"buffers" data]])
0010 - (24-bit data)
[[#Backplate firmware upload|0011 - Backplate firmware upload (ACK)]]
0014 - (16-bit data)
[[#Get TFE version|0018 - Get TFE version (response)]]
[[#Get build info|0019 - Get build info (response)]]
[[#Get BSL version|001b - Get BSL version (response)]]
001c - Response to 009c; always(?) "BSL"
001d - Response to 009d; always(?) bbbb
[[#Get hardware version?|001e - Get hardware version? (response)]]
[[#Get serial number|001f - Get serial number (response)]]
[[#"Buffers"|0022 - 32-bit data (likely 2x 16-bit; possibly multiple times)]]
[[#"Buffers"|0023 - 48-bit data (likely 3x 16-bit; possibly multiple times)]]
[[#"Buffers"|0025 - 16-bit data (possibly multiple times)]]
[[#"Buffers"|0027 - 64-bit data (possibly multiple times)]]
[[#"Buffers"|0029 - 48-bit data (likely 3x 16-bit; possibly multiple times)]]
[[#"Buffers"|002b - 64-bit data (possibly multiple times)]]
[[#"Buffers"|002f - End of "buffers" (16-bit data)]]

=== Backplate firmware upload ===
For uploading the firmware, the following sequence is used:
Send 0091 data=0000<firmware type>
Recv 0011 data=0000
Send 0092 data=0100...
Recv 0011 data=0100
Send 0092 data=0200...
Recv 0011 data=0200
...
Send 0092 data=a901...
Recv 0011 data=a901
Send 0093 data=aa01
Recv 0011 data=aa01
Following the upload, the [[#Backplate initialisation|backplate initialisation process]] begins immediately (that is, without message 00ff being sent to order a reset).
Presumably the 0011 message is an ACK, and the first 16 bits of each message is the line number.
The format itself appears to be Motorola S-record (SREC).
Uploading the BSL firmware was followed by the TFE firmware, so it may be required (though uploading the TFE firmware does ''not'' require uploading the BSL).

Firmware type is either 4d for TFE or 42 for BSL.

=== Backplate state ===
Data:
* 8-bit "state"
* 8-bit "flags"
* 8-bit "px0" (may be wider?)
* 40-bit UNKNOWN (includes at least "p2" and "voc")
* 16-bit centi-volts "vi"
* 16-bit milli-volts "vo"
* 16-bit milli-volts "vb"
* 8-bit ("pins" or "wires")
* 8-bit ("wires" or "pins")
* 16-bit UNKNOWN

=== FET control ===
Turn on W1: d5aa96 8200 0200 00 01 29a2
Turn off W1: d5aa96 8200 0200 00 00 08b2
Turn on Y1: d5aa96 8200 0200 01 01 1891
Turn off Y1: d5aa96 8200 0200 01 00 3981
Turn on G : d5aa96 8200 0200 02 01 4bc4
Turn off G : d5aa96 8200 0200 02 00 6ad4
Turn on OB: d5aa96 8200 0200 03 01 7af7
Turn off OB: d5aa96 8200 0200 03 00 5be7
Turn on W2: d5aa96 8200 0200 04 01 ed6e
Turn off W2: d5aa96 8200 0200 04 00 cc7e
Turn on Y2: d5aa96 8200 0200 07 01 be3b
Turn off Y2: d5aa96 8200 0200 07 00 9f2b
Turn on * : d5aa96 8200 0200 0b 01 d37e
Turn off * : d5aa96 8200 0200 0b 00 f26e

For the sake of documentation, we will refer to the unique id numbers for each wire as "wire id numbers".
So wire id 0 is W1, wire id 1 is Y1, wire id B is *, etc.

=== FET presence ===
The backplate will, at least upon connection, send information about which FETs have a wire present.
This data is received with command ids 0004 and 0009, in that order.
Each sensor is represented by one byte which is either 00 (not present) or 01 (present).

The content of 0004 is in order of the "wire id numbers" used for control:
W1, Y1, G, OB, W2, ?0, ?0, Y2, ?1, ?1, ?0, *, ?0

The content of 0009 is arranged differently and has 2 more values:
W1, Y1, ?1, ?1, ?0, G, OB, W2, ?0, Y2, ?0, *, ?0, ?0, ?0

After these are received, the display sends back command 008f with the exact data from message 0004.
Message 008f does not itself receive any response.

In a power outage condition, 0004 will report all absent (including unknown ones), whereas 0009 will continue to report the same as when power is available.

=== Get build info ===
Message 0099 (no data) requests the backplate report information about its build.
The response will be message 0019 in ASCII (one line, no trailing newline).

=== Get serial number ===
Message 009f (no data) requests the backplate report its serial number (a 64-bit hexadecimal value).
The response will be message 001f in uppercase ASCII.

=== Get hardware version? ===
Message 009e (no data) requests the backplate report a "Backplate-"X.Y version string.
Since the firmware file on the display CPU uses these strings as "MinApplicability" and "MaxApplicability" ranges, it is probable they refer to the hardware.

Witnessed versions:
"Backplate-2.8" - Florida Lowes

=== Get BSL version ===
Message 009b (no data) requests the backplate report its BSL version number.
The response will be message 001b in ASCII.

=== Get TFE version ===
Message 0098 (no data) requests the backplate report its TFE version number.
The response will be message 0018 in ASCII.

=== Periodic status ===
Sending message 0083 (no data) will trigger various periodic messages:
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
000a - (every second; 16-bit data)

The Nest client sends 0083 every 30 seconds, but at least the periodic temperature status will continue on for an hour before stopping.

=== Temperature reading ===
The backplate will send message 0002 every 30 seconds.
The data contains two 16-bit numbers, which nlclient logs in decimal.
The first number is the temperature in centi-celcius.
The second number is the humidity in per-millis.

=== Reset ===
At least upon connection, the display sends message 00ff to the backplate to reset.

The backplate answers with:
0001 msg "<version> <build timestamp "YYYY-MM-DD HH:MM:SS"> K"
[[#FET presence|0004 FET presence]]
[[#FET presence|0009 FET presence]]
0001 msg "*sense 06d1 06d0 0001 0001 0000 0000 0000 0001 06d9 06d8 06d8; detect 09d3 065c"
0001 msg "BRK"

== Run BeagleBone/Debian programs ==
ln -s . /lib/arm-linux-gnueabihf
ln -s ld-2.11.1.so /lib/ld-linux-armhf.so.3

Nest Hacking

2014-08-07T02:21:33Z

Luke-Jr: /* Display to backplate */

== Hardware ==

[https://www.ifixit.com/Teardown/Nest+Learning+Thermostat+2nd+Generation+Teardown/13818 Pictures]

=== Backplate ===
* ST Microelectronics STM32L151VB ultra-low-power 32 MHz ARM Cortex-M3 MCU
* Sensirion SHT20 humidity and temperature sensor
* Texas Instruments LW051A 8-channel CMOS analog multiplexer/demultiplexer

=== Display ===
* Texas Instruments AM3703CUS Sitara ARM Cortex A8 microprocessor
* Texas Instruments TPS65921B power management and USB single chip
* Samsung K4X51163PK 512 Mb mobile DRAM
* Ember EM357 integrated ZigBee/802.15.4 system-on-chip
* Micron MT29F2G16ABBEAH4 2 Gb NAND flash memory
* Skyworks 2436L high power 2.4 GHz 802.15.4 front-end module
* Texas Instruments WL1270B 802.11 b/g/n Wi-Fi solution
* Avago ADBM-A350 optical finger navigation module (knob movement sensor)

== Info ==
* /dev/event1 is the knob; /dev/event2 is the button
* /sys/class/hwmon/hwmon0/device/in0_battery_type * 0.003 is battery voltage
** Nest turns off wifi below 3.7 V, and waits until 3.8 V to automatically reconnect

== Nest software ==
/nestlabs/sbin/nlclient -config /nestlabs/etc/client.config -config /nestlabs/etc/Display/Display-2/client.config

=== Backplate communications ===
Backplate communications can be decoded from a (filtered) strace log using [http://luke.dashjr.org/programs/freeabode/kindling/NestDecode.pl NestDecode.pl], or decoded in real time using [http://luke.dashjr.org/programs/freeabode/kindling/nest-intercept.c nest-intercept.c].

nest-intercept.c requires one argument, the thread id reading from the backplate controller.
The easiest way to get this is to strace the nlclient process with -ff and look for a thread reading from fd 54.

Note that nest-intercept.c also has a "hack" variable which can be set to 0 (default is 2) in order to corrupt the TFE version response and trigger nlclient into uploading the firmware again.

=== Backplate firmware ===
Found in /nestlabs/share/bp/data/firmware/nlbpfirmware.plist

There are 12 different firmwares in the file:
* Test vs Production
* Backplate 2 vs Backplate 3
* TFE (BP_D2 for Bp2, AMBER_BP for Bp3) vs BSL
* For TFE firmwares, hex vs srec (which for some reason DO differ!)

Python script to extract them into individual files: [http://luke.dashjr.org/programs/freeabode/kindling/extract-fw.py extract-fw.py]

=== Backplate initialisation ===
When the backplate is first connected, the following sequence occurs:
tcflush(fd, TCIFLUSH)
Set baud to 115200 (-opost -isig -icanon -echo ...)
tcflush(fd, TCIOFLUSH)
tcsendbreak(fd, 1)
Send [[#Reset|00ff - Reset]]
Recv 0001 - (message from backplate; ASCII)
Recv [[#FET presence|0004 - FET presence]]
Recv [[#FET presence|0009 - FET presence]]
Send [[#FET presence|008f - FET presence]]
Send [[#Periodic status|0083 - Periodic status request]]
Send 0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
Recv 0001 - (message from backplate; ASCII)
Recv 0001 - (message from backplate; ASCII)
Recv 0010 - (24-bit data)
Send [[#Get TFE version|0098 - Get TFE version]]
Recv 000a - (every second; 16-bit data)
Recv 0007 - (every second; 16-bit data)
Recv [[#Get TFE version|0018 - Get TFE version (response)]]
Send [[#Get build info|0099 - Get build info]]
Recv [[#Get build info|0019 - Get build info (response)]]
Sometimes:
Send 009d - (no data; responds with 001d (constant?) data=bbbb)
Recv 001d - Response to 009d; always(?) bbbb
Sometimes:
Send [[#Get BSL version|009b - Get BSL version]]
Recv [[#Get BSL version|001b - Get BSL version (response)]]
Sometimes:
Send 009c - (no data; responds with 001c (constant?) data="BSL")
Recv 001c - Response to 009c; always(?) "BSL"
Send [[#Get serial number|009f - Get serial number]]
Recv [[#Get serial number|001f - Get serial number (response)]]
Send [[#Get hardware version?|009e - Get hardware version?]]
Recv [[#Get hardware version?|001e - Get hardware version? (response)]]

== Nest backplate interface ==
* Connected on /dev/ttyO2
* All communications with backplate begin with (d5)d5aa96 (d5 is doubled only for data FROM backplate)
* Everything is little endian
* 16-bit command
* 16-bit data length
* <data>
* 16-bit checksum

Monitor:
strace -ff -p $(pidof nlclient) -x -s9999 -e read,write 2>&1 | grep '(54'

=== Checksum ===
<Bytes-from-end>.<bit-value> <xor-with>
00.01 2110 (1021)
00.02 4220 (2042: 1021<<1)
00.04 8440 (4084: 2048<<1)
00.08 0881 (8108: 4084<<1)
00.10 3112 (1231: 8108<<1^1021)
00.20 6224 (2462: 1231<<1)
00.40 c448 (48c4: 2462<<1)
00.80 8891 (9188: 48c4<<1)
01.01 3133 (3313: 9188<<1^1021)
01.02 6266
01.04 c4cc
01.08 a989
01.10 7303
01.20 e606
01.40 cc0d
01.80 981b
02.01 3037
02.02 606e
...
03.01 b476
03.02 68ed
03.04 f1ca
03.08 c385
03.10 a71b
03.20 4e37
03.40 9c6e
03.80 38dd
...
07.20 687b

If you compute the contribution of the individual bit changes in the data you end up with the xor table above; byte offset from the end of the data, bit pattern, xor value. Correcting for little endianess in the output you end up with the hex values in parenthesis. The least significant bit is 0x1021 and each subsequent bit is a shift left, if the XOR value has the 0x8000 bit set then it is XORed with 0x1021. This is the CRC-CCITT polynomial.

8 7 6 5 4 3 2 1 0
d5 aa 96 82 00 02 00 00 00: 08b2
|| |
|| 68ed
|408b
20d4

08b2: 68ed ^ 408b ^ 20d4

Starting at the least significant bit and filling in the XOR values for each bit gives the above diagram; the diagram stops at the 20d4 XOR value because at that point it matches the final CRC. This tells us that the CRC covers the 6 bytes prior.

#!/usr/bin/env perl
use Digest::CRC qw(crc);
my $data = pack("H*", "820002000000");
printf("%04x\n", crc($data,16,0,0,0,0x1021,0,0));

We can also compute the same CRC in Perl; note the result will be byte swapped since the data encodes the number as little endian.

=== Command ids ===

==== Display to backplate ====
[[#FET control|0082 - FET control]]
[[#Periodic status|0083 - Periodic status request]]
[[#FET presence|008f - FET presence]]
0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
[[#Backplate firmware upload|0091 - Backplate firmware upload (start)]]
[[#Backplate firmware upload|0092 - Backplate firmware upload]]
[[#Backplate firmware upload|0093 - Backplate firmware upload (finish)]]
[[#Get TFE version|0098 - Get TFE version]]
[[#Get build info|0099 - Get build info]]
[[#Get BSL version|009b - Get BSL version]]
009c - (no data; responds with 001c (constant?) data="BSL")
009d - (no data; responds with 001d (constant?) data=bbbb)
[[#Get hardware version?|009e - Get hardware version?]]
[[#Get serial number|009f - Get serial number]]
00a1 - (16-bit data)
00a2 - (every 30 seconds; no data; likely triggers [0025] [0027] 0022 0023 [0029] [002b] 000c 002f)
00a3 - (every 30 seconds; no data; likely ACK to 002f)
00a4 - (16-bit data)
00b1 - button pressed/unpressed (no data)
00b3 - (32-bit data; always ffffffff?)
00b5 - (16-bit data; always 0f00?)
00b9 - (32-bit data; always 0000ffff?)
00ba - (48-bit data; always 000000000000?)
00c2 - (48-bit data)
[[#Reset|00ff - Reset]]

==== Backplate to display ====
0001 - (message from backplate; ASCII)
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
[[#FET presence|0004 - FET presence]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
[[#FET presence|0009 - FET presence]]
000a - (every second; 2x(?) 16-bit data)
[[#Backplate state|000b - Backplate state]]
000c - (16-bit values: pir, px1, px1 divisor, px2, px2 divisor, alir, av)
0010 - (24-bit data)
[[#Backplate firmware upload|0011 - Backplate firmware upload (ACK)]]
0014 - (16-bit data)
[[#Get TFE version|0018 - Get TFE version (response)]]
[[#Get build info|0019 - Get build info (response)]]
[[#Get BSL version|001b - Get BSL version (response)]]
001c - Response to 009c; always(?) "BSL"
001d - Response to 009d; always(?) bbbb
[[#Get hardware version?|001e - Get hardware version? (response)]]
[[#Get serial number|001f - Get serial number (response)]]
0022 - (every 30 seconds; 4, 8, 20, 28, 36, 56, 60, 54, 68, 72, or 176 byte data)
0023 - (6, 12, 30, 42, 54, 78, 84, 90, 96, 102, 108, 144, or 150 byte data)
0025 - (2, 4, 12, 14, 20, or 24 byte data)
0027 - (8, 16, 48, 56, 80, or 96 byte data)
0029 - (6, 12, 36, 42, 60, or 72 byte data)
002b - (8, 16, 24, 32, 40, 128, or 152 byte data)
002f - (every 30 seconds; 16-bit data; "end of buffers ACK" log msg)

=== Backplate firmware upload ===
For uploading the firmware, the following sequence is used:
Send 0091 data=0000<firmware type>
Recv 0011 data=0000
Send 0092 data=0100...
Recv 0011 data=0100
Send 0092 data=0200...
Recv 0011 data=0200
...
Send 0092 data=a901...
Recv 0011 data=a901
Send 0093 data=aa01
Recv 0011 data=aa01
Following the upload, the [[#Backplate initialisation|backplate initialisation process]] begins immediately (that is, without message 00ff being sent to order a reset).
Presumably the 0011 message is an ACK, and the first 16 bits of each message is the line number.
The format itself appears to be Motorola S-record (SREC).
Uploading the BSL firmware was followed by the TFE firmware, so it may be required (though uploading the TFE firmware does ''not'' require uploading the BSL).

Firmware type is either 4d for TFE or 42 for BSL.

=== Backplate state ===
Data:
* 8-bit "state"
* 8-bit "flags"
* 8-bit "px0" (may be wider?)
* 40-bit UNKNOWN (includes at least "p2" and "voc")
* 16-bit centi-volts "vi"
* 16-bit milli-volts "vo"
* 16-bit milli-volts "vb"
* 8-bit ("pins" or "wires")
* 8-bit ("wires" or "pins")
* 16-bit UNKNOWN

=== FET control ===
Turn on W1: d5aa96 8200 0200 00 01 29a2
Turn off W1: d5aa96 8200 0200 00 00 08b2
Turn on Y1: d5aa96 8200 0200 01 01 1891
Turn off Y1: d5aa96 8200 0200 01 00 3981
Turn on G : d5aa96 8200 0200 02 01 4bc4
Turn off G : d5aa96 8200 0200 02 00 6ad4
Turn on OB: d5aa96 8200 0200 03 01 7af7
Turn off OB: d5aa96 8200 0200 03 00 5be7
Turn on W2: d5aa96 8200 0200 04 01 ed6e
Turn off W2: d5aa96 8200 0200 04 00 cc7e
Turn on Y2: d5aa96 8200 0200 07 01 be3b
Turn off Y2: d5aa96 8200 0200 07 00 9f2b
Turn on * : d5aa96 8200 0200 0b 01 d37e
Turn off * : d5aa96 8200 0200 0b 00 f26e

For the sake of documentation, we will refer to the unique id numbers for each wire as "wire id numbers".
So wire id 0 is W1, wire id 1 is Y1, wire id B is *, etc.

=== FET presence ===
The backplate will, at least upon connection, send information about which FETs have a wire present.
This data is received with command ids 0004 and 0009, in that order.
Each sensor is represented by one byte which is either 00 (not present) or 01 (present).

The content of 0004 is in order of the "wire id numbers" used for control:
W1, Y1, G, OB, W2, ?0, ?0, Y2, ?1, ?1, ?0, *, ?0

The content of 0009 is arranged differently and has 2 more values:
W1, Y1, ?1, ?1, ?0, G, OB, W2, ?0, Y2, ?0, *, ?0, ?0, ?0

After these are received, the display sends back command 008f with the exact data from message 0004.
Message 008f does not itself receive any response.

In a power outage condition, 0004 will report all absent (including unknown ones), whereas 0009 will continue to report the same as when power is available.

=== Get build info ===
Message 0099 (no data) requests the backplate report information about its build.
The response will be message 0019 in ASCII (one line, no trailing newline).

=== Get serial number ===
Message 009f (no data) requests the backplate report its serial number (a 64-bit hexadecimal value).
The response will be message 001f in uppercase ASCII.

=== Get hardware version? ===
Message 009e (no data) requests the backplate report a "Backplate-"X.Y version string.
Since the firmware file on the display CPU uses these strings as "MinApplicability" and "MaxApplicability" ranges, it is probable they refer to the hardware.

Witnessed versions:
"Backplate-2.8" - Florida Lowes

=== Get BSL version ===
Message 009b (no data) requests the backplate report its BSL version number.
The response will be message 001b in ASCII.

=== Get TFE version ===
Message 0098 (no data) requests the backplate report its TFE version number.
The response will be message 0018 in ASCII.

=== Periodic status ===
Sending message 0083 (no data) will trigger various periodic messages:
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
000a - (every second; 16-bit data)

The Nest client sends 0083 every 30 seconds, but at least the periodic temperature status will continue on for an hour before stopping.

=== Temperature reading ===
The backplate will send message 0002 every 30 seconds.
The data contains two 16-bit numbers, which nlclient logs in decimal.
The first number is the temperature in centi-celcius.
The second number is the humidity in per-millis.

=== Reset ===
At least upon connection, the display sends message 00ff to the backplate to reset.

The backplate answers with:
0001 msg "<version> <build timestamp "YYYY-MM-DD HH:MM:SS"> K"
[[#FET presence|0004 FET presence]]
[[#FET presence|0009 FET presence]]
0001 msg "*sense 06d1 06d0 0001 0001 0000 0000 0000 0001 06d9 06d8 06d8; detect 09d3 065c"
0001 msg "BRK"

== Run BeagleBone/Debian programs ==
ln -s . /lib/arm-linux-gnueabihf
ln -s ld-2.11.1.so /lib/ld-linux-armhf.so.3

Nest Hacking

2014-08-07T02:08:24Z

Luke-Jr: 002f is serial number

== Hardware ==

[https://www.ifixit.com/Teardown/Nest+Learning+Thermostat+2nd+Generation+Teardown/13818 Pictures]

=== Backplate ===
* ST Microelectronics STM32L151VB ultra-low-power 32 MHz ARM Cortex-M3 MCU
* Sensirion SHT20 humidity and temperature sensor
* Texas Instruments LW051A 8-channel CMOS analog multiplexer/demultiplexer

=== Display ===
* Texas Instruments AM3703CUS Sitara ARM Cortex A8 microprocessor
* Texas Instruments TPS65921B power management and USB single chip
* Samsung K4X51163PK 512 Mb mobile DRAM
* Ember EM357 integrated ZigBee/802.15.4 system-on-chip
* Micron MT29F2G16ABBEAH4 2 Gb NAND flash memory
* Skyworks 2436L high power 2.4 GHz 802.15.4 front-end module
* Texas Instruments WL1270B 802.11 b/g/n Wi-Fi solution
* Avago ADBM-A350 optical finger navigation module (knob movement sensor)

== Info ==
* /dev/event1 is the knob; /dev/event2 is the button
* /sys/class/hwmon/hwmon0/device/in0_battery_type * 0.003 is battery voltage
** Nest turns off wifi below 3.7 V, and waits until 3.8 V to automatically reconnect

== Nest software ==
/nestlabs/sbin/nlclient -config /nestlabs/etc/client.config -config /nestlabs/etc/Display/Display-2/client.config

=== Backplate communications ===
Backplate communications can be decoded from a (filtered) strace log using [http://luke.dashjr.org/programs/freeabode/kindling/NestDecode.pl NestDecode.pl], or decoded in real time using [http://luke.dashjr.org/programs/freeabode/kindling/nest-intercept.c nest-intercept.c].

nest-intercept.c requires one argument, the thread id reading from the backplate controller.
The easiest way to get this is to strace the nlclient process with -ff and look for a thread reading from fd 54.

Note that nest-intercept.c also has a "hack" variable which can be set to 0 (default is 2) in order to corrupt the TFE version response and trigger nlclient into uploading the firmware again.

=== Backplate firmware ===
Found in /nestlabs/share/bp/data/firmware/nlbpfirmware.plist

There are 12 different firmwares in the file:
* Test vs Production
* Backplate 2 vs Backplate 3
* TFE (BP_D2 for Bp2, AMBER_BP for Bp3) vs BSL
* For TFE firmwares, hex vs srec (which for some reason DO differ!)

Python script to extract them into individual files: [http://luke.dashjr.org/programs/freeabode/kindling/extract-fw.py extract-fw.py]

=== Backplate initialisation ===
When the backplate is first connected, the following sequence occurs:
tcflush(fd, TCIFLUSH)
Set baud to 115200 (-opost -isig -icanon -echo ...)
tcflush(fd, TCIOFLUSH)
tcsendbreak(fd, 1)
Send [[#Reset|00ff - Reset]]
Recv 0001 - (message from backplate; ASCII)
Recv [[#FET presence|0004 - FET presence]]
Recv [[#FET presence|0009 - FET presence]]
Send [[#FET presence|008f - FET presence]]
Send [[#Periodic status|0083 - Periodic status request]]
Send 0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
Recv 0001 - (message from backplate; ASCII)
Recv 0001 - (message from backplate; ASCII)
Recv 0010 - (24-bit data)
Send [[#Get TFE version|0098 - Get TFE version]]
Recv 000a - (every second; 16-bit data)
Recv 0007 - (every second; 16-bit data)
Recv [[#Get TFE version|0018 - Get TFE version (response)]]
Send [[#Get build info|0099 - Get build info]]
Recv [[#Get build info|0019 - Get build info (response)]]
Sometimes:
Send 009d - (no data; responds with 001d (constant?) data=bbbb)
Recv 001d - Response to 009d; always(?) bbbb
Sometimes:
Send [[#Get BSL version|009b - Get BSL version]]
Recv [[#Get BSL version|001b - Get BSL version (response)]]
Sometimes:
Send 009c - (no data; responds with 001c (constant?) data="BSL")
Recv 001c - Response to 009c; always(?) "BSL"
Send [[#Get serial number|009f - Get serial number]]
Recv [[#Get serial number|001f - Get serial number (response)]]
Send [[#Get hardware version?|009e - Get hardware version?]]
Recv [[#Get hardware version?|001e - Get hardware version? (response)]]

== Nest backplate interface ==
* Connected on /dev/ttyO2
* All communications with backplate begin with (d5)d5aa96 (d5 is doubled only for data FROM backplate)
* Everything is little endian
* 16-bit command
* 16-bit data length
* <data>
* 16-bit checksum

Monitor:
strace -ff -p $(pidof nlclient) -x -s9999 -e read,write 2>&1 | grep '(54'

=== Checksum ===
<Bytes-from-end>.<bit-value> <xor-with>
00.01 2110 (1021)
00.02 4220 (2042: 1021<<1)
00.04 8440 (4084: 2048<<1)
00.08 0881 (8108: 4084<<1)
00.10 3112 (1231: 8108<<1^1021)
00.20 6224 (2462: 1231<<1)
00.40 c448 (48c4: 2462<<1)
00.80 8891 (9188: 48c4<<1)
01.01 3133 (3313: 9188<<1^1021)
01.02 6266
01.04 c4cc
01.08 a989
01.10 7303
01.20 e606
01.40 cc0d
01.80 981b
02.01 3037
02.02 606e
...
03.01 b476
03.02 68ed
03.04 f1ca
03.08 c385
03.10 a71b
03.20 4e37
03.40 9c6e
03.80 38dd
...
07.20 687b

If you compute the contribution of the individual bit changes in the data you end up with the xor table above; byte offset from the end of the data, bit pattern, xor value. Correcting for little endianess in the output you end up with the hex values in parenthesis. The least significant bit is 0x1021 and each subsequent bit is a shift left, if the XOR value has the 0x8000 bit set then it is XORed with 0x1021. This is the CRC-CCITT polynomial.

8 7 6 5 4 3 2 1 0
d5 aa 96 82 00 02 00 00 00: 08b2
|| |
|| 68ed
|408b
20d4

08b2: 68ed ^ 408b ^ 20d4

Starting at the least significant bit and filling in the XOR values for each bit gives the above diagram; the diagram stops at the 20d4 XOR value because at that point it matches the final CRC. This tells us that the CRC covers the 6 bytes prior.

#!/usr/bin/env perl
use Digest::CRC qw(crc);
my $data = pack("H*", "820002000000");
printf("%04x\n", crc($data,16,0,0,0,0x1021,0,0));

We can also compute the same CRC in Perl; note the result will be byte swapped since the data encodes the number as little endian.

=== Command ids ===

==== Display to backplate ====
[[#FET control|0082 - FET control]]
[[#Periodic status|0083 - Periodic status request]]
[[#FET presence|008f - FET presence]]
0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
[[#Backplate firmware upload|0091 - Backplate firmware upload (start)]]
[[#Backplate firmware upload|0092 - Backplate firmware upload]]
[[#Backplate firmware upload|0093 - Backplate firmware upload (finish)]]
[[#Get TFE version|0098 - Get TFE version]]
[[#Get build info|0099 - Get build info]]
[[#Get BSL version|009b - Get BSL version]]
009c - (no data; responds with 001c (constant?) data="BSL")
009d - (no data; responds with 001d (constant?) data=bbbb)
[[#Get hardware version?|009e - Get hardware version?]]
[[#Get serial number|009f - Get serial number]]
00a1 - (16-bit data)
00a2 - (every 30 seconds; no data)
00a3 - (every 30 seconds; no data)
00a4 - (16-bit data)
00b1 - button pressed/unpressed (no data)
00b3 - (32-bit data; always ffffffff?)
00b5 - (16-bit data; always 0f00?)
00b9 - (32-bit data; always 0000ffff?)
00ba - (48-bit data; always 000000000000?)
00c2 - (48-bit data)
[[#Reset|00ff - Reset]]

==== Backplate to display ====
0001 - (message from backplate; ASCII)
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
[[#FET presence|0004 - FET presence]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
[[#FET presence|0009 - FET presence]]
000a - (every second; 2x(?) 16-bit data)
[[#Backplate state|000b - Backplate state]]
000c - (16-bit values: pir, px1, px1 divisor, px2, px2 divisor, alir, av)
0010 - (24-bit data)
[[#Backplate firmware upload|0011 - Backplate firmware upload (ACK)]]
0014 - (16-bit data)
[[#Get TFE version|0018 - Get TFE version (response)]]
[[#Get build info|0019 - Get build info (response)]]
[[#Get BSL version|001b - Get BSL version (response)]]
001c - Response to 009c; always(?) "BSL"
001d - Response to 009d; always(?) bbbb
[[#Get hardware version?|001e - Get hardware version? (response)]]
[[#Get serial number|001f - Get serial number (response)]]
0022 - (every 30 seconds; 4, 8, 20, 28, 36, 56, 60, 54, 68, 72, or 176 byte data)
0023 - (6, 12, 30, 42, 54, 78, 84, 90, 96, 102, 108, 144, or 150 byte data)
0025 - (2, 4, 12, 14, 20, or 24 byte data)
0027 - (8, 16, 48, 56, 80, or 96 byte data)
0029 - (6, 12, 36, 42, 60, or 72 byte data)
002b - (8, 16, 24, 32, 40, 128, or 152 byte data)
002f - (every 30 seconds; 16-bit data; "end of buffers ACK" log msg)

=== Backplate firmware upload ===
For uploading the firmware, the following sequence is used:
Send 0091 data=0000<firmware type>
Recv 0011 data=0000
Send 0092 data=0100...
Recv 0011 data=0100
Send 0092 data=0200...
Recv 0011 data=0200
...
Send 0092 data=a901...
Recv 0011 data=a901
Send 0093 data=aa01
Recv 0011 data=aa01
Following the upload, the [[#Backplate initialisation|backplate initialisation process]] begins immediately (that is, without message 00ff being sent to order a reset).
Presumably the 0011 message is an ACK, and the first 16 bits of each message is the line number.
The format itself appears to be Motorola S-record (SREC).
Uploading the BSL firmware was followed by the TFE firmware, so it may be required (though uploading the TFE firmware does ''not'' require uploading the BSL).

Firmware type is either 4d for TFE or 42 for BSL.

=== Backplate state ===
Data:
* 8-bit "state"
* 8-bit "flags"
* 8-bit "px0" (may be wider?)
* 40-bit UNKNOWN (includes at least "p2" and "voc")
* 16-bit centi-volts "vi"
* 16-bit milli-volts "vo"
* 16-bit milli-volts "vb"
* 8-bit ("pins" or "wires")
* 8-bit ("wires" or "pins")
* 16-bit UNKNOWN

=== FET control ===
Turn on W1: d5aa96 8200 0200 00 01 29a2
Turn off W1: d5aa96 8200 0200 00 00 08b2
Turn on Y1: d5aa96 8200 0200 01 01 1891
Turn off Y1: d5aa96 8200 0200 01 00 3981
Turn on G : d5aa96 8200 0200 02 01 4bc4
Turn off G : d5aa96 8200 0200 02 00 6ad4
Turn on OB: d5aa96 8200 0200 03 01 7af7
Turn off OB: d5aa96 8200 0200 03 00 5be7
Turn on W2: d5aa96 8200 0200 04 01 ed6e
Turn off W2: d5aa96 8200 0200 04 00 cc7e
Turn on Y2: d5aa96 8200 0200 07 01 be3b
Turn off Y2: d5aa96 8200 0200 07 00 9f2b
Turn on * : d5aa96 8200 0200 0b 01 d37e
Turn off * : d5aa96 8200 0200 0b 00 f26e

For the sake of documentation, we will refer to the unique id numbers for each wire as "wire id numbers".
So wire id 0 is W1, wire id 1 is Y1, wire id B is *, etc.

=== FET presence ===
The backplate will, at least upon connection, send information about which FETs have a wire present.
This data is received with command ids 0004 and 0009, in that order.
Each sensor is represented by one byte which is either 00 (not present) or 01 (present).

The content of 0004 is in order of the "wire id numbers" used for control:
W1, Y1, G, OB, W2, ?0, ?0, Y2, ?1, ?1, ?0, *, ?0

The content of 0009 is arranged differently and has 2 more values:
W1, Y1, ?1, ?1, ?0, G, OB, W2, ?0, Y2, ?0, *, ?0, ?0, ?0

After these are received, the display sends back command 008f with the exact data from message 0004.
Message 008f does not itself receive any response.

In a power outage condition, 0004 will report all absent (including unknown ones), whereas 0009 will continue to report the same as when power is available.

=== Get build info ===
Message 0099 (no data) requests the backplate report information about its build.
The response will be message 0019 in ASCII (one line, no trailing newline).

=== Get serial number ===
Message 009f (no data) requests the backplate report its serial number (a 64-bit hexadecimal value).
The response will be message 001f in uppercase ASCII.

=== Get hardware version? ===
Message 009e (no data) requests the backplate report a "Backplate-"X.Y version string.
Since the firmware file on the display CPU uses these strings as "MinApplicability" and "MaxApplicability" ranges, it is probable they refer to the hardware.

Witnessed versions:
"Backplate-2.8" - Florida Lowes

=== Get BSL version ===
Message 009b (no data) requests the backplate report its BSL version number.
The response will be message 001b in ASCII.

=== Get TFE version ===
Message 0098 (no data) requests the backplate report its TFE version number.
The response will be message 0018 in ASCII.

=== Periodic status ===
Sending message 0083 (no data) will trigger various periodic messages:
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
000a - (every second; 16-bit data)

The Nest client sends 0083 every 30 seconds, but at least the periodic temperature status will continue on for an hour before stopping.

=== Temperature reading ===
The backplate will send message 0002 every 30 seconds.
The data contains two 16-bit numbers, which nlclient logs in decimal.
The first number is the temperature in centi-celcius.
The second number is the humidity in per-millis.

=== Reset ===
At least upon connection, the display sends message 00ff to the backplate to reset.

The backplate answers with:
0001 msg "<version> <build timestamp "YYYY-MM-DD HH:MM:SS"> K"
[[#FET presence|0004 FET presence]]
[[#FET presence|0009 FET presence]]
0001 msg "*sense 06d1 06d0 0001 0001 0000 0000 0000 0001 06d9 06d8 06d8; detect 09d3 065c"
0001 msg "BRK"

== Run BeagleBone/Debian programs ==
ln -s . /lib/arm-linux-gnueabihf
ln -s ld-2.11.1.so /lib/ld-linux-armhf.so.3

Nest Hacking

2014-08-07T02:05:05Z

Luke-Jr: /* Backplate to display */

== Hardware ==

[https://www.ifixit.com/Teardown/Nest+Learning+Thermostat+2nd+Generation+Teardown/13818 Pictures]

=== Backplate ===
* ST Microelectronics STM32L151VB ultra-low-power 32 MHz ARM Cortex-M3 MCU
* Sensirion SHT20 humidity and temperature sensor
* Texas Instruments LW051A 8-channel CMOS analog multiplexer/demultiplexer

=== Display ===
* Texas Instruments AM3703CUS Sitara ARM Cortex A8 microprocessor
* Texas Instruments TPS65921B power management and USB single chip
* Samsung K4X51163PK 512 Mb mobile DRAM
* Ember EM357 integrated ZigBee/802.15.4 system-on-chip
* Micron MT29F2G16ABBEAH4 2 Gb NAND flash memory
* Skyworks 2436L high power 2.4 GHz 802.15.4 front-end module
* Texas Instruments WL1270B 802.11 b/g/n Wi-Fi solution
* Avago ADBM-A350 optical finger navigation module (knob movement sensor)

== Info ==
* /dev/event1 is the knob; /dev/event2 is the button
* /sys/class/hwmon/hwmon0/device/in0_battery_type * 0.003 is battery voltage
** Nest turns off wifi below 3.7 V, and waits until 3.8 V to automatically reconnect

== Nest software ==
/nestlabs/sbin/nlclient -config /nestlabs/etc/client.config -config /nestlabs/etc/Display/Display-2/client.config

=== Backplate communications ===
Backplate communications can be decoded from a (filtered) strace log using [http://luke.dashjr.org/programs/freeabode/kindling/NestDecode.pl NestDecode.pl], or decoded in real time using [http://luke.dashjr.org/programs/freeabode/kindling/nest-intercept.c nest-intercept.c].

nest-intercept.c requires one argument, the thread id reading from the backplate controller.
The easiest way to get this is to strace the nlclient process with -ff and look for a thread reading from fd 54.

Note that nest-intercept.c also has a "hack" variable which can be set to 0 (default is 2) in order to corrupt the TFE version response and trigger nlclient into uploading the firmware again.

=== Backplate firmware ===
Found in /nestlabs/share/bp/data/firmware/nlbpfirmware.plist

There are 12 different firmwares in the file:
* Test vs Production
* Backplate 2 vs Backplate 3
* TFE (BP_D2 for Bp2, AMBER_BP for Bp3) vs BSL
* For TFE firmwares, hex vs srec (which for some reason DO differ!)

Python script to extract them into individual files: [http://luke.dashjr.org/programs/freeabode/kindling/extract-fw.py extract-fw.py]

=== Backplate initialisation ===
When the backplate is first connected, the following sequence occurs:
tcflush(fd, TCIFLUSH)
Set baud to 115200 (-opost -isig -icanon -echo ...)
tcflush(fd, TCIOFLUSH)
tcsendbreak(fd, 1)
Send [[#Reset|00ff - Reset]]
Recv 0001 - (message from backplate; ASCII)
Recv [[#FET presence|0004 - FET presence]]
Recv [[#FET presence|0009 - FET presence]]
Send [[#FET presence|008f - FET presence]]
Send [[#Periodic status|0083 - Periodic status request]]
Send 0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
Recv 0001 - (message from backplate; ASCII)
Recv 0001 - (message from backplate; ASCII)
Recv 0010 - (24-bit data)
Send [[#Get TFE version|0098 - Get TFE version]]
Recv 000a - (every second; 16-bit data)
Recv 0007 - (every second; 16-bit data)
Recv [[#Get TFE version|0018 - Get TFE version (response)]]
Send [[#Get build info|0099 - Get build info]]
Recv [[#Get build info|0019 - Get build info (response)]]
Sometimes:
Send 009d - (no data; responds with 001d (constant?) data=bbbb)
Recv 001d - Response to 009d; always(?) bbbb
Sometimes:
Send [[#Get BSL version|009b - Get BSL version]]
Recv [[#Get BSL version|001b - Get BSL version (response)]]
Sometimes:
Send 009c - (no data; responds with 001c (constant?) data="BSL")
Recv 001c - Response to 009c; always(?) "BSL"
Send [[#Get firmware hash?|009f - Get firmware hash?]]
Recv [[#Get firmware hash?|001f - Get firmware hash? (response)]]
Send [[#Get hardware version?|009e - Get hardware version?]]
Recv [[#Get hardware version?|001e - Get hardware version? (response)]]

== Nest backplate interface ==
* Connected on /dev/ttyO2
* All communications with backplate begin with (d5)d5aa96 (d5 is doubled only for data FROM backplate)
* Everything is little endian
* 16-bit command
* 16-bit data length
* <data>
* 16-bit checksum

Monitor:
strace -ff -p $(pidof nlclient) -x -s9999 -e read,write 2>&1 | grep '(54'

=== Checksum ===
<Bytes-from-end>.<bit-value> <xor-with>
00.01 2110 (1021)
00.02 4220 (2042: 1021<<1)
00.04 8440 (4084: 2048<<1)
00.08 0881 (8108: 4084<<1)
00.10 3112 (1231: 8108<<1^1021)
00.20 6224 (2462: 1231<<1)
00.40 c448 (48c4: 2462<<1)
00.80 8891 (9188: 48c4<<1)
01.01 3133 (3313: 9188<<1^1021)
01.02 6266
01.04 c4cc
01.08 a989
01.10 7303
01.20 e606
01.40 cc0d
01.80 981b
02.01 3037
02.02 606e
...
03.01 b476
03.02 68ed
03.04 f1ca
03.08 c385
03.10 a71b
03.20 4e37
03.40 9c6e
03.80 38dd
...
07.20 687b

If you compute the contribution of the individual bit changes in the data you end up with the xor table above; byte offset from the end of the data, bit pattern, xor value. Correcting for little endianess in the output you end up with the hex values in parenthesis. The least significant bit is 0x1021 and each subsequent bit is a shift left, if the XOR value has the 0x8000 bit set then it is XORed with 0x1021. This is the CRC-CCITT polynomial.

8 7 6 5 4 3 2 1 0
d5 aa 96 82 00 02 00 00 00: 08b2
|| |
|| 68ed
|408b
20d4

08b2: 68ed ^ 408b ^ 20d4

Starting at the least significant bit and filling in the XOR values for each bit gives the above diagram; the diagram stops at the 20d4 XOR value because at that point it matches the final CRC. This tells us that the CRC covers the 6 bytes prior.

#!/usr/bin/env perl
use Digest::CRC qw(crc);
my $data = pack("H*", "820002000000");
printf("%04x\n", crc($data,16,0,0,0,0x1021,0,0));

We can also compute the same CRC in Perl; note the result will be byte swapped since the data encodes the number as little endian.

=== Command ids ===

==== Display to backplate ====
[[#FET control|0082 - FET control]]
[[#Periodic status|0083 - Periodic status request]]
[[#FET presence|008f - FET presence]]
0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
[[#Backplate firmware upload|0091 - Backplate firmware upload (start)]]
[[#Backplate firmware upload|0092 - Backplate firmware upload]]
[[#Backplate firmware upload|0093 - Backplate firmware upload (finish)]]
[[#Get TFE version|0098 - Get TFE version]]
[[#Get build info|0099 - Get build info]]
[[#Get BSL version|009b - Get BSL version]]
009c - (no data; responds with 001c (constant?) data="BSL")
009d - (no data; responds with 001d (constant?) data=bbbb)
[[#Get hardware version?|009e - Get hardware version?]]
[[#Get firmware hash?|009f - Get firmware hash?]]
00a1 - (16-bit data)
00a2 - (every 30 seconds; no data)
00a3 - (every 30 seconds; no data)
00a4 - (16-bit data)
00b1 - button pressed/unpressed (no data)
00b3 - (32-bit data; always ffffffff?)
00b5 - (16-bit data; always 0f00?)
00b9 - (32-bit data; always 0000ffff?)
00ba - (48-bit data; always 000000000000?)
00c2 - (48-bit data)
[[#Reset|00ff - Reset]]

==== Backplate to display ====
0001 - (message from backplate; ASCII)
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
[[#FET presence|0004 - FET presence]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
[[#FET presence|0009 - FET presence]]
000a - (every second; 2x(?) 16-bit data)
[[#Backplate state|000b - Backplate state]]
000c - (16-bit values: pir, px1, px1 divisor, px2, px2 divisor, alir, av)
0010 - (24-bit data)
[[#Backplate firmware upload|0011 - Backplate firmware upload (ACK)]]
0014 - (16-bit data)
[[#Get TFE version|0018 - Get TFE version (response)]]
[[#Get build info|0019 - Get build info (response)]]
[[#Get BSL version|001b - Get BSL version (response)]]
001c - Response to 009c; always(?) "BSL"
001d - Response to 009d; always(?) bbbb
[[#Get hardware version?|001e - Get hardware version? (response)]]
[[#Get firmware hash?|001f - Get firmware hash? (response)]]
0022 - (every 30 seconds; 4, 8, 20, 28, 36, 56, 60, 54, 68, 72, or 176 byte data)
0023 - (6, 12, 30, 42, 54, 78, 84, 90, 96, 102, 108, 144, or 150 byte data)
0025 - (2, 4, 12, 14, 20, or 24 byte data)
0027 - (8, 16, 48, 56, 80, or 96 byte data)
0029 - (6, 12, 36, 42, 60, or 72 byte data)
002b - (8, 16, 24, 32, 40, 128, or 152 byte data)
002f - (every 30 seconds; 16-bit data; "end of buffers ACK" log msg)

=== Backplate firmware upload ===
For uploading the firmware, the following sequence is used:
Send 0091 data=0000<firmware type>
Recv 0011 data=0000
Send 0092 data=0100...
Recv 0011 data=0100
Send 0092 data=0200...
Recv 0011 data=0200
...
Send 0092 data=a901...
Recv 0011 data=a901
Send 0093 data=aa01
Recv 0011 data=aa01
Following the upload, the [[#Backplate initialisation|backplate initialisation process]] begins immediately (that is, without message 00ff being sent to order a reset).
Presumably the 0011 message is an ACK, and the first 16 bits of each message is the line number.
The format itself appears to be Motorola S-record (SREC).
Uploading the BSL firmware was followed by the TFE firmware, so it may be required (though uploading the TFE firmware does ''not'' require uploading the BSL).

Firmware type is either 4d for TFE or 42 for BSL.

=== Backplate state ===
Data:
* 8-bit "state"
* 8-bit "flags"
* 8-bit "px0" (may be wider?)
* 40-bit UNKNOWN (includes at least "p2" and "voc")
* 16-bit centi-volts "vi"
* 16-bit milli-volts "vo"
* 16-bit milli-volts "vb"
* 8-bit ("pins" or "wires")
* 8-bit ("wires" or "pins")
* 16-bit UNKNOWN

=== FET control ===
Turn on W1: d5aa96 8200 0200 00 01 29a2
Turn off W1: d5aa96 8200 0200 00 00 08b2
Turn on Y1: d5aa96 8200 0200 01 01 1891
Turn off Y1: d5aa96 8200 0200 01 00 3981
Turn on G : d5aa96 8200 0200 02 01 4bc4
Turn off G : d5aa96 8200 0200 02 00 6ad4
Turn on OB: d5aa96 8200 0200 03 01 7af7
Turn off OB: d5aa96 8200 0200 03 00 5be7
Turn on W2: d5aa96 8200 0200 04 01 ed6e
Turn off W2: d5aa96 8200 0200 04 00 cc7e
Turn on Y2: d5aa96 8200 0200 07 01 be3b
Turn off Y2: d5aa96 8200 0200 07 00 9f2b
Turn on * : d5aa96 8200 0200 0b 01 d37e
Turn off * : d5aa96 8200 0200 0b 00 f26e

For the sake of documentation, we will refer to the unique id numbers for each wire as "wire id numbers".
So wire id 0 is W1, wire id 1 is Y1, wire id B is *, etc.

=== FET presence ===
The backplate will, at least upon connection, send information about which FETs have a wire present.
This data is received with command ids 0004 and 0009, in that order.
Each sensor is represented by one byte which is either 00 (not present) or 01 (present).

The content of 0004 is in order of the "wire id numbers" used for control:
W1, Y1, G, OB, W2, ?0, ?0, Y2, ?1, ?1, ?0, *, ?0

The content of 0009 is arranged differently and has 2 more values:
W1, Y1, ?1, ?1, ?0, G, OB, W2, ?0, Y2, ?0, *, ?0, ?0, ?0

After these are received, the display sends back command 008f with the exact data from message 0004.
Message 008f does not itself receive any response.

In a power outage condition, 0004 will report all absent (including unknown ones), whereas 0009 will continue to report the same as when power is available.

=== Get build info ===
Message 0099 (no data) requests the backplate report information about its build.
The response will be message 0019 in ASCII (one line, no trailing newline).

=== Get firmware hash? ===
Message 009f (no data) requests the backplate report a 64-bit hexadecimal value, probably a hash of the firmware (since Nest's software requests it at the same time as version and build info).
The response will be message 001f in uppercase ASCII.

=== Get hardware version? ===
Message 009e (no data) requests the backplate report a "Backplate-"X.Y version string.
Since the firmware file on the display CPU uses these strings as "MinApplicability" and "MaxApplicability" ranges, it is probable they refer to the hardware.

Witnessed versions:
"Backplate-2.8" - Florida Lowes

=== Get BSL version ===
Message 009b (no data) requests the backplate report its BSL version number.
The response will be message 001b in ASCII.

=== Get TFE version ===
Message 0098 (no data) requests the backplate report its TFE version number.
The response will be message 0018 in ASCII.

=== Periodic status ===
Sending message 0083 (no data) will trigger various periodic messages:
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
000a - (every second; 16-bit data)

The Nest client sends 0083 every 30 seconds, but at least the periodic temperature status will continue on for an hour before stopping.

=== Temperature reading ===
The backplate will send message 0002 every 30 seconds.
The data contains two 16-bit numbers, which nlclient logs in decimal.
The first number is the temperature in centi-celcius.
The second number is the humidity in per-millis.

=== Reset ===
At least upon connection, the display sends message 00ff to the backplate to reset.

The backplate answers with:
0001 msg "<version> <build timestamp "YYYY-MM-DD HH:MM:SS"> K"
[[#FET presence|0004 FET presence]]
[[#FET presence|0009 FET presence]]
0001 msg "*sense 06d1 06d0 0001 0001 0000 0000 0000 0001 06d9 06d8 06d8; detect 09d3 065c"
0001 msg "BRK"

== Run BeagleBone/Debian programs ==
ln -s . /lib/arm-linux-gnueabihf
ln -s ld-2.11.1.so /lib/ld-linux-armhf.so.3

Nest Hacking

2014-08-07T01:56:03Z

Luke-Jr: /* Info */

== Hardware ==

[https://www.ifixit.com/Teardown/Nest+Learning+Thermostat+2nd+Generation+Teardown/13818 Pictures]

=== Backplate ===
* ST Microelectronics STM32L151VB ultra-low-power 32 MHz ARM Cortex-M3 MCU
* Sensirion SHT20 humidity and temperature sensor
* Texas Instruments LW051A 8-channel CMOS analog multiplexer/demultiplexer

=== Display ===
* Texas Instruments AM3703CUS Sitara ARM Cortex A8 microprocessor
* Texas Instruments TPS65921B power management and USB single chip
* Samsung K4X51163PK 512 Mb mobile DRAM
* Ember EM357 integrated ZigBee/802.15.4 system-on-chip
* Micron MT29F2G16ABBEAH4 2 Gb NAND flash memory
* Skyworks 2436L high power 2.4 GHz 802.15.4 front-end module
* Texas Instruments WL1270B 802.11 b/g/n Wi-Fi solution
* Avago ADBM-A350 optical finger navigation module (knob movement sensor)

== Info ==
* /dev/event1 is the knob; /dev/event2 is the button
* /sys/class/hwmon/hwmon0/device/in0_battery_type * 0.003 is battery voltage
** Nest turns off wifi below 3.7 V, and waits until 3.8 V to automatically reconnect

== Nest software ==
/nestlabs/sbin/nlclient -config /nestlabs/etc/client.config -config /nestlabs/etc/Display/Display-2/client.config

=== Backplate communications ===
Backplate communications can be decoded from a (filtered) strace log using [http://luke.dashjr.org/programs/freeabode/kindling/NestDecode.pl NestDecode.pl], or decoded in real time using [http://luke.dashjr.org/programs/freeabode/kindling/nest-intercept.c nest-intercept.c].

nest-intercept.c requires one argument, the thread id reading from the backplate controller.
The easiest way to get this is to strace the nlclient process with -ff and look for a thread reading from fd 54.

Note that nest-intercept.c also has a "hack" variable which can be set to 0 (default is 2) in order to corrupt the TFE version response and trigger nlclient into uploading the firmware again.

=== Backplate firmware ===
Found in /nestlabs/share/bp/data/firmware/nlbpfirmware.plist

There are 12 different firmwares in the file:
* Test vs Production
* Backplate 2 vs Backplate 3
* TFE (BP_D2 for Bp2, AMBER_BP for Bp3) vs BSL
* For TFE firmwares, hex vs srec (which for some reason DO differ!)

Python script to extract them into individual files: [http://luke.dashjr.org/programs/freeabode/kindling/extract-fw.py extract-fw.py]

=== Backplate initialisation ===
When the backplate is first connected, the following sequence occurs:
tcflush(fd, TCIFLUSH)
Set baud to 115200 (-opost -isig -icanon -echo ...)
tcflush(fd, TCIOFLUSH)
tcsendbreak(fd, 1)
Send [[#Reset|00ff - Reset]]
Recv 0001 - (message from backplate; ASCII)
Recv [[#FET presence|0004 - FET presence]]
Recv [[#FET presence|0009 - FET presence]]
Send [[#FET presence|008f - FET presence]]
Send [[#Periodic status|0083 - Periodic status request]]
Send 0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
Recv 0001 - (message from backplate; ASCII)
Recv 0001 - (message from backplate; ASCII)
Recv 0010 - (24-bit data)
Send [[#Get TFE version|0098 - Get TFE version]]
Recv 000a - (every second; 16-bit data)
Recv 0007 - (every second; 16-bit data)
Recv [[#Get TFE version|0018 - Get TFE version (response)]]
Send [[#Get build info|0099 - Get build info]]
Recv [[#Get build info|0019 - Get build info (response)]]
Sometimes:
Send 009d - (no data; responds with 001d (constant?) data=bbbb)
Recv 001d - Response to 009d; always(?) bbbb
Sometimes:
Send [[#Get BSL version|009b - Get BSL version]]
Recv [[#Get BSL version|001b - Get BSL version (response)]]
Sometimes:
Send 009c - (no data; responds with 001c (constant?) data="BSL")
Recv 001c - Response to 009c; always(?) "BSL"
Send [[#Get firmware hash?|009f - Get firmware hash?]]
Recv [[#Get firmware hash?|001f - Get firmware hash? (response)]]
Send [[#Get hardware version?|009e - Get hardware version?]]
Recv [[#Get hardware version?|001e - Get hardware version? (response)]]

== Nest backplate interface ==
* Connected on /dev/ttyO2
* All communications with backplate begin with (d5)d5aa96 (d5 is doubled only for data FROM backplate)
* Everything is little endian
* 16-bit command
* 16-bit data length
* <data>
* 16-bit checksum

Monitor:
strace -ff -p $(pidof nlclient) -x -s9999 -e read,write 2>&1 | grep '(54'

=== Checksum ===
<Bytes-from-end>.<bit-value> <xor-with>
00.01 2110 (1021)
00.02 4220 (2042: 1021<<1)
00.04 8440 (4084: 2048<<1)
00.08 0881 (8108: 4084<<1)
00.10 3112 (1231: 8108<<1^1021)
00.20 6224 (2462: 1231<<1)
00.40 c448 (48c4: 2462<<1)
00.80 8891 (9188: 48c4<<1)
01.01 3133 (3313: 9188<<1^1021)
01.02 6266
01.04 c4cc
01.08 a989
01.10 7303
01.20 e606
01.40 cc0d
01.80 981b
02.01 3037
02.02 606e
...
03.01 b476
03.02 68ed
03.04 f1ca
03.08 c385
03.10 a71b
03.20 4e37
03.40 9c6e
03.80 38dd
...
07.20 687b

If you compute the contribution of the individual bit changes in the data you end up with the xor table above; byte offset from the end of the data, bit pattern, xor value. Correcting for little endianess in the output you end up with the hex values in parenthesis. The least significant bit is 0x1021 and each subsequent bit is a shift left, if the XOR value has the 0x8000 bit set then it is XORed with 0x1021. This is the CRC-CCITT polynomial.

8 7 6 5 4 3 2 1 0
d5 aa 96 82 00 02 00 00 00: 08b2
|| |
|| 68ed
|408b
20d4

08b2: 68ed ^ 408b ^ 20d4

Starting at the least significant bit and filling in the XOR values for each bit gives the above diagram; the diagram stops at the 20d4 XOR value because at that point it matches the final CRC. This tells us that the CRC covers the 6 bytes prior.

#!/usr/bin/env perl
use Digest::CRC qw(crc);
my $data = pack("H*", "820002000000");
printf("%04x\n", crc($data,16,0,0,0,0x1021,0,0));

We can also compute the same CRC in Perl; note the result will be byte swapped since the data encodes the number as little endian.

=== Command ids ===

==== Display to backplate ====
[[#FET control|0082 - FET control]]
[[#Periodic status|0083 - Periodic status request]]
[[#FET presence|008f - FET presence]]
0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
[[#Backplate firmware upload|0091 - Backplate firmware upload (start)]]
[[#Backplate firmware upload|0092 - Backplate firmware upload]]
[[#Backplate firmware upload|0093 - Backplate firmware upload (finish)]]
[[#Get TFE version|0098 - Get TFE version]]
[[#Get build info|0099 - Get build info]]
[[#Get BSL version|009b - Get BSL version]]
009c - (no data; responds with 001c (constant?) data="BSL")
009d - (no data; responds with 001d (constant?) data=bbbb)
[[#Get hardware version?|009e - Get hardware version?]]
[[#Get firmware hash?|009f - Get firmware hash?]]
00a1 - (16-bit data)
00a2 - (every 30 seconds; no data)
00a3 - (every 30 seconds; no data)
00a4 - (16-bit data)
00b1 - button pressed/unpressed (no data)
00b3 - (32-bit data; always ffffffff?)
00b5 - (16-bit data; always 0f00?)
00b9 - (32-bit data; always 0000ffff?)
00ba - (48-bit data; always 000000000000?)
00c2 - (48-bit data)
[[#Reset|00ff - Reset]]

==== Backplate to display ====
0001 - (message from backplate; ASCII)
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
[[#FET presence|0004 - FET presence]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
[[#FET presence|0009 - FET presence]]
000a - (every second; 16-bit data)
[[#Backplate state|000b - Backplate state]]
000c - (16-bit values: pir, px1, px1 divisor, px2, px2 divisor, alir, av)
0010 - (24-bit data)
[[#Backplate firmware upload|0011 - Backplate firmware upload (ACK)]]
0014 - (16-bit data)
[[#Get TFE version|0018 - Get TFE version (response)]]
[[#Get build info|0019 - Get build info (response)]]
[[#Get BSL version|001b - Get BSL version (response)]]
001c - Response to 009c; always(?) "BSL"
001d - Response to 009d; always(?) bbbb
[[#Get hardware version?|001e - Get hardware version? (response)]]
[[#Get firmware hash?|001f - Get firmware hash? (response)]]
0022 - (every 30 seconds; 4, 8, 20, 28, 36, 56, 60, 54, 68, 72, or 176 byte data)
0023 - (6, 12, 30, 42, 54, 78, 84, 90, 96, 102, 108, 144, or 150 byte data)
0025 - (2, 4, 12, 14, 20, or 24 byte data)
0027 - (8, 16, 48, 56, 80, or 96 byte data)
0029 - (6, 12, 36, 42, 60, or 72 byte data)
002b - (8, 16, 24, 32, 40, 128, or 152 byte data)
002f - (every 30 seconds; 16-bit data; "end of buffers ACK" log msg)

=== Backplate firmware upload ===
For uploading the firmware, the following sequence is used:
Send 0091 data=0000<firmware type>
Recv 0011 data=0000
Send 0092 data=0100...
Recv 0011 data=0100
Send 0092 data=0200...
Recv 0011 data=0200
...
Send 0092 data=a901...
Recv 0011 data=a901
Send 0093 data=aa01
Recv 0011 data=aa01
Following the upload, the [[#Backplate initialisation|backplate initialisation process]] begins immediately (that is, without message 00ff being sent to order a reset).
Presumably the 0011 message is an ACK, and the first 16 bits of each message is the line number.
The format itself appears to be Motorola S-record (SREC).
Uploading the BSL firmware was followed by the TFE firmware, so it may be required (though uploading the TFE firmware does ''not'' require uploading the BSL).

Firmware type is either 4d for TFE or 42 for BSL.

=== Backplate state ===
Data:
* 8-bit "state"
* 8-bit "flags"
* 8-bit "px0" (may be wider?)
* 40-bit UNKNOWN (includes at least "p2" and "voc")
* 16-bit centi-volts "vi"
* 16-bit milli-volts "vo"
* 16-bit milli-volts "vb"
* 8-bit ("pins" or "wires")
* 8-bit ("wires" or "pins")
* 16-bit UNKNOWN

=== FET control ===
Turn on W1: d5aa96 8200 0200 00 01 29a2
Turn off W1: d5aa96 8200 0200 00 00 08b2
Turn on Y1: d5aa96 8200 0200 01 01 1891
Turn off Y1: d5aa96 8200 0200 01 00 3981
Turn on G : d5aa96 8200 0200 02 01 4bc4
Turn off G : d5aa96 8200 0200 02 00 6ad4
Turn on OB: d5aa96 8200 0200 03 01 7af7
Turn off OB: d5aa96 8200 0200 03 00 5be7
Turn on W2: d5aa96 8200 0200 04 01 ed6e
Turn off W2: d5aa96 8200 0200 04 00 cc7e
Turn on Y2: d5aa96 8200 0200 07 01 be3b
Turn off Y2: d5aa96 8200 0200 07 00 9f2b
Turn on * : d5aa96 8200 0200 0b 01 d37e
Turn off * : d5aa96 8200 0200 0b 00 f26e

For the sake of documentation, we will refer to the unique id numbers for each wire as "wire id numbers".
So wire id 0 is W1, wire id 1 is Y1, wire id B is *, etc.

=== FET presence ===
The backplate will, at least upon connection, send information about which FETs have a wire present.
This data is received with command ids 0004 and 0009, in that order.
Each sensor is represented by one byte which is either 00 (not present) or 01 (present).

The content of 0004 is in order of the "wire id numbers" used for control:
W1, Y1, G, OB, W2, ?0, ?0, Y2, ?1, ?1, ?0, *, ?0

The content of 0009 is arranged differently and has 2 more values:
W1, Y1, ?1, ?1, ?0, G, OB, W2, ?0, Y2, ?0, *, ?0, ?0, ?0

After these are received, the display sends back command 008f with the exact data from message 0004.
Message 008f does not itself receive any response.

In a power outage condition, 0004 will report all absent (including unknown ones), whereas 0009 will continue to report the same as when power is available.

=== Get build info ===
Message 0099 (no data) requests the backplate report information about its build.
The response will be message 0019 in ASCII (one line, no trailing newline).

=== Get firmware hash? ===
Message 009f (no data) requests the backplate report a 64-bit hexadecimal value, probably a hash of the firmware (since Nest's software requests it at the same time as version and build info).
The response will be message 001f in uppercase ASCII.

=== Get hardware version? ===
Message 009e (no data) requests the backplate report a "Backplate-"X.Y version string.
Since the firmware file on the display CPU uses these strings as "MinApplicability" and "MaxApplicability" ranges, it is probable they refer to the hardware.

Witnessed versions:
"Backplate-2.8" - Florida Lowes

=== Get BSL version ===
Message 009b (no data) requests the backplate report its BSL version number.
The response will be message 001b in ASCII.

=== Get TFE version ===
Message 0098 (no data) requests the backplate report its TFE version number.
The response will be message 0018 in ASCII.

=== Periodic status ===
Sending message 0083 (no data) will trigger various periodic messages:
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
000a - (every second; 16-bit data)

The Nest client sends 0083 every 30 seconds, but at least the periodic temperature status will continue on for an hour before stopping.

=== Temperature reading ===
The backplate will send message 0002 every 30 seconds.
The data contains two 16-bit numbers, which nlclient logs in decimal.
The first number is the temperature in centi-celcius.
The second number is the humidity in per-millis.

=== Reset ===
At least upon connection, the display sends message 00ff to the backplate to reset.

The backplate answers with:
0001 msg "<version> <build timestamp "YYYY-MM-DD HH:MM:SS"> K"
[[#FET presence|0004 FET presence]]
[[#FET presence|0009 FET presence]]
0001 msg "*sense 06d1 06d0 0001 0001 0000 0000 0000 0001 06d9 06d8 06d8; detect 09d3 065c"
0001 msg "BRK"

== Run BeagleBone/Debian programs ==
ln -s . /lib/arm-linux-gnueabihf
ln -s ld-2.11.1.so /lib/ld-linux-armhf.so.3

Nest Hacking

2014-08-07T01:53:02Z

Luke-Jr: /* Info */

== Hardware ==

[https://www.ifixit.com/Teardown/Nest+Learning+Thermostat+2nd+Generation+Teardown/13818 Pictures]

=== Backplate ===
* ST Microelectronics STM32L151VB ultra-low-power 32 MHz ARM Cortex-M3 MCU
* Sensirion SHT20 humidity and temperature sensor
* Texas Instruments LW051A 8-channel CMOS analog multiplexer/demultiplexer

=== Display ===
* Texas Instruments AM3703CUS Sitara ARM Cortex A8 microprocessor
* Texas Instruments TPS65921B power management and USB single chip
* Samsung K4X51163PK 512 Mb mobile DRAM
* Ember EM357 integrated ZigBee/802.15.4 system-on-chip
* Micron MT29F2G16ABBEAH4 2 Gb NAND flash memory
* Skyworks 2436L high power 2.4 GHz 802.15.4 front-end module
* Texas Instruments WL1270B 802.11 b/g/n Wi-Fi solution
* Avago ADBM-A350 optical finger navigation module (knob movement sensor)

== Info ==
* /dev/event1 is the knob; /dev/event2 is the button
* /sys/class/hwmon/hwmon0/device/in0_battery_type * 0.003 is battery voltage

== Nest software ==
/nestlabs/sbin/nlclient -config /nestlabs/etc/client.config -config /nestlabs/etc/Display/Display-2/client.config

=== Backplate communications ===
Backplate communications can be decoded from a (filtered) strace log using [http://luke.dashjr.org/programs/freeabode/kindling/NestDecode.pl NestDecode.pl], or decoded in real time using [http://luke.dashjr.org/programs/freeabode/kindling/nest-intercept.c nest-intercept.c].

nest-intercept.c requires one argument, the thread id reading from the backplate controller.
The easiest way to get this is to strace the nlclient process with -ff and look for a thread reading from fd 54.

Note that nest-intercept.c also has a "hack" variable which can be set to 0 (default is 2) in order to corrupt the TFE version response and trigger nlclient into uploading the firmware again.

=== Backplate firmware ===
Found in /nestlabs/share/bp/data/firmware/nlbpfirmware.plist

There are 12 different firmwares in the file:
* Test vs Production
* Backplate 2 vs Backplate 3
* TFE (BP_D2 for Bp2, AMBER_BP for Bp3) vs BSL
* For TFE firmwares, hex vs srec (which for some reason DO differ!)

Python script to extract them into individual files: [http://luke.dashjr.org/programs/freeabode/kindling/extract-fw.py extract-fw.py]

=== Backplate initialisation ===
When the backplate is first connected, the following sequence occurs:
tcflush(fd, TCIFLUSH)
Set baud to 115200 (-opost -isig -icanon -echo ...)
tcflush(fd, TCIOFLUSH)
tcsendbreak(fd, 1)
Send [[#Reset|00ff - Reset]]
Recv 0001 - (message from backplate; ASCII)
Recv [[#FET presence|0004 - FET presence]]
Recv [[#FET presence|0009 - FET presence]]
Send [[#FET presence|008f - FET presence]]
Send [[#Periodic status|0083 - Periodic status request]]
Send 0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
Recv 0001 - (message from backplate; ASCII)
Recv 0001 - (message from backplate; ASCII)
Recv 0010 - (24-bit data)
Send [[#Get TFE version|0098 - Get TFE version]]
Recv 000a - (every second; 16-bit data)
Recv 0007 - (every second; 16-bit data)
Recv [[#Get TFE version|0018 - Get TFE version (response)]]
Send [[#Get build info|0099 - Get build info]]
Recv [[#Get build info|0019 - Get build info (response)]]
Sometimes:
Send 009d - (no data; responds with 001d (constant?) data=bbbb)
Recv 001d - Response to 009d; always(?) bbbb
Sometimes:
Send [[#Get BSL version|009b - Get BSL version]]
Recv [[#Get BSL version|001b - Get BSL version (response)]]
Sometimes:
Send 009c - (no data; responds with 001c (constant?) data="BSL")
Recv 001c - Response to 009c; always(?) "BSL"
Send [[#Get firmware hash?|009f - Get firmware hash?]]
Recv [[#Get firmware hash?|001f - Get firmware hash? (response)]]
Send [[#Get hardware version?|009e - Get hardware version?]]
Recv [[#Get hardware version?|001e - Get hardware version? (response)]]

== Nest backplate interface ==
* Connected on /dev/ttyO2
* All communications with backplate begin with (d5)d5aa96 (d5 is doubled only for data FROM backplate)
* Everything is little endian
* 16-bit command
* 16-bit data length
* <data>
* 16-bit checksum

Monitor:
strace -ff -p $(pidof nlclient) -x -s9999 -e read,write 2>&1 | grep '(54'

=== Checksum ===
<Bytes-from-end>.<bit-value> <xor-with>
00.01 2110 (1021)
00.02 4220 (2042: 1021<<1)
00.04 8440 (4084: 2048<<1)
00.08 0881 (8108: 4084<<1)
00.10 3112 (1231: 8108<<1^1021)
00.20 6224 (2462: 1231<<1)
00.40 c448 (48c4: 2462<<1)
00.80 8891 (9188: 48c4<<1)
01.01 3133 (3313: 9188<<1^1021)
01.02 6266
01.04 c4cc
01.08 a989
01.10 7303
01.20 e606
01.40 cc0d
01.80 981b
02.01 3037
02.02 606e
...
03.01 b476
03.02 68ed
03.04 f1ca
03.08 c385
03.10 a71b
03.20 4e37
03.40 9c6e
03.80 38dd
...
07.20 687b

If you compute the contribution of the individual bit changes in the data you end up with the xor table above; byte offset from the end of the data, bit pattern, xor value. Correcting for little endianess in the output you end up with the hex values in parenthesis. The least significant bit is 0x1021 and each subsequent bit is a shift left, if the XOR value has the 0x8000 bit set then it is XORed with 0x1021. This is the CRC-CCITT polynomial.

8 7 6 5 4 3 2 1 0
d5 aa 96 82 00 02 00 00 00: 08b2
|| |
|| 68ed
|408b
20d4

08b2: 68ed ^ 408b ^ 20d4

Starting at the least significant bit and filling in the XOR values for each bit gives the above diagram; the diagram stops at the 20d4 XOR value because at that point it matches the final CRC. This tells us that the CRC covers the 6 bytes prior.

#!/usr/bin/env perl
use Digest::CRC qw(crc);
my $data = pack("H*", "820002000000");
printf("%04x\n", crc($data,16,0,0,0,0x1021,0,0));

We can also compute the same CRC in Perl; note the result will be byte swapped since the data encodes the number as little endian.

=== Command ids ===

==== Display to backplate ====
[[#FET control|0082 - FET control]]
[[#Periodic status|0083 - Periodic status request]]
[[#FET presence|008f - FET presence]]
0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
[[#Backplate firmware upload|0091 - Backplate firmware upload (start)]]
[[#Backplate firmware upload|0092 - Backplate firmware upload]]
[[#Backplate firmware upload|0093 - Backplate firmware upload (finish)]]
[[#Get TFE version|0098 - Get TFE version]]
[[#Get build info|0099 - Get build info]]
[[#Get BSL version|009b - Get BSL version]]
009c - (no data; responds with 001c (constant?) data="BSL")
009d - (no data; responds with 001d (constant?) data=bbbb)
[[#Get hardware version?|009e - Get hardware version?]]
[[#Get firmware hash?|009f - Get firmware hash?]]
00a1 - (16-bit data)
00a2 - (every 30 seconds; no data)
00a3 - (every 30 seconds; no data)
00a4 - (16-bit data)
00b1 - button pressed/unpressed (no data)
00b3 - (32-bit data; always ffffffff?)
00b5 - (16-bit data; always 0f00?)
00b9 - (32-bit data; always 0000ffff?)
00ba - (48-bit data; always 000000000000?)
00c2 - (48-bit data)
[[#Reset|00ff - Reset]]

==== Backplate to display ====
0001 - (message from backplate; ASCII)
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
[[#FET presence|0004 - FET presence]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
[[#FET presence|0009 - FET presence]]
000a - (every second; 16-bit data)
[[#Backplate state|000b - Backplate state]]
000c - (16-bit values: pir, px1, px1 divisor, px2, px2 divisor, alir, av)
0010 - (24-bit data)
[[#Backplate firmware upload|0011 - Backplate firmware upload (ACK)]]
0014 - (16-bit data)
[[#Get TFE version|0018 - Get TFE version (response)]]
[[#Get build info|0019 - Get build info (response)]]
[[#Get BSL version|001b - Get BSL version (response)]]
001c - Response to 009c; always(?) "BSL"
001d - Response to 009d; always(?) bbbb
[[#Get hardware version?|001e - Get hardware version? (response)]]
[[#Get firmware hash?|001f - Get firmware hash? (response)]]
0022 - (every 30 seconds; 4, 8, 20, 28, 36, 56, 60, 54, 68, 72, or 176 byte data)
0023 - (6, 12, 30, 42, 54, 78, 84, 90, 96, 102, 108, 144, or 150 byte data)
0025 - (2, 4, 12, 14, 20, or 24 byte data)
0027 - (8, 16, 48, 56, 80, or 96 byte data)
0029 - (6, 12, 36, 42, 60, or 72 byte data)
002b - (8, 16, 24, 32, 40, 128, or 152 byte data)
002f - (every 30 seconds; 16-bit data; "end of buffers ACK" log msg)

=== Backplate firmware upload ===
For uploading the firmware, the following sequence is used:
Send 0091 data=0000<firmware type>
Recv 0011 data=0000
Send 0092 data=0100...
Recv 0011 data=0100
Send 0092 data=0200...
Recv 0011 data=0200
...
Send 0092 data=a901...
Recv 0011 data=a901
Send 0093 data=aa01
Recv 0011 data=aa01
Following the upload, the [[#Backplate initialisation|backplate initialisation process]] begins immediately (that is, without message 00ff being sent to order a reset).
Presumably the 0011 message is an ACK, and the first 16 bits of each message is the line number.
The format itself appears to be Motorola S-record (SREC).
Uploading the BSL firmware was followed by the TFE firmware, so it may be required (though uploading the TFE firmware does ''not'' require uploading the BSL).

Firmware type is either 4d for TFE or 42 for BSL.

=== Backplate state ===
Data:
* 8-bit "state"
* 8-bit "flags"
* 8-bit "px0" (may be wider?)
* 40-bit UNKNOWN (includes at least "p2" and "voc")
* 16-bit centi-volts "vi"
* 16-bit milli-volts "vo"
* 16-bit milli-volts "vb"
* 8-bit ("pins" or "wires")
* 8-bit ("wires" or "pins")
* 16-bit UNKNOWN

=== FET control ===
Turn on W1: d5aa96 8200 0200 00 01 29a2
Turn off W1: d5aa96 8200 0200 00 00 08b2
Turn on Y1: d5aa96 8200 0200 01 01 1891
Turn off Y1: d5aa96 8200 0200 01 00 3981
Turn on G : d5aa96 8200 0200 02 01 4bc4
Turn off G : d5aa96 8200 0200 02 00 6ad4
Turn on OB: d5aa96 8200 0200 03 01 7af7
Turn off OB: d5aa96 8200 0200 03 00 5be7
Turn on W2: d5aa96 8200 0200 04 01 ed6e
Turn off W2: d5aa96 8200 0200 04 00 cc7e
Turn on Y2: d5aa96 8200 0200 07 01 be3b
Turn off Y2: d5aa96 8200 0200 07 00 9f2b
Turn on * : d5aa96 8200 0200 0b 01 d37e
Turn off * : d5aa96 8200 0200 0b 00 f26e

For the sake of documentation, we will refer to the unique id numbers for each wire as "wire id numbers".
So wire id 0 is W1, wire id 1 is Y1, wire id B is *, etc.

=== FET presence ===
The backplate will, at least upon connection, send information about which FETs have a wire present.
This data is received with command ids 0004 and 0009, in that order.
Each sensor is represented by one byte which is either 00 (not present) or 01 (present).

The content of 0004 is in order of the "wire id numbers" used for control:
W1, Y1, G, OB, W2, ?0, ?0, Y2, ?1, ?1, ?0, *, ?0

The content of 0009 is arranged differently and has 2 more values:
W1, Y1, ?1, ?1, ?0, G, OB, W2, ?0, Y2, ?0, *, ?0, ?0, ?0

After these are received, the display sends back command 008f with the exact data from message 0004.
Message 008f does not itself receive any response.

In a power outage condition, 0004 will report all absent (including unknown ones), whereas 0009 will continue to report the same as when power is available.

=== Get build info ===
Message 0099 (no data) requests the backplate report information about its build.
The response will be message 0019 in ASCII (one line, no trailing newline).

=== Get firmware hash? ===
Message 009f (no data) requests the backplate report a 64-bit hexadecimal value, probably a hash of the firmware (since Nest's software requests it at the same time as version and build info).
The response will be message 001f in uppercase ASCII.

=== Get hardware version? ===
Message 009e (no data) requests the backplate report a "Backplate-"X.Y version string.
Since the firmware file on the display CPU uses these strings as "MinApplicability" and "MaxApplicability" ranges, it is probable they refer to the hardware.

Witnessed versions:
"Backplate-2.8" - Florida Lowes

=== Get BSL version ===
Message 009b (no data) requests the backplate report its BSL version number.
The response will be message 001b in ASCII.

=== Get TFE version ===
Message 0098 (no data) requests the backplate report its TFE version number.
The response will be message 0018 in ASCII.

=== Periodic status ===
Sending message 0083 (no data) will trigger various periodic messages:
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
000a - (every second; 16-bit data)

The Nest client sends 0083 every 30 seconds, but at least the periodic temperature status will continue on for an hour before stopping.

=== Temperature reading ===
The backplate will send message 0002 every 30 seconds.
The data contains two 16-bit numbers, which nlclient logs in decimal.
The first number is the temperature in centi-celcius.
The second number is the humidity in per-millis.

=== Reset ===
At least upon connection, the display sends message 00ff to the backplate to reset.

The backplate answers with:
0001 msg "<version> <build timestamp "YYYY-MM-DD HH:MM:SS"> K"
[[#FET presence|0004 FET presence]]
[[#FET presence|0009 FET presence]]
0001 msg "*sense 06d1 06d0 0001 0001 0000 0000 0000 0001 06d9 06d8 06d8; detect 09d3 065c"
0001 msg "BRK"

== Run BeagleBone/Debian programs ==
ln -s . /lib/arm-linux-gnueabihf
ln -s ld-2.11.1.so /lib/ld-linux-armhf.so.3

Nest Hacking

2014-08-06T02:09:29Z

Luke-Jr: /* Hardware */

== Hardware ==

[https://www.ifixit.com/Teardown/Nest+Learning+Thermostat+2nd+Generation+Teardown/13818 Pictures]

=== Backplate ===
* ST Microelectronics STM32L151VB ultra-low-power 32 MHz ARM Cortex-M3 MCU
* Sensirion SHT20 humidity and temperature sensor
* Texas Instruments LW051A 8-channel CMOS analog multiplexer/demultiplexer

=== Display ===
* Texas Instruments AM3703CUS Sitara ARM Cortex A8 microprocessor
* Texas Instruments TPS65921B power management and USB single chip
* Samsung K4X51163PK 512 Mb mobile DRAM
* Ember EM357 integrated ZigBee/802.15.4 system-on-chip
* Micron MT29F2G16ABBEAH4 2 Gb NAND flash memory
* Skyworks 2436L high power 2.4 GHz 802.15.4 front-end module
* Texas Instruments WL1270B 802.11 b/g/n Wi-Fi solution
* Avago ADBM-A350 optical finger navigation module (knob movement sensor)

== Info ==
* /dev/event1 is the knob; /dev/event2 is the button

== Nest software ==
/nestlabs/sbin/nlclient -config /nestlabs/etc/client.config -config /nestlabs/etc/Display/Display-2/client.config

=== Backplate communications ===
Backplate communications can be decoded from a (filtered) strace log using [http://luke.dashjr.org/programs/freeabode/kindling/NestDecode.pl NestDecode.pl], or decoded in real time using [http://luke.dashjr.org/programs/freeabode/kindling/nest-intercept.c nest-intercept.c].

nest-intercept.c requires one argument, the thread id reading from the backplate controller.
The easiest way to get this is to strace the nlclient process with -ff and look for a thread reading from fd 54.

Note that nest-intercept.c also has a "hack" variable which can be set to 0 (default is 2) in order to corrupt the TFE version response and trigger nlclient into uploading the firmware again.

=== Backplate firmware ===
Found in /nestlabs/share/bp/data/firmware/nlbpfirmware.plist

There are 12 different firmwares in the file:
* Test vs Production
* Backplate 2 vs Backplate 3
* TFE (BP_D2 for Bp2, AMBER_BP for Bp3) vs BSL
* For TFE firmwares, hex vs srec (which for some reason DO differ!)

Python script to extract them into individual files: [http://luke.dashjr.org/programs/freeabode/kindling/extract-fw.py extract-fw.py]

=== Backplate initialisation ===
When the backplate is first connected, the following sequence occurs:
tcflush(fd, TCIFLUSH)
Set baud to 115200 (-opost -isig -icanon -echo ...)
tcflush(fd, TCIOFLUSH)
tcsendbreak(fd, 1)
Send [[#Reset|00ff - Reset]]
Recv 0001 - (message from backplate; ASCII)
Recv [[#FET presence|0004 - FET presence]]
Recv [[#FET presence|0009 - FET presence]]
Send [[#FET presence|008f - FET presence]]
Send [[#Periodic status|0083 - Periodic status request]]
Send 0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
Recv 0001 - (message from backplate; ASCII)
Recv 0001 - (message from backplate; ASCII)
Recv 0010 - (24-bit data)
Send [[#Get TFE version|0098 - Get TFE version]]
Recv 000a - (every second; 16-bit data)
Recv 0007 - (every second; 16-bit data)
Recv [[#Get TFE version|0018 - Get TFE version (response)]]
Send [[#Get build info|0099 - Get build info]]
Recv [[#Get build info|0019 - Get build info (response)]]
Sometimes:
Send 009d - (no data; responds with 001d (constant?) data=bbbb)
Recv 001d - Response to 009d; always(?) bbbb
Sometimes:
Send [[#Get BSL version|009b - Get BSL version]]
Recv [[#Get BSL version|001b - Get BSL version (response)]]
Sometimes:
Send 009c - (no data; responds with 001c (constant?) data="BSL")
Recv 001c - Response to 009c; always(?) "BSL"
Send [[#Get firmware hash?|009f - Get firmware hash?]]
Recv [[#Get firmware hash?|001f - Get firmware hash? (response)]]
Send [[#Get hardware version?|009e - Get hardware version?]]
Recv [[#Get hardware version?|001e - Get hardware version? (response)]]

== Nest backplate interface ==
* Connected on /dev/ttyO2
* All communications with backplate begin with (d5)d5aa96 (d5 is doubled only for data FROM backplate)
* Everything is little endian
* 16-bit command
* 16-bit data length
* <data>
* 16-bit checksum

Monitor:
strace -ff -p $(pidof nlclient) -x -s9999 -e read,write 2>&1 | grep '(54'

=== Checksum ===
<Bytes-from-end>.<bit-value> <xor-with>
00.01 2110 (1021)
00.02 4220 (2042: 1021<<1)
00.04 8440 (4084: 2048<<1)
00.08 0881 (8108: 4084<<1)
00.10 3112 (1231: 8108<<1^1021)
00.20 6224 (2462: 1231<<1)
00.40 c448 (48c4: 2462<<1)
00.80 8891 (9188: 48c4<<1)
01.01 3133 (3313: 9188<<1^1021)
01.02 6266
01.04 c4cc
01.08 a989
01.10 7303
01.20 e606
01.40 cc0d
01.80 981b
02.01 3037
02.02 606e
...
03.01 b476
03.02 68ed
03.04 f1ca
03.08 c385
03.10 a71b
03.20 4e37
03.40 9c6e
03.80 38dd
...
07.20 687b

If you compute the contribution of the individual bit changes in the data you end up with the xor table above; byte offset from the end of the data, bit pattern, xor value. Correcting for little endianess in the output you end up with the hex values in parenthesis. The least significant bit is 0x1021 and each subsequent bit is a shift left, if the XOR value has the 0x8000 bit set then it is XORed with 0x1021. This is the CRC-CCITT polynomial.

8 7 6 5 4 3 2 1 0
d5 aa 96 82 00 02 00 00 00: 08b2
|| |
|| 68ed
|408b
20d4

08b2: 68ed ^ 408b ^ 20d4

Starting at the least significant bit and filling in the XOR values for each bit gives the above diagram; the diagram stops at the 20d4 XOR value because at that point it matches the final CRC. This tells us that the CRC covers the 6 bytes prior.

#!/usr/bin/env perl
use Digest::CRC qw(crc);
my $data = pack("H*", "820002000000");
printf("%04x\n", crc($data,16,0,0,0,0x1021,0,0));

We can also compute the same CRC in Perl; note the result will be byte swapped since the data encodes the number as little endian.

=== Command ids ===

==== Display to backplate ====
[[#FET control|0082 - FET control]]
[[#Periodic status|0083 - Periodic status request]]
[[#FET presence|008f - FET presence]]
0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
[[#Backplate firmware upload|0091 - Backplate firmware upload (start)]]
[[#Backplate firmware upload|0092 - Backplate firmware upload]]
[[#Backplate firmware upload|0093 - Backplate firmware upload (finish)]]
[[#Get TFE version|0098 - Get TFE version]]
[[#Get build info|0099 - Get build info]]
[[#Get BSL version|009b - Get BSL version]]
009c - (no data; responds with 001c (constant?) data="BSL")
009d - (no data; responds with 001d (constant?) data=bbbb)
[[#Get hardware version?|009e - Get hardware version?]]
[[#Get firmware hash?|009f - Get firmware hash?]]
00a1 - (16-bit data)
00a2 - (every 30 seconds; no data)
00a3 - (every 30 seconds; no data)
00a4 - (16-bit data)
00b1 - button pressed/unpressed (no data)
00b3 - (32-bit data; always ffffffff?)
00b5 - (16-bit data; always 0f00?)
00b9 - (32-bit data; always 0000ffff?)
00ba - (48-bit data; always 000000000000?)
00c2 - (48-bit data)
[[#Reset|00ff - Reset]]

==== Backplate to display ====
0001 - (message from backplate; ASCII)
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
[[#FET presence|0004 - FET presence]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
[[#FET presence|0009 - FET presence]]
000a - (every second; 16-bit data)
[[#Backplate state|000b - Backplate state]]
000c - (16-bit values: pir, px1, px1 divisor, px2, px2 divisor, alir, av)
0010 - (24-bit data)
[[#Backplate firmware upload|0011 - Backplate firmware upload (ACK)]]
0014 - (16-bit data)
[[#Get TFE version|0018 - Get TFE version (response)]]
[[#Get build info|0019 - Get build info (response)]]
[[#Get BSL version|001b - Get BSL version (response)]]
001c - Response to 009c; always(?) "BSL"
001d - Response to 009d; always(?) bbbb
[[#Get hardware version?|001e - Get hardware version? (response)]]
[[#Get firmware hash?|001f - Get firmware hash? (response)]]
0022 - (every 30 seconds; 4, 8, 20, 28, 36, 56, 60, 54, 68, 72, or 176 byte data)
0023 - (6, 12, 30, 42, 54, 78, 84, 90, 96, 102, 108, 144, or 150 byte data)
0025 - (2, 4, 12, 14, 20, or 24 byte data)
0027 - (8, 16, 48, 56, 80, or 96 byte data)
0029 - (6, 12, 36, 42, 60, or 72 byte data)
002b - (8, 16, 24, 32, 40, 128, or 152 byte data)
002f - (every 30 seconds; 16-bit data; "end of buffers ACK" log msg)

=== Backplate firmware upload ===
For uploading the firmware, the following sequence is used:
Send 0091 data=0000<firmware type>
Recv 0011 data=0000
Send 0092 data=0100...
Recv 0011 data=0100
Send 0092 data=0200...
Recv 0011 data=0200
...
Send 0092 data=a901...
Recv 0011 data=a901
Send 0093 data=aa01
Recv 0011 data=aa01
Following the upload, the [[#Backplate initialisation|backplate initialisation process]] begins immediately (that is, without message 00ff being sent to order a reset).
Presumably the 0011 message is an ACK, and the first 16 bits of each message is the line number.
The format itself appears to be Motorola S-record (SREC).
Uploading the BSL firmware was followed by the TFE firmware, so it may be required (though uploading the TFE firmware does ''not'' require uploading the BSL).

Firmware type is either 4d for TFE or 42 for BSL.

=== Backplate state ===
Data:
* 8-bit "state"
* 8-bit "flags"
* 8-bit "px0" (may be wider?)
* 40-bit UNKNOWN (includes at least "p2" and "voc")
* 16-bit centi-volts "vi"
* 16-bit milli-volts "vo"
* 16-bit milli-volts "vb"
* 8-bit ("pins" or "wires")
* 8-bit ("wires" or "pins")
* 16-bit UNKNOWN

=== FET control ===
Turn on W1: d5aa96 8200 0200 00 01 29a2
Turn off W1: d5aa96 8200 0200 00 00 08b2
Turn on Y1: d5aa96 8200 0200 01 01 1891
Turn off Y1: d5aa96 8200 0200 01 00 3981
Turn on G : d5aa96 8200 0200 02 01 4bc4
Turn off G : d5aa96 8200 0200 02 00 6ad4
Turn on OB: d5aa96 8200 0200 03 01 7af7
Turn off OB: d5aa96 8200 0200 03 00 5be7
Turn on W2: d5aa96 8200 0200 04 01 ed6e
Turn off W2: d5aa96 8200 0200 04 00 cc7e
Turn on Y2: d5aa96 8200 0200 07 01 be3b
Turn off Y2: d5aa96 8200 0200 07 00 9f2b
Turn on * : d5aa96 8200 0200 0b 01 d37e
Turn off * : d5aa96 8200 0200 0b 00 f26e

For the sake of documentation, we will refer to the unique id numbers for each wire as "wire id numbers".
So wire id 0 is W1, wire id 1 is Y1, wire id B is *, etc.

=== FET presence ===
The backplate will, at least upon connection, send information about which FETs have a wire present.
This data is received with command ids 0004 and 0009, in that order.
Each sensor is represented by one byte which is either 00 (not present) or 01 (present).

The content of 0004 is in order of the "wire id numbers" used for control:
W1, Y1, G, OB, W2, ?0, ?0, Y2, ?1, ?1, ?0, *, ?0

The content of 0009 is arranged differently and has 2 more values:
W1, Y1, ?1, ?1, ?0, G, OB, W2, ?0, Y2, ?0, *, ?0, ?0, ?0

After these are received, the display sends back command 008f with the exact data from message 0004.
Message 008f does not itself receive any response.

In a power outage condition, 0004 will report all absent (including unknown ones), whereas 0009 will continue to report the same as when power is available.

=== Get build info ===
Message 0099 (no data) requests the backplate report information about its build.
The response will be message 0019 in ASCII (one line, no trailing newline).

=== Get firmware hash? ===
Message 009f (no data) requests the backplate report a 64-bit hexadecimal value, probably a hash of the firmware (since Nest's software requests it at the same time as version and build info).
The response will be message 001f in uppercase ASCII.

=== Get hardware version? ===
Message 009e (no data) requests the backplate report a "Backplate-"X.Y version string.
Since the firmware file on the display CPU uses these strings as "MinApplicability" and "MaxApplicability" ranges, it is probable they refer to the hardware.

Witnessed versions:
"Backplate-2.8" - Florida Lowes

=== Get BSL version ===
Message 009b (no data) requests the backplate report its BSL version number.
The response will be message 001b in ASCII.

=== Get TFE version ===
Message 0098 (no data) requests the backplate report its TFE version number.
The response will be message 0018 in ASCII.

=== Periodic status ===
Sending message 0083 (no data) will trigger various periodic messages:
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
000a - (every second; 16-bit data)

The Nest client sends 0083 every 30 seconds, but at least the periodic temperature status will continue on for an hour before stopping.

=== Temperature reading ===
The backplate will send message 0002 every 30 seconds.
The data contains two 16-bit numbers, which nlclient logs in decimal.
The first number is the temperature in centi-celcius.
The second number is the humidity in per-millis.

=== Reset ===
At least upon connection, the display sends message 00ff to the backplate to reset.

The backplate answers with:
0001 msg "<version> <build timestamp "YYYY-MM-DD HH:MM:SS"> K"
[[#FET presence|0004 FET presence]]
[[#FET presence|0009 FET presence]]
0001 msg "*sense 06d1 06d0 0001 0001 0000 0000 0000 0001 06d9 06d8 06d8; detect 09d3 065c"
0001 msg "BRK"

== Run BeagleBone/Debian programs ==
ln -s . /lib/arm-linux-gnueabihf
ln -s ld-2.11.1.so /lib/ld-linux-armhf.so.3

Nest Hacking

2014-08-04T07:14:04Z

Luke-Jr: /* Backplate initialisation */ Serial config

== Hardware ==
* TSL2571 Light-to-Digital Converter

== Info ==
* /dev/event1 is the knob; /dev/event2 is the button

== Nest software ==
/nestlabs/sbin/nlclient -config /nestlabs/etc/client.config -config /nestlabs/etc/Display/Display-2/client.config

=== Backplate communications ===
Backplate communications can be decoded from a (filtered) strace log using [http://luke.dashjr.org/programs/freeabode/kindling/NestDecode.pl NestDecode.pl], or decoded in real time using [http://luke.dashjr.org/programs/freeabode/kindling/nest-intercept.c nest-intercept.c].

nest-intercept.c requires one argument, the thread id reading from the backplate controller.
The easiest way to get this is to strace the nlclient process with -ff and look for a thread reading from fd 54.

Note that nest-intercept.c also has a "hack" variable which can be set to 0 (default is 2) in order to corrupt the TFE version response and trigger nlclient into uploading the firmware again.

=== Backplate firmware ===
Found in /nestlabs/share/bp/data/firmware/nlbpfirmware.plist

There are 12 different firmwares in the file:
* Test vs Production
* Backplate 2 vs Backplate 3
* TFE (BP_D2 for Bp2, AMBER_BP for Bp3) vs BSL
* For TFE firmwares, hex vs srec (which for some reason DO differ!)

Python script to extract them into individual files: [http://luke.dashjr.org/programs/freeabode/kindling/extract-fw.py extract-fw.py]

=== Backplate initialisation ===
When the backplate is first connected, the following sequence occurs:
tcflush(fd, TCIFLUSH)
Set baud to 115200 (-opost -isig -icanon -echo ...)
tcflush(fd, TCIOFLUSH)
tcsendbreak(fd, 1)
Send [[#Reset|00ff - Reset]]
Recv 0001 - (message from backplate; ASCII)
Recv [[#FET presence|0004 - FET presence]]
Recv [[#FET presence|0009 - FET presence]]
Send [[#FET presence|008f - FET presence]]
Send [[#Periodic status|0083 - Periodic status request]]
Send 0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
Recv 0001 - (message from backplate; ASCII)
Recv 0001 - (message from backplate; ASCII)
Recv 0010 - (24-bit data)
Send [[#Get TFE version|0098 - Get TFE version]]
Recv 000a - (every second; 16-bit data)
Recv 0007 - (every second; 16-bit data)
Recv [[#Get TFE version|0018 - Get TFE version (response)]]
Send [[#Get build info|0099 - Get build info]]
Recv [[#Get build info|0019 - Get build info (response)]]
Sometimes:
Send 009d - (no data; responds with 001d (constant?) data=bbbb)
Recv 001d - Response to 009d; always(?) bbbb
Sometimes:
Send [[#Get BSL version|009b - Get BSL version]]
Recv [[#Get BSL version|001b - Get BSL version (response)]]
Sometimes:
Send 009c - (no data; responds with 001c (constant?) data="BSL")
Recv 001c - Response to 009c; always(?) "BSL"
Send [[#Get firmware hash?|009f - Get firmware hash?]]
Recv [[#Get firmware hash?|001f - Get firmware hash? (response)]]
Send [[#Get hardware version?|009e - Get hardware version?]]
Recv [[#Get hardware version?|001e - Get hardware version? (response)]]

== Nest backplate interface ==
* Connected on /dev/ttyO2
* All communications with backplate begin with (d5)d5aa96 (d5 is doubled only for data FROM backplate)
* Everything is little endian
* 16-bit command
* 16-bit data length
* <data>
* 16-bit checksum

Monitor:
strace -ff -p $(pidof nlclient) -x -s9999 -e read,write 2>&1 | grep '(54'

=== Checksum ===
<Bytes-from-end>.<bit-value> <xor-with>
00.01 2110 (1021)
00.02 4220 (2042: 1021<<1)
00.04 8440 (4084: 2048<<1)
00.08 0881 (8108: 4084<<1)
00.10 3112 (1231: 8108<<1^1021)
00.20 6224 (2462: 1231<<1)
00.40 c448 (48c4: 2462<<1)
00.80 8891 (9188: 48c4<<1)
01.01 3133 (3313: 9188<<1^1021)
01.02 6266
01.04 c4cc
01.08 a989
01.10 7303
01.20 e606
01.40 cc0d
01.80 981b
02.01 3037
02.02 606e
...
03.01 b476
03.02 68ed
03.04 f1ca
03.08 c385
03.10 a71b
03.20 4e37
03.40 9c6e
03.80 38dd
...
07.20 687b

If you compute the contribution of the individual bit changes in the data you end up with the xor table above; byte offset from the end of the data, bit pattern, xor value. Correcting for little endianess in the output you end up with the hex values in parenthesis. The least significant bit is 0x1021 and each subsequent bit is a shift left, if the XOR value has the 0x8000 bit set then it is XORed with 0x1021. This is the CRC-CCITT polynomial.

8 7 6 5 4 3 2 1 0
d5 aa 96 82 00 02 00 00 00: 08b2
|| |
|| 68ed
|408b
20d4

08b2: 68ed ^ 408b ^ 20d4

Starting at the least significant bit and filling in the XOR values for each bit gives the above diagram; the diagram stops at the 20d4 XOR value because at that point it matches the final CRC. This tells us that the CRC covers the 6 bytes prior.

#!/usr/bin/env perl
use Digest::CRC qw(crc);
my $data = pack("H*", "820002000000");
printf("%04x\n", crc($data,16,0,0,0,0x1021,0,0));

We can also compute the same CRC in Perl; note the result will be byte swapped since the data encodes the number as little endian.

=== Command ids ===

==== Display to backplate ====
[[#FET control|0082 - FET control]]
[[#Periodic status|0083 - Periodic status request]]
[[#FET presence|008f - FET presence]]
0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
[[#Backplate firmware upload|0091 - Backplate firmware upload (start)]]
[[#Backplate firmware upload|0092 - Backplate firmware upload]]
[[#Backplate firmware upload|0093 - Backplate firmware upload (finish)]]
[[#Get TFE version|0098 - Get TFE version]]
[[#Get build info|0099 - Get build info]]
[[#Get BSL version|009b - Get BSL version]]
009c - (no data; responds with 001c (constant?) data="BSL")
009d - (no data; responds with 001d (constant?) data=bbbb)
[[#Get hardware version?|009e - Get hardware version?]]
[[#Get firmware hash?|009f - Get firmware hash?]]
00a1 - (16-bit data)
00a2 - (every 30 seconds; no data)
00a3 - (every 30 seconds; no data)
00a4 - (16-bit data)
00b1 - button pressed/unpressed (no data)
00b3 - (32-bit data; always ffffffff?)
00b5 - (16-bit data; always 0f00?)
00b9 - (32-bit data; always 0000ffff?)
00ba - (48-bit data; always 000000000000?)
00c2 - (48-bit data)
[[#Reset|00ff - Reset]]

==== Backplate to display ====
0001 - (message from backplate; ASCII)
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
[[#FET presence|0004 - FET presence]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
[[#FET presence|0009 - FET presence]]
000a - (every second; 16-bit data)
[[#Backplate state|000b - Backplate state]]
000c - (16-bit values: pir, px1, px1 divisor, px2, px2 divisor, alir, av)
0010 - (24-bit data)
[[#Backplate firmware upload|0011 - Backplate firmware upload (ACK)]]
0014 - (16-bit data)
[[#Get TFE version|0018 - Get TFE version (response)]]
[[#Get build info|0019 - Get build info (response)]]
[[#Get BSL version|001b - Get BSL version (response)]]
001c - Response to 009c; always(?) "BSL"
001d - Response to 009d; always(?) bbbb
[[#Get hardware version?|001e - Get hardware version? (response)]]
[[#Get firmware hash?|001f - Get firmware hash? (response)]]
0022 - (every 30 seconds; 4, 8, 20, 28, 36, 56, 60, 54, 68, 72, or 176 byte data)
0023 - (6, 12, 30, 42, 54, 78, 84, 90, 96, 102, 108, 144, or 150 byte data)
0025 - (2, 4, 12, 14, 20, or 24 byte data)
0027 - (8, 16, 48, 56, 80, or 96 byte data)
0029 - (6, 12, 36, 42, 60, or 72 byte data)
002b - (8, 16, 24, 32, 40, 128, or 152 byte data)
002f - (every 30 seconds; 16-bit data; "end of buffers ACK" log msg)

=== Backplate firmware upload ===
For uploading the firmware, the following sequence is used:
Send 0091 data=0000<firmware type>
Recv 0011 data=0000
Send 0092 data=0100...
Recv 0011 data=0100
Send 0092 data=0200...
Recv 0011 data=0200
...
Send 0092 data=a901...
Recv 0011 data=a901
Send 0093 data=aa01
Recv 0011 data=aa01
Following the upload, the [[#Backplate initialisation|backplate initialisation process]] begins immediately (that is, without message 00ff being sent to order a reset).
Presumably the 0011 message is an ACK, and the first 16 bits of each message is the line number.
The format itself appears to be Motorola S-record (SREC).
Uploading the BSL firmware was followed by the TFE firmware, so it may be required (though uploading the TFE firmware does ''not'' require uploading the BSL).

Firmware type is either 4d for TFE or 42 for BSL.

=== Backplate state ===
Data:
* 8-bit "state"
* 8-bit "flags"
* 8-bit "px0" (may be wider?)
* 40-bit UNKNOWN (includes at least "p2" and "voc")
* 16-bit centi-volts "vi"
* 16-bit milli-volts "vo"
* 16-bit milli-volts "vb"
* 8-bit ("pins" or "wires")
* 8-bit ("wires" or "pins")
* 16-bit UNKNOWN

=== FET control ===
Turn on W1: d5aa96 8200 0200 00 01 29a2
Turn off W1: d5aa96 8200 0200 00 00 08b2
Turn on Y1: d5aa96 8200 0200 01 01 1891
Turn off Y1: d5aa96 8200 0200 01 00 3981
Turn on G : d5aa96 8200 0200 02 01 4bc4
Turn off G : d5aa96 8200 0200 02 00 6ad4
Turn on OB: d5aa96 8200 0200 03 01 7af7
Turn off OB: d5aa96 8200 0200 03 00 5be7
Turn on W2: d5aa96 8200 0200 04 01 ed6e
Turn off W2: d5aa96 8200 0200 04 00 cc7e
Turn on Y2: d5aa96 8200 0200 07 01 be3b
Turn off Y2: d5aa96 8200 0200 07 00 9f2b
Turn on * : d5aa96 8200 0200 0b 01 d37e
Turn off * : d5aa96 8200 0200 0b 00 f26e

For the sake of documentation, we will refer to the unique id numbers for each wire as "wire id numbers".
So wire id 0 is W1, wire id 1 is Y1, wire id B is *, etc.

=== FET presence ===
The backplate will, at least upon connection, send information about which FETs have a wire present.
This data is received with command ids 0004 and 0009, in that order.
Each sensor is represented by one byte which is either 00 (not present) or 01 (present).

The content of 0004 is in order of the "wire id numbers" used for control:
W1, Y1, G, OB, W2, ?0, ?0, Y2, ?1, ?1, ?0, *, ?0

The content of 0009 is arranged differently and has 2 more values:
W1, Y1, ?1, ?1, ?0, G, OB, W2, ?0, Y2, ?0, *, ?0, ?0, ?0

After these are received, the display sends back command 008f with the exact data from message 0004.
Message 008f does not itself receive any response.

In a power outage condition, 0004 will report all absent (including unknown ones), whereas 0009 will continue to report the same as when power is available.

=== Get build info ===
Message 0099 (no data) requests the backplate report information about its build.
The response will be message 0019 in ASCII (one line, no trailing newline).

=== Get firmware hash? ===
Message 009f (no data) requests the backplate report a 64-bit hexadecimal value, probably a hash of the firmware (since Nest's software requests it at the same time as version and build info).
The response will be message 001f in uppercase ASCII.

=== Get hardware version? ===
Message 009e (no data) requests the backplate report a "Backplate-"X.Y version string.
Since the firmware file on the display CPU uses these strings as "MinApplicability" and "MaxApplicability" ranges, it is probable they refer to the hardware.

Witnessed versions:
"Backplate-2.8" - Florida Lowes

=== Get BSL version ===
Message 009b (no data) requests the backplate report its BSL version number.
The response will be message 001b in ASCII.

=== Get TFE version ===
Message 0098 (no data) requests the backplate report its TFE version number.
The response will be message 0018 in ASCII.

=== Periodic status ===
Sending message 0083 (no data) will trigger various periodic messages:
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
000a - (every second; 16-bit data)

The Nest client sends 0083 every 30 seconds, but at least the periodic temperature status will continue on for an hour before stopping.

=== Temperature reading ===
The backplate will send message 0002 every 30 seconds.
The data contains two 16-bit numbers, which nlclient logs in decimal.
The first number is the temperature in centi-celcius.
The second number is the humidity in per-millis.

=== Reset ===
At least upon connection, the display sends message 00ff to the backplate to reset.

The backplate answers with:
0001 msg "<version> <build timestamp "YYYY-MM-DD HH:MM:SS"> K"
[[#FET presence|0004 FET presence]]
[[#FET presence|0009 FET presence]]
0001 msg "*sense 06d1 06d0 0001 0001 0000 0000 0000 0001 06d9 06d8 06d8; detect 09d3 065c"
0001 msg "BRK"

== Run BeagleBone/Debian programs ==
ln -s . /lib/arm-linux-gnueabihf
ln -s ld-2.11.1.so /lib/ld-linux-armhf.so.3

Nest Hacking

2014-08-03T20:15:25Z

Luke-Jr: /* FET presence */

== Hardware ==
* TSL2571 Light-to-Digital Converter

== Info ==
* /dev/event1 is the knob; /dev/event2 is the button

== Nest software ==
/nestlabs/sbin/nlclient -config /nestlabs/etc/client.config -config /nestlabs/etc/Display/Display-2/client.config

=== Backplate communications ===
Backplate communications can be decoded from a (filtered) strace log using [http://luke.dashjr.org/programs/freeabode/kindling/NestDecode.pl NestDecode.pl], or decoded in real time using [http://luke.dashjr.org/programs/freeabode/kindling/nest-intercept.c nest-intercept.c].

nest-intercept.c requires one argument, the thread id reading from the backplate controller.
The easiest way to get this is to strace the nlclient process with -ff and look for a thread reading from fd 54.

Note that nest-intercept.c also has a "hack" variable which can be set to 0 (default is 2) in order to corrupt the TFE version response and trigger nlclient into uploading the firmware again.

=== Backplate firmware ===
Found in /nestlabs/share/bp/data/firmware/nlbpfirmware.plist

There are 12 different firmwares in the file:
* Test vs Production
* Backplate 2 vs Backplate 3
* TFE (BP_D2 for Bp2, AMBER_BP for Bp3) vs BSL
* For TFE firmwares, hex vs srec (which for some reason DO differ!)

Python script to extract them into individual files: [http://luke.dashjr.org/programs/freeabode/kindling/extract-fw.py extract-fw.py]

=== Backplate initialisation ===
When the backplate is first connected, the following sequence occurs:
Send [[#Reset|00ff - Reset]]
Recv 0001 - (message from backplate; ASCII)
Recv [[#FET presence|0004 - FET presence]]
Recv [[#FET presence|0009 - FET presence]]
Send [[#FET presence|008f - FET presence]]
Send [[#Periodic status|0083 - Periodic status request]]
Send 0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
Recv 0001 - (message from backplate; ASCII)
Recv 0001 - (message from backplate; ASCII)
Recv 0010 - (24-bit data)
Send [[#Get TFE version|0098 - Get TFE version]]
Recv 000a - (every second; 16-bit data)
Recv 0007 - (every second; 16-bit data)
Recv [[#Get TFE version|0018 - Get TFE version (response)]]
Send [[#Get build info|0099 - Get build info]]
Recv [[#Get build info|0019 - Get build info (response)]]
Sometimes:
Send 009d - (no data; responds with 001d (constant?) data=bbbb)
Recv 001d - Response to 009d; always(?) bbbb
Sometimes:
Send [[#Get BSL version|009b - Get BSL version]]
Recv [[#Get BSL version|001b - Get BSL version (response)]]
Sometimes:
Send 009c - (no data; responds with 001c (constant?) data="BSL")
Recv 001c - Response to 009c; always(?) "BSL"
Send [[#Get firmware hash?|009f - Get firmware hash?]]
Recv [[#Get firmware hash?|001f - Get firmware hash? (response)]]
Send [[#Get hardware version?|009e - Get hardware version?]]
Recv [[#Get hardware version?|001e - Get hardware version? (response)]]

== Nest backplate interface ==
* Connected on /dev/ttyO2
* All communications with backplate begin with (d5)d5aa96 (d5 is doubled only for data FROM backplate)
* Everything is little endian
* 16-bit command
* 16-bit data length
* <data>
* 16-bit checksum

Monitor:
strace -ff -p $(pidof nlclient) -x -s9999 -e read,write 2>&1 | grep '(54'

=== Checksum ===
<Bytes-from-end>.<bit-value> <xor-with>
00.01 2110 (1021)
00.02 4220 (2042: 1021<<1)
00.04 8440 (4084: 2048<<1)
00.08 0881 (8108: 4084<<1)
00.10 3112 (1231: 8108<<1^1021)
00.20 6224 (2462: 1231<<1)
00.40 c448 (48c4: 2462<<1)
00.80 8891 (9188: 48c4<<1)
01.01 3133 (3313: 9188<<1^1021)
01.02 6266
01.04 c4cc
01.08 a989
01.10 7303
01.20 e606
01.40 cc0d
01.80 981b
02.01 3037
02.02 606e
...
03.01 b476
03.02 68ed
03.04 f1ca
03.08 c385
03.10 a71b
03.20 4e37
03.40 9c6e
03.80 38dd
...
07.20 687b

If you compute the contribution of the individual bit changes in the data you end up with the xor table above; byte offset from the end of the data, bit pattern, xor value. Correcting for little endianess in the output you end up with the hex values in parenthesis. The least significant bit is 0x1021 and each subsequent bit is a shift left, if the XOR value has the 0x8000 bit set then it is XORed with 0x1021. This is the CRC-CCITT polynomial.

8 7 6 5 4 3 2 1 0
d5 aa 96 82 00 02 00 00 00: 08b2
|| |
|| 68ed
|408b
20d4

08b2: 68ed ^ 408b ^ 20d4

Starting at the least significant bit and filling in the XOR values for each bit gives the above diagram; the diagram stops at the 20d4 XOR value because at that point it matches the final CRC. This tells us that the CRC covers the 6 bytes prior.

#!/usr/bin/env perl
use Digest::CRC qw(crc);
my $data = pack("H*", "820002000000");
printf("%04x\n", crc($data,16,0,0,0,0x1021,0,0));

We can also compute the same CRC in Perl; note the result will be byte swapped since the data encodes the number as little endian.

=== Command ids ===

==== Display to backplate ====
[[#FET control|0082 - FET control]]
[[#Periodic status|0083 - Periodic status request]]
[[#FET presence|008f - FET presence]]
0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
[[#Backplate firmware upload|0091 - Backplate firmware upload (start)]]
[[#Backplate firmware upload|0092 - Backplate firmware upload]]
[[#Backplate firmware upload|0093 - Backplate firmware upload (finish)]]
[[#Get TFE version|0098 - Get TFE version]]
[[#Get build info|0099 - Get build info]]
[[#Get BSL version|009b - Get BSL version]]
009c - (no data; responds with 001c (constant?) data="BSL")
009d - (no data; responds with 001d (constant?) data=bbbb)
[[#Get hardware version?|009e - Get hardware version?]]
[[#Get firmware hash?|009f - Get firmware hash?]]
00a1 - (16-bit data)
00a2 - (every 30 seconds; no data)
00a3 - (every 30 seconds; no data)
00a4 - (16-bit data)
00b1 - button pressed/unpressed (no data)
00b3 - (32-bit data; always ffffffff?)
00b5 - (16-bit data; always 0f00?)
00b9 - (32-bit data; always 0000ffff?)
00ba - (48-bit data; always 000000000000?)
00c2 - (48-bit data)
[[#Reset|00ff - Reset]]

==== Backplate to display ====
0001 - (message from backplate; ASCII)
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
[[#FET presence|0004 - FET presence]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
[[#FET presence|0009 - FET presence]]
000a - (every second; 16-bit data)
[[#Backplate state|000b - Backplate state]]
000c - (16-bit values: pir, px1, px1 divisor, px2, px2 divisor, alir, av)
0010 - (24-bit data)
[[#Backplate firmware upload|0011 - Backplate firmware upload (ACK)]]
0014 - (16-bit data)
[[#Get TFE version|0018 - Get TFE version (response)]]
[[#Get build info|0019 - Get build info (response)]]
[[#Get BSL version|001b - Get BSL version (response)]]
001c - Response to 009c; always(?) "BSL"
001d - Response to 009d; always(?) bbbb
[[#Get hardware version?|001e - Get hardware version? (response)]]
[[#Get firmware hash?|001f - Get firmware hash? (response)]]
0022 - (every 30 seconds; 4, 8, 20, 28, 36, 56, 60, 54, 68, 72, or 176 byte data)
0023 - (6, 12, 30, 42, 54, 78, 84, 90, 96, 102, 108, 144, or 150 byte data)
0025 - (2, 4, 12, 14, 20, or 24 byte data)
0027 - (8, 16, 48, 56, 80, or 96 byte data)
0029 - (6, 12, 36, 42, 60, or 72 byte data)
002b - (8, 16, 24, 32, 40, 128, or 152 byte data)
002f - (every 30 seconds; 16-bit data; "end of buffers ACK" log msg)

=== Backplate firmware upload ===
For uploading the firmware, the following sequence is used:
Send 0091 data=0000<firmware type>
Recv 0011 data=0000
Send 0092 data=0100...
Recv 0011 data=0100
Send 0092 data=0200...
Recv 0011 data=0200
...
Send 0092 data=a901...
Recv 0011 data=a901
Send 0093 data=aa01
Recv 0011 data=aa01
Following the upload, the [[#Backplate initialisation|backplate initialisation process]] begins immediately (that is, without message 00ff being sent to order a reset).
Presumably the 0011 message is an ACK, and the first 16 bits of each message is the line number.
The format itself appears to be Motorola S-record (SREC).
Uploading the BSL firmware was followed by the TFE firmware, so it may be required (though uploading the TFE firmware does ''not'' require uploading the BSL).

Firmware type is either 4d for TFE or 42 for BSL.

=== Backplate state ===
Data:
* 8-bit "state"
* 8-bit "flags"
* 8-bit "px0" (may be wider?)
* 40-bit UNKNOWN (includes at least "p2" and "voc")
* 16-bit centi-volts "vi"
* 16-bit milli-volts "vo"
* 16-bit milli-volts "vb"
* 8-bit ("pins" or "wires")
* 8-bit ("wires" or "pins")
* 16-bit UNKNOWN

=== FET control ===
Turn on W1: d5aa96 8200 0200 00 01 29a2
Turn off W1: d5aa96 8200 0200 00 00 08b2
Turn on Y1: d5aa96 8200 0200 01 01 1891
Turn off Y1: d5aa96 8200 0200 01 00 3981
Turn on G : d5aa96 8200 0200 02 01 4bc4
Turn off G : d5aa96 8200 0200 02 00 6ad4
Turn on OB: d5aa96 8200 0200 03 01 7af7
Turn off OB: d5aa96 8200 0200 03 00 5be7
Turn on W2: d5aa96 8200 0200 04 01 ed6e
Turn off W2: d5aa96 8200 0200 04 00 cc7e
Turn on Y2: d5aa96 8200 0200 07 01 be3b
Turn off Y2: d5aa96 8200 0200 07 00 9f2b
Turn on * : d5aa96 8200 0200 0b 01 d37e
Turn off * : d5aa96 8200 0200 0b 00 f26e

For the sake of documentation, we will refer to the unique id numbers for each wire as "wire id numbers".
So wire id 0 is W1, wire id 1 is Y1, wire id B is *, etc.

=== FET presence ===
The backplate will, at least upon connection, send information about which FETs have a wire present.
This data is received with command ids 0004 and 0009, in that order.
Each sensor is represented by one byte which is either 00 (not present) or 01 (present).

The content of 0004 is in order of the "wire id numbers" used for control:
W1, Y1, G, OB, W2, ?0, ?0, Y2, ?1, ?1, ?0, *, ?0

The content of 0009 is arranged differently and has 2 more values:
W1, Y1, ?1, ?1, ?0, G, OB, W2, ?0, Y2, ?0, *, ?0, ?0, ?0

After these are received, the display sends back command 008f with the exact data from message 0004.
Message 008f does not itself receive any response.

In a power outage condition, 0004 will report all absent (including unknown ones), whereas 0009 will continue to report the same as when power is available.

=== Get build info ===
Message 0099 (no data) requests the backplate report information about its build.
The response will be message 0019 in ASCII (one line, no trailing newline).

=== Get firmware hash? ===
Message 009f (no data) requests the backplate report a 64-bit hexadecimal value, probably a hash of the firmware (since Nest's software requests it at the same time as version and build info).
The response will be message 001f in uppercase ASCII.

=== Get hardware version? ===
Message 009e (no data) requests the backplate report a "Backplate-"X.Y version string.
Since the firmware file on the display CPU uses these strings as "MinApplicability" and "MaxApplicability" ranges, it is probable they refer to the hardware.

Witnessed versions:
"Backplate-2.8" - Florida Lowes

=== Get BSL version ===
Message 009b (no data) requests the backplate report its BSL version number.
The response will be message 001b in ASCII.

=== Get TFE version ===
Message 0098 (no data) requests the backplate report its TFE version number.
The response will be message 0018 in ASCII.

=== Periodic status ===
Sending message 0083 (no data) will trigger various periodic messages:
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
000a - (every second; 16-bit data)

The Nest client sends 0083 every 30 seconds, but at least the periodic temperature status will continue on for an hour before stopping.

=== Temperature reading ===
The backplate will send message 0002 every 30 seconds.
The data contains two 16-bit numbers, which nlclient logs in decimal.
The first number is the temperature in centi-celcius.
The second number is the humidity in per-millis.

=== Reset ===
At least upon connection, the display sends message 00ff to the backplate to reset.

The backplate answers with:
0001 msg "<version> <build timestamp "YYYY-MM-DD HH:MM:SS"> K"
[[#FET presence|0004 FET presence]]
[[#FET presence|0009 FET presence]]
0001 msg "*sense 06d1 06d0 0001 0001 0000 0000 0000 0001 06d9 06d8 06d8; detect 09d3 065c"
0001 msg "BRK"

== Run BeagleBone/Debian programs ==
ln -s . /lib/arm-linux-gnueabihf
ln -s ld-2.11.1.so /lib/ld-linux-armhf.so.3

Nest Hacking

2014-07-30T17:42:42Z

Luke-Jr:

== Hardware ==
* TSL2571 Light-to-Digital Converter

== Info ==
* /dev/event1 is the knob; /dev/event2 is the button

== Nest software ==
/nestlabs/sbin/nlclient -config /nestlabs/etc/client.config -config /nestlabs/etc/Display/Display-2/client.config

=== Backplate communications ===
Backplate communications can be decoded from a (filtered) strace log using [http://luke.dashjr.org/programs/freeabode/kindling/NestDecode.pl NestDecode.pl], or decoded in real time using [http://luke.dashjr.org/programs/freeabode/kindling/nest-intercept.c nest-intercept.c].

nest-intercept.c requires one argument, the thread id reading from the backplate controller.
The easiest way to get this is to strace the nlclient process with -ff and look for a thread reading from fd 54.

Note that nest-intercept.c also has a "hack" variable which can be set to 0 (default is 2) in order to corrupt the TFE version response and trigger nlclient into uploading the firmware again.

=== Backplate firmware ===
Found in /nestlabs/share/bp/data/firmware/nlbpfirmware.plist

There are 12 different firmwares in the file:
* Test vs Production
* Backplate 2 vs Backplate 3
* TFE (BP_D2 for Bp2, AMBER_BP for Bp3) vs BSL
* For TFE firmwares, hex vs srec (which for some reason DO differ!)

Python script to extract them into individual files: [http://luke.dashjr.org/programs/freeabode/kindling/extract-fw.py extract-fw.py]

=== Backplate initialisation ===
When the backplate is first connected, the following sequence occurs:
Send [[#Reset|00ff - Reset]]
Recv 0001 - (message from backplate; ASCII)
Recv [[#FET presence|0004 - FET presence]]
Recv [[#FET presence|0009 - FET presence]]
Send [[#FET presence|008f - FET presence]]
Send [[#Periodic status|0083 - Periodic status request]]
Send 0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
Recv 0001 - (message from backplate; ASCII)
Recv 0001 - (message from backplate; ASCII)
Recv 0010 - (24-bit data)
Send [[#Get TFE version|0098 - Get TFE version]]
Recv 000a - (every second; 16-bit data)
Recv 0007 - (every second; 16-bit data)
Recv [[#Get TFE version|0018 - Get TFE version (response)]]
Send [[#Get build info|0099 - Get build info]]
Recv [[#Get build info|0019 - Get build info (response)]]
Sometimes:
Send 009d - (no data; responds with 001d (constant?) data=bbbb)
Recv 001d - Response to 009d; always(?) bbbb
Sometimes:
Send [[#Get BSL version|009b - Get BSL version]]
Recv [[#Get BSL version|001b - Get BSL version (response)]]
Sometimes:
Send 009c - (no data; responds with 001c (constant?) data="BSL")
Recv 001c - Response to 009c; always(?) "BSL"
Send [[#Get firmware hash?|009f - Get firmware hash?]]
Recv [[#Get firmware hash?|001f - Get firmware hash? (response)]]
Send [[#Get hardware version?|009e - Get hardware version?]]
Recv [[#Get hardware version?|001e - Get hardware version? (response)]]

== Nest backplate interface ==
* Connected on /dev/ttyO2
* All communications with backplate begin with (d5)d5aa96 (d5 is doubled only for data FROM backplate)
* Everything is little endian
* 16-bit command
* 16-bit data length
* <data>
* 16-bit checksum

Monitor:
strace -ff -p $(pidof nlclient) -x -s9999 -e read,write 2>&1 | grep '(54'

=== Checksum ===
<Bytes-from-end>.<bit-value> <xor-with>
00.01 2110 (1021)
00.02 4220 (2042: 1021<<1)
00.04 8440 (4084: 2048<<1)
00.08 0881 (8108: 4084<<1)
00.10 3112 (1231: 8108<<1^1021)
00.20 6224 (2462: 1231<<1)
00.40 c448 (48c4: 2462<<1)
00.80 8891 (9188: 48c4<<1)
01.01 3133 (3313: 9188<<1^1021)
01.02 6266
01.04 c4cc
01.08 a989
01.10 7303
01.20 e606
01.40 cc0d
01.80 981b
02.01 3037
02.02 606e
...
03.01 b476
03.02 68ed
03.04 f1ca
03.08 c385
03.10 a71b
03.20 4e37
03.40 9c6e
03.80 38dd
...
07.20 687b

If you compute the contribution of the individual bit changes in the data you end up with the xor table above; byte offset from the end of the data, bit pattern, xor value. Correcting for little endianess in the output you end up with the hex values in parenthesis. The least significant bit is 0x1021 and each subsequent bit is a shift left, if the XOR value has the 0x8000 bit set then it is XORed with 0x1021. This is the CRC-CCITT polynomial.

8 7 6 5 4 3 2 1 0
d5 aa 96 82 00 02 00 00 00: 08b2
|| |
|| 68ed
|408b
20d4

08b2: 68ed ^ 408b ^ 20d4

Starting at the least significant bit and filling in the XOR values for each bit gives the above diagram; the diagram stops at the 20d4 XOR value because at that point it matches the final CRC. This tells us that the CRC covers the 6 bytes prior.

#!/usr/bin/env perl
use Digest::CRC qw(crc);
my $data = pack("H*", "820002000000");
printf("%04x\n", crc($data,16,0,0,0,0x1021,0,0));

We can also compute the same CRC in Perl; note the result will be byte swapped since the data encodes the number as little endian.

=== Command ids ===

==== Display to backplate ====
[[#FET control|0082 - FET control]]
[[#Periodic status|0083 - Periodic status request]]
[[#FET presence|008f - FET presence]]
0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
[[#Backplate firmware upload|0091 - Backplate firmware upload (start)]]
[[#Backplate firmware upload|0092 - Backplate firmware upload]]
[[#Backplate firmware upload|0093 - Backplate firmware upload (finish)]]
[[#Get TFE version|0098 - Get TFE version]]
[[#Get build info|0099 - Get build info]]
[[#Get BSL version|009b - Get BSL version]]
009c - (no data; responds with 001c (constant?) data="BSL")
009d - (no data; responds with 001d (constant?) data=bbbb)
[[#Get hardware version?|009e - Get hardware version?]]
[[#Get firmware hash?|009f - Get firmware hash?]]
00a1 - (16-bit data)
00a2 - (every 30 seconds; no data)
00a3 - (every 30 seconds; no data)
00a4 - (16-bit data)
00b1 - button pressed/unpressed (no data)
00b3 - (32-bit data; always ffffffff?)
00b5 - (16-bit data; always 0f00?)
00b9 - (32-bit data; always 0000ffff?)
00ba - (48-bit data; always 000000000000?)
00c2 - (48-bit data)
[[#Reset|00ff - Reset]]

==== Backplate to display ====
0001 - (message from backplate; ASCII)
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
[[#FET presence|0004 - FET presence]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
[[#FET presence|0009 - FET presence]]
000a - (every second; 16-bit data)
[[#Backplate state|000b - Backplate state]]
000c - (16-bit values: pir, px1, px1 divisor, px2, px2 divisor, alir, av)
0010 - (24-bit data)
[[#Backplate firmware upload|0011 - Backplate firmware upload (ACK)]]
0014 - (16-bit data)
[[#Get TFE version|0018 - Get TFE version (response)]]
[[#Get build info|0019 - Get build info (response)]]
[[#Get BSL version|001b - Get BSL version (response)]]
001c - Response to 009c; always(?) "BSL"
001d - Response to 009d; always(?) bbbb
[[#Get hardware version?|001e - Get hardware version? (response)]]
[[#Get firmware hash?|001f - Get firmware hash? (response)]]
0022 - (every 30 seconds; 4, 8, 20, 28, 36, 56, 60, 54, 68, 72, or 176 byte data)
0023 - (6, 12, 30, 42, 54, 78, 84, 90, 96, 102, 108, 144, or 150 byte data)
0025 - (2, 4, 12, 14, 20, or 24 byte data)
0027 - (8, 16, 48, 56, 80, or 96 byte data)
0029 - (6, 12, 36, 42, 60, or 72 byte data)
002b - (8, 16, 24, 32, 40, 128, or 152 byte data)
002f - (every 30 seconds; 16-bit data; "end of buffers ACK" log msg)

=== Backplate firmware upload ===
For uploading the firmware, the following sequence is used:
Send 0091 data=0000<firmware type>
Recv 0011 data=0000
Send 0092 data=0100...
Recv 0011 data=0100
Send 0092 data=0200...
Recv 0011 data=0200
...
Send 0092 data=a901...
Recv 0011 data=a901
Send 0093 data=aa01
Recv 0011 data=aa01
Following the upload, the [[#Backplate initialisation|backplate initialisation process]] begins immediately (that is, without message 00ff being sent to order a reset).
Presumably the 0011 message is an ACK, and the first 16 bits of each message is the line number.
The format itself appears to be Motorola S-record (SREC).
Uploading the BSL firmware was followed by the TFE firmware, so it may be required (though uploading the TFE firmware does ''not'' require uploading the BSL).

Firmware type is either 4d for TFE or 42 for BSL.

=== Backplate state ===
Data:
* 8-bit "state"
* 8-bit "flags"
* 8-bit "px0" (may be wider?)
* 40-bit UNKNOWN (includes at least "p2" and "voc")
* 16-bit centi-volts "vi"
* 16-bit milli-volts "vo"
* 16-bit milli-volts "vb"
* 8-bit ("pins" or "wires")
* 8-bit ("wires" or "pins")
* 16-bit UNKNOWN

=== FET control ===
Turn on W1: d5aa96 8200 0200 00 01 29a2
Turn off W1: d5aa96 8200 0200 00 00 08b2
Turn on Y1: d5aa96 8200 0200 01 01 1891
Turn off Y1: d5aa96 8200 0200 01 00 3981
Turn on G : d5aa96 8200 0200 02 01 4bc4
Turn off G : d5aa96 8200 0200 02 00 6ad4
Turn on OB: d5aa96 8200 0200 03 01 7af7
Turn off OB: d5aa96 8200 0200 03 00 5be7
Turn on W2: d5aa96 8200 0200 04 01 ed6e
Turn off W2: d5aa96 8200 0200 04 00 cc7e
Turn on Y2: d5aa96 8200 0200 07 01 be3b
Turn off Y2: d5aa96 8200 0200 07 00 9f2b
Turn on * : d5aa96 8200 0200 0b 01 d37e
Turn off * : d5aa96 8200 0200 0b 00 f26e

For the sake of documentation, we will refer to the unique id numbers for each wire as "wire id numbers".
So wire id 0 is W1, wire id 1 is Y1, wire id B is *, etc.

=== FET presence ===
The backplate will, at least upon connection, send information about which FETs have a wire present.
This data is received with command ids 0004 and 0009, in that order.
Each sensor is represented by one byte which is either 00 (not present) or 01 (present).

The content of 0004 is in order of the "wire id numbers" used for control:
W1, Y1, G, OB, W2, ?0, ?0, Y2, ?1, ?1, ?0, *, ?0

The content of 0009 is arranged differently and has 2 more values:
W1, Y1, ?1, ?1, ?0, G, OB, W2, ?0, Y2, ?0, *, ?0, ?0, ?0

After these are received, the display sends back command 008f with the exact data from message 0004.
Message 008f does not itself receive any response.

=== Get build info ===
Message 0099 (no data) requests the backplate report information about its build.
The response will be message 0019 in ASCII (one line, no trailing newline).

=== Get firmware hash? ===
Message 009f (no data) requests the backplate report a 64-bit hexadecimal value, probably a hash of the firmware (since Nest's software requests it at the same time as version and build info).
The response will be message 001f in uppercase ASCII.

=== Get hardware version? ===
Message 009e (no data) requests the backplate report a "Backplate-"X.Y version string.
Since the firmware file on the display CPU uses these strings as "MinApplicability" and "MaxApplicability" ranges, it is probable they refer to the hardware.

Witnessed versions:
"Backplate-2.8" - Florida Lowes

=== Get BSL version ===
Message 009b (no data) requests the backplate report its BSL version number.
The response will be message 001b in ASCII.

=== Get TFE version ===
Message 0098 (no data) requests the backplate report its TFE version number.
The response will be message 0018 in ASCII.

=== Periodic status ===
Sending message 0083 (no data) will trigger various periodic messages:
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
000a - (every second; 16-bit data)

The Nest client sends 0083 every 30 seconds, but at least the periodic temperature status will continue on for an hour before stopping.

=== Temperature reading ===
The backplate will send message 0002 every 30 seconds.
The data contains two 16-bit numbers, which nlclient logs in decimal.
The first number is the temperature in centi-celcius.
The second number is the humidity in per-millis.

=== Reset ===
At least upon connection, the display sends message 00ff to the backplate to reset.

The backplate answers with:
0001 msg "<version> <build timestamp "YYYY-MM-DD HH:MM:SS"> K"
[[#FET presence|0004 FET presence]]
[[#FET presence|0009 FET presence]]
0001 msg "*sense 06d1 06d0 0001 0001 0000 0000 0000 0001 06d9 06d8 06d8; detect 09d3 065c"
0001 msg "BRK"

== Run BeagleBone/Debian programs ==
ln -s . /lib/arm-linux-gnueabihf
ln -s ld-2.11.1.so /lib/ld-linux-armhf.so.3

Nest Hacking

2014-07-28T03:27:31Z

Luke-Jr: /* Backplate firmware */

== Hardware ==
* TSL2571 Light-to-Digital Converter

== Info ==
* /dev/event1 is the knob; /dev/event2 is the button

== Nest software ==
/nestlabs/sbin/nlclient -config /nestlabs/etc/client.config -config /nestlabs/etc/Display/Display-2/client.config

=== Backplate communications ===
Backplate communications can be decoded from a (filtered) strace log using [http://luke.dashjr.org/programs/freeabode/kindling/NestDecode.pl NestDecode.pl], or decoded in real time using [http://luke.dashjr.org/programs/freeabode/kindling/nest-intercept.c nest-intercept.c].

nest-intercept.c requires one argument, the thread id reading from the backplate controller.
The easiest way to get this is to strace the nlclient process with -ff and look for a thread reading from fd 54.

Note that nest-intercept.c also has a "hack" variable which can be set to 0 (default is 2) in order to corrupt the TFE version response and trigger nlclient into uploading the firmware again.

=== Backplate firmware ===
Found in /nestlabs/share/bp/data/firmware/nlbpfirmware.plist

There are 12 different firmwares in the file:
* Test vs Production
* Backplate 2 vs Backplate 3
* TFE (BP_D2 for Bp2, AMBER_BP for Bp3) vs BSL
* For TFE firmwares, hex vs srec (which for some reason DO differ!)

Python script to extract them into individual files: [http://luke.dashjr.org/programs/freeabode/kindling/extract-fw.py extract-fw.py]

=== Backplate initialisation ===
When the backplate is first connected, the following sequence occurs:
Send [[#Reset|00ff - Reset]]
Recv 0001 - (message from backplate; ASCII)
Recv [[#FET presence|0004 - FET presence]]
Recv [[#FET presence|0009 - FET presence]]
Send [[#FET presence|008f - FET presence]]
Send 0083 - (every 30 seconds; no data; triggers periodic messages 0002, 0007, and 000a; also triggers 0005 to some extent?)
Send 0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
Recv 0001 - (message from backplate; ASCII)
Recv 0001 - (message from backplate; ASCII)
Recv 0010 - (24-bit data)
Send [[#Get TFE version|0098 - Get TFE version]]
Recv 000a - (every second; 16-bit data)
Recv 0007 - (every second; 16-bit data)
Recv [[#Get TFE version|0018 - Get TFE version (response)]]
Send [[#Get build info|0099 - Get build info]]
Recv [[#Get build info|0019 - Get build info (response)]]
Sometimes:
Send 009d - (no data; responds with 001d (constant?) data=bbbb)
Recv 001d - Response to 009d; always(?) bbbb
Sometimes:
Send [[#Get BSL version|009b - Get BSL version]]
Recv [[#Get BSL version|001b - Get BSL version (response)]]
Sometimes:
Send 009c - (no data; responds with 001c (constant?) data="BSL")
Recv 001c - Response to 009c; always(?) "BSL"
Send [[#Get firmware hash?|009f - Get firmware hash?]]
Recv [[#Get firmware hash?|001f - Get firmware hash? (response)]]
Send [[#Get hardware version?|009e - Get hardware version?]]
Recv [[#Get hardware version?|001e - Get hardware version? (response)]]

== Nest backplate interface ==
* Connected on /dev/ttyO2
* All communications with backplate begin with (d5)d5aa96 (d5 is doubled only for data FROM backplate)
* Everything is little endian
* 16-bit command
* 16-bit data length
* <data>
* 16-bit checksum

Monitor:
strace -ff -p $(pidof nlclient) -x -s9999 -e read,write 2>&1 | grep '(54'

=== Checksum ===
<Bytes-from-end>.<bit-value> <xor-with>
00.01 2110 (1021)
00.02 4220 (2042: 1021<<1)
00.04 8440 (4084: 2048<<1)
00.08 0881 (8108: 4084<<1)
00.10 3112 (1231: 8108<<1^1021)
00.20 6224 (2462: 1231<<1)
00.40 c448 (48c4: 2462<<1)
00.80 8891 (9188: 48c4<<1)
01.01 3133 (3313: 9188<<1^1021)
01.02 6266
01.04 c4cc
01.08 a989
01.10 7303
01.20 e606
01.40 cc0d
01.80 981b
02.01 3037
02.02 606e
...
03.01 b476
03.02 68ed
03.04 f1ca
03.08 c385
03.10 a71b
03.20 4e37
03.40 9c6e
03.80 38dd
...
07.20 687b

If you compute the contribution of the individual bit changes in the data you end up with the xor table above; byte offset from the end of the data, bit pattern, xor value. Correcting for little endianess in the output you end up with the hex values in parenthesis. The least significant bit is 0x1021 and each subsequent bit is a shift left, if the XOR value has the 0x8000 bit set then it is XORed with 0x1021. This is the CRC-CCITT polynomial.

8 7 6 5 4 3 2 1 0
d5 aa 96 82 00 02 00 00 00: 08b2
|| |
|| 68ed
|408b
20d4

08b2: 68ed ^ 408b ^ 20d4

Starting at the least significant bit and filling in the XOR values for each bit gives the above diagram; the diagram stops at the 20d4 XOR value because at that point it matches the final CRC. This tells us that the CRC covers the 6 bytes prior.

#!/usr/bin/env perl
use Digest::CRC qw(crc);
my $data = pack("H*", "820002000000");
printf("%04x\n", crc($data,16,0,0,0,0x1021,0,0));

We can also compute the same CRC in Perl; note the result will be byte swapped since the data encodes the number as little endian.

=== Command ids ===

==== Display to backplate ====
[[#FET control|0082 - FET control]]
0083 - (every 30 seconds; no data; triggers periodic messages 0002, 0007, and 000a; also triggers 0005 to some extent?)
[[#FET presence|008f - FET presence]]
0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
[[#Backplate firmware upload|0091 - Backplate firmware upload (start)]]
[[#Backplate firmware upload|0092 - Backplate firmware upload]]
[[#Backplate firmware upload|0093 - Backplate firmware upload (finish)]]
[[#Get TFE version|0098 - Get TFE version]]
[[#Get build info|0099 - Get build info]]
[[#Get BSL version|009b - Get BSL version]]
009c - (no data; responds with 001c (constant?) data="BSL")
009d - (no data; responds with 001d (constant?) data=bbbb)
[[#Get hardware version?|009e - Get hardware version?]]
[[#Get firmware hash?|009f - Get firmware hash?]]
00a1 - (16-bit data)
00a2 - (every 30 seconds; no data)
00a3 - (every 30 seconds; no data)
00a4 - (16-bit data)
00b1 - button pressed/unpressed (no data)
00b3 - (32-bit data; always ffffffff?)
00b5 - (16-bit data; always 0f00?)
00b9 - (32-bit data; always 0000ffff?)
00ba - (48-bit data; always 000000000000?)
00c2 - (48-bit data)
[[#Reset|00ff - Reset]]

==== Backplate to display ====
0001 - (message from backplate; ASCII)
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
[[#FET presence|0004 - FET presence]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
[[#FET presence|0009 - FET presence]]
000a - (every second; 16-bit data)
[[#Backplate state|000b - Backplate state]]
000c - (16-bit values: pir, px1, px1 divisor, px2, px2 divisor, alir, av)
0010 - (24-bit data)
[[#Backplate firmware upload|0011 - Backplate firmware upload (ACK)]]
0014 - (16-bit data)
[[#Get TFE version|0018 - Get TFE version (response)]]
[[#Get build info|0019 - Get build info (response)]]
[[#Get BSL version|001b - Get BSL version (response)]]
001c - Response to 009c; always(?) "BSL"
001d - Response to 009d; always(?) bbbb
[[#Get hardware version?|001e - Get hardware version? (response)]]
[[#Get firmware hash?|001f - Get firmware hash? (response)]]
0022 - (every 30 seconds; 4, 8, 20, 28, 36, 56, 60, 54, 68, 72, or 176 byte data)
0023 - (6, 12, 30, 42, 54, 78, 84, 90, 96, 102, 108, 144, or 150 byte data)
0025 - (2, 4, 12, 14, 20, or 24 byte data)
0027 - (8, 16, 48, 56, 80, or 96 byte data)
0029 - (6, 12, 36, 42, 60, or 72 byte data)
002b - (8, 16, 24, 32, 40, 128, or 152 byte data)
002f - (every 30 seconds; 16-bit data; "end of buffers ACK" log msg)

=== Backplate firmware upload ===
For uploading the firmware, the following sequence is used:
Send 0091 data=0000<firmware type>
Recv 0011 data=0000
Send 0092 data=0100...
Recv 0011 data=0100
Send 0092 data=0200...
Recv 0011 data=0200
...
Send 0092 data=a901...
Recv 0011 data=a901
Send 0093 data=aa01
Recv 0011 data=aa01
Following the upload, the [[#Backplate initialisation|backplate initialisation process]] begins immediately (that is, without message 00ff being sent to order a reset).
Presumably the 0011 message is an ACK, and the first 16 bits of each message is the line number.
The format itself appears to be Motorola S-record (SREC).
Uploading the BSL firmware was followed by the TFE firmware, so it may be required (though uploading the TFE firmware does ''not'' require uploading the BSL).

Firmware type is either 4d for TFE or 42 for BSL.

=== Backplate state ===
Data:
* 8-bit "state"
* 8-bit "flags"
* 8-bit "px0" (may be wider?)
* 40-bit UNKNOWN (includes at least "p2" and "voc")
* 16-bit centi-volts "vi"
* 16-bit milli-volts "vo"
* 16-bit milli-volts "vb"
* 8-bit ("pins" or "wires")
* 8-bit ("wires" or "pins")
* 16-bit UNKNOWN

=== FET control ===
Turn on W1: d5aa96 8200 0200 00 01 29a2
Turn off W1: d5aa96 8200 0200 00 00 08b2
Turn on Y1: d5aa96 8200 0200 01 01 1891
Turn off Y1: d5aa96 8200 0200 01 00 3981
Turn on G : d5aa96 8200 0200 02 01 4bc4
Turn off G : d5aa96 8200 0200 02 00 6ad4
Turn on OB: d5aa96 8200 0200 03 01 7af7
Turn off OB: d5aa96 8200 0200 03 00 5be7
Turn on W2: d5aa96 8200 0200 04 01 ed6e
Turn off W2: d5aa96 8200 0200 04 00 cc7e
Turn on Y2: d5aa96 8200 0200 07 01 be3b
Turn off Y2: d5aa96 8200 0200 07 00 9f2b
Turn on * : d5aa96 8200 0200 0b 01 d37e
Turn off * : d5aa96 8200 0200 0b 00 f26e

For the sake of documentation, we will refer to the unique id numbers for each wire as "wire id numbers".
So wire id 0 is W1, wire id 1 is Y1, wire id B is *, etc.

=== FET presence ===
The backplate will, at least upon connection, send information about which FETs have a wire present.
This data is received with command ids 0004 and 0009, in that order.
Each sensor is represented by one byte which is either 00 (not present) or 01 (present).

The content of 0004 is in order of the "wire id numbers" used for control:
W1, Y1, G, OB, W2, ?0, ?0, Y2, ?1, ?1, ?0, *, ?0

The content of 0009 is arranged differently and has 2 more values:
W1, Y1, ?1, ?1, ?0, G, OB, W2, ?0, Y2, ?0, *, ?0, ?0, ?0

After these are received, the display sends back command 008f with the exact data from message 0004.
Message 008f does not itself receive any response.

=== Get build info ===
Message 0099 (no data) requests the backplate report information about its build.
The response will be message 0019 in ASCII (one line, no trailing newline).

=== Get firmware hash? ===
Message 009f (no data) requests the backplate report a 64-bit hexadecimal value, probably a hash of the firmware (since Nest's software requests it at the same time as version and build info).
The response will be message 001f in uppercase ASCII.

=== Get hardware version? ===
Message 009e (no data) requests the backplate report a "Backplate-"X.Y version string.
Since the firmware file on the display CPU uses these strings as "MinApplicability" and "MaxApplicability" ranges, it is probable they refer to the hardware.

Witnessed versions:
"Backplate-2.8" - Florida Lowes

=== Get BSL version ===
Message 009b (no data) requests the backplate report its BSL version number.
The response will be message 001b in ASCII.

=== Get TFE version ===
Message 0098 (no data) requests the backplate report its TFE version number.
The response will be message 0018 in ASCII.

=== Temperature reading ===
The backplate will send message 0002 every 30 seconds.
The data contains two 16-bit numbers, which nlclient logs in decimal.
The first number is the temperature in centi-celcius.
The second number is the humidity in per-millis.

=== Reset ===
At least upon connection, the display sends message 00ff to the backplate to reset.

The backplate answers with:
0001 msg "<version> <build timestamp "YYYY-MM-DD HH:MM:SS"> K"
[[#FET presence|0004 FET presence]]
[[#FET presence|0009 FET presence]]
0001 msg "*sense 06d1 06d0 0001 0001 0000 0000 0000 0001 06d9 06d8 06d8; detect 09d3 065c"
0001 msg "BRK"

== Run BeagleBone/Debian programs ==
ln -s . /lib/arm-linux-gnueabihf
ln -s ld-2.11.1.so /lib/ld-linux-armhf.so.3

Nest Hacking

2014-07-28T01:50:35Z

Luke-Jr: /* Backplate firmware upload */

== Hardware ==
* TSL2571 Light-to-Digital Converter

== Info ==
* /dev/event1 is the knob; /dev/event2 is the button

== Nest software ==
/nestlabs/sbin/nlclient -config /nestlabs/etc/client.config -config /nestlabs/etc/Display/Display-2/client.config

=== Backplate communications ===
Backplate communications can be decoded from a (filtered) strace log using [http://luke.dashjr.org/programs/freeabode/kindling/NestDecode.pl NestDecode.pl], or decoded in real time using [http://luke.dashjr.org/programs/freeabode/kindling/nest-intercept.c nest-intercept.c].

nest-intercept.c requires one argument, the thread id reading from the backplate controller.
The easiest way to get this is to strace the nlclient process with -ff and look for a thread reading from fd 54.

Note that nest-intercept.c also has a "hack" variable which can be set to 0 (default is 2) in order to corrupt the TFE version response and trigger nlclient into uploading the firmware again.

=== Backplate firmware ===
Found in /nestlabs/share/bp/data/firmware/nlbpfirmware.plist

There are 6 different firmwares in the file:
* Backplate 2 vs Backplate 3
* TFE (BP_D2 for Bp2, AMBER_BP for Bp3) vs BSL
* For TFE firmwares, hex vs srec (which for some reason DO differ!)

=== Backplate initialisation ===
When the backplate is first connected, the following sequence occurs:
Send [[#Reset|00ff - Reset]]
Recv 0001 - (message from backplate; ASCII)
Recv [[#FET presence|0004 - FET presence]]
Recv [[#FET presence|0009 - FET presence]]
Send [[#FET presence|008f - FET presence]]
Send 0083 - (every 30 seconds; no data; triggers periodic messages 0002, 0007, and 000a; also triggers 0005 to some extent?)
Send 0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
Recv 0001 - (message from backplate; ASCII)
Recv 0001 - (message from backplate; ASCII)
Recv 0010 - (24-bit data)
Send [[#Get TFE version|0098 - Get TFE version]]
Recv 000a - (every second; 16-bit data)
Recv 0007 - (every second; 16-bit data)
Recv [[#Get TFE version|0018 - Get TFE version (response)]]
Send [[#Get build info|0099 - Get build info]]
Recv [[#Get build info|0019 - Get build info (response)]]
Sometimes:
Send 009d - (no data; responds with 001d (constant?) data=bbbb)
Recv 001d - Response to 009d; always(?) bbbb
Sometimes:
Send [[#Get BSL version|009b - Get BSL version]]
Recv [[#Get BSL version|001b - Get BSL version (response)]]
Sometimes:
Send 009c - (no data; responds with 001c (constant?) data="BSL")
Recv 001c - Response to 009c; always(?) "BSL"
Send [[#Get firmware hash?|009f - Get firmware hash?]]
Recv [[#Get firmware hash?|001f - Get firmware hash? (response)]]
Send [[#Get hardware version?|009e - Get hardware version?]]
Recv [[#Get hardware version?|001e - Get hardware version? (response)]]

== Nest backplate interface ==
* Connected on /dev/ttyO2
* All communications with backplate begin with (d5)d5aa96 (d5 is doubled only for data FROM backplate)
* Everything is little endian
* 16-bit command
* 16-bit data length
* <data>
* 16-bit checksum

Monitor:
strace -ff -p $(pidof nlclient) -x -s9999 -e read,write 2>&1 | grep '(54'

=== Checksum ===
<Bytes-from-end>.<bit-value> <xor-with>
00.01 2110 (1021)
00.02 4220 (2042: 1021<<1)
00.04 8440 (4084: 2048<<1)
00.08 0881 (8108: 4084<<1)
00.10 3112 (1231: 8108<<1^1021)
00.20 6224 (2462: 1231<<1)
00.40 c448 (48c4: 2462<<1)
00.80 8891 (9188: 48c4<<1)
01.01 3133 (3313: 9188<<1^1021)
01.02 6266
01.04 c4cc
01.08 a989
01.10 7303
01.20 e606
01.40 cc0d
01.80 981b
02.01 3037
02.02 606e
...
03.01 b476
03.02 68ed
03.04 f1ca
03.08 c385
03.10 a71b
03.20 4e37
03.40 9c6e
03.80 38dd
...
07.20 687b

If you compute the contribution of the individual bit changes in the data you end up with the xor table above; byte offset from the end of the data, bit pattern, xor value. Correcting for little endianess in the output you end up with the hex values in parenthesis. The least significant bit is 0x1021 and each subsequent bit is a shift left, if the XOR value has the 0x8000 bit set then it is XORed with 0x1021. This is the CRC-CCITT polynomial.

8 7 6 5 4 3 2 1 0
d5 aa 96 82 00 02 00 00 00: 08b2
|| |
|| 68ed
|408b
20d4

08b2: 68ed ^ 408b ^ 20d4

Starting at the least significant bit and filling in the XOR values for each bit gives the above diagram; the diagram stops at the 20d4 XOR value because at that point it matches the final CRC. This tells us that the CRC covers the 6 bytes prior.

#!/usr/bin/env perl
use Digest::CRC qw(crc);
my $data = pack("H*", "820002000000");
printf("%04x\n", crc($data,16,0,0,0,0x1021,0,0));

We can also compute the same CRC in Perl; note the result will be byte swapped since the data encodes the number as little endian.

=== Command ids ===

==== Display to backplate ====
[[#FET control|0082 - FET control]]
0083 - (every 30 seconds; no data; triggers periodic messages 0002, 0007, and 000a; also triggers 0005 to some extent?)
[[#FET presence|008f - FET presence]]
0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
[[#Backplate firmware upload|0091 - Backplate firmware upload (start)]]
[[#Backplate firmware upload|0092 - Backplate firmware upload]]
[[#Backplate firmware upload|0093 - Backplate firmware upload (finish)]]
[[#Get TFE version|0098 - Get TFE version]]
[[#Get build info|0099 - Get build info]]
[[#Get BSL version|009b - Get BSL version]]
009c - (no data; responds with 001c (constant?) data="BSL")
009d - (no data; responds with 001d (constant?) data=bbbb)
[[#Get hardware version?|009e - Get hardware version?]]
[[#Get firmware hash?|009f - Get firmware hash?]]
00a1 - (16-bit data)
00a2 - (every 30 seconds; no data)
00a3 - (every 30 seconds; no data)
00a4 - (16-bit data)
00b1 - button pressed/unpressed (no data)
00b3 - (32-bit data; always ffffffff?)
00b5 - (16-bit data; always 0f00?)
00b9 - (32-bit data; always 0000ffff?)
00ba - (48-bit data; always 000000000000?)
00c2 - (48-bit data)
[[#Reset|00ff - Reset]]

==== Backplate to display ====
0001 - (message from backplate; ASCII)
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
[[#FET presence|0004 - FET presence]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
[[#FET presence|0009 - FET presence]]
000a - (every second; 16-bit data)
[[#Backplate state|000b - Backplate state]]
000c - (16-bit values: pir, px1, px1 divisor, px2, px2 divisor, alir, av)
0010 - (24-bit data)
[[#Backplate firmware upload|0011 - Backplate firmware upload (ACK)]]
0014 - (16-bit data)
[[#Get TFE version|0018 - Get TFE version (response)]]
[[#Get build info|0019 - Get build info (response)]]
[[#Get BSL version|001b - Get BSL version (response)]]
001c - Response to 009c; always(?) "BSL"
001d - Response to 009d; always(?) bbbb
[[#Get hardware version?|001e - Get hardware version? (response)]]
[[#Get firmware hash?|001f - Get firmware hash? (response)]]
0022 - (every 30 seconds; 4, 8, 20, 28, 36, 56, 60, 54, 68, 72, or 176 byte data)
0023 - (6, 12, 30, 42, 54, 78, 84, 90, 96, 102, 108, 144, or 150 byte data)
0025 - (2, 4, 12, 14, 20, or 24 byte data)
0027 - (8, 16, 48, 56, 80, or 96 byte data)
0029 - (6, 12, 36, 42, 60, or 72 byte data)
002b - (8, 16, 24, 32, 40, 128, or 152 byte data)
002f - (every 30 seconds; 16-bit data; "end of buffers ACK" log msg)

=== Backplate firmware upload ===
For uploading the firmware, the following sequence is used:
Send 0091 data=0000<firmware type>
Recv 0011 data=0000
Send 0092 data=0100...
Recv 0011 data=0100
Send 0092 data=0200...
Recv 0011 data=0200
...
Send 0092 data=a901...
Recv 0011 data=a901
Send 0093 data=aa01
Recv 0011 data=aa01
Following the upload, the [[#Backplate initialisation|backplate initialisation process]] begins immediately (that is, without message 00ff being sent to order a reset).
Presumably the 0011 message is an ACK, and the first 16 bits of each message is the line number.
The format itself appears to be Motorola S-record (SREC).
Uploading the BSL firmware was followed by the TFE firmware, so it may be required (though uploading the TFE firmware does ''not'' require uploading the BSL).

Firmware type is either 4d for TFE or 42 for BSL.

=== Backplate state ===
Data:
* 8-bit "state"
* 8-bit "flags"
* 8-bit "px0" (may be wider?)
* 40-bit UNKNOWN (includes at least "p2" and "voc")
* 16-bit centi-volts "vi"
* 16-bit milli-volts "vo"
* 16-bit milli-volts "vb"
* 8-bit ("pins" or "wires")
* 8-bit ("wires" or "pins")
* 16-bit UNKNOWN

=== FET control ===
Turn on W1: d5aa96 8200 0200 00 01 29a2
Turn off W1: d5aa96 8200 0200 00 00 08b2
Turn on Y1: d5aa96 8200 0200 01 01 1891
Turn off Y1: d5aa96 8200 0200 01 00 3981
Turn on G : d5aa96 8200 0200 02 01 4bc4
Turn off G : d5aa96 8200 0200 02 00 6ad4
Turn on OB: d5aa96 8200 0200 03 01 7af7
Turn off OB: d5aa96 8200 0200 03 00 5be7
Turn on W2: d5aa96 8200 0200 04 01 ed6e
Turn off W2: d5aa96 8200 0200 04 00 cc7e
Turn on Y2: d5aa96 8200 0200 07 01 be3b
Turn off Y2: d5aa96 8200 0200 07 00 9f2b
Turn on * : d5aa96 8200 0200 0b 01 d37e
Turn off * : d5aa96 8200 0200 0b 00 f26e

For the sake of documentation, we will refer to the unique id numbers for each wire as "wire id numbers".
So wire id 0 is W1, wire id 1 is Y1, wire id B is *, etc.

=== FET presence ===
The backplate will, at least upon connection, send information about which FETs have a wire present.
This data is received with command ids 0004 and 0009, in that order.
Each sensor is represented by one byte which is either 00 (not present) or 01 (present).

The content of 0004 is in order of the "wire id numbers" used for control:
W1, Y1, G, OB, W2, ?0, ?0, Y2, ?1, ?1, ?0, *, ?0

The content of 0009 is arranged differently and has 2 more values:
W1, Y1, ?1, ?1, ?0, G, OB, W2, ?0, Y2, ?0, *, ?0, ?0, ?0

After these are received, the display sends back command 008f with the exact data from message 0004.
Message 008f does not itself receive any response.

=== Get build info ===
Message 0099 (no data) requests the backplate report information about its build.
The response will be message 0019 in ASCII (one line, no trailing newline).

=== Get firmware hash? ===
Message 009f (no data) requests the backplate report a 64-bit hexadecimal value, probably a hash of the firmware (since Nest's software requests it at the same time as version and build info).
The response will be message 001f in uppercase ASCII.

=== Get hardware version? ===
Message 009e (no data) requests the backplate report a "Backplate-"X.Y version string.
Since the firmware file on the display CPU uses these strings as "MinApplicability" and "MaxApplicability" ranges, it is probable they refer to the hardware.

Witnessed versions:
"Backplate-2.8" - Florida Lowes

=== Get BSL version ===
Message 009b (no data) requests the backplate report its BSL version number.
The response will be message 001b in ASCII.

=== Get TFE version ===
Message 0098 (no data) requests the backplate report its TFE version number.
The response will be message 0018 in ASCII.

=== Temperature reading ===
The backplate will send message 0002 every 30 seconds.
The data contains two 16-bit numbers, which nlclient logs in decimal.
The first number is the temperature in centi-celcius.
The second number is the humidity in per-millis.

=== Reset ===
At least upon connection, the display sends message 00ff to the backplate to reset.

The backplate answers with:
0001 msg "<version> <build timestamp "YYYY-MM-DD HH:MM:SS"> K"
[[#FET presence|0004 FET presence]]
[[#FET presence|0009 FET presence]]
0001 msg "*sense 06d1 06d0 0001 0001 0000 0000 0000 0001 06d9 06d8 06d8; detect 09d3 065c"
0001 msg "BRK"

== Run BeagleBone/Debian programs ==
ln -s . /lib/arm-linux-gnueabihf
ln -s ld-2.11.1.so /lib/ld-linux-armhf.so.3

Nest Hacking

2014-07-28T01:38:03Z

Luke-Jr: /* Backplate to display */

== Hardware ==
* TSL2571 Light-to-Digital Converter

== Info ==
* /dev/event1 is the knob; /dev/event2 is the button

== Nest software ==
/nestlabs/sbin/nlclient -config /nestlabs/etc/client.config -config /nestlabs/etc/Display/Display-2/client.config

=== Backplate communications ===
Backplate communications can be decoded from a (filtered) strace log using [http://luke.dashjr.org/programs/freeabode/kindling/NestDecode.pl NestDecode.pl], or decoded in real time using [http://luke.dashjr.org/programs/freeabode/kindling/nest-intercept.c nest-intercept.c].

nest-intercept.c requires one argument, the thread id reading from the backplate controller.
The easiest way to get this is to strace the nlclient process with -ff and look for a thread reading from fd 54.

Note that nest-intercept.c also has a "hack" variable which can be set to 0 (default is 2) in order to corrupt the TFE version response and trigger nlclient into uploading the firmware again.

=== Backplate firmware ===
Found in /nestlabs/share/bp/data/firmware/nlbpfirmware.plist

There are 6 different firmwares in the file:
* Backplate 2 vs Backplate 3
* TFE (BP_D2 for Bp2, AMBER_BP for Bp3) vs BSL
* For TFE firmwares, hex vs srec (which for some reason DO differ!)

=== Backplate initialisation ===
When the backplate is first connected, the following sequence occurs:
Send [[#Reset|00ff - Reset]]
Recv 0001 - (message from backplate; ASCII)
Recv [[#FET presence|0004 - FET presence]]
Recv [[#FET presence|0009 - FET presence]]
Send [[#FET presence|008f - FET presence]]
Send 0083 - (every 30 seconds; no data; triggers periodic messages 0002, 0007, and 000a; also triggers 0005 to some extent?)
Send 0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
Recv 0001 - (message from backplate; ASCII)
Recv 0001 - (message from backplate; ASCII)
Recv 0010 - (24-bit data)
Send [[#Get TFE version|0098 - Get TFE version]]
Recv 000a - (every second; 16-bit data)
Recv 0007 - (every second; 16-bit data)
Recv [[#Get TFE version|0018 - Get TFE version (response)]]
Send [[#Get build info|0099 - Get build info]]
Recv [[#Get build info|0019 - Get build info (response)]]
Sometimes:
Send 009d - (no data; responds with 001d (constant?) data=bbbb)
Recv 001d - Response to 009d; always(?) bbbb
Sometimes:
Send [[#Get BSL version|009b - Get BSL version]]
Recv [[#Get BSL version|001b - Get BSL version (response)]]
Sometimes:
Send 009c - (no data; responds with 001c (constant?) data="BSL")
Recv 001c - Response to 009c; always(?) "BSL"
Send [[#Get firmware hash?|009f - Get firmware hash?]]
Recv [[#Get firmware hash?|001f - Get firmware hash? (response)]]
Send [[#Get hardware version?|009e - Get hardware version?]]
Recv [[#Get hardware version?|001e - Get hardware version? (response)]]

== Nest backplate interface ==
* Connected on /dev/ttyO2
* All communications with backplate begin with (d5)d5aa96 (d5 is doubled only for data FROM backplate)
* Everything is little endian
* 16-bit command
* 16-bit data length
* <data>
* 16-bit checksum

Monitor:
strace -ff -p $(pidof nlclient) -x -s9999 -e read,write 2>&1 | grep '(54'

=== Checksum ===
<Bytes-from-end>.<bit-value> <xor-with>
00.01 2110 (1021)
00.02 4220 (2042: 1021<<1)
00.04 8440 (4084: 2048<<1)
00.08 0881 (8108: 4084<<1)
00.10 3112 (1231: 8108<<1^1021)
00.20 6224 (2462: 1231<<1)
00.40 c448 (48c4: 2462<<1)
00.80 8891 (9188: 48c4<<1)
01.01 3133 (3313: 9188<<1^1021)
01.02 6266
01.04 c4cc
01.08 a989
01.10 7303
01.20 e606
01.40 cc0d
01.80 981b
02.01 3037
02.02 606e
...
03.01 b476
03.02 68ed
03.04 f1ca
03.08 c385
03.10 a71b
03.20 4e37
03.40 9c6e
03.80 38dd
...
07.20 687b

If you compute the contribution of the individual bit changes in the data you end up with the xor table above; byte offset from the end of the data, bit pattern, xor value. Correcting for little endianess in the output you end up with the hex values in parenthesis. The least significant bit is 0x1021 and each subsequent bit is a shift left, if the XOR value has the 0x8000 bit set then it is XORed with 0x1021. This is the CRC-CCITT polynomial.

8 7 6 5 4 3 2 1 0
d5 aa 96 82 00 02 00 00 00: 08b2
|| |
|| 68ed
|408b
20d4

08b2: 68ed ^ 408b ^ 20d4

Starting at the least significant bit and filling in the XOR values for each bit gives the above diagram; the diagram stops at the 20d4 XOR value because at that point it matches the final CRC. This tells us that the CRC covers the 6 bytes prior.

#!/usr/bin/env perl
use Digest::CRC qw(crc);
my $data = pack("H*", "820002000000");
printf("%04x\n", crc($data,16,0,0,0,0x1021,0,0));

We can also compute the same CRC in Perl; note the result will be byte swapped since the data encodes the number as little endian.

=== Command ids ===

==== Display to backplate ====
[[#FET control|0082 - FET control]]
0083 - (every 30 seconds; no data; triggers periodic messages 0002, 0007, and 000a; also triggers 0005 to some extent?)
[[#FET presence|008f - FET presence]]
0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
[[#Backplate firmware upload|0091 - Backplate firmware upload (start)]]
[[#Backplate firmware upload|0092 - Backplate firmware upload]]
[[#Backplate firmware upload|0093 - Backplate firmware upload (finish)]]
[[#Get TFE version|0098 - Get TFE version]]
[[#Get build info|0099 - Get build info]]
[[#Get BSL version|009b - Get BSL version]]
009c - (no data; responds with 001c (constant?) data="BSL")
009d - (no data; responds with 001d (constant?) data=bbbb)
[[#Get hardware version?|009e - Get hardware version?]]
[[#Get firmware hash?|009f - Get firmware hash?]]
00a1 - (16-bit data)
00a2 - (every 30 seconds; no data)
00a3 - (every 30 seconds; no data)
00a4 - (16-bit data)
00b1 - button pressed/unpressed (no data)
00b3 - (32-bit data; always ffffffff?)
00b5 - (16-bit data; always 0f00?)
00b9 - (32-bit data; always 0000ffff?)
00ba - (48-bit data; always 000000000000?)
00c2 - (48-bit data)
[[#Reset|00ff - Reset]]

==== Backplate to display ====
0001 - (message from backplate; ASCII)
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
[[#FET presence|0004 - FET presence]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
[[#FET presence|0009 - FET presence]]
000a - (every second; 16-bit data)
[[#Backplate state|000b - Backplate state]]
000c - (16-bit values: pir, px1, px1 divisor, px2, px2 divisor, alir, av)
0010 - (24-bit data)
[[#Backplate firmware upload|0011 - Backplate firmware upload (ACK)]]
0014 - (16-bit data)
[[#Get TFE version|0018 - Get TFE version (response)]]
[[#Get build info|0019 - Get build info (response)]]
[[#Get BSL version|001b - Get BSL version (response)]]
001c - Response to 009c; always(?) "BSL"
001d - Response to 009d; always(?) bbbb
[[#Get hardware version?|001e - Get hardware version? (response)]]
[[#Get firmware hash?|001f - Get firmware hash? (response)]]
0022 - (every 30 seconds; 4, 8, 20, 28, 36, 56, 60, 54, 68, 72, or 176 byte data)
0023 - (6, 12, 30, 42, 54, 78, 84, 90, 96, 102, 108, 144, or 150 byte data)
0025 - (2, 4, 12, 14, 20, or 24 byte data)
0027 - (8, 16, 48, 56, 80, or 96 byte data)
0029 - (6, 12, 36, 42, 60, or 72 byte data)
002b - (8, 16, 24, 32, 40, 128, or 152 byte data)
002f - (every 30 seconds; 16-bit data; "end of buffers ACK" log msg)

=== Backplate firmware upload ===
At least for uploading the TFE firmware, the following sequence is used:
Send 0091 data=00004d
Recv 0011 data=0000
Send 0092 data=0100...
Recv 0011 data=0100
Send 0092 data=0200...
Recv 0011 data=0200
...
Send 0092 data=a901...
Recv 0011 data=a901
Send 0093 data=aa01
Recv 0011 data=aa01
Following the upload, the [[#Backplate initialisation|backplate initialisation process]] begins immediately (that is, without message 00ff being sent to order a reset).
Presumably the 0011 message is an ACK, and the first 16 bits of each message is the line number.
The format itself appears to be Motorola S-record (SREC).

=== Backplate state ===
Data:
* 8-bit "state"
* 8-bit "flags"
* 8-bit "px0" (may be wider?)
* 40-bit UNKNOWN (includes at least "p2" and "voc")
* 16-bit centi-volts "vi"
* 16-bit milli-volts "vo"
* 16-bit milli-volts "vb"
* 8-bit ("pins" or "wires")
* 8-bit ("wires" or "pins")
* 16-bit UNKNOWN

=== FET control ===
Turn on W1: d5aa96 8200 0200 00 01 29a2
Turn off W1: d5aa96 8200 0200 00 00 08b2
Turn on Y1: d5aa96 8200 0200 01 01 1891
Turn off Y1: d5aa96 8200 0200 01 00 3981
Turn on G : d5aa96 8200 0200 02 01 4bc4
Turn off G : d5aa96 8200 0200 02 00 6ad4
Turn on OB: d5aa96 8200 0200 03 01 7af7
Turn off OB: d5aa96 8200 0200 03 00 5be7
Turn on W2: d5aa96 8200 0200 04 01 ed6e
Turn off W2: d5aa96 8200 0200 04 00 cc7e
Turn on Y2: d5aa96 8200 0200 07 01 be3b
Turn off Y2: d5aa96 8200 0200 07 00 9f2b
Turn on * : d5aa96 8200 0200 0b 01 d37e
Turn off * : d5aa96 8200 0200 0b 00 f26e

For the sake of documentation, we will refer to the unique id numbers for each wire as "wire id numbers".
So wire id 0 is W1, wire id 1 is Y1, wire id B is *, etc.

=== FET presence ===
The backplate will, at least upon connection, send information about which FETs have a wire present.
This data is received with command ids 0004 and 0009, in that order.
Each sensor is represented by one byte which is either 00 (not present) or 01 (present).

The content of 0004 is in order of the "wire id numbers" used for control:
W1, Y1, G, OB, W2, ?0, ?0, Y2, ?1, ?1, ?0, *, ?0

The content of 0009 is arranged differently and has 2 more values:
W1, Y1, ?1, ?1, ?0, G, OB, W2, ?0, Y2, ?0, *, ?0, ?0, ?0

After these are received, the display sends back command 008f with the exact data from message 0004.
Message 008f does not itself receive any response.

=== Get build info ===
Message 0099 (no data) requests the backplate report information about its build.
The response will be message 0019 in ASCII (one line, no trailing newline).

=== Get firmware hash? ===
Message 009f (no data) requests the backplate report a 64-bit hexadecimal value, probably a hash of the firmware (since Nest's software requests it at the same time as version and build info).
The response will be message 001f in uppercase ASCII.

=== Get hardware version? ===
Message 009e (no data) requests the backplate report a "Backplate-"X.Y version string.
Since the firmware file on the display CPU uses these strings as "MinApplicability" and "MaxApplicability" ranges, it is probable they refer to the hardware.

Witnessed versions:
"Backplate-2.8" - Florida Lowes

=== Get BSL version ===
Message 009b (no data) requests the backplate report its BSL version number.
The response will be message 001b in ASCII.

=== Get TFE version ===
Message 0098 (no data) requests the backplate report its TFE version number.
The response will be message 0018 in ASCII.

=== Temperature reading ===
The backplate will send message 0002 every 30 seconds.
The data contains two 16-bit numbers, which nlclient logs in decimal.
The first number is the temperature in centi-celcius.
The second number is the humidity in per-millis.

=== Reset ===
At least upon connection, the display sends message 00ff to the backplate to reset.

The backplate answers with:
0001 msg "<version> <build timestamp "YYYY-MM-DD HH:MM:SS"> K"
[[#FET presence|0004 FET presence]]
[[#FET presence|0009 FET presence]]
0001 msg "*sense 06d1 06d0 0001 0001 0000 0000 0000 0001 06d9 06d8 06d8; detect 09d3 065c"
0001 msg "BRK"

== Run BeagleBone/Debian programs ==
ln -s . /lib/arm-linux-gnueabihf
ln -s ld-2.11.1.so /lib/ld-linux-armhf.so.3

Nest Hacking

2014-07-28T01:37:48Z

Luke-Jr: /* Display to backplate */

== Hardware ==
* TSL2571 Light-to-Digital Converter

== Info ==
* /dev/event1 is the knob; /dev/event2 is the button

== Nest software ==
/nestlabs/sbin/nlclient -config /nestlabs/etc/client.config -config /nestlabs/etc/Display/Display-2/client.config

=== Backplate communications ===
Backplate communications can be decoded from a (filtered) strace log using [http://luke.dashjr.org/programs/freeabode/kindling/NestDecode.pl NestDecode.pl], or decoded in real time using [http://luke.dashjr.org/programs/freeabode/kindling/nest-intercept.c nest-intercept.c].

nest-intercept.c requires one argument, the thread id reading from the backplate controller.
The easiest way to get this is to strace the nlclient process with -ff and look for a thread reading from fd 54.

Note that nest-intercept.c also has a "hack" variable which can be set to 0 (default is 2) in order to corrupt the TFE version response and trigger nlclient into uploading the firmware again.

=== Backplate firmware ===
Found in /nestlabs/share/bp/data/firmware/nlbpfirmware.plist

There are 6 different firmwares in the file:
* Backplate 2 vs Backplate 3
* TFE (BP_D2 for Bp2, AMBER_BP for Bp3) vs BSL
* For TFE firmwares, hex vs srec (which for some reason DO differ!)

=== Backplate initialisation ===
When the backplate is first connected, the following sequence occurs:
Send [[#Reset|00ff - Reset]]
Recv 0001 - (message from backplate; ASCII)
Recv [[#FET presence|0004 - FET presence]]
Recv [[#FET presence|0009 - FET presence]]
Send [[#FET presence|008f - FET presence]]
Send 0083 - (every 30 seconds; no data; triggers periodic messages 0002, 0007, and 000a; also triggers 0005 to some extent?)
Send 0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
Recv 0001 - (message from backplate; ASCII)
Recv 0001 - (message from backplate; ASCII)
Recv 0010 - (24-bit data)
Send [[#Get TFE version|0098 - Get TFE version]]
Recv 000a - (every second; 16-bit data)
Recv 0007 - (every second; 16-bit data)
Recv [[#Get TFE version|0018 - Get TFE version (response)]]
Send [[#Get build info|0099 - Get build info]]
Recv [[#Get build info|0019 - Get build info (response)]]
Sometimes:
Send 009d - (no data; responds with 001d (constant?) data=bbbb)
Recv 001d - Response to 009d; always(?) bbbb
Sometimes:
Send [[#Get BSL version|009b - Get BSL version]]
Recv [[#Get BSL version|001b - Get BSL version (response)]]
Sometimes:
Send 009c - (no data; responds with 001c (constant?) data="BSL")
Recv 001c - Response to 009c; always(?) "BSL"
Send [[#Get firmware hash?|009f - Get firmware hash?]]
Recv [[#Get firmware hash?|001f - Get firmware hash? (response)]]
Send [[#Get hardware version?|009e - Get hardware version?]]
Recv [[#Get hardware version?|001e - Get hardware version? (response)]]

== Nest backplate interface ==
* Connected on /dev/ttyO2
* All communications with backplate begin with (d5)d5aa96 (d5 is doubled only for data FROM backplate)
* Everything is little endian
* 16-bit command
* 16-bit data length
* <data>
* 16-bit checksum

Monitor:
strace -ff -p $(pidof nlclient) -x -s9999 -e read,write 2>&1 | grep '(54'

=== Checksum ===
<Bytes-from-end>.<bit-value> <xor-with>
00.01 2110 (1021)
00.02 4220 (2042: 1021<<1)
00.04 8440 (4084: 2048<<1)
00.08 0881 (8108: 4084<<1)
00.10 3112 (1231: 8108<<1^1021)
00.20 6224 (2462: 1231<<1)
00.40 c448 (48c4: 2462<<1)
00.80 8891 (9188: 48c4<<1)
01.01 3133 (3313: 9188<<1^1021)
01.02 6266
01.04 c4cc
01.08 a989
01.10 7303
01.20 e606
01.40 cc0d
01.80 981b
02.01 3037
02.02 606e
...
03.01 b476
03.02 68ed
03.04 f1ca
03.08 c385
03.10 a71b
03.20 4e37
03.40 9c6e
03.80 38dd
...
07.20 687b

If you compute the contribution of the individual bit changes in the data you end up with the xor table above; byte offset from the end of the data, bit pattern, xor value. Correcting for little endianess in the output you end up with the hex values in parenthesis. The least significant bit is 0x1021 and each subsequent bit is a shift left, if the XOR value has the 0x8000 bit set then it is XORed with 0x1021. This is the CRC-CCITT polynomial.

8 7 6 5 4 3 2 1 0
d5 aa 96 82 00 02 00 00 00: 08b2
|| |
|| 68ed
|408b
20d4

08b2: 68ed ^ 408b ^ 20d4

Starting at the least significant bit and filling in the XOR values for each bit gives the above diagram; the diagram stops at the 20d4 XOR value because at that point it matches the final CRC. This tells us that the CRC covers the 6 bytes prior.

#!/usr/bin/env perl
use Digest::CRC qw(crc);
my $data = pack("H*", "820002000000");
printf("%04x\n", crc($data,16,0,0,0,0x1021,0,0));

We can also compute the same CRC in Perl; note the result will be byte swapped since the data encodes the number as little endian.

=== Command ids ===

==== Display to backplate ====
[[#FET control|0082 - FET control]]
0083 - (every 30 seconds; no data; triggers periodic messages 0002, 0007, and 000a; also triggers 0005 to some extent?)
[[#FET presence|008f - FET presence]]
0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
[[#Backplate firmware upload|0091 - Backplate firmware upload (start)]]
[[#Backplate firmware upload|0092 - Backplate firmware upload]]
[[#Backplate firmware upload|0093 - Backplate firmware upload (finish)]]
[[#Get TFE version|0098 - Get TFE version]]
[[#Get build info|0099 - Get build info]]
[[#Get BSL version|009b - Get BSL version]]
009c - (no data; responds with 001c (constant?) data="BSL")
009d - (no data; responds with 001d (constant?) data=bbbb)
[[#Get hardware version?|009e - Get hardware version?]]
[[#Get firmware hash?|009f - Get firmware hash?]]
00a1 - (16-bit data)
00a2 - (every 30 seconds; no data)
00a3 - (every 30 seconds; no data)
00a4 - (16-bit data)
00b1 - button pressed/unpressed (no data)
00b3 - (32-bit data; always ffffffff?)
00b5 - (16-bit data; always 0f00?)
00b9 - (32-bit data; always 0000ffff?)
00ba - (48-bit data; always 000000000000?)
00c2 - (48-bit data)
[[#Reset|00ff - Reset]]

==== Backplate to display ====
0001 - (message from backplate; ASCII)
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
[[#FET presence|0004 - FET presence]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
[[#FET presence|0009 - FET presence]]
000a - (every second; 16-bit data)
[[#Backplate state|000b - Backplate state]]
000c - (16-bit values: pir, px1, px1 divisor, px2, px2 divisor, alir, av)
0010 - (24-bit data)
[[#Backplate firmware upload|0011 - Backplate firmware upload]]
0014 - (16-bit data)
[[#Get TFE version|0018 - Get TFE version (response)]]
[[#Get build info|0019 - Get build info (response)]]
[[#Get BSL version|001b - Get BSL version (response)]]
001c - Response to 009c; always(?) "BSL"
001d - Response to 009d; always(?) bbbb
[[#Get hardware version?|001e - Get hardware version? (response)]]
[[#Get firmware hash?|001f - Get firmware hash? (response)]]
0022 - (every 30 seconds; 4, 8, 20, 28, 36, 56, 60, 54, 68, 72, or 176 byte data)
0023 - (6, 12, 30, 42, 54, 78, 84, 90, 96, 102, 108, 144, or 150 byte data)
0025 - (2, 4, 12, 14, 20, or 24 byte data)
0027 - (8, 16, 48, 56, 80, or 96 byte data)
0029 - (6, 12, 36, 42, 60, or 72 byte data)
002b - (8, 16, 24, 32, 40, 128, or 152 byte data)
002f - (every 30 seconds; 16-bit data; "end of buffers ACK" log msg)

=== Backplate firmware upload ===
At least for uploading the TFE firmware, the following sequence is used:
Send 0091 data=00004d
Recv 0011 data=0000
Send 0092 data=0100...
Recv 0011 data=0100
Send 0092 data=0200...
Recv 0011 data=0200
...
Send 0092 data=a901...
Recv 0011 data=a901
Send 0093 data=aa01
Recv 0011 data=aa01
Following the upload, the [[#Backplate initialisation|backplate initialisation process]] begins immediately (that is, without message 00ff being sent to order a reset).
Presumably the 0011 message is an ACK, and the first 16 bits of each message is the line number.
The format itself appears to be Motorola S-record (SREC).

=== Backplate state ===
Data:
* 8-bit "state"
* 8-bit "flags"
* 8-bit "px0" (may be wider?)
* 40-bit UNKNOWN (includes at least "p2" and "voc")
* 16-bit centi-volts "vi"
* 16-bit milli-volts "vo"
* 16-bit milli-volts "vb"
* 8-bit ("pins" or "wires")
* 8-bit ("wires" or "pins")
* 16-bit UNKNOWN

=== FET control ===
Turn on W1: d5aa96 8200 0200 00 01 29a2
Turn off W1: d5aa96 8200 0200 00 00 08b2
Turn on Y1: d5aa96 8200 0200 01 01 1891
Turn off Y1: d5aa96 8200 0200 01 00 3981
Turn on G : d5aa96 8200 0200 02 01 4bc4
Turn off G : d5aa96 8200 0200 02 00 6ad4
Turn on OB: d5aa96 8200 0200 03 01 7af7
Turn off OB: d5aa96 8200 0200 03 00 5be7
Turn on W2: d5aa96 8200 0200 04 01 ed6e
Turn off W2: d5aa96 8200 0200 04 00 cc7e
Turn on Y2: d5aa96 8200 0200 07 01 be3b
Turn off Y2: d5aa96 8200 0200 07 00 9f2b
Turn on * : d5aa96 8200 0200 0b 01 d37e
Turn off * : d5aa96 8200 0200 0b 00 f26e

For the sake of documentation, we will refer to the unique id numbers for each wire as "wire id numbers".
So wire id 0 is W1, wire id 1 is Y1, wire id B is *, etc.

=== FET presence ===
The backplate will, at least upon connection, send information about which FETs have a wire present.
This data is received with command ids 0004 and 0009, in that order.
Each sensor is represented by one byte which is either 00 (not present) or 01 (present).

The content of 0004 is in order of the "wire id numbers" used for control:
W1, Y1, G, OB, W2, ?0, ?0, Y2, ?1, ?1, ?0, *, ?0

The content of 0009 is arranged differently and has 2 more values:
W1, Y1, ?1, ?1, ?0, G, OB, W2, ?0, Y2, ?0, *, ?0, ?0, ?0

After these are received, the display sends back command 008f with the exact data from message 0004.
Message 008f does not itself receive any response.

=== Get build info ===
Message 0099 (no data) requests the backplate report information about its build.
The response will be message 0019 in ASCII (one line, no trailing newline).

=== Get firmware hash? ===
Message 009f (no data) requests the backplate report a 64-bit hexadecimal value, probably a hash of the firmware (since Nest's software requests it at the same time as version and build info).
The response will be message 001f in uppercase ASCII.

=== Get hardware version? ===
Message 009e (no data) requests the backplate report a "Backplate-"X.Y version string.
Since the firmware file on the display CPU uses these strings as "MinApplicability" and "MaxApplicability" ranges, it is probable they refer to the hardware.

Witnessed versions:
"Backplate-2.8" - Florida Lowes

=== Get BSL version ===
Message 009b (no data) requests the backplate report its BSL version number.
The response will be message 001b in ASCII.

=== Get TFE version ===
Message 0098 (no data) requests the backplate report its TFE version number.
The response will be message 0018 in ASCII.

=== Temperature reading ===
The backplate will send message 0002 every 30 seconds.
The data contains two 16-bit numbers, which nlclient logs in decimal.
The first number is the temperature in centi-celcius.
The second number is the humidity in per-millis.

=== Reset ===
At least upon connection, the display sends message 00ff to the backplate to reset.

The backplate answers with:
0001 msg "<version> <build timestamp "YYYY-MM-DD HH:MM:SS"> K"
[[#FET presence|0004 FET presence]]
[[#FET presence|0009 FET presence]]
0001 msg "*sense 06d1 06d0 0001 0001 0000 0000 0000 0001 06d9 06d8 06d8; detect 09d3 065c"
0001 msg "BRK"

== Run BeagleBone/Debian programs ==
ln -s . /lib/arm-linux-gnueabihf
ln -s ld-2.11.1.so /lib/ld-linux-armhf.so.3

Nest Hacking

2014-07-28T00:01:50Z

Luke-Jr: /* Backplate communications */

== Hardware ==
* TSL2571 Light-to-Digital Converter

== Info ==
* /dev/event1 is the knob; /dev/event2 is the button

== Nest software ==
/nestlabs/sbin/nlclient -config /nestlabs/etc/client.config -config /nestlabs/etc/Display/Display-2/client.config

=== Backplate communications ===
Backplate communications can be decoded from a (filtered) strace log using [http://luke.dashjr.org/programs/freeabode/kindling/NestDecode.pl NestDecode.pl], or decoded in real time using [http://luke.dashjr.org/programs/freeabode/kindling/nest-intercept.c nest-intercept.c].

nest-intercept.c requires one argument, the thread id reading from the backplate controller.
The easiest way to get this is to strace the nlclient process with -ff and look for a thread reading from fd 54.

Note that nest-intercept.c also has a "hack" variable which can be set to 0 (default is 2) in order to corrupt the TFE version response and trigger nlclient into uploading the firmware again.

=== Backplate firmware ===
Found in /nestlabs/share/bp/data/firmware/nlbpfirmware.plist

There are 6 different firmwares in the file:
* Backplate 2 vs Backplate 3
* TFE (BP_D2 for Bp2, AMBER_BP for Bp3) vs BSL
* For TFE firmwares, hex vs srec (which for some reason DO differ!)

=== Backplate initialisation ===
When the backplate is first connected, the following sequence occurs:
Send [[#Reset|00ff - Reset]]
Recv 0001 - (message from backplate; ASCII)
Recv [[#FET presence|0004 - FET presence]]
Recv [[#FET presence|0009 - FET presence]]
Send [[#FET presence|008f - FET presence]]
Send 0083 - (every 30 seconds; no data; triggers periodic messages 0002, 0007, and 000a; also triggers 0005 to some extent?)
Send 0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
Recv 0001 - (message from backplate; ASCII)
Recv 0001 - (message from backplate; ASCII)
Recv 0010 - (24-bit data)
Send [[#Get TFE version|0098 - Get TFE version]]
Recv 000a - (every second; 16-bit data)
Recv 0007 - (every second; 16-bit data)
Recv [[#Get TFE version|0018 - Get TFE version (response)]]
Send [[#Get build info|0099 - Get build info]]
Recv [[#Get build info|0019 - Get build info (response)]]
Sometimes:
Send 009d - (no data; responds with 001d (constant?) data=bbbb)
Recv 001d - Response to 009d; always(?) bbbb
Sometimes:
Send [[#Get BSL version|009b - Get BSL version]]
Recv [[#Get BSL version|001b - Get BSL version (response)]]
Sometimes:
Send 009c - (no data; responds with 001c (constant?) data="BSL")
Recv 001c - Response to 009c; always(?) "BSL"
Send [[#Get firmware hash?|009f - Get firmware hash?]]
Recv [[#Get firmware hash?|001f - Get firmware hash? (response)]]
Send [[#Get hardware version?|009e - Get hardware version?]]
Recv [[#Get hardware version?|001e - Get hardware version? (response)]]

== Nest backplate interface ==
* Connected on /dev/ttyO2
* All communications with backplate begin with (d5)d5aa96 (d5 is doubled only for data FROM backplate)
* Everything is little endian
* 16-bit command
* 16-bit data length
* <data>
* 16-bit checksum

Monitor:
strace -ff -p $(pidof nlclient) -x -s9999 -e read,write 2>&1 | grep '(54'

=== Checksum ===
<Bytes-from-end>.<bit-value> <xor-with>
00.01 2110 (1021)
00.02 4220 (2042: 1021<<1)
00.04 8440 (4084: 2048<<1)
00.08 0881 (8108: 4084<<1)
00.10 3112 (1231: 8108<<1^1021)
00.20 6224 (2462: 1231<<1)
00.40 c448 (48c4: 2462<<1)
00.80 8891 (9188: 48c4<<1)
01.01 3133 (3313: 9188<<1^1021)
01.02 6266
01.04 c4cc
01.08 a989
01.10 7303
01.20 e606
01.40 cc0d
01.80 981b
02.01 3037
02.02 606e
...
03.01 b476
03.02 68ed
03.04 f1ca
03.08 c385
03.10 a71b
03.20 4e37
03.40 9c6e
03.80 38dd
...
07.20 687b

If you compute the contribution of the individual bit changes in the data you end up with the xor table above; byte offset from the end of the data, bit pattern, xor value. Correcting for little endianess in the output you end up with the hex values in parenthesis. The least significant bit is 0x1021 and each subsequent bit is a shift left, if the XOR value has the 0x8000 bit set then it is XORed with 0x1021. This is the CRC-CCITT polynomial.

8 7 6 5 4 3 2 1 0
d5 aa 96 82 00 02 00 00 00: 08b2
|| |
|| 68ed
|408b
20d4

08b2: 68ed ^ 408b ^ 20d4

Starting at the least significant bit and filling in the XOR values for each bit gives the above diagram; the diagram stops at the 20d4 XOR value because at that point it matches the final CRC. This tells us that the CRC covers the 6 bytes prior.

#!/usr/bin/env perl
use Digest::CRC qw(crc);
my $data = pack("H*", "820002000000");
printf("%04x\n", crc($data,16,0,0,0,0x1021,0,0));

We can also compute the same CRC in Perl; note the result will be byte swapped since the data encodes the number as little endian.

=== Command ids ===

==== Display to backplate ====
[[#FET control|0082 - FET control]]
0083 - (every 30 seconds; no data; triggers periodic messages 0002, 0007, and 000a; also triggers 0005 to some extent?)
[[#FET presence|008f - FET presence]]
0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
[[#Backplate firmware upload|0091 - Backplate firmware upload]]
[[#Backplate firmware upload|0092 - Backplate firmware upload]]
[[#Get TFE version|0098 - Get TFE version]]
[[#Get build info|0099 - Get build info]]
[[#Get BSL version|009b - Get BSL version]]
009c - (no data; responds with 001c (constant?) data="BSL")
009d - (no data; responds with 001d (constant?) data=bbbb)
[[#Get hardware version?|009e - Get hardware version?]]
[[#Get firmware hash?|009f - Get firmware hash?]]
00a1 - (16-bit data)
00a2 - (every 30 seconds; no data)
00a3 - (every 30 seconds; no data)
00a4 - (16-bit data)
00b1 - button pressed/unpressed (no data)
00b3 - (32-bit data; always ffffffff?)
00b5 - (16-bit data; always 0f00?)
00b9 - (32-bit data; always 0000ffff?)
00ba - (48-bit data; always 000000000000?)
00c2 - (48-bit data)
[[#Reset|00ff - Reset]]

==== Backplate to display ====
0001 - (message from backplate; ASCII)
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
[[#FET presence|0004 - FET presence]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
[[#FET presence|0009 - FET presence]]
000a - (every second; 16-bit data)
[[#Backplate state|000b - Backplate state]]
000c - (16-bit values: pir, px1, px1 divisor, px2, px2 divisor, alir, av)
0010 - (24-bit data)
[[#Backplate firmware upload|0011 - Backplate firmware upload]]
0014 - (16-bit data)
[[#Get TFE version|0018 - Get TFE version (response)]]
[[#Get build info|0019 - Get build info (response)]]
[[#Get BSL version|001b - Get BSL version (response)]]
001c - Response to 009c; always(?) "BSL"
001d - Response to 009d; always(?) bbbb
[[#Get hardware version?|001e - Get hardware version? (response)]]
[[#Get firmware hash?|001f - Get firmware hash? (response)]]
0022 - (every 30 seconds; 4, 8, 20, 28, 36, 56, 60, 54, 68, 72, or 176 byte data)
0023 - (6, 12, 30, 42, 54, 78, 84, 90, 96, 102, 108, 144, or 150 byte data)
0025 - (2, 4, 12, 14, 20, or 24 byte data)
0027 - (8, 16, 48, 56, 80, or 96 byte data)
0029 - (6, 12, 36, 42, 60, or 72 byte data)
002b - (8, 16, 24, 32, 40, 128, or 152 byte data)
002f - (every 30 seconds; 16-bit data; "end of buffers ACK" log msg)

=== Backplate firmware upload ===
At least for uploading the TFE firmware, the following sequence is used:
Send 0091 data=00004d
Recv 0011 data=0000
Send 0092 data=0100...
Recv 0011 data=0100
Send 0092 data=0200...
Recv 0011 data=0200
...
Send 0092 data=a901...
Recv 0011 data=a901
Send 0093 data=aa01
Recv 0011 data=aa01
Following the upload, the [[#Backplate initialisation|backplate initialisation process]] begins immediately (that is, without message 00ff being sent to order a reset).
Presumably the 0011 message is an ACK, and the first 16 bits of each message is the line number.
The format itself appears to be Motorola S-record (SREC).

=== Backplate state ===
Data:
* 8-bit "state"
* 8-bit "flags"
* 8-bit "px0" (may be wider?)
* 40-bit UNKNOWN (includes at least "p2" and "voc")
* 16-bit centi-volts "vi"
* 16-bit milli-volts "vo"
* 16-bit milli-volts "vb"
* 8-bit ("pins" or "wires")
* 8-bit ("wires" or "pins")
* 16-bit UNKNOWN

=== FET control ===
Turn on W1: d5aa96 8200 0200 00 01 29a2
Turn off W1: d5aa96 8200 0200 00 00 08b2
Turn on Y1: d5aa96 8200 0200 01 01 1891
Turn off Y1: d5aa96 8200 0200 01 00 3981
Turn on G : d5aa96 8200 0200 02 01 4bc4
Turn off G : d5aa96 8200 0200 02 00 6ad4
Turn on OB: d5aa96 8200 0200 03 01 7af7
Turn off OB: d5aa96 8200 0200 03 00 5be7
Turn on W2: d5aa96 8200 0200 04 01 ed6e
Turn off W2: d5aa96 8200 0200 04 00 cc7e
Turn on Y2: d5aa96 8200 0200 07 01 be3b
Turn off Y2: d5aa96 8200 0200 07 00 9f2b
Turn on * : d5aa96 8200 0200 0b 01 d37e
Turn off * : d5aa96 8200 0200 0b 00 f26e

For the sake of documentation, we will refer to the unique id numbers for each wire as "wire id numbers".
So wire id 0 is W1, wire id 1 is Y1, wire id B is *, etc.

=== FET presence ===
The backplate will, at least upon connection, send information about which FETs have a wire present.
This data is received with command ids 0004 and 0009, in that order.
Each sensor is represented by one byte which is either 00 (not present) or 01 (present).

The content of 0004 is in order of the "wire id numbers" used for control:
W1, Y1, G, OB, W2, ?0, ?0, Y2, ?1, ?1, ?0, *, ?0

The content of 0009 is arranged differently and has 2 more values:
W1, Y1, ?1, ?1, ?0, G, OB, W2, ?0, Y2, ?0, *, ?0, ?0, ?0

After these are received, the display sends back command 008f with the exact data from message 0004.
Message 008f does not itself receive any response.

=== Get build info ===
Message 0099 (no data) requests the backplate report information about its build.
The response will be message 0019 in ASCII (one line, no trailing newline).

=== Get firmware hash? ===
Message 009f (no data) requests the backplate report a 64-bit hexadecimal value, probably a hash of the firmware (since Nest's software requests it at the same time as version and build info).
The response will be message 001f in uppercase ASCII.

=== Get hardware version? ===
Message 009e (no data) requests the backplate report a "Backplate-"X.Y version string.
Since the firmware file on the display CPU uses these strings as "MinApplicability" and "MaxApplicability" ranges, it is probable they refer to the hardware.

Witnessed versions:
"Backplate-2.8" - Florida Lowes

=== Get BSL version ===
Message 009b (no data) requests the backplate report its BSL version number.
The response will be message 001b in ASCII.

=== Get TFE version ===
Message 0098 (no data) requests the backplate report its TFE version number.
The response will be message 0018 in ASCII.

=== Temperature reading ===
The backplate will send message 0002 every 30 seconds.
The data contains two 16-bit numbers, which nlclient logs in decimal.
The first number is the temperature in centi-celcius.
The second number is the humidity in per-millis.

=== Reset ===
At least upon connection, the display sends message 00ff to the backplate to reset.

The backplate answers with:
0001 msg "<version> <build timestamp "YYYY-MM-DD HH:MM:SS"> K"
[[#FET presence|0004 FET presence]]
[[#FET presence|0009 FET presence]]
0001 msg "*sense 06d1 06d0 0001 0001 0000 0000 0000 0001 06d9 06d8 06d8; detect 09d3 065c"
0001 msg "BRK"

== Run BeagleBone/Debian programs ==
ln -s . /lib/arm-linux-gnueabihf
ln -s ld-2.11.1.so /lib/ld-linux-armhf.so.3

Nest Hacking

2014-07-27T23:57:17Z

Luke-Jr: /* Backplate firmware upload */

== Hardware ==
* TSL2571 Light-to-Digital Converter

== Info ==
* /dev/event1 is the knob; /dev/event2 is the button

== Nest software ==
/nestlabs/sbin/nlclient -config /nestlabs/etc/client.config -config /nestlabs/etc/Display/Display-2/client.config

=== Backplate communications ===
Backplate communications can be decoded from a (filtered) strace log using [http://luke.dashjr.org/programs/freeabode/kindling/NestDecode.pl NestDecode.pl], or decoded (half-duplex for now - only reads) in real time using [http://luke.dashjr.org/programs/freeabode/kindling/nest-intercept.c nest-intercept.c].

nest-intercept.c requires one argument, the thread id reading from the backplate controller.
The easiest way to get this is to strace the nlclient process with -ff and look for a thread reading from fd 54.

=== Backplate firmware ===
Found in /nestlabs/share/bp/data/firmware/nlbpfirmware.plist

There are 6 different firmwares in the file:
* Backplate 2 vs Backplate 3
* TFE (BP_D2 for Bp2, AMBER_BP for Bp3) vs BSL
* For TFE firmwares, hex vs srec (which for some reason DO differ!)

=== Backplate initialisation ===
When the backplate is first connected, the following sequence occurs:
Send [[#Reset|00ff - Reset]]
Recv 0001 - (message from backplate; ASCII)
Recv [[#FET presence|0004 - FET presence]]
Recv [[#FET presence|0009 - FET presence]]
Send [[#FET presence|008f - FET presence]]
Send 0083 - (every 30 seconds; no data; triggers periodic messages 0002, 0007, and 000a; also triggers 0005 to some extent?)
Send 0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
Recv 0001 - (message from backplate; ASCII)
Recv 0001 - (message from backplate; ASCII)
Recv 0010 - (24-bit data)
Send [[#Get TFE version|0098 - Get TFE version]]
Recv 000a - (every second; 16-bit data)
Recv 0007 - (every second; 16-bit data)
Recv [[#Get TFE version|0018 - Get TFE version (response)]]
Send [[#Get build info|0099 - Get build info]]
Recv [[#Get build info|0019 - Get build info (response)]]
Sometimes:
Send 009d - (no data; responds with 001d (constant?) data=bbbb)
Recv 001d - Response to 009d; always(?) bbbb
Sometimes:
Send [[#Get BSL version|009b - Get BSL version]]
Recv [[#Get BSL version|001b - Get BSL version (response)]]
Sometimes:
Send 009c - (no data; responds with 001c (constant?) data="BSL")
Recv 001c - Response to 009c; always(?) "BSL"
Send [[#Get firmware hash?|009f - Get firmware hash?]]
Recv [[#Get firmware hash?|001f - Get firmware hash? (response)]]
Send [[#Get hardware version?|009e - Get hardware version?]]
Recv [[#Get hardware version?|001e - Get hardware version? (response)]]

== Nest backplate interface ==
* Connected on /dev/ttyO2
* All communications with backplate begin with (d5)d5aa96 (d5 is doubled only for data FROM backplate)
* Everything is little endian
* 16-bit command
* 16-bit data length
* <data>
* 16-bit checksum

Monitor:
strace -ff -p $(pidof nlclient) -x -s9999 -e read,write 2>&1 | grep '(54'

=== Checksum ===
<Bytes-from-end>.<bit-value> <xor-with>
00.01 2110 (1021)
00.02 4220 (2042: 1021<<1)
00.04 8440 (4084: 2048<<1)
00.08 0881 (8108: 4084<<1)
00.10 3112 (1231: 8108<<1^1021)
00.20 6224 (2462: 1231<<1)
00.40 c448 (48c4: 2462<<1)
00.80 8891 (9188: 48c4<<1)
01.01 3133 (3313: 9188<<1^1021)
01.02 6266
01.04 c4cc
01.08 a989
01.10 7303
01.20 e606
01.40 cc0d
01.80 981b
02.01 3037
02.02 606e
...
03.01 b476
03.02 68ed
03.04 f1ca
03.08 c385
03.10 a71b
03.20 4e37
03.40 9c6e
03.80 38dd
...
07.20 687b

If you compute the contribution of the individual bit changes in the data you end up with the xor table above; byte offset from the end of the data, bit pattern, xor value. Correcting for little endianess in the output you end up with the hex values in parenthesis. The least significant bit is 0x1021 and each subsequent bit is a shift left, if the XOR value has the 0x8000 bit set then it is XORed with 0x1021. This is the CRC-CCITT polynomial.

8 7 6 5 4 3 2 1 0
d5 aa 96 82 00 02 00 00 00: 08b2
|| |
|| 68ed
|408b
20d4

08b2: 68ed ^ 408b ^ 20d4

Starting at the least significant bit and filling in the XOR values for each bit gives the above diagram; the diagram stops at the 20d4 XOR value because at that point it matches the final CRC. This tells us that the CRC covers the 6 bytes prior.

#!/usr/bin/env perl
use Digest::CRC qw(crc);
my $data = pack("H*", "820002000000");
printf("%04x\n", crc($data,16,0,0,0,0x1021,0,0));

We can also compute the same CRC in Perl; note the result will be byte swapped since the data encodes the number as little endian.

=== Command ids ===

==== Display to backplate ====
[[#FET control|0082 - FET control]]
0083 - (every 30 seconds; no data; triggers periodic messages 0002, 0007, and 000a; also triggers 0005 to some extent?)
[[#FET presence|008f - FET presence]]
0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
[[#Backplate firmware upload|0091 - Backplate firmware upload]]
[[#Backplate firmware upload|0092 - Backplate firmware upload]]
[[#Get TFE version|0098 - Get TFE version]]
[[#Get build info|0099 - Get build info]]
[[#Get BSL version|009b - Get BSL version]]
009c - (no data; responds with 001c (constant?) data="BSL")
009d - (no data; responds with 001d (constant?) data=bbbb)
[[#Get hardware version?|009e - Get hardware version?]]
[[#Get firmware hash?|009f - Get firmware hash?]]
00a1 - (16-bit data)
00a2 - (every 30 seconds; no data)
00a3 - (every 30 seconds; no data)
00a4 - (16-bit data)
00b1 - button pressed/unpressed (no data)
00b3 - (32-bit data; always ffffffff?)
00b5 - (16-bit data; always 0f00?)
00b9 - (32-bit data; always 0000ffff?)
00ba - (48-bit data; always 000000000000?)
00c2 - (48-bit data)
[[#Reset|00ff - Reset]]

==== Backplate to display ====
0001 - (message from backplate; ASCII)
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
[[#FET presence|0004 - FET presence]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
[[#FET presence|0009 - FET presence]]
000a - (every second; 16-bit data)
[[#Backplate state|000b - Backplate state]]
000c - (16-bit values: pir, px1, px1 divisor, px2, px2 divisor, alir, av)
0010 - (24-bit data)
[[#Backplate firmware upload|0011 - Backplate firmware upload]]
0014 - (16-bit data)
[[#Get TFE version|0018 - Get TFE version (response)]]
[[#Get build info|0019 - Get build info (response)]]
[[#Get BSL version|001b - Get BSL version (response)]]
001c - Response to 009c; always(?) "BSL"
001d - Response to 009d; always(?) bbbb
[[#Get hardware version?|001e - Get hardware version? (response)]]
[[#Get firmware hash?|001f - Get firmware hash? (response)]]
0022 - (every 30 seconds; 4, 8, 20, 28, 36, 56, 60, 54, 68, 72, or 176 byte data)
0023 - (6, 12, 30, 42, 54, 78, 84, 90, 96, 102, 108, 144, or 150 byte data)
0025 - (2, 4, 12, 14, 20, or 24 byte data)
0027 - (8, 16, 48, 56, 80, or 96 byte data)
0029 - (6, 12, 36, 42, 60, or 72 byte data)
002b - (8, 16, 24, 32, 40, 128, or 152 byte data)
002f - (every 30 seconds; 16-bit data; "end of buffers ACK" log msg)

=== Backplate firmware upload ===
At least for uploading the TFE firmware, the following sequence is used:
Send 0091 data=00004d
Recv 0011 data=0000
Send 0092 data=0100...
Recv 0011 data=0100
Send 0092 data=0200...
Recv 0011 data=0200
...
Send 0092 data=a901...
Recv 0011 data=a901
Send 0093 data=aa01
Recv 0011 data=aa01
Following the upload, the [[#Backplate initialisation|backplate initialisation process]] begins immediately (that is, without message 00ff being sent to order a reset).
Presumably the 0011 message is an ACK, and the first 16 bits of each message is the line number.
The format itself appears to be Motorola S-record (SREC).

=== Backplate state ===
Data:
* 8-bit "state"
* 8-bit "flags"
* 8-bit "px0" (may be wider?)
* 40-bit UNKNOWN (includes at least "p2" and "voc")
* 16-bit centi-volts "vi"
* 16-bit milli-volts "vo"
* 16-bit milli-volts "vb"
* 8-bit ("pins" or "wires")
* 8-bit ("wires" or "pins")
* 16-bit UNKNOWN

=== FET control ===
Turn on W1: d5aa96 8200 0200 00 01 29a2
Turn off W1: d5aa96 8200 0200 00 00 08b2
Turn on Y1: d5aa96 8200 0200 01 01 1891
Turn off Y1: d5aa96 8200 0200 01 00 3981
Turn on G : d5aa96 8200 0200 02 01 4bc4
Turn off G : d5aa96 8200 0200 02 00 6ad4
Turn on OB: d5aa96 8200 0200 03 01 7af7
Turn off OB: d5aa96 8200 0200 03 00 5be7
Turn on W2: d5aa96 8200 0200 04 01 ed6e
Turn off W2: d5aa96 8200 0200 04 00 cc7e
Turn on Y2: d5aa96 8200 0200 07 01 be3b
Turn off Y2: d5aa96 8200 0200 07 00 9f2b
Turn on * : d5aa96 8200 0200 0b 01 d37e
Turn off * : d5aa96 8200 0200 0b 00 f26e

For the sake of documentation, we will refer to the unique id numbers for each wire as "wire id numbers".
So wire id 0 is W1, wire id 1 is Y1, wire id B is *, etc.

=== FET presence ===
The backplate will, at least upon connection, send information about which FETs have a wire present.
This data is received with command ids 0004 and 0009, in that order.
Each sensor is represented by one byte which is either 00 (not present) or 01 (present).

The content of 0004 is in order of the "wire id numbers" used for control:
W1, Y1, G, OB, W2, ?0, ?0, Y2, ?1, ?1, ?0, *, ?0

The content of 0009 is arranged differently and has 2 more values:
W1, Y1, ?1, ?1, ?0, G, OB, W2, ?0, Y2, ?0, *, ?0, ?0, ?0

After these are received, the display sends back command 008f with the exact data from message 0004.
Message 008f does not itself receive any response.

=== Get build info ===
Message 0099 (no data) requests the backplate report information about its build.
The response will be message 0019 in ASCII (one line, no trailing newline).

=== Get firmware hash? ===
Message 009f (no data) requests the backplate report a 64-bit hexadecimal value, probably a hash of the firmware (since Nest's software requests it at the same time as version and build info).
The response will be message 001f in uppercase ASCII.

=== Get hardware version? ===
Message 009e (no data) requests the backplate report a "Backplate-"X.Y version string.
Since the firmware file on the display CPU uses these strings as "MinApplicability" and "MaxApplicability" ranges, it is probable they refer to the hardware.

Witnessed versions:
"Backplate-2.8" - Florida Lowes

=== Get BSL version ===
Message 009b (no data) requests the backplate report its BSL version number.
The response will be message 001b in ASCII.

=== Get TFE version ===
Message 0098 (no data) requests the backplate report its TFE version number.
The response will be message 0018 in ASCII.

=== Temperature reading ===
The backplate will send message 0002 every 30 seconds.
The data contains two 16-bit numbers, which nlclient logs in decimal.
The first number is the temperature in centi-celcius.
The second number is the humidity in per-millis.

=== Reset ===
At least upon connection, the display sends message 00ff to the backplate to reset.

The backplate answers with:
0001 msg "<version> <build timestamp "YYYY-MM-DD HH:MM:SS"> K"
[[#FET presence|0004 FET presence]]
[[#FET presence|0009 FET presence]]
0001 msg "*sense 06d1 06d0 0001 0001 0000 0000 0000 0001 06d9 06d8 06d8; detect 09d3 065c"
0001 msg "BRK"

== Run BeagleBone/Debian programs ==
ln -s . /lib/arm-linux-gnueabihf
ln -s ld-2.11.1.so /lib/ld-linux-armhf.so.3

Nest Hacking

2014-07-27T23:36:10Z

Luke-Jr: /* Backplate firmware upload */

== Hardware ==
* TSL2571 Light-to-Digital Converter

== Info ==
* /dev/event1 is the knob; /dev/event2 is the button

== Nest software ==
/nestlabs/sbin/nlclient -config /nestlabs/etc/client.config -config /nestlabs/etc/Display/Display-2/client.config

=== Backplate communications ===
Backplate communications can be decoded from a (filtered) strace log using [http://luke.dashjr.org/programs/freeabode/kindling/NestDecode.pl NestDecode.pl], or decoded (half-duplex for now - only reads) in real time using [http://luke.dashjr.org/programs/freeabode/kindling/nest-intercept.c nest-intercept.c].

nest-intercept.c requires one argument, the thread id reading from the backplate controller.
The easiest way to get this is to strace the nlclient process with -ff and look for a thread reading from fd 54.

=== Backplate firmware ===
Found in /nestlabs/share/bp/data/firmware/nlbpfirmware.plist

There are 6 different firmwares in the file:
* Backplate 2 vs Backplate 3
* TFE (BP_D2 for Bp2, AMBER_BP for Bp3) vs BSL
* For TFE firmwares, hex vs srec (which for some reason DO differ!)

=== Backplate initialisation ===
When the backplate is first connected, the following sequence occurs:
Send [[#Reset|00ff - Reset]]
Recv 0001 - (message from backplate; ASCII)
Recv [[#FET presence|0004 - FET presence]]
Recv [[#FET presence|0009 - FET presence]]
Send [[#FET presence|008f - FET presence]]
Send 0083 - (every 30 seconds; no data; triggers periodic messages 0002, 0007, and 000a; also triggers 0005 to some extent?)
Send 0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
Recv 0001 - (message from backplate; ASCII)
Recv 0001 - (message from backplate; ASCII)
Recv 0010 - (24-bit data)
Send [[#Get TFE version|0098 - Get TFE version]]
Recv 000a - (every second; 16-bit data)
Recv 0007 - (every second; 16-bit data)
Recv [[#Get TFE version|0018 - Get TFE version (response)]]
Send [[#Get build info|0099 - Get build info]]
Recv [[#Get build info|0019 - Get build info (response)]]
Sometimes:
Send 009d - (no data; responds with 001d (constant?) data=bbbb)
Recv 001d - Response to 009d; always(?) bbbb
Sometimes:
Send [[#Get BSL version|009b - Get BSL version]]
Recv [[#Get BSL version|001b - Get BSL version (response)]]
Sometimes:
Send 009c - (no data; responds with 001c (constant?) data="BSL")
Recv 001c - Response to 009c; always(?) "BSL"
Send [[#Get firmware hash?|009f - Get firmware hash?]]
Recv [[#Get firmware hash?|001f - Get firmware hash? (response)]]
Send [[#Get hardware version?|009e - Get hardware version?]]
Recv [[#Get hardware version?|001e - Get hardware version? (response)]]

== Nest backplate interface ==
* Connected on /dev/ttyO2
* All communications with backplate begin with (d5)d5aa96 (d5 is doubled only for data FROM backplate)
* Everything is little endian
* 16-bit command
* 16-bit data length
* <data>
* 16-bit checksum

Monitor:
strace -ff -p $(pidof nlclient) -x -s9999 -e read,write 2>&1 | grep '(54'

=== Checksum ===
<Bytes-from-end>.<bit-value> <xor-with>
00.01 2110 (1021)
00.02 4220 (2042: 1021<<1)
00.04 8440 (4084: 2048<<1)
00.08 0881 (8108: 4084<<1)
00.10 3112 (1231: 8108<<1^1021)
00.20 6224 (2462: 1231<<1)
00.40 c448 (48c4: 2462<<1)
00.80 8891 (9188: 48c4<<1)
01.01 3133 (3313: 9188<<1^1021)
01.02 6266
01.04 c4cc
01.08 a989
01.10 7303
01.20 e606
01.40 cc0d
01.80 981b
02.01 3037
02.02 606e
...
03.01 b476
03.02 68ed
03.04 f1ca
03.08 c385
03.10 a71b
03.20 4e37
03.40 9c6e
03.80 38dd
...
07.20 687b

If you compute the contribution of the individual bit changes in the data you end up with the xor table above; byte offset from the end of the data, bit pattern, xor value. Correcting for little endianess in the output you end up with the hex values in parenthesis. The least significant bit is 0x1021 and each subsequent bit is a shift left, if the XOR value has the 0x8000 bit set then it is XORed with 0x1021. This is the CRC-CCITT polynomial.

8 7 6 5 4 3 2 1 0
d5 aa 96 82 00 02 00 00 00: 08b2
|| |
|| 68ed
|408b
20d4

08b2: 68ed ^ 408b ^ 20d4

Starting at the least significant bit and filling in the XOR values for each bit gives the above diagram; the diagram stops at the 20d4 XOR value because at that point it matches the final CRC. This tells us that the CRC covers the 6 bytes prior.

#!/usr/bin/env perl
use Digest::CRC qw(crc);
my $data = pack("H*", "820002000000");
printf("%04x\n", crc($data,16,0,0,0,0x1021,0,0));

We can also compute the same CRC in Perl; note the result will be byte swapped since the data encodes the number as little endian.

=== Command ids ===

==== Display to backplate ====
[[#FET control|0082 - FET control]]
0083 - (every 30 seconds; no data; triggers periodic messages 0002, 0007, and 000a; also triggers 0005 to some extent?)
[[#FET presence|008f - FET presence]]
0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
[[#Backplate firmware upload|0091 - Backplate firmware upload]]
[[#Backplate firmware upload|0092 - Backplate firmware upload]]
[[#Get TFE version|0098 - Get TFE version]]
[[#Get build info|0099 - Get build info]]
[[#Get BSL version|009b - Get BSL version]]
009c - (no data; responds with 001c (constant?) data="BSL")
009d - (no data; responds with 001d (constant?) data=bbbb)
[[#Get hardware version?|009e - Get hardware version?]]
[[#Get firmware hash?|009f - Get firmware hash?]]
00a1 - (16-bit data)
00a2 - (every 30 seconds; no data)
00a3 - (every 30 seconds; no data)
00a4 - (16-bit data)
00b1 - button pressed/unpressed (no data)
00b3 - (32-bit data; always ffffffff?)
00b5 - (16-bit data; always 0f00?)
00b9 - (32-bit data; always 0000ffff?)
00ba - (48-bit data; always 000000000000?)
00c2 - (48-bit data)
[[#Reset|00ff - Reset]]

==== Backplate to display ====
0001 - (message from backplate; ASCII)
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
[[#FET presence|0004 - FET presence]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
[[#FET presence|0009 - FET presence]]
000a - (every second; 16-bit data)
[[#Backplate state|000b - Backplate state]]
000c - (16-bit values: pir, px1, px1 divisor, px2, px2 divisor, alir, av)
0010 - (24-bit data)
[[#Backplate firmware upload|0011 - Backplate firmware upload]]
0014 - (16-bit data)
[[#Get TFE version|0018 - Get TFE version (response)]]
[[#Get build info|0019 - Get build info (response)]]
[[#Get BSL version|001b - Get BSL version (response)]]
001c - Response to 009c; always(?) "BSL"
001d - Response to 009d; always(?) bbbb
[[#Get hardware version?|001e - Get hardware version? (response)]]
[[#Get firmware hash?|001f - Get firmware hash? (response)]]
0022 - (every 30 seconds; 4, 8, 20, 28, 36, 56, 60, 54, 68, 72, or 176 byte data)
0023 - (6, 12, 30, 42, 54, 78, 84, 90, 96, 102, 108, 144, or 150 byte data)
0025 - (2, 4, 12, 14, 20, or 24 byte data)
0027 - (8, 16, 48, 56, 80, or 96 byte data)
0029 - (6, 12, 36, 42, 60, or 72 byte data)
002b - (8, 16, 24, 32, 40, 128, or 152 byte data)
002f - (every 30 seconds; 16-bit data; "end of buffers ACK" log msg)

=== Backplate firmware upload ===
At least for uploading the TFE firmware, the following sequence is used:
Send 0091 data=00004d
Recv 0011 data=0000
Send 0092 data=0100...
Recv 0011 data=0100
Send 0092 data=0200...
Recv 0011 data=0200
...
(UNKNOWN)
Presumably the 0011 message is an ACK, and the first 16 bits of each message is the line number.
The format itself appears to be Motorola S-record (SREC).

=== Backplate state ===
Data:
* 8-bit "state"
* 8-bit "flags"
* 8-bit "px0" (may be wider?)
* 40-bit UNKNOWN (includes at least "p2" and "voc")
* 16-bit centi-volts "vi"
* 16-bit milli-volts "vo"
* 16-bit milli-volts "vb"
* 8-bit ("pins" or "wires")
* 8-bit ("wires" or "pins")
* 16-bit UNKNOWN

=== FET control ===
Turn on W1: d5aa96 8200 0200 00 01 29a2
Turn off W1: d5aa96 8200 0200 00 00 08b2
Turn on Y1: d5aa96 8200 0200 01 01 1891
Turn off Y1: d5aa96 8200 0200 01 00 3981
Turn on G : d5aa96 8200 0200 02 01 4bc4
Turn off G : d5aa96 8200 0200 02 00 6ad4
Turn on OB: d5aa96 8200 0200 03 01 7af7
Turn off OB: d5aa96 8200 0200 03 00 5be7
Turn on W2: d5aa96 8200 0200 04 01 ed6e
Turn off W2: d5aa96 8200 0200 04 00 cc7e
Turn on Y2: d5aa96 8200 0200 07 01 be3b
Turn off Y2: d5aa96 8200 0200 07 00 9f2b
Turn on * : d5aa96 8200 0200 0b 01 d37e
Turn off * : d5aa96 8200 0200 0b 00 f26e

For the sake of documentation, we will refer to the unique id numbers for each wire as "wire id numbers".
So wire id 0 is W1, wire id 1 is Y1, wire id B is *, etc.

=== FET presence ===
The backplate will, at least upon connection, send information about which FETs have a wire present.
This data is received with command ids 0004 and 0009, in that order.
Each sensor is represented by one byte which is either 00 (not present) or 01 (present).

The content of 0004 is in order of the "wire id numbers" used for control:
W1, Y1, G, OB, W2, ?0, ?0, Y2, ?1, ?1, ?0, *, ?0

The content of 0009 is arranged differently and has 2 more values:
W1, Y1, ?1, ?1, ?0, G, OB, W2, ?0, Y2, ?0, *, ?0, ?0, ?0

After these are received, the display sends back command 008f with the exact data from message 0004.
Message 008f does not itself receive any response.

=== Get build info ===
Message 0099 (no data) requests the backplate report information about its build.
The response will be message 0019 in ASCII (one line, no trailing newline).

=== Get firmware hash? ===
Message 009f (no data) requests the backplate report a 64-bit hexadecimal value, probably a hash of the firmware (since Nest's software requests it at the same time as version and build info).
The response will be message 001f in uppercase ASCII.

=== Get hardware version? ===
Message 009e (no data) requests the backplate report a "Backplate-"X.Y version string.
Since the firmware file on the display CPU uses these strings as "MinApplicability" and "MaxApplicability" ranges, it is probable they refer to the hardware.

Witnessed versions:
"Backplate-2.8" - Florida Lowes

=== Get BSL version ===
Message 009b (no data) requests the backplate report its BSL version number.
The response will be message 001b in ASCII.

=== Get TFE version ===
Message 0098 (no data) requests the backplate report its TFE version number.
The response will be message 0018 in ASCII.

=== Temperature reading ===
The backplate will send message 0002 every 30 seconds.
The data contains two 16-bit numbers, which nlclient logs in decimal.
The first number is the temperature in centi-celcius.
The second number is the humidity in per-millis.

=== Reset ===
At least upon connection, the display sends message 00ff to the backplate to reset.

The backplate answers with:
0001 msg "<version> <build timestamp "YYYY-MM-DD HH:MM:SS"> K"
[[#FET presence|0004 FET presence]]
[[#FET presence|0009 FET presence]]
0001 msg "*sense 06d1 06d0 0001 0001 0000 0000 0000 0001 06d9 06d8 06d8; detect 09d3 065c"
0001 msg "BRK"

== Run BeagleBone/Debian programs ==
ln -s . /lib/arm-linux-gnueabihf
ln -s ld-2.11.1.so /lib/ld-linux-armhf.so.3

Nest Hacking

2014-07-27T23:31:25Z

Luke-Jr: /* Command ids */ Backplate firmware upload

== Hardware ==
* TSL2571 Light-to-Digital Converter

== Info ==
* /dev/event1 is the knob; /dev/event2 is the button

== Nest software ==
/nestlabs/sbin/nlclient -config /nestlabs/etc/client.config -config /nestlabs/etc/Display/Display-2/client.config

=== Backplate communications ===
Backplate communications can be decoded from a (filtered) strace log using [http://luke.dashjr.org/programs/freeabode/kindling/NestDecode.pl NestDecode.pl], or decoded (half-duplex for now - only reads) in real time using [http://luke.dashjr.org/programs/freeabode/kindling/nest-intercept.c nest-intercept.c].

nest-intercept.c requires one argument, the thread id reading from the backplate controller.
The easiest way to get this is to strace the nlclient process with -ff and look for a thread reading from fd 54.

=== Backplate firmware ===
Found in /nestlabs/share/bp/data/firmware/nlbpfirmware.plist

There are 6 different firmwares in the file:
* Backplate 2 vs Backplate 3
* TFE (BP_D2 for Bp2, AMBER_BP for Bp3) vs BSL
* For TFE firmwares, hex vs srec (which for some reason DO differ!)

=== Backplate initialisation ===
When the backplate is first connected, the following sequence occurs:
Send [[#Reset|00ff - Reset]]
Recv 0001 - (message from backplate; ASCII)
Recv [[#FET presence|0004 - FET presence]]
Recv [[#FET presence|0009 - FET presence]]
Send [[#FET presence|008f - FET presence]]
Send 0083 - (every 30 seconds; no data; triggers periodic messages 0002, 0007, and 000a; also triggers 0005 to some extent?)
Send 0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
Recv 0001 - (message from backplate; ASCII)
Recv 0001 - (message from backplate; ASCII)
Recv 0010 - (24-bit data)
Send [[#Get TFE version|0098 - Get TFE version]]
Recv 000a - (every second; 16-bit data)
Recv 0007 - (every second; 16-bit data)
Recv [[#Get TFE version|0018 - Get TFE version (response)]]
Send [[#Get build info|0099 - Get build info]]
Recv [[#Get build info|0019 - Get build info (response)]]
Sometimes:
Send 009d - (no data; responds with 001d (constant?) data=bbbb)
Recv 001d - Response to 009d; always(?) bbbb
Sometimes:
Send [[#Get BSL version|009b - Get BSL version]]
Recv [[#Get BSL version|001b - Get BSL version (response)]]
Sometimes:
Send 009c - (no data; responds with 001c (constant?) data="BSL")
Recv 001c - Response to 009c; always(?) "BSL"
Send [[#Get firmware hash?|009f - Get firmware hash?]]
Recv [[#Get firmware hash?|001f - Get firmware hash? (response)]]
Send [[#Get hardware version?|009e - Get hardware version?]]
Recv [[#Get hardware version?|001e - Get hardware version? (response)]]

== Nest backplate interface ==
* Connected on /dev/ttyO2
* All communications with backplate begin with (d5)d5aa96 (d5 is doubled only for data FROM backplate)
* Everything is little endian
* 16-bit command
* 16-bit data length
* <data>
* 16-bit checksum

Monitor:
strace -ff -p $(pidof nlclient) -x -s9999 -e read,write 2>&1 | grep '(54'

=== Checksum ===
<Bytes-from-end>.<bit-value> <xor-with>
00.01 2110 (1021)
00.02 4220 (2042: 1021<<1)
00.04 8440 (4084: 2048<<1)
00.08 0881 (8108: 4084<<1)
00.10 3112 (1231: 8108<<1^1021)
00.20 6224 (2462: 1231<<1)
00.40 c448 (48c4: 2462<<1)
00.80 8891 (9188: 48c4<<1)
01.01 3133 (3313: 9188<<1^1021)
01.02 6266
01.04 c4cc
01.08 a989
01.10 7303
01.20 e606
01.40 cc0d
01.80 981b
02.01 3037
02.02 606e
...
03.01 b476
03.02 68ed
03.04 f1ca
03.08 c385
03.10 a71b
03.20 4e37
03.40 9c6e
03.80 38dd
...
07.20 687b

If you compute the contribution of the individual bit changes in the data you end up with the xor table above; byte offset from the end of the data, bit pattern, xor value. Correcting for little endianess in the output you end up with the hex values in parenthesis. The least significant bit is 0x1021 and each subsequent bit is a shift left, if the XOR value has the 0x8000 bit set then it is XORed with 0x1021. This is the CRC-CCITT polynomial.

8 7 6 5 4 3 2 1 0
d5 aa 96 82 00 02 00 00 00: 08b2
|| |
|| 68ed
|408b
20d4

08b2: 68ed ^ 408b ^ 20d4

Starting at the least significant bit and filling in the XOR values for each bit gives the above diagram; the diagram stops at the 20d4 XOR value because at that point it matches the final CRC. This tells us that the CRC covers the 6 bytes prior.

#!/usr/bin/env perl
use Digest::CRC qw(crc);
my $data = pack("H*", "820002000000");
printf("%04x\n", crc($data,16,0,0,0,0x1021,0,0));

We can also compute the same CRC in Perl; note the result will be byte swapped since the data encodes the number as little endian.

=== Command ids ===

==== Display to backplate ====
[[#FET control|0082 - FET control]]
0083 - (every 30 seconds; no data; triggers periodic messages 0002, 0007, and 000a; also triggers 0005 to some extent?)
[[#FET presence|008f - FET presence]]
0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
[[#Backplate firmware upload|0091 - Backplate firmware upload]]
[[#Backplate firmware upload|0092 - Backplate firmware upload]]
[[#Get TFE version|0098 - Get TFE version]]
[[#Get build info|0099 - Get build info]]
[[#Get BSL version|009b - Get BSL version]]
009c - (no data; responds with 001c (constant?) data="BSL")
009d - (no data; responds with 001d (constant?) data=bbbb)
[[#Get hardware version?|009e - Get hardware version?]]
[[#Get firmware hash?|009f - Get firmware hash?]]
00a1 - (16-bit data)
00a2 - (every 30 seconds; no data)
00a3 - (every 30 seconds; no data)
00a4 - (16-bit data)
00b1 - button pressed/unpressed (no data)
00b3 - (32-bit data; always ffffffff?)
00b5 - (16-bit data; always 0f00?)
00b9 - (32-bit data; always 0000ffff?)
00ba - (48-bit data; always 000000000000?)
00c2 - (48-bit data)
[[#Reset|00ff - Reset]]

==== Backplate to display ====
0001 - (message from backplate; ASCII)
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
[[#FET presence|0004 - FET presence]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
[[#FET presence|0009 - FET presence]]
000a - (every second; 16-bit data)
[[#Backplate state|000b - Backplate state]]
000c - (16-bit values: pir, px1, px1 divisor, px2, px2 divisor, alir, av)
0010 - (24-bit data)
[[#Backplate firmware upload|0011 - Backplate firmware upload]]
0014 - (16-bit data)
[[#Get TFE version|0018 - Get TFE version (response)]]
[[#Get build info|0019 - Get build info (response)]]
[[#Get BSL version|001b - Get BSL version (response)]]
001c - Response to 009c; always(?) "BSL"
001d - Response to 009d; always(?) bbbb
[[#Get hardware version?|001e - Get hardware version? (response)]]
[[#Get firmware hash?|001f - Get firmware hash? (response)]]
0022 - (every 30 seconds; 4, 8, 20, 28, 36, 56, 60, 54, 68, 72, or 176 byte data)
0023 - (6, 12, 30, 42, 54, 78, 84, 90, 96, 102, 108, 144, or 150 byte data)
0025 - (2, 4, 12, 14, 20, or 24 byte data)
0027 - (8, 16, 48, 56, 80, or 96 byte data)
0029 - (6, 12, 36, 42, 60, or 72 byte data)
002b - (8, 16, 24, 32, 40, 128, or 152 byte data)
002f - (every 30 seconds; 16-bit data; "end of buffers ACK" log msg)

=== Backplate state ===
Data:
* 8-bit "state"
* 8-bit "flags"
* 8-bit "px0" (may be wider?)
* 40-bit UNKNOWN (includes at least "p2" and "voc")
* 16-bit centi-volts "vi"
* 16-bit milli-volts "vo"
* 16-bit milli-volts "vb"
* 8-bit ("pins" or "wires")
* 8-bit ("wires" or "pins")
* 16-bit UNKNOWN

=== FET control ===
Turn on W1: d5aa96 8200 0200 00 01 29a2
Turn off W1: d5aa96 8200 0200 00 00 08b2
Turn on Y1: d5aa96 8200 0200 01 01 1891
Turn off Y1: d5aa96 8200 0200 01 00 3981
Turn on G : d5aa96 8200 0200 02 01 4bc4
Turn off G : d5aa96 8200 0200 02 00 6ad4
Turn on OB: d5aa96 8200 0200 03 01 7af7
Turn off OB: d5aa96 8200 0200 03 00 5be7
Turn on W2: d5aa96 8200 0200 04 01 ed6e
Turn off W2: d5aa96 8200 0200 04 00 cc7e
Turn on Y2: d5aa96 8200 0200 07 01 be3b
Turn off Y2: d5aa96 8200 0200 07 00 9f2b
Turn on * : d5aa96 8200 0200 0b 01 d37e
Turn off * : d5aa96 8200 0200 0b 00 f26e

For the sake of documentation, we will refer to the unique id numbers for each wire as "wire id numbers".
So wire id 0 is W1, wire id 1 is Y1, wire id B is *, etc.

=== FET presence ===
The backplate will, at least upon connection, send information about which FETs have a wire present.
This data is received with command ids 0004 and 0009, in that order.
Each sensor is represented by one byte which is either 00 (not present) or 01 (present).

The content of 0004 is in order of the "wire id numbers" used for control:
W1, Y1, G, OB, W2, ?0, ?0, Y2, ?1, ?1, ?0, *, ?0

The content of 0009 is arranged differently and has 2 more values:
W1, Y1, ?1, ?1, ?0, G, OB, W2, ?0, Y2, ?0, *, ?0, ?0, ?0

After these are received, the display sends back command 008f with the exact data from message 0004.
Message 008f does not itself receive any response.

=== Get build info ===
Message 0099 (no data) requests the backplate report information about its build.
The response will be message 0019 in ASCII (one line, no trailing newline).

=== Get firmware hash? ===
Message 009f (no data) requests the backplate report a 64-bit hexadecimal value, probably a hash of the firmware (since Nest's software requests it at the same time as version and build info).
The response will be message 001f in uppercase ASCII.

=== Get hardware version? ===
Message 009e (no data) requests the backplate report a "Backplate-"X.Y version string.
Since the firmware file on the display CPU uses these strings as "MinApplicability" and "MaxApplicability" ranges, it is probable they refer to the hardware.

Witnessed versions:
"Backplate-2.8" - Florida Lowes

=== Get BSL version ===
Message 009b (no data) requests the backplate report its BSL version number.
The response will be message 001b in ASCII.

=== Get TFE version ===
Message 0098 (no data) requests the backplate report its TFE version number.
The response will be message 0018 in ASCII.

=== Temperature reading ===
The backplate will send message 0002 every 30 seconds.
The data contains two 16-bit numbers, which nlclient logs in decimal.
The first number is the temperature in centi-celcius.
The second number is the humidity in per-millis.

=== Reset ===
At least upon connection, the display sends message 00ff to the backplate to reset.

The backplate answers with:
0001 msg "<version> <build timestamp "YYYY-MM-DD HH:MM:SS"> K"
[[#FET presence|0004 FET presence]]
[[#FET presence|0009 FET presence]]
0001 msg "*sense 06d1 06d0 0001 0001 0000 0000 0000 0001 06d9 06d8 06d8; detect 09d3 065c"
0001 msg "BRK"

== Run BeagleBone/Debian programs ==
ln -s . /lib/arm-linux-gnueabihf
ln -s ld-2.11.1.so /lib/ld-linux-armhf.so.3

Nest Hacking

2014-07-27T22:07:09Z

Luke-Jr: /* Backplate firmware */

== Hardware ==
* TSL2571 Light-to-Digital Converter

== Info ==
* /dev/event1 is the knob; /dev/event2 is the button

== Nest software ==
/nestlabs/sbin/nlclient -config /nestlabs/etc/client.config -config /nestlabs/etc/Display/Display-2/client.config

=== Backplate communications ===
Backplate communications can be decoded from a (filtered) strace log using [http://luke.dashjr.org/programs/freeabode/kindling/NestDecode.pl NestDecode.pl], or decoded (half-duplex for now - only reads) in real time using [http://luke.dashjr.org/programs/freeabode/kindling/nest-intercept.c nest-intercept.c].

nest-intercept.c requires one argument, the thread id reading from the backplate controller.
The easiest way to get this is to strace the nlclient process with -ff and look for a thread reading from fd 54.

=== Backplate firmware ===
Found in /nestlabs/share/bp/data/firmware/nlbpfirmware.plist

There are 6 different firmwares in the file:
* Backplate 2 vs Backplate 3
* TFE (BP_D2 for Bp2, AMBER_BP for Bp3) vs BSL
* For TFE firmwares, hex vs srec (which for some reason DO differ!)

=== Backplate initialisation ===
When the backplate is first connected, the following sequence occurs:
Send [[#Reset|00ff - Reset]]
Recv 0001 - (message from backplate; ASCII)
Recv [[#FET presence|0004 - FET presence]]
Recv [[#FET presence|0009 - FET presence]]
Send [[#FET presence|008f - FET presence]]
Send 0083 - (every 30 seconds; no data; triggers periodic messages 0002, 0007, and 000a; also triggers 0005 to some extent?)
Send 0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
Recv 0001 - (message from backplate; ASCII)
Recv 0001 - (message from backplate; ASCII)
Recv 0010 - (24-bit data)
Send [[#Get TFE version|0098 - Get TFE version]]
Recv 000a - (every second; 16-bit data)
Recv 0007 - (every second; 16-bit data)
Recv [[#Get TFE version|0018 - Get TFE version (response)]]
Send [[#Get build info|0099 - Get build info]]
Recv [[#Get build info|0019 - Get build info (response)]]
Sometimes:
Send 009d - (no data; responds with 001d (constant?) data=bbbb)
Recv 001d - Response to 009d; always(?) bbbb
Sometimes:
Send [[#Get BSL version|009b - Get BSL version]]
Recv [[#Get BSL version|001b - Get BSL version (response)]]
Sometimes:
Send 009c - (no data; responds with 001c (constant?) data="BSL")
Recv 001c - Response to 009c; always(?) "BSL"
Send [[#Get firmware hash?|009f - Get firmware hash?]]
Recv [[#Get firmware hash?|001f - Get firmware hash? (response)]]
Send [[#Get hardware version?|009e - Get hardware version?]]
Recv [[#Get hardware version?|001e - Get hardware version? (response)]]

== Nest backplate interface ==
* Connected on /dev/ttyO2
* All communications with backplate begin with (d5)d5aa96 (d5 is doubled only for data FROM backplate)
* Everything is little endian
* 16-bit command
* 16-bit data length
* <data>
* 16-bit checksum

Monitor:
strace -ff -p $(pidof nlclient) -x -s9999 -e read,write 2>&1 | grep '(54'

=== Checksum ===
<Bytes-from-end>.<bit-value> <xor-with>
00.01 2110 (1021)
00.02 4220 (2042: 1021<<1)
00.04 8440 (4084: 2048<<1)
00.08 0881 (8108: 4084<<1)
00.10 3112 (1231: 8108<<1^1021)
00.20 6224 (2462: 1231<<1)
00.40 c448 (48c4: 2462<<1)
00.80 8891 (9188: 48c4<<1)
01.01 3133 (3313: 9188<<1^1021)
01.02 6266
01.04 c4cc
01.08 a989
01.10 7303
01.20 e606
01.40 cc0d
01.80 981b
02.01 3037
02.02 606e
...
03.01 b476
03.02 68ed
03.04 f1ca
03.08 c385
03.10 a71b
03.20 4e37
03.40 9c6e
03.80 38dd
...
07.20 687b

If you compute the contribution of the individual bit changes in the data you end up with the xor table above; byte offset from the end of the data, bit pattern, xor value. Correcting for little endianess in the output you end up with the hex values in parenthesis. The least significant bit is 0x1021 and each subsequent bit is a shift left, if the XOR value has the 0x8000 bit set then it is XORed with 0x1021. This is the CRC-CCITT polynomial.

8 7 6 5 4 3 2 1 0
d5 aa 96 82 00 02 00 00 00: 08b2
|| |
|| 68ed
|408b
20d4

08b2: 68ed ^ 408b ^ 20d4

Starting at the least significant bit and filling in the XOR values for each bit gives the above diagram; the diagram stops at the 20d4 XOR value because at that point it matches the final CRC. This tells us that the CRC covers the 6 bytes prior.

#!/usr/bin/env perl
use Digest::CRC qw(crc);
my $data = pack("H*", "820002000000");
printf("%04x\n", crc($data,16,0,0,0,0x1021,0,0));

We can also compute the same CRC in Perl; note the result will be byte swapped since the data encodes the number as little endian.

=== Command ids ===

==== Display to backplate ====
[[#FET control|0082 - FET control]]
0083 - (every 30 seconds; no data; triggers periodic messages 0002, 0007, and 000a; also triggers 0005 to some extent?)
[[#FET presence|008f - FET presence]]
0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
[[#Get TFE version|0098 - Get TFE version]]
[[#Get build info|0099 - Get build info]]
[[#Get BSL version|009b - Get BSL version]]
009c - (no data; responds with 001c (constant?) data="BSL")
009d - (no data; responds with 001d (constant?) data=bbbb)
[[#Get hardware version?|009e - Get hardware version?]]
[[#Get firmware hash?|009f - Get firmware hash?]]
00a1 - (16-bit data)
00a2 - (every 30 seconds; no data)
00a3 - (every 30 seconds; no data)
00a4 - (16-bit data)
00b1 - button pressed/unpressed (no data)
00b3 - (32-bit data; always ffffffff?)
00b5 - (16-bit data; always 0f00?)
00b9 - (32-bit data; always 0000ffff?)
00ba - (48-bit data; always 000000000000?)
00c2 - (48-bit data)
[[#Reset|00ff - Reset]]

==== Backplate to display ====
0001 - (message from backplate; ASCII)
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
[[#FET presence|0004 - FET presence]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
[[#FET presence|0009 - FET presence]]
000a - (every second; 16-bit data)
[[#Backplate state|000b - Backplate state]]
000c - (16-bit values: pir, px1, px1 divisor, px2, px2 divisor, alir, av)
0010 - (24-bit data)
0014 - (16-bit data)
[[#Get TFE version|0018 - Get TFE version (response)]]
[[#Get build info|0019 - Get build info (response)]]
[[#Get BSL version|001b - Get BSL version (response)]]
001c - Response to 009c; always(?) "BSL"
001d - Response to 009d; always(?) bbbb
[[#Get hardware version?|001e - Get hardware version? (response)]]
[[#Get firmware hash?|001f - Get firmware hash? (response)]]
0022 - (every 30 seconds; 4, 8, 20, 28, 36, 56, 60, 54, 68, 72, or 176 byte data)
0023 - (6, 12, 30, 42, 54, 78, 84, 90, 96, 102, 108, 144, or 150 byte data)
0025 - (2, 4, 12, 14, 20, or 24 byte data)
0027 - (8, 16, 48, 56, 80, or 96 byte data)
0029 - (6, 12, 36, 42, 60, or 72 byte data)
002b - (8, 16, 24, 32, 40, 128, or 152 byte data)
002f - (every 30 seconds; 16-bit data; "end of buffers ACK" log msg)

=== Backplate state ===
Data:
* 8-bit "state"
* 8-bit "flags"
* 8-bit "px0" (may be wider?)
* 40-bit UNKNOWN (includes at least "p2" and "voc")
* 16-bit centi-volts "vi"
* 16-bit milli-volts "vo"
* 16-bit milli-volts "vb"
* 8-bit ("pins" or "wires")
* 8-bit ("wires" or "pins")
* 16-bit UNKNOWN

=== FET control ===
Turn on W1: d5aa96 8200 0200 00 01 29a2
Turn off W1: d5aa96 8200 0200 00 00 08b2
Turn on Y1: d5aa96 8200 0200 01 01 1891
Turn off Y1: d5aa96 8200 0200 01 00 3981
Turn on G : d5aa96 8200 0200 02 01 4bc4
Turn off G : d5aa96 8200 0200 02 00 6ad4
Turn on OB: d5aa96 8200 0200 03 01 7af7
Turn off OB: d5aa96 8200 0200 03 00 5be7
Turn on W2: d5aa96 8200 0200 04 01 ed6e
Turn off W2: d5aa96 8200 0200 04 00 cc7e
Turn on Y2: d5aa96 8200 0200 07 01 be3b
Turn off Y2: d5aa96 8200 0200 07 00 9f2b
Turn on * : d5aa96 8200 0200 0b 01 d37e
Turn off * : d5aa96 8200 0200 0b 00 f26e

For the sake of documentation, we will refer to the unique id numbers for each wire as "wire id numbers".
So wire id 0 is W1, wire id 1 is Y1, wire id B is *, etc.

=== FET presence ===
The backplate will, at least upon connection, send information about which FETs have a wire present.
This data is received with command ids 0004 and 0009, in that order.
Each sensor is represented by one byte which is either 00 (not present) or 01 (present).

The content of 0004 is in order of the "wire id numbers" used for control:
W1, Y1, G, OB, W2, ?0, ?0, Y2, ?1, ?1, ?0, *, ?0

The content of 0009 is arranged differently and has 2 more values:
W1, Y1, ?1, ?1, ?0, G, OB, W2, ?0, Y2, ?0, *, ?0, ?0, ?0

After these are received, the display sends back command 008f with the exact data from message 0004.
Message 008f does not itself receive any response.

=== Get build info ===
Message 0099 (no data) requests the backplate report information about its build.
The response will be message 0019 in ASCII (one line, no trailing newline).

=== Get firmware hash? ===
Message 009f (no data) requests the backplate report a 64-bit hexadecimal value, probably a hash of the firmware (since Nest's software requests it at the same time as version and build info).
The response will be message 001f in uppercase ASCII.

=== Get hardware version? ===
Message 009e (no data) requests the backplate report a "Backplate-"X.Y version string.
Since the firmware file on the display CPU uses these strings as "MinApplicability" and "MaxApplicability" ranges, it is probable they refer to the hardware.

Witnessed versions:
"Backplate-2.8" - Florida Lowes

=== Get BSL version ===
Message 009b (no data) requests the backplate report its BSL version number.
The response will be message 001b in ASCII.

=== Get TFE version ===
Message 0098 (no data) requests the backplate report its TFE version number.
The response will be message 0018 in ASCII.

=== Temperature reading ===
The backplate will send message 0002 every 30 seconds.
The data contains two 16-bit numbers, which nlclient logs in decimal.
The first number is the temperature in centi-celcius.
The second number is the humidity in per-millis.

=== Reset ===
At least upon connection, the display sends message 00ff to the backplate to reset.

The backplate answers with:
0001 msg "<version> <build timestamp "YYYY-MM-DD HH:MM:SS"> K"
[[#FET presence|0004 FET presence]]
[[#FET presence|0009 FET presence]]
0001 msg "*sense 06d1 06d0 0001 0001 0000 0000 0000 0001 06d9 06d8 06d8; detect 09d3 065c"
0001 msg "BRK"

== Run BeagleBone/Debian programs ==
ln -s . /lib/arm-linux-gnueabihf
ln -s ld-2.11.1.so /lib/ld-linux-armhf.so.3

Nest Hacking

2014-07-27T04:53:44Z

Luke-Jr: 00ff does a reset

== Hardware ==
* TSL2571 Light-to-Digital Converter

== Info ==
* /dev/event1 is the knob; /dev/event2 is the button

== Nest software ==
/nestlabs/sbin/nlclient -config /nestlabs/etc/client.config -config /nestlabs/etc/Display/Display-2/client.config

=== Backplate firmware ===
Found in /nestlabs/share/bp/data/firmware/nlbpfirmware.plist

There are 6 different firmwares in the file:
* Backplate 2 vs Backplate 3
* TFE (BP_D2 for Bp2, AMBER_BP for Bp3) vs BSL
* For TFE firmwares, hex vs srec (which for some reason DO differ!)

=== Backplate initialisation ===
When the backplate is first connected, the following sequence occurs:
Send [[#Reset|00ff - Reset]]
Recv 0001 - (message from backplate; ASCII)
Recv [[#FET presence|0004 - FET presence]]
Recv [[#FET presence|0009 - FET presence]]
Send [[#FET presence|008f - FET presence]]
Send 0083 - (every 30 seconds; no data; triggers periodic messages 0002, 0007, and 000a; also triggers 0005 to some extent?)
Send 0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
Recv 0001 - (message from backplate; ASCII)
Recv 0001 - (message from backplate; ASCII)
Recv 0010 - (24-bit data)
Send [[#Get TFE version|0098 - Get TFE version]]
Recv 000a - (every second; 16-bit data)
Recv 0007 - (every second; 16-bit data)
Recv [[#Get TFE version|0018 - Get TFE version (response)]]
Send [[#Get build info|0099 - Get build info]]
Recv [[#Get build info|0019 - Get build info (response)]]
Sometimes:
Send 009d - (no data; responds with 001d (constant?) data=bbbb)
Recv 001d - Response to 009d; always(?) bbbb
Sometimes:
Send [[#Get BSL version|009b - Get BSL version]]
Recv [[#Get BSL version|001b - Get BSL version (response)]]
Sometimes:
Send 009c - (no data; responds with 001c (constant?) data="BSL")
Recv 001c - Response to 009c; always(?) "BSL"
Send [[#Get firmware hash?|009f - Get firmware hash?]]
Recv [[#Get firmware hash?|001f - Get firmware hash? (response)]]
Send [[#Get hardware version?|009e - Get hardware version?]]
Recv [[#Get hardware version?|001e - Get hardware version? (response)]]

== Nest backplate interface ==
* Connected on /dev/ttyO2
* All communications with backplate begin with (d5)d5aa96 (d5 is doubled only for data FROM backplate)
* Everything is little endian
* 16-bit command
* 16-bit data length
* <data>
* 16-bit checksum

Monitor:
strace -ff -p $(pidof nlclient) -x -s9999 -e read,write 2>&1 | grep '(54'

=== Checksum ===
<Bytes-from-end>.<bit-value> <xor-with>
00.01 2110 (1021)
00.02 4220 (2042: 1021<<1)
00.04 8440 (4084: 2048<<1)
00.08 0881 (8108: 4084<<1)
00.10 3112 (1231: 8108<<1^1021)
00.20 6224 (2462: 1231<<1)
00.40 c448 (48c4: 2462<<1)
00.80 8891 (9188: 48c4<<1)
01.01 3133 (3313: 9188<<1^1021)
01.02 6266
01.04 c4cc
01.08 a989
01.10 7303
01.20 e606
01.40 cc0d
01.80 981b
02.01 3037
02.02 606e
...
03.01 b476
03.02 68ed
03.04 f1ca
03.08 c385
03.10 a71b
03.20 4e37
03.40 9c6e
03.80 38dd
...
07.20 687b

If you compute the contribution of the individual bit changes in the data you end up with the xor table above; byte offset from the end of the data, bit pattern, xor value. Correcting for little endianess in the output you end up with the hex values in parenthesis. The least significant bit is 0x1021 and each subsequent bit is a shift left, if the XOR value has the 0x8000 bit set then it is XORed with 0x1021. This is the CRC-CCITT polynomial.

8 7 6 5 4 3 2 1 0
d5 aa 96 82 00 02 00 00 00: 08b2
|| |
|| 68ed
|408b
20d4

08b2: 68ed ^ 408b ^ 20d4

Starting at the least significant bit and filling in the XOR values for each bit gives the above diagram; the diagram stops at the 20d4 XOR value because at that point it matches the final CRC. This tells us that the CRC covers the 6 bytes prior.

#!/usr/bin/env perl
use Digest::CRC qw(crc);
my $data = pack("H*", "820002000000");
printf("%04x\n", crc($data,16,0,0,0,0x1021,0,0));

We can also compute the same CRC in Perl; note the result will be byte swapped since the data encodes the number as little endian.

=== Command ids ===

==== Display to backplate ====
[[#FET control|0082 - FET control]]
0083 - (every 30 seconds; no data; triggers periodic messages 0002, 0007, and 000a; also triggers 0005 to some extent?)
[[#FET presence|008f - FET presence]]
0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
[[#Get TFE version|0098 - Get TFE version]]
[[#Get build info|0099 - Get build info]]
[[#Get BSL version|009b - Get BSL version]]
009c - (no data; responds with 001c (constant?) data="BSL")
009d - (no data; responds with 001d (constant?) data=bbbb)
[[#Get hardware version?|009e - Get hardware version?]]
[[#Get firmware hash?|009f - Get firmware hash?]]
00a1 - (16-bit data)
00a2 - (every 30 seconds; no data)
00a3 - (every 30 seconds; no data)
00a4 - (16-bit data)
00b1 - button pressed/unpressed (no data)
00b3 - (32-bit data; always ffffffff?)
00b5 - (16-bit data; always 0f00?)
00b9 - (32-bit data; always 0000ffff?)
00ba - (48-bit data; always 000000000000?)
00c2 - (48-bit data)
[[#Reset|00ff - Reset]]

==== Backplate to display ====
0001 - (message from backplate; ASCII)
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
[[#FET presence|0004 - FET presence]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
[[#FET presence|0009 - FET presence]]
000a - (every second; 16-bit data)
[[#Backplate state|000b - Backplate state]]
000c - (16-bit values: pir, px1, px1 divisor, px2, px2 divisor, alir, av)
0010 - (24-bit data)
0014 - (16-bit data)
[[#Get TFE version|0018 - Get TFE version (response)]]
[[#Get build info|0019 - Get build info (response)]]
[[#Get BSL version|001b - Get BSL version (response)]]
001c - Response to 009c; always(?) "BSL"
001d - Response to 009d; always(?) bbbb
[[#Get hardware version?|001e - Get hardware version? (response)]]
[[#Get firmware hash?|001f - Get firmware hash? (response)]]
0022 - (every 30 seconds; 4, 8, 20, 28, 36, 56, 60, 54, 68, 72, or 176 byte data)
0023 - (6, 12, 30, 42, 54, 78, 84, 90, 96, 102, 108, 144, or 150 byte data)
0025 - (2, 4, 12, 14, 20, or 24 byte data)
0027 - (8, 16, 48, 56, 80, or 96 byte data)
0029 - (6, 12, 36, 42, 60, or 72 byte data)
002b - (8, 16, 24, 32, 40, 128, or 152 byte data)
002f - (every 30 seconds; 16-bit data; "end of buffers ACK" log msg)

=== Backplate state ===
Data:
* 8-bit "state"
* 8-bit "flags"
* 8-bit "px0" (may be wider?)
* 40-bit UNKNOWN (includes at least "p2" and "voc")
* 16-bit centi-volts "vi"
* 16-bit milli-volts "vo"
* 16-bit milli-volts "vb"
* 8-bit ("pins" or "wires")
* 8-bit ("wires" or "pins")
* 16-bit UNKNOWN

=== FET control ===
Turn on W1: d5aa96 8200 0200 00 01 29a2
Turn off W1: d5aa96 8200 0200 00 00 08b2
Turn on Y1: d5aa96 8200 0200 01 01 1891
Turn off Y1: d5aa96 8200 0200 01 00 3981
Turn on G : d5aa96 8200 0200 02 01 4bc4
Turn off G : d5aa96 8200 0200 02 00 6ad4
Turn on OB: d5aa96 8200 0200 03 01 7af7
Turn off OB: d5aa96 8200 0200 03 00 5be7
Turn on W2: d5aa96 8200 0200 04 01 ed6e
Turn off W2: d5aa96 8200 0200 04 00 cc7e
Turn on Y2: d5aa96 8200 0200 07 01 be3b
Turn off Y2: d5aa96 8200 0200 07 00 9f2b
Turn on * : d5aa96 8200 0200 0b 01 d37e
Turn off * : d5aa96 8200 0200 0b 00 f26e

For the sake of documentation, we will refer to the unique id numbers for each wire as "wire id numbers".
So wire id 0 is W1, wire id 1 is Y1, wire id B is *, etc.

=== FET presence ===
The backplate will, at least upon connection, send information about which FETs have a wire present.
This data is received with command ids 0004 and 0009, in that order.
Each sensor is represented by one byte which is either 00 (not present) or 01 (present).

The content of 0004 is in order of the "wire id numbers" used for control:
W1, Y1, G, OB, W2, ?0, ?0, Y2, ?1, ?1, ?0, *, ?0

The content of 0009 is arranged differently and has 2 more values:
W1, Y1, ?1, ?1, ?0, G, OB, W2, ?0, Y2, ?0, *, ?0, ?0, ?0

After these are received, the display sends back command 008f with the exact data from message 0004.
Message 008f does not itself receive any response.

=== Get build info ===
Message 0099 (no data) requests the backplate report information about its build.
The response will be message 0019 in ASCII (one line, no trailing newline).

=== Get firmware hash? ===
Message 009f (no data) requests the backplate report a 64-bit hexadecimal value, probably a hash of the firmware (since Nest's software requests it at the same time as version and build info).
The response will be message 001f in uppercase ASCII.

=== Get hardware version? ===
Message 009e (no data) requests the backplate report a "Backplate-"X.Y version string.
Since the firmware file on the display CPU uses these strings as "MinApplicability" and "MaxApplicability" ranges, it is probable they refer to the hardware.

Witnessed versions:
"Backplate-2.8" - Florida Lowes

=== Get BSL version ===
Message 009b (no data) requests the backplate report its BSL version number.
The response will be message 001b in ASCII.

=== Get TFE version ===
Message 0098 (no data) requests the backplate report its TFE version number.
The response will be message 0018 in ASCII.

=== Temperature reading ===
The backplate will send message 0002 every 30 seconds.
The data contains two 16-bit numbers, which nlclient logs in decimal.
The first number is the temperature in centi-celcius.
The second number is the humidity in per-millis.

=== Reset ===
At least upon connection, the display sends message 00ff to the backplate to reset.

The backplate answers with:
0001 msg "<version> <build timestamp "YYYY-MM-DD HH:MM:SS"> K"
[[#FET presence|0004 FET presence]]
[[#FET presence|0009 FET presence]]
0001 msg "*sense 06d1 06d0 0001 0001 0000 0000 0000 0001 06d9 06d8 06d8; detect 09d3 065c"
0001 msg "BRK"

== Run BeagleBone/Debian programs ==
ln -s . /lib/arm-linux-gnueabihf
ln -s ld-2.11.1.so /lib/ld-linux-armhf.so.3

Nest Hacking

2014-07-27T04:50:11Z

Luke-Jr:

== Hardware ==
* TSL2571 Light-to-Digital Converter

== Info ==
* /dev/event1 is the knob; /dev/event2 is the button

== Nest software ==
/nestlabs/sbin/nlclient -config /nestlabs/etc/client.config -config /nestlabs/etc/Display/Display-2/client.config

=== Backplate firmware ===
Found in /nestlabs/share/bp/data/firmware/nlbpfirmware.plist

There are 6 different firmwares in the file:
* Backplate 2 vs Backplate 3
* TFE (BP_D2 for Bp2, AMBER_BP for Bp3) vs BSL
* For TFE firmwares, hex vs srec (which for some reason DO differ!)

=== Backplate initialisation ===
When the backplate is first connected, the following sequence occurs:
Send [[#Request info|00ff - Request info]]
Recv 0001 - (message from backplate; ASCII)
Recv [[#FET presence|0004 - FET presence]]
Recv [[#FET presence|0009 - FET presence]]
Send [[#FET presence|008f - FET presence]]
Send 0083 - (every 30 seconds; no data; triggers periodic messages 0002, 0007, and 000a; also triggers 0005 to some extent?)
Send 0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
Recv 0001 - (message from backplate; ASCII)
Recv 0001 - (message from backplate; ASCII)
Recv 0010 - (24-bit data)
Send [[#Get TFE version|0098 - Get TFE version]]
Recv 000a - (every second; 16-bit data)
Recv 0007 - (every second; 16-bit data)
Recv [[#Get TFE version|0018 - Get TFE version (response)]]
Send [[#Get build info|0099 - Get build info]]
Recv [[#Get build info|0019 - Get build info (response)]]
Sometimes:
Send 009d - (no data; responds with 001d (constant?) data=bbbb)
Recv 001d - Response to 009d; always(?) bbbb
Sometimes:
Send [[#Get BSL version|009b - Get BSL version]]
Recv [[#Get BSL version|001b - Get BSL version (response)]]
Sometimes:
Send 009c - (no data; responds with 001c (constant?) data="BSL")
Recv 001c - Response to 009c; always(?) "BSL"
Send [[#Get firmware hash?|009f - Get firmware hash?]]
Recv [[#Get firmware hash?|001f - Get firmware hash? (response)]]
Send [[#Get hardware version?|009e - Get hardware version?]]
Recv [[#Get hardware version?|001e - Get hardware version? (response)]]

== Nest backplate interface ==
* Connected on /dev/ttyO2
* All communications with backplate begin with (d5)d5aa96 (d5 is doubled only for data FROM backplate)
* Everything is little endian
* 16-bit command
* 16-bit data length
* <data>
* 16-bit checksum

Monitor:
strace -ff -p $(pidof nlclient) -x -s9999 -e read,write 2>&1 | grep '(54'

=== Checksum ===
<Bytes-from-end>.<bit-value> <xor-with>
00.01 2110 (1021)
00.02 4220 (2042: 1021<<1)
00.04 8440 (4084: 2048<<1)
00.08 0881 (8108: 4084<<1)
00.10 3112 (1231: 8108<<1^1021)
00.20 6224 (2462: 1231<<1)
00.40 c448 (48c4: 2462<<1)
00.80 8891 (9188: 48c4<<1)
01.01 3133 (3313: 9188<<1^1021)
01.02 6266
01.04 c4cc
01.08 a989
01.10 7303
01.20 e606
01.40 cc0d
01.80 981b
02.01 3037
02.02 606e
...
03.01 b476
03.02 68ed
03.04 f1ca
03.08 c385
03.10 a71b
03.20 4e37
03.40 9c6e
03.80 38dd
...
07.20 687b

If you compute the contribution of the individual bit changes in the data you end up with the xor table above; byte offset from the end of the data, bit pattern, xor value. Correcting for little endianess in the output you end up with the hex values in parenthesis. The least significant bit is 0x1021 and each subsequent bit is a shift left, if the XOR value has the 0x8000 bit set then it is XORed with 0x1021. This is the CRC-CCITT polynomial.

8 7 6 5 4 3 2 1 0
d5 aa 96 82 00 02 00 00 00: 08b2
|| |
|| 68ed
|408b
20d4

08b2: 68ed ^ 408b ^ 20d4

Starting at the least significant bit and filling in the XOR values for each bit gives the above diagram; the diagram stops at the 20d4 XOR value because at that point it matches the final CRC. This tells us that the CRC covers the 6 bytes prior.

#!/usr/bin/env perl
use Digest::CRC qw(crc);
my $data = pack("H*", "820002000000");
printf("%04x\n", crc($data,16,0,0,0,0x1021,0,0));

We can also compute the same CRC in Perl; note the result will be byte swapped since the data encodes the number as little endian.

=== Command ids ===

==== Display to backplate ====
[[#FET control|0082 - FET control]]
0083 - (every 30 seconds; no data; triggers periodic messages 0002, 0007, and 000a; also triggers 0005 to some extent?)
[[#FET presence|008f - FET presence]]
0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
[[#Get TFE version|0098 - Get TFE version]]
[[#Get build info|0099 - Get build info]]
[[#Get BSL version|009b - Get BSL version]]
009c - (no data; responds with 001c (constant?) data="BSL")
009d - (no data; responds with 001d (constant?) data=bbbb)
[[#Get hardware version?|009e - Get hardware version?]]
[[#Get firmware hash?|009f - Get firmware hash?]]
00a1 - (16-bit data)
00a2 - (every 30 seconds; no data)
00a3 - (every 30 seconds; no data)
00a4 - (16-bit data)
00b1 - button pressed/unpressed (no data)
00b3 - (32-bit data; always ffffffff?)
00b5 - (16-bit data; always 0f00?)
00b9 - (32-bit data; always 0000ffff?)
00ba - (48-bit data; always 000000000000?)
00c2 - (48-bit data)
[[#Request info|00ff - Request info]]

==== Backplate to display ====
0001 - (message from backplate; ASCII)
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
[[#FET presence|0004 - FET presence]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
[[#FET presence|0009 - FET presence]]
000a - (every second; 16-bit data)
[[#Backplate state|000b - Backplate state]]
000c - (16-bit values: pir, px1, px1 divisor, px2, px2 divisor, alir, av)
0010 - (24-bit data)
0014 - (16-bit data)
[[#Get TFE version|0018 - Get TFE version (response)]]
[[#Get build info|0019 - Get build info (response)]]
[[#Get BSL version|001b - Get BSL version (response)]]
001c - Response to 009c; always(?) "BSL"
001d - Response to 009d; always(?) bbbb
[[#Get hardware version?|001e - Get hardware version? (response)]]
[[#Get firmware hash?|001f - Get firmware hash? (response)]]
0022 - (every 30 seconds; 4, 8, 20, 28, 36, 56, 60, 54, 68, 72, or 176 byte data)
0023 - (6, 12, 30, 42, 54, 78, 84, 90, 96, 102, 108, 144, or 150 byte data)
0025 - (2, 4, 12, 14, 20, or 24 byte data)
0027 - (8, 16, 48, 56, 80, or 96 byte data)
0029 - (6, 12, 36, 42, 60, or 72 byte data)
002b - (8, 16, 24, 32, 40, 128, or 152 byte data)
002f - (every 30 seconds; 16-bit data; "end of buffers ACK" log msg)

=== Backplate state ===
Data:
* 8-bit "state"
* 8-bit "flags"
* 8-bit "px0" (may be wider?)
* 40-bit UNKNOWN (includes at least "p2" and "voc")
* 16-bit centi-volts "vi"
* 16-bit milli-volts "vo"
* 16-bit milli-volts "vb"
* 8-bit ("pins" or "wires")
* 8-bit ("wires" or "pins")
* 16-bit UNKNOWN

=== FET control ===
Turn on W1: d5aa96 8200 0200 00 01 29a2
Turn off W1: d5aa96 8200 0200 00 00 08b2
Turn on Y1: d5aa96 8200 0200 01 01 1891
Turn off Y1: d5aa96 8200 0200 01 00 3981
Turn on G : d5aa96 8200 0200 02 01 4bc4
Turn off G : d5aa96 8200 0200 02 00 6ad4
Turn on OB: d5aa96 8200 0200 03 01 7af7
Turn off OB: d5aa96 8200 0200 03 00 5be7
Turn on W2: d5aa96 8200 0200 04 01 ed6e
Turn off W2: d5aa96 8200 0200 04 00 cc7e
Turn on Y2: d5aa96 8200 0200 07 01 be3b
Turn off Y2: d5aa96 8200 0200 07 00 9f2b
Turn on * : d5aa96 8200 0200 0b 01 d37e
Turn off * : d5aa96 8200 0200 0b 00 f26e

For the sake of documentation, we will refer to the unique id numbers for each wire as "wire id numbers".
So wire id 0 is W1, wire id 1 is Y1, wire id B is *, etc.

=== FET presence ===
The backplate will, at least upon connection, send information about which FETs have a wire present.
This data is received with command ids 0004 and 0009, in that order.
Each sensor is represented by one byte which is either 00 (not present) or 01 (present).

The content of 0004 is in order of the "wire id numbers" used for control:
W1, Y1, G, OB, W2, ?0, ?0, Y2, ?1, ?1, ?0, *, ?0

The content of 0009 is arranged differently and has 2 more values:
W1, Y1, ?1, ?1, ?0, G, OB, W2, ?0, Y2, ?0, *, ?0, ?0, ?0

After these are received, the display sends back command 008f with the exact data from message 0004.
Message 008f does not itself receive any response.

=== Get build info ===
Message 0099 (no data) requests the backplate report information about its build.
The response will be message 0019 in ASCII (one line, no trailing newline).

=== Get firmware hash? ===
Message 009f (no data) requests the backplate report a 64-bit hexadecimal value, probably a hash of the firmware (since Nest's software requests it at the same time as version and build info).
The response will be message 001f in uppercase ASCII.

=== Get hardware version? ===
Message 009e (no data) requests the backplate report a "Backplate-"X.Y version string.
Since the firmware file on the display CPU uses these strings as "MinApplicability" and "MaxApplicability" ranges, it is probable they refer to the hardware.

Witnessed versions:
"Backplate-2.8" - Florida Lowes

=== Get BSL version ===
Message 009b (no data) requests the backplate report its BSL version number.
The response will be message 001b in ASCII.

=== Get TFE version ===
Message 0098 (no data) requests the backplate report its TFE version number.
The response will be message 0018 in ASCII.

=== Temperature reading ===
The backplate will send message 0002 every 30 seconds.
The data contains two 16-bit numbers, which nlclient logs in decimal.
The first number is the temperature in centi-celcius.
The second number is the humidity in per-millis.

=== Request info ===
At least upon connection, the display sends message 00ff to the backplate to request information.
This takes just under half a second, so it may trigger some initialisation as well.

The backplate answers with:
0001 msg "<version> <build timestamp "YYYY-MM-DD HH:MM:SS"> K"
[[#FET presence|0004 FET presence]]
[[#FET presence|0009 FET presence]]
0001 msg "*sense 06d1 06d0 0001 0001 0000 0000 0000 0001 06d9 06d8 06d8; detect 09d3 065c"
0001 msg "BRK"

== Run BeagleBone/Debian programs ==
ln -s . /lib/arm-linux-gnueabihf
ln -s ld-2.11.1.so /lib/ld-linux-armhf.so.3

Nest Hacking

2014-07-27T04:46:31Z

Luke-Jr: Get BSL version

== Hardware ==
* TSL2571 Light-to-Digital Converter

== Info ==
* /dev/event1 is the knob; /dev/event2 is the button

== Nest software ==
/nestlabs/sbin/nlclient -config /nestlabs/etc/client.config -config /nestlabs/etc/Display/Display-2/client.config

=== Backplate firmware ===
Found in /nestlabs/share/bp/data/firmware/nlbpfirmware.plist

There are 6 different firmwares in the file:
* Backplate 2 vs Backplate 3
* TFE (BP_D2 for Bp2, AMBER_BP for Bp3) vs BSL
* For TFE firmwares, hex vs srec (which for some reason DO differ!)

=== Backplate initialisation ===
When the backplate is first connected, the following sequence occurs:
Send [[#Request info|00ff - Request info]]
Recv 0001 - (message from backplate; ASCII)
Recv [[#FET presence|0004 - FET presence]]
Recv [[#FET presence|0009 - FET presence]]
Send [[#FET presence|008f - FET presence]]
Send 0083 - (every 30 seconds; no data; triggers periodic messages 0002, 0007, and 000a; also triggers 0005 to some extent?)
Send 0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
Recv 0001 - (message from backplate; ASCII)
Recv 0001 - (message from backplate; ASCII)
Recv 0010 - (24-bit data)
Send [[#Get TFE version|0098 - Get TFE version]]
Recv 000a - (every second; 16-bit data)
Recv 0007 - (every second; 16-bit data)
Recv [[#Get TFE version|0018 - Get TFE version (response)]]
Send [[#Get build info|0099 - Get build info]]
Recv [[#Get build info|0019 - Get build info (response)]]
Sometimes:
Send 009d - (no data)
Recv 001d - (16-bit data)
Sometimes:
Send [[#Get BSL version|009b - Get BSL version]]
Recv [[#Get BSL version|001b - Get BSL version (response)]]
Sometimes:
Send 009c - (no data)
Recv 001c - (24-bit data)
Send [[#Get firmware hash?|009f - Get firmware hash?]]
Recv [[#Get firmware hash?|001f - Get firmware hash? (response)]]
Send [[#Get hardware version?|009e - Get hardware version?]]
Recv [[#Get hardware version?|001e - Get hardware version? (response)]]

== Nest backplate interface ==
* Connected on /dev/ttyO2
* All communications with backplate begin with (d5)d5aa96 (d5 is doubled only for data FROM backplate)
* Everything is little endian
* 16-bit command
* 16-bit data length
* <data>
* 16-bit checksum

Monitor:
strace -ff -p $(pidof nlclient) -x -s9999 -e read,write 2>&1 | grep '(54'

=== Checksum ===
<Bytes-from-end>.<bit-value> <xor-with>
00.01 2110 (1021)
00.02 4220 (2042: 1021<<1)
00.04 8440 (4084: 2048<<1)
00.08 0881 (8108: 4084<<1)
00.10 3112 (1231: 8108<<1^1021)
00.20 6224 (2462: 1231<<1)
00.40 c448 (48c4: 2462<<1)
00.80 8891 (9188: 48c4<<1)
01.01 3133 (3313: 9188<<1^1021)
01.02 6266
01.04 c4cc
01.08 a989
01.10 7303
01.20 e606
01.40 cc0d
01.80 981b
02.01 3037
02.02 606e
...
03.01 b476
03.02 68ed
03.04 f1ca
03.08 c385
03.10 a71b
03.20 4e37
03.40 9c6e
03.80 38dd
...
07.20 687b

If you compute the contribution of the individual bit changes in the data you end up with the xor table above; byte offset from the end of the data, bit pattern, xor value. Correcting for little endianess in the output you end up with the hex values in parenthesis. The least significant bit is 0x1021 and each subsequent bit is a shift left, if the XOR value has the 0x8000 bit set then it is XORed with 0x1021. This is the CRC-CCITT polynomial.

8 7 6 5 4 3 2 1 0
d5 aa 96 82 00 02 00 00 00: 08b2
|| |
|| 68ed
|408b
20d4

08b2: 68ed ^ 408b ^ 20d4

Starting at the least significant bit and filling in the XOR values for each bit gives the above diagram; the diagram stops at the 20d4 XOR value because at that point it matches the final CRC. This tells us that the CRC covers the 6 bytes prior.

#!/usr/bin/env perl
use Digest::CRC qw(crc);
my $data = pack("H*", "820002000000");
printf("%04x\n", crc($data,16,0,0,0,0x1021,0,0));

We can also compute the same CRC in Perl; note the result will be byte swapped since the data encodes the number as little endian.

=== Command ids ===

==== Display to backplate ====
[[#FET control|0082 - FET control]]
0083 - (every 30 seconds; no data; triggers periodic messages 0002, 0007, and 000a; also triggers 0005 to some extent?)
[[#FET presence|008f - FET presence]]
0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
[[#Get TFE version|0098 - Get TFE version]]
[[#Get build info|0099 - Get build info]]
[[#Get BSL version|009b - Get BSL version]]
009c - (no data)
009d - (no data)
[[#Get hardware version?|009e - Get hardware version?]]
[[#Get firmware hash?|009f - Get firmware hash?]]
00a1 - (16-bit data)
00a2 - (every 30 seconds; no data)
00a3 - (every 30 seconds; no data)
00a4 - (16-bit data)
00b1 - button pressed/unpressed (no data)
00b3 - (32-bit data; always ffffffff?)
00b5 - (16-bit data; always 0f00?)
00b9 - (32-bit data; always 0000ffff?)
00ba - (48-bit data; always 000000000000?)
00c2 - (48-bit data)
[[#Request info|00ff - Request info]]

==== Backplate to display ====
0001 - (message from backplate; ASCII)
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
[[#FET presence|0004 - FET presence]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
[[#FET presence|0009 - FET presence]]
000a - (every second; 16-bit data)
[[#Backplate state|000b - Backplate state]]
000c - (16-bit values: pir, px1, px1 divisor, px2, px2 divisor, alir, av)
0010 - (24-bit data)
0014 - (16-bit data)
[[#Get TFE version|0018 - Get TFE version (response)]]
[[#Get build info|0019 - Get build info (response)]]
[[#Get BSL version|001b - Get BSL version (response)]]
001c - (24-bit data)
001d - (16-bit data)
[[#Get hardware version?|001e - Get hardware version? (response)]]
[[#Get firmware hash?|001f - Get firmware hash? (response)]]
0022 - (every 30 seconds; 4, 8, 20, 28, 36, 56, 60, 54, 68, 72, or 176 byte data)
0023 - (6, 12, 30, 42, 54, 78, 84, 90, 96, 102, 108, 144, or 150 byte data)
0025 - (2, 4, 12, 14, 20, or 24 byte data)
0027 - (8, 16, 48, 56, 80, or 96 byte data)
0029 - (6, 12, 36, 42, 60, or 72 byte data)
002b - (8, 16, 24, 32, 40, 128, or 152 byte data)
002f - (every 30 seconds; 16-bit data; "end of buffers ACK" log msg)

=== Backplate state ===
Data:
* 8-bit "state"
* 8-bit "flags"
* 8-bit "px0" (may be wider?)
* 40-bit UNKNOWN (includes at least "p2" and "voc")
* 16-bit centi-volts "vi"
* 16-bit milli-volts "vo"
* 16-bit milli-volts "vb"
* 8-bit ("pins" or "wires")
* 8-bit ("wires" or "pins")
* 16-bit UNKNOWN

=== FET control ===
Turn on W1: d5aa96 8200 0200 00 01 29a2
Turn off W1: d5aa96 8200 0200 00 00 08b2
Turn on Y1: d5aa96 8200 0200 01 01 1891
Turn off Y1: d5aa96 8200 0200 01 00 3981
Turn on G : d5aa96 8200 0200 02 01 4bc4
Turn off G : d5aa96 8200 0200 02 00 6ad4
Turn on OB: d5aa96 8200 0200 03 01 7af7
Turn off OB: d5aa96 8200 0200 03 00 5be7
Turn on W2: d5aa96 8200 0200 04 01 ed6e
Turn off W2: d5aa96 8200 0200 04 00 cc7e
Turn on Y2: d5aa96 8200 0200 07 01 be3b
Turn off Y2: d5aa96 8200 0200 07 00 9f2b
Turn on * : d5aa96 8200 0200 0b 01 d37e
Turn off * : d5aa96 8200 0200 0b 00 f26e

For the sake of documentation, we will refer to the unique id numbers for each wire as "wire id numbers".
So wire id 0 is W1, wire id 1 is Y1, wire id B is *, etc.

=== FET presence ===
The backplate will, at least upon connection, send information about which FETs have a wire present.
This data is received with command ids 0004 and 0009, in that order.
Each sensor is represented by one byte which is either 00 (not present) or 01 (present).

The content of 0004 is in order of the "wire id numbers" used for control:
W1, Y1, G, OB, W2, ?0, ?0, Y2, ?1, ?1, ?0, *, ?0

The content of 0009 is arranged differently and has 2 more values:
W1, Y1, ?1, ?1, ?0, G, OB, W2, ?0, Y2, ?0, *, ?0, ?0, ?0

After these are received, the display sends back command 008f with the exact data from message 0004.
Message 008f does not itself receive any response.

=== Get build info ===
Message 0099 (no data) requests the backplate report information about its build.
The response will be message 0019 in ASCII (one line, no trailing newline).

=== Get firmware hash? ===
Message 009f (no data) requests the backplate report a 64-bit hexadecimal value, probably a hash of the firmware (since Nest's software requests it at the same time as version and build info).
The response will be message 001f in uppercase ASCII.

=== Get hardware version? ===
Message 009e (no data) requests the backplate report a "Backplate-"X.Y version string.
Since the firmware file on the display CPU uses these strings as "MinApplicability" and "MaxApplicability" ranges, it is probable they refer to the hardware.

Witnessed versions:
"Backplate-2.8" - Florida Lowes

=== Get BSL version ===
Message 009b (no data) requests the backplate report its BSL version number.
The response will be message 001b in ASCII.

=== Get TFE version ===
Message 0098 (no data) requests the backplate report its TFE version number.
The response will be message 0018 in ASCII.

=== Temperature reading ===
The backplate will send message 0002 every 30 seconds.
The data contains two 16-bit numbers, which nlclient logs in decimal.
The first number is the temperature in centi-celcius.
The second number is the humidity in per-millis.

=== Request info ===
At least upon connection, the display sends message 00ff to the backplate to request information.
This takes just under half a second, so it may trigger some initialisation as well.

The backplate answers with:
0001 msg "<version> <build timestamp "YYYY-MM-DD HH:MM:SS"> K"
[[#FET presence|0004 FET presence]]
[[#FET presence|0009 FET presence]]
0001 msg "*sense 06d1 06d0 0001 0001 0000 0000 0000 0001 06d9 06d8 06d8; detect 09d3 065c"
0001 msg "BRK"

== Run BeagleBone/Debian programs ==
ln -s . /lib/arm-linux-gnueabihf
ln -s ld-2.11.1.so /lib/ld-linux-armhf.so.3

Nest Hacking

2014-07-27T04:44:17Z

Luke-Jr: 0098 is TFE version

== Hardware ==
* TSL2571 Light-to-Digital Converter

== Info ==
* /dev/event1 is the knob; /dev/event2 is the button

== Nest software ==
/nestlabs/sbin/nlclient -config /nestlabs/etc/client.config -config /nestlabs/etc/Display/Display-2/client.config

=== Backplate firmware ===
Found in /nestlabs/share/bp/data/firmware/nlbpfirmware.plist

There are 6 different firmwares in the file:
* Backplate 2 vs Backplate 3
* TFE (BP_D2 for Bp2, AMBER_BP for Bp3) vs BSL
* For TFE firmwares, hex vs srec (which for some reason DO differ!)

=== Backplate initialisation ===
When the backplate is first connected, the following sequence occurs:
Send [[#Request info|00ff - Request info]]
Recv 0001 - (message from backplate; ASCII)
Recv [[#FET presence|0004 - FET presence]]
Recv [[#FET presence|0009 - FET presence]]
Send [[#FET presence|008f - FET presence]]
Send 0083 - (every 30 seconds; no data; triggers periodic messages 0002, 0007, and 000a; also triggers 0005 to some extent?)
Send 0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
Recv 0001 - (message from backplate; ASCII)
Recv 0001 - (message from backplate; ASCII)
Recv 0010 - (24-bit data)
Send [[#Get TFE version|0098 - Get TFE version]]
Recv 000a - (every second; 16-bit data)
Recv 0007 - (every second; 16-bit data)
Recv [[#Get TFE version|0018 - Get TFE version (response)]]
Send [[#Get build info|0099 - Get build info]]
Recv [[#Get build info|0019 - Get build info (response)]]
Sometimes:
Send 009d - (no data)
Recv 001d - (16-bit data)
Sometimes:
Send 009b - (no data)
Recv 001b - (24-bit data)
Sometimes:
Send 009c - (no data)
Recv 001c - (24-bit data)
Send [[#Get firmware hash?|009f - Get firmware hash?]]
Recv [[#Get firmware hash?|001f - Get firmware hash? (response)]]
Send [[#Get hardware version?|009e - Get hardware version?]]
Recv [[#Get hardware version?|001e - Get hardware version? (response)]]

== Nest backplate interface ==
* Connected on /dev/ttyO2
* All communications with backplate begin with (d5)d5aa96 (d5 is doubled only for data FROM backplate)
* Everything is little endian
* 16-bit command
* 16-bit data length
* <data>
* 16-bit checksum

Monitor:
strace -ff -p $(pidof nlclient) -x -s9999 -e read,write 2>&1 | grep '(54'

=== Checksum ===
<Bytes-from-end>.<bit-value> <xor-with>
00.01 2110 (1021)
00.02 4220 (2042: 1021<<1)
00.04 8440 (4084: 2048<<1)
00.08 0881 (8108: 4084<<1)
00.10 3112 (1231: 8108<<1^1021)
00.20 6224 (2462: 1231<<1)
00.40 c448 (48c4: 2462<<1)
00.80 8891 (9188: 48c4<<1)
01.01 3133 (3313: 9188<<1^1021)
01.02 6266
01.04 c4cc
01.08 a989
01.10 7303
01.20 e606
01.40 cc0d
01.80 981b
02.01 3037
02.02 606e
...
03.01 b476
03.02 68ed
03.04 f1ca
03.08 c385
03.10 a71b
03.20 4e37
03.40 9c6e
03.80 38dd
...
07.20 687b

If you compute the contribution of the individual bit changes in the data you end up with the xor table above; byte offset from the end of the data, bit pattern, xor value. Correcting for little endianess in the output you end up with the hex values in parenthesis. The least significant bit is 0x1021 and each subsequent bit is a shift left, if the XOR value has the 0x8000 bit set then it is XORed with 0x1021. This is the CRC-CCITT polynomial.

8 7 6 5 4 3 2 1 0
d5 aa 96 82 00 02 00 00 00: 08b2
|| |
|| 68ed
|408b
20d4

08b2: 68ed ^ 408b ^ 20d4

Starting at the least significant bit and filling in the XOR values for each bit gives the above diagram; the diagram stops at the 20d4 XOR value because at that point it matches the final CRC. This tells us that the CRC covers the 6 bytes prior.

#!/usr/bin/env perl
use Digest::CRC qw(crc);
my $data = pack("H*", "820002000000");
printf("%04x\n", crc($data,16,0,0,0,0x1021,0,0));

We can also compute the same CRC in Perl; note the result will be byte swapped since the data encodes the number as little endian.

=== Command ids ===

==== Display to backplate ====
[[#FET control|0082 - FET control]]
0083 - (every 30 seconds; no data; triggers periodic messages 0002, 0007, and 000a; also triggers 0005 to some extent?)
[[#FET presence|008f - FET presence]]
0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
[[#Get TFE version|0098 - Get TFE version]]
[[#Get build info|0099 - Get build info]]
009b - (no data)
009c - (no data)
009d - (no data)
[[#Get hardware version?|009e - Get hardware version?]]
[[#Get firmware hash?|009f - Get firmware hash?]]
00a1 - (16-bit data)
00a2 - (every 30 seconds; no data)
00a3 - (every 30 seconds; no data)
00a4 - (16-bit data)
00b1 - button pressed/unpressed (no data)
00b3 - (32-bit data; always ffffffff?)
00b5 - (16-bit data; always 0f00?)
00b9 - (32-bit data; always 0000ffff?)
00ba - (48-bit data; always 000000000000?)
00c2 - (48-bit data)
[[#Request info|00ff - Request info]]

==== Backplate to display ====
0001 - (message from backplate; ASCII)
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
[[#FET presence|0004 - FET presence]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
[[#FET presence|0009 - FET presence]]
000a - (every second; 16-bit data)
[[#Backplate state|000b - Backplate state]]
000c - (16-bit values: pir, px1, px1 divisor, px2, px2 divisor, alir, av)
0010 - (24-bit data)
0014 - (16-bit data)
[[#Get TFE version|0018 - Get TFE version (response)]]
[[#Get build info|0019 - Get build info (response)]]
001b - (24-bit data)
001c - (24-bit data)
001d - (16-bit data)
[[#Get hardware version?|001e - Get hardware version? (response)]]
[[#Get firmware hash?|001f - Get firmware hash? (response)]]
0022 - (every 30 seconds; 4, 8, 20, 28, 36, 56, 60, 54, 68, 72, or 176 byte data)
0023 - (6, 12, 30, 42, 54, 78, 84, 90, 96, 102, 108, 144, or 150 byte data)
0025 - (2, 4, 12, 14, 20, or 24 byte data)
0027 - (8, 16, 48, 56, 80, or 96 byte data)
0029 - (6, 12, 36, 42, 60, or 72 byte data)
002b - (8, 16, 24, 32, 40, 128, or 152 byte data)
002f - (every 30 seconds; 16-bit data; "end of buffers ACK" log msg)

=== Backplate state ===
Data:
* 8-bit "state"
* 8-bit "flags"
* 8-bit "px0" (may be wider?)
* 40-bit UNKNOWN (includes at least "p2" and "voc")
* 16-bit centi-volts "vi"
* 16-bit milli-volts "vo"
* 16-bit milli-volts "vb"
* 8-bit ("pins" or "wires")
* 8-bit ("wires" or "pins")
* 16-bit UNKNOWN

=== FET control ===
Turn on W1: d5aa96 8200 0200 00 01 29a2
Turn off W1: d5aa96 8200 0200 00 00 08b2
Turn on Y1: d5aa96 8200 0200 01 01 1891
Turn off Y1: d5aa96 8200 0200 01 00 3981
Turn on G : d5aa96 8200 0200 02 01 4bc4
Turn off G : d5aa96 8200 0200 02 00 6ad4
Turn on OB: d5aa96 8200 0200 03 01 7af7
Turn off OB: d5aa96 8200 0200 03 00 5be7
Turn on W2: d5aa96 8200 0200 04 01 ed6e
Turn off W2: d5aa96 8200 0200 04 00 cc7e
Turn on Y2: d5aa96 8200 0200 07 01 be3b
Turn off Y2: d5aa96 8200 0200 07 00 9f2b
Turn on * : d5aa96 8200 0200 0b 01 d37e
Turn off * : d5aa96 8200 0200 0b 00 f26e

For the sake of documentation, we will refer to the unique id numbers for each wire as "wire id numbers".
So wire id 0 is W1, wire id 1 is Y1, wire id B is *, etc.

=== FET presence ===
The backplate will, at least upon connection, send information about which FETs have a wire present.
This data is received with command ids 0004 and 0009, in that order.
Each sensor is represented by one byte which is either 00 (not present) or 01 (present).

The content of 0004 is in order of the "wire id numbers" used for control:
W1, Y1, G, OB, W2, ?0, ?0, Y2, ?1, ?1, ?0, *, ?0

The content of 0009 is arranged differently and has 2 more values:
W1, Y1, ?1, ?1, ?0, G, OB, W2, ?0, Y2, ?0, *, ?0, ?0, ?0

After these are received, the display sends back command 008f with the exact data from message 0004.
Message 008f does not itself receive any response.

=== Get build info ===
Message 0099 (no data) requests the backplate report information about its build.
The response will be message 0019 in ASCII (one line, no trailing newline).

=== Get firmware hash? ===
Message 009f (no data) requests the backplate report a 64-bit hexadecimal value, probably a hash of the firmware (since Nest's software requests it at the same time as version and build info).
The response will be message 001f in uppercase ASCII.

=== Get hardware version? ===
Message 009e (no data) requests the backplate report a "Backplate-"X.Y version string.
Since the firmware file on the display CPU uses these strings as "MinApplicability" and "MaxApplicability" ranges, it is probable they refer to the hardware.

Witnessed versions:
"Backplate-2.8" - Florida Lowes

=== Get TFE version ===
Message 0098 (no data) requests the backplate report its TFE version number.
The response will be message 0018 in ASCII.

=== Temperature reading ===
The backplate will send message 0002 every 30 seconds.
The data contains two 16-bit numbers, which nlclient logs in decimal.
The first number is the temperature in centi-celcius.
The second number is the humidity in per-millis.

=== Request info ===
At least upon connection, the display sends message 00ff to the backplate to request information.
This takes just under half a second, so it may trigger some initialisation as well.

The backplate answers with:
0001 msg "<version> <build timestamp "YYYY-MM-DD HH:MM:SS"> K"
[[#FET presence|0004 FET presence]]
[[#FET presence|0009 FET presence]]
0001 msg "*sense 06d1 06d0 0001 0001 0000 0000 0000 0001 06d9 06d8 06d8; detect 09d3 065c"
0001 msg "BRK"

== Run BeagleBone/Debian programs ==
ln -s . /lib/arm-linux-gnueabihf
ln -s ld-2.11.1.so /lib/ld-linux-armhf.so.3

Nest Hacking

2014-07-27T04:32:26Z

Luke-Jr: /* Backplate initialisation */

== Hardware ==
* TSL2571 Light-to-Digital Converter

== Info ==
* /dev/event1 is the knob; /dev/event2 is the button

== Nest software ==
/nestlabs/sbin/nlclient -config /nestlabs/etc/client.config -config /nestlabs/etc/Display/Display-2/client.config

=== Backplate firmware ===
Found in /nestlabs/share/bp/data/firmware/nlbpfirmware.plist

There are 6 different firmwares in the file:
* Backplate 2 vs Backplate 3
* TFE (BP_D2 for Bp2, AMBER_BP for Bp3) vs BSL
* For TFE firmwares, hex vs srec (which for some reason DO differ!)

=== Backplate initialisation ===
When the backplate is first connected, the following sequence occurs:
Send [[#Request info|00ff - Request info]]
Recv 0001 - (message from backplate; ASCII)
Recv [[#FET presence|0004 - FET presence]]
Recv [[#FET presence|0009 - FET presence]]
Send [[#FET presence|008f - FET presence]]
Send 0083 - (every 30 seconds; no data; triggers periodic messages 0002, 0007, and 000a; also triggers 0005 to some extent?)
Send 0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
Recv 0001 - (message from backplate; ASCII)
Recv 0001 - (message from backplate; ASCII)
Recv 0010 - (24-bit data)
Send [[#Get version|0098 - Get version]]
Recv 000a - (every second; 16-bit data)
Recv 0007 - (every second; 16-bit data)
Recv [[#Get version|0018 - Get version (response)]]
Send [[#Get build info|0099 - Get build info]]
Recv [[#Get build info|0019 - Get build info (response)]]
Sometimes:
Send 009d - (no data)
Recv 001d - (16-bit data)
Sometimes:
Send 009b - (no data)
Recv 001b - (24-bit data)
Sometimes:
Send 009c - (no data)
Recv 001c - (24-bit data)
Send [[#Get firmware hash?|009f - Get firmware hash?]]
Recv [[#Get firmware hash?|001f - Get firmware hash? (response)]]
Send [[#Get hardware version?|009e - Get hardware version?]]
Recv [[#Get hardware version?|001e - Get hardware version? (response)]]

== Nest backplate interface ==
* Connected on /dev/ttyO2
* All communications with backplate begin with (d5)d5aa96 (d5 is doubled only for data FROM backplate)
* Everything is little endian
* 16-bit command
* 16-bit data length
* <data>
* 16-bit checksum

Monitor:
strace -ff -p $(pidof nlclient) -x -s9999 -e read,write 2>&1 | grep '(54'

=== Checksum ===
<Bytes-from-end>.<bit-value> <xor-with>
00.01 2110 (1021)
00.02 4220 (2042: 1021<<1)
00.04 8440 (4084: 2048<<1)
00.08 0881 (8108: 4084<<1)
00.10 3112 (1231: 8108<<1^1021)
00.20 6224 (2462: 1231<<1)
00.40 c448 (48c4: 2462<<1)
00.80 8891 (9188: 48c4<<1)
01.01 3133 (3313: 9188<<1^1021)
01.02 6266
01.04 c4cc
01.08 a989
01.10 7303
01.20 e606
01.40 cc0d
01.80 981b
02.01 3037
02.02 606e
...
03.01 b476
03.02 68ed
03.04 f1ca
03.08 c385
03.10 a71b
03.20 4e37
03.40 9c6e
03.80 38dd
...
07.20 687b

If you compute the contribution of the individual bit changes in the data you end up with the xor table above; byte offset from the end of the data, bit pattern, xor value. Correcting for little endianess in the output you end up with the hex values in parenthesis. The least significant bit is 0x1021 and each subsequent bit is a shift left, if the XOR value has the 0x8000 bit set then it is XORed with 0x1021. This is the CRC-CCITT polynomial.

8 7 6 5 4 3 2 1 0
d5 aa 96 82 00 02 00 00 00: 08b2
|| |
|| 68ed
|408b
20d4

08b2: 68ed ^ 408b ^ 20d4

Starting at the least significant bit and filling in the XOR values for each bit gives the above diagram; the diagram stops at the 20d4 XOR value because at that point it matches the final CRC. This tells us that the CRC covers the 6 bytes prior.

#!/usr/bin/env perl
use Digest::CRC qw(crc);
my $data = pack("H*", "820002000000");
printf("%04x\n", crc($data,16,0,0,0,0x1021,0,0));

We can also compute the same CRC in Perl; note the result will be byte swapped since the data encodes the number as little endian.

=== Command ids ===

==== Display to backplate ====
[[#FET control|0082 - FET control]]
0083 - (every 30 seconds; no data; triggers periodic messages 0002, 0007, and 000a; also triggers 0005 to some extent?)
[[#FET presence|008f - FET presence]]
0090 - (no data; response 0010 with constant(?) 3 bytes a77948)
[[#Get version|0098 - Get version]]
[[#Get build info|0099 - Get build info]]
009b - (no data)
009c - (no data)
009d - (no data)
[[#Get hardware version?|009e - Get hardware version?]]
[[#Get firmware hash?|009f - Get firmware hash?]]
00a1 - (16-bit data)
00a2 - (every 30 seconds; no data)
00a3 - (every 30 seconds; no data)
00a4 - (16-bit data)
00b1 - button pressed/unpressed (no data)
00b3 - (32-bit data; always ffffffff?)
00b5 - (16-bit data; always 0f00?)
00b9 - (32-bit data; always 0000ffff?)
00ba - (48-bit data; always 000000000000?)
00c2 - (48-bit data)
[[#Request info|00ff - Request info]]

==== Backplate to display ====
0001 - (message from backplate; ASCII)
[[#Temperature reading|0002 - Temperature reading (twice every 30 seconds; 32-bit data)]]
[[#FET presence|0004 - FET presence]]
0005 - (32-bit data)
0007 - (every second; 16-bit data)
[[#FET presence|0009 - FET presence]]
000a - (every second; 16-bit data)
[[#Backplate state|000b - Backplate state]]
000c - (16-bit values: pir, px1, px1 divisor, px2, px2 divisor, alir, av)
0010 - (24-bit data)
0014 - (16-bit data)
[[#Get version|0018 - Get version (response)]]
[[#Get build info|0019 - Get build info (response)]]
001b - (24-bit data)
001c - (24-bit data)
001d - (16-bit data)
[[#Get hardware version?|001e - Get hardware version? (response)]]
[[#Get firmware hash?|001f - Get firmware hash? (response)]]
0022 - (every 30 seconds; 4, 8, 20, 28, 36, 56, 60, 54, 68, 72, or 176 byte data)
0023 - (6, 12, 30, 42, 54, 78, 84, 90, 96, 102, 108, 144, or 150 byte data)
0025 - (2, 4, 12, 14, 20, or 24 byte data)
0027 - (8, 16, 48, 56, 80, or 96 byte data)
0029 - (6, 12, 36, 42, 60, or 72 byte data)
002b - (8, 16, 24, 32, 40, 128, or 152 byte data)
002f - (every 30 seconds; 16-bit data; "end of buffers ACK" log msg)

=== Backplate state ===
Data:
* 8-bit "state"
* 8-bit "flags"
* 8-bit "px0" (may be wider?)
* 40-bit UNKNOWN (includes at least "p2" and "voc")
* 16-bit centi-volts "vi"
* 16-bit milli-volts "vo"
* 16-bit milli-volts "vb"
* 8-bit ("pins" or "wires")
* 8-bit ("wires" or "pins")
* 16-bit UNKNOWN

=== FET control ===
Turn on W1: d5aa96 8200 0200 00 01 29a2
Turn off W1: d5aa96 8200 0200 00 00 08b2
Turn on Y1: d5aa96 8200 0200 01 01 1891
Turn off Y1: d5aa96 8200 0200 01 00 3981
Turn on G : d5aa96 8200 0200 02 01 4bc4
Turn off G : d5aa96 8200 0200 02 00 6ad4
Turn on OB: d5aa96 8200 0200 03 01 7af7
Turn off OB: d5aa96 8200 0200 03 00 5be7
Turn on W2: d5aa96 8200 0200 04 01 ed6e
Turn off W2: d5aa96 8200 0200 04 00 cc7e
Turn on Y2: d5aa96 8200 0200 07 01 be3b
Turn off Y2: d5aa96 8200 0200 07 00 9f2b
Turn on * : d5aa96 8200 0200 0b 01 d37e
Turn off * : d5aa96 8200 0200 0b 00 f26e

For the sake of documentation, we will refer to the unique id numbers for each wire as "wire id numbers".
So wire id 0 is W1, wire id 1 is Y1, wire id B is *, etc.

=== FET presence ===
The backplate will, at least upon connection, send information about which FETs have a wire present.
This data is received with command ids 0004 and 0009, in that order.
Each sensor is represented by one byte which is either 00 (not present) or 01 (present).

The content of 0004 is in order of the "wire id numbers" used for control:
W1, Y1, G, OB, W2, ?0, ?0, Y2, ?1, ?1, ?0, *, ?0

The content of 0009 is arranged differently and has 2 more values:
W1, Y1, ?1, ?1, ?0, G, OB, W2, ?0, Y2, ?0, *, ?0, ?0, ?0

After these are received, the display sends back command 008f with the exact data from message 0004.
Message 008f does not itself receive any response.

=== Get build info ===
Message 0099 (no data) requests the backplate report information about its build.
The response will be message 0019 in ASCII (one line, no trailing newline).

=== Get firmware hash? ===
Message 009f (no data) requests the backplate report a 64-bit hexadecimal value, probably a hash of the firmware (since Nest's software requests it at the same time as version and build info).
The response will be message 001f in uppercase ASCII.

=== Get hardware version? ===
Message 009e (no data) requests the backplate report a "Backplate-"X.Y version string.
Since the firmware file on the display CPU uses these strings as "MinApplicability" and "MaxApplicability" ranges, it is probable they refer to the hardware.

Witnessed versions:
"Backplate-2.8" - Florida Lowes

=== Get version ===
Message 0098 (no data) requests the backplate report its version number.
The response will be message 0018 in ASCII.

=== Temperature reading ===
The backplate will send message 0002 every 30 seconds.
The data contains two 16-bit numbers, which nlclient logs in decimal.
The first number is the temperature in centi-celcius.
The second number is the humidity in per-millis.

=== Request info ===
At least upon connection, the display sends message 00ff to the backplate to request information.
This takes just under half a second, so it may trigger some initialisation as well.

The backplate answers with:
0001 msg "<version> <build timestamp "YYYY-MM-DD HH:MM:SS"> K"
[[#FET presence|0004 FET presence]]
[[#FET presence|0009 FET presence]]
0001 msg "*sense 06d1 06d0 0001 0001 0000 0000 0000 0001 06d9 06d8 06d8; detect 09d3 065c"
0001 msg "BRK"

== Run BeagleBone/Debian programs ==
ln -s . /lib/arm-linux-gnueabihf
ln -s ld-2.11.1.so /lib/ld-linux-armhf.so.3

Nest Hacking

2014-07-27T04:21:22Z

Luke-Jr: /* Get hardware version? */

Nest Hacking

2014-07-27T04:19:21Z

Luke-Jr: /* Command ids */

Nest Hacking

2014-07-27T04:15:55Z

Luke-Jr: /* Get firmware hash? */