twine.md

Hacking a Twine

I got a Twine the other week because I was interested in tracking temperature and moisture readings from my house, particularly to know if something is flooding.

Once setup, the Twine sends periodic readings of its temperature sensor and any external probes (moisture sensor) to the Supermechanical site. I was disappointed to find that there isn't currently a way to access those periodic readings. You can set rules that fire if certain conditions are crossed (e.g. temp above 80) and push data out. However, there is currently no way to build a time-series graph of those readings over time.

These are my notes from spending a few hours poking around the Twine to see how it operated. I would love to know if others have/do get farther in any analysis.

Wifi specs

The Twine uses the GainSpan Wifi module to connect to the Internet. See this thread for datasheet links: http://community.supermechanical.com/index.php?p=/discussion/comment/651#Comment_651

Turning on the Webserver

The Twine does not appear to listen on any ports unless it is in setup mode. To trigger setup mode you simply turn the Twine upside down (you may also need to remove/replace the batteries to trigger it if it has gone to sleep). In setup mode the Twine will:

1. Create the WAP "\III Twine"
2. Listen on the static address 192.168.240.1
3. Open an HTTP API on port 80.
4. Resolve all lookups for "twinesetup.com" to 192.168.240.1.

APIs

The Twine runs an API on port 80 that responds to a variety of requests under http://twinesetup.com/<...>. All responses I found were in XML format. The server responds with the following header:

Server: $ProjectRevision: 4.2.2.12 $

I found the following requests to respond:

• GET /gainspan/system/config/httpd

<httpd><username>twine</username><password>twine</password><port>0</port></httpd>

Not sure what this is for. I didn't find that I needed to enter a username/password to access the twine.

• GET /gainspan/system/api/version

<version>0.8.0</version>

API version of firmware?

• GET /gainspan/system/config/network

<network><mode>limited-ap</mode><client><wireless><channel>6</channel><ssid>shamu</ssid><security></security><wepauth>(null)</wepauth><password>{password}</password></wireless><ip><ip_type>dhcp</ip_type><ip_addr>0.0.0.0</ip_addr><subnetmask>255.255.255.0</subnetmask><gateway>0.0.0.0</gateway><dns_addr>0.0.0.0</dns_addr></ip></client><reg_domain>fcc</reg_domain></network>

Wifi configuration. Currently connected to a WAP named "shamu".

• POST /gainspan/system/config/network

Used to update saved network configuration. Payload is the same as above.

• GET /gainspan/system/prov/scan_params

<scan_params><channel>0</channel><ssid_filter>*</ssid_filter><scan_time>150</scan_time></scan_params>

• GET /gainspan/system/prov/ap_list

<ap_list><ap><index>1</index><ssid>shamu</ssid><rssi>58</rssi><nw_type>infra</nw_type><security>wpa-personal</security><channel>6</channel></ap><ap><index>2</index><ssid>wifi-guest</ssid><rssi>36</rssi><nw_type>infra</nw_type><security>none</security><channel>11</channel></ap><ap><index>3</index><ssid>wifi</ssid><rssi>36</rssi><nw_type>infra</nw_type><security>wpa-personal</security><channel>11</channel></ap></ap_list>

Lists found WAPs.

• GET /gainspan/profile/tls/config

<tls_params><data_server_ip>107.21.16.90</data_server_ip><data_period>10</data_period><data_type>udp</data_type><data_port>8255</data_port><snmp_server_ip>(null)</snmp_server_ip><sntp_server_ip>{8-byte hex ident}</sntp_server_ip></tls_params>

This is the current configuration data for the Twine. The data_server_ip (107.21.16.90) maps to the server "twine.supermechanical.com" which is an EC2 server. The {8-byte hex ident} (removed for security) appears to be the ID of the Twine box.

Once configured, the Twine will periodically push UDP packets to the data_server_ip address on port 32887.

• POST /gainspan/profile/tls/config

You can POST the XML payload above back to this URL to change the settings. I've only tried changing data_server_ip and sntp_server_ip. You can change the data_server_ip, but you don't appear to be able to change sntp_server_ip.

By changing the data_server_ip I was able to get the Twine to post data to a specific IP, by which I could then dump the packet contents with Wireshark.

UDP Packets

The periodic updates the Twine sends are UDP packets sent to twine.supermechanical.com on port 32887. The payload is 274 bytes and the first 8 bytes are the sntp_server_ip from above. I haven't done much more analysis on the packets beyond that.

Having a full definition of the packet format would mean that, in theory, you could point the Twine to a custom address and record the sensor readings over time.

Nice job! I managed to post data to a branded smart plug (which also includes a Gainward chip), but I didn't manage to have it send the data to the specified server (I registered both the smart plug and the server in the same lan). Is it something I do wrong?