The TH12 th12 is an internet connected low-power wireless temperature and humidity sensor. It uses 2xAA batteries and has 3 to 5 years of run life with the standard configuration parameters.

The TH12 th12 uses [6LoWPAN] 6lp and RPL rpl to autoconfigure a globally routeable IPv6 address. Once connected, you interact with it using CoAP coap, a RESTful UDP based protocol.

This software is based on the Contiki Operating System and is released under the same open source license.

The TH12 hardware will also be available as open hardware soon.

On power up, the RED led flashes on. The TH12 then stays awake for wake_time seconds. During this time, RPL rpl is establishing the IPv6 address for the TH12 th12. Once the routing has been established, the TH12 th12 will POST its sensor data as a JSON to the configured location (default is coap://coap-8.lowpan.com/sink).

An example reading is below:

    {"t":" 24.5C","h":"18.7%","vb":"3048mV"}

The eui field is the EUI64 mac address of the TH12 th12 reporting node. t is the current temperature, h is the humidity, and vb is the battery voltage.

The TH12 th12 reports this data at the specified interval and periodically checks that the other end is listening (if not, the TH12 th12 does the best that if can to recover. For details see Recovering from Errors).

If the POST is sucessful, and the TH12 is not in low-power mode, then the GREEN led will turn on.

Most of the time the TH12 th12 lies dormant with its radio completely off. In this mode it draws a very small amount of current (12 uA) from its batteries and therefore consumes very little power. There are also some very efficient power converters that strive to get the most from your batteries. See the Wake Current analysis for more details.

There are several parameters that can be configured in the TH12. The are all under the /config resource. You GET or POST to them using the param=foo query string:

The following example uses coap-client from libcoap to perform a GET on the netloc parameter; it returns the host part of the location the TH12 will POST its data to:

coap-client coap://[2002:c63d:eeef:8:ee47:3c4d:12bd:d1ce]/config?param=netloc

returns:

coap-8.lowpan.com

To set this parameter, POST the desired value to it.

Copper is also a nice add-on to Firefox that implements coap://. For the receiving, sink side, we recommend Californium which is a Java server. For CoAP in embedded devices, see Erbium, which is included in Contiki, and/or SMCP. The current TH12 software implements CoAP-07/08. The TH12 firmware will be updated once the IETF finalizes the RFC.

The default values should result in a properly posting TH12 lasting for approx. 5 years on 2x AA batteries. If it is failing to post then it would fail for 2.5 years. See the Runtime spreadsheet for details.

The TH12 th12 does the best it can to recover from errors. Periodically, according to the value of posts_per_check, the TH12 th12 sends a "confirmable" POST (using a CoAP CON message). This type of POST instructs the sink that an acknowledgment of the POST should be sent. In addition, CON messages will also be retried 4 times over 60 secs to help ensure that they arrive in a lossy network environment. All other times, the TH12 th12 sends a "non-confirmable" (NON) message which is essentially a single raw UDP datagram.

The 60 second timeout for a CON message is particularly costly as the radio's receiver needs to stay ON during this time. For this reason, the TH12 th12 only performs these "sink checks" infrequently. If max_post_fails number of "sink checks" fail, then the TH12 th12 assumes the worst and reboots.

Also aside from using CON during these sink checks, the TH12 th12 does a fresh DNS lookup for the sink. In this way, the sink ip address can change with minimal disruption; the TH12 th12 will get the new address once the DNS has propagated.

TS Mist uses NAT64 to operate a ipv6 site-local address space corresponding to your RPL DAG behind a NAT that can interface with the ipv4 Internet. As it's a NAT the normal rules apply, you can initiate connection out of the NAT (and get responses), but not the other way. The 6-4 address translation happens automatically by Mist.

Mist uses a special prefix to indicate that the ipv6 address should get translated and NAT'd to an ipv4 address. This prefix is ::ffff:0/8

Lets say the server you'd like to post to is at 209.208.27.17. Then you'd configure the TH12 to post to ::ffff:d1d0:1b11 (d1d0:1b11 == 209.208.27.17).

As the NAT makes it difficult to initiate downstream connections, the only practical way to configure the TH12 in this setup is to use the #defines in coap-post-sleep.c. You want to clear out the hostname to post to and hardcode in the special ipv6 address. The typical way Thingsquare devices get around this is to use websockets (which is not a COAP-ish thing). In the future there may be websocket based firmware available for the TH12 but currently there is not.