Difference between revisions of "Nest Hacking"

Latest revision as of 20:21, 3 January 2017

Hardware

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 NestDecode.pl, or decoded in real time using 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: 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 00ff - Reset
Recv 0001 - (message from backplate; ASCII)
Recv 0004 - FET presence
Recv 0009 - FET presence
Send 008f - FET presence
Send 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 0098 - Get Mono/TFE version
Recv 000a - (every second; 16-bit data)
Recv 0007 - (every second; 16-bit data)
Recv 0018 - Get Mono/TFE version (response)
Send 0099 - Get Mono/TFE build info
Recv 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 009b - Get BSL version
  Recv 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 009f - Get serial number
Recv 001f - Get serial number (response)
Send 009e - Get hardware version
Recv 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
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

0082 - FET control
0083 - Periodic status request
008f - FET presence
0090 - get Mono/TFE id (no data; response 0010 with 3 bytes)
0091 - Backplate firmware upload (start)
0092 - Backplate firmware upload
0093 - Backplate firmware upload (finish)
0098 - Get Mono/TFE version
0099 - Get Mono/TFE build info
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)
009e - Get hardware version
009f - Get serial number
00a1 - quiet (16-bit max sleep seconds)
00a2 - Request "buffers" (every 30 seconds; no data; triggers [0025] [0027] 0022 0023 [0029] [002b] 000c 002f)
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
00ff - Reset

Backplate to display

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

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:

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.

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"
0004 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