Wednesday 28 May 2014

How to generate source code documentation in TinyOS (nesdoc)

TinyOS uses Nesdoc to generate documentation from source code (as Doxygen does), to build the documents (found later in $TOSROOT/doc folder under your platform name) just type (and replace with your platform's name):
make platform docs
This should go smoothly but... there are small things to tweak, for example:

error: StorageVolumes.h: No such file or directory
If you include the STM25P component (external flash memory support), if fails locating StorageVolumes.h file, as this file is generated in build time from the definitions in your platform's target file (at tos/support/make):

VOLUME_FILE = volumes-stm25p.xml
VOLUME_ALLOCATOR ?= tos-storage-stm25p
One quick work-around is to previously build the application and then copy the generated StorageVolumes.h file from the resulting build/platform location to your application path, then run the make docs command again.

I did found the following errors:

Traceback (most recent call last):
  File "/usr/lib/tinyos/nesdoc/archive.py", line 352, in <module>
    doc.writexml(ifile)
  File "/usr/lib/python2.7/xml/dom/minidom.py", line 1751, in writexml
    node.writexml(writer, indent, addindent, newl)
  File "/usr/lib/python2.7/xml/dom/minidom.py", line 816, in writexml
    node.writexml(writer, indent+addindent, addindent, newl)
  File "/usr/lib/python2.7/xml/dom/minidom.py", line 816, in writexml
    node.writexml(writer, indent+addindent, addindent, newl)
  File "/usr/lib/python2.7/xml/dom/minidom.py", line 816, in writexml
    node.writexml(writer, indent+addindent, addindent, newl)
  File "/usr/lib/python2.7/xml/dom/minidom.py", line 816, in writexml
    node.writexml(writer, indent+addindent, addindent, newl)
  File "/usr/lib/python2.7/xml/dom/minidom.py", line 812, in writexml
    self.childNodes[0].writexml(writer, '', '', '')
  File "/usr/lib/python2.7/xml/dom/minidom.py", line 1040, in writexml
    _write_data(writer, "%s%s%s" % (indent, self.data, newl))
  File "/usr/lib/python2.7/xml/dom/minidom.py", line 297, in _write_data
    writer.write(data)
UnicodeEncodeError: 'ascii' codec can't encode characters in position 244-245: ordinal not in range(128)


Just edit archive.py (see error log for details on its location and change:
--- /usr/lib/tinyos/nesdoc/archive_old.py
+++ /usr/lib/tinyos/nesdoc/archive.py
@@ -1,4 +1,5 @@
 # -*- python -*-
+# -*- coding: utf-8 -*- 
 # Copyright (c) 2005 Intel Corporation
 # All rights reserved.
 #
@@ -43,6 +44,7 @@
 from nesdoc.graph import generate_graph
 from nesdoc.html import *
 import os
+import codecs

 def check(x):
   if not x:
@@ -292,7 +294,7 @@
       refd.appendChild(qnameidx[qname].cloneNode(True))
     doc.appendChild(copy)
-    ifile = file(filename, "w")
-    doc.writexml(ifile)
+    ifile = file(filename, "wb")
+    doc.writexml(codecs.open(filename, 'wb', 'utf-8'), encoding='utf-8')
     doc.unlink()
     ifile.close(

And this one:

Traceback (most recent call last):
  File "/usr/lib/tinyos/nesdoc/genhtml.py", line 96, in <module>
    generate_component(ixml.documentElement)
  File "/usr/lib/tinyos/nesdoc/components.py", line 91, in generate_component
    ht.pdoc(idoc)
  File "/usr/lib/tinyos/nesdoc/html.py", line 149, in pdoc
    self.p(self.escape_email(val))
  File "/usr/lib/tinyos/nesdoc/html.py", line 51, in p
    self.f.write(s)
UnicodeEncodeError: 'ascii' codec can't encode characters in position 2-3: ordinal not in range(128)

As done above, edit the html.py file with the following: 

--- /usr/lib/tinyos/nesdoc/html_old.py
+++ /usr/lib/tinyos/nesdoc/html.py
@@ -48,7 +48,7 @@
     if self.at0:
       self.f.write(" " * self.ind)
       self.at0 = False
-    self.f.write(s)
+    self.f.write(s.encode('utf-8'))

   # print a string and end the line
   def pln(self, s): 

Afterwards the documentation can be viewed and navegated through by browsing the generated index.html file at $TOSROOT/doc/nesdoc/platform:

Nesdoc output: components, interfaces and wirings

Sunday 25 May 2014

Stumbled on (2): What most Schools don't teach

I wasn't able to post anything last Sunday due to my daughter's birthday, so this week stumbling upon arrives a bit late, anyway today I found a video interesting to show to non-coders and specially to parents and youngsters: this new world is more about bits than atoms, coding and programming it is not reserved only to Computer Science majors, but to anyone willing to learn... sadly neither my school or college taught me how to code, so I was a late bloomer and an autodidact (now I code for a living), perhaps the video below can give you more reasons to start early.

What most Schools don't teach (core.org)

Some of the biggest names in tech and Hollywood have joined forces in a new video for Code.org, a non-profit focused on computer programming education, to encourage students to take coding classes.

First stumbled by Alicia1321.
Source: Code.org

Monday 12 May 2014

Using Telecom Design's TD120x as a SIGFOX gateway with a Z1 mote


As mentioned in an earlier post, I recently got a demo kit from SIGFOX and finally I had some time to start playing with.

I had a head start and told that the starter kit was based on Telecom Design TD1204, which provides a serial AT-based modem to allow communication over a serial link, so it made easier testing using software tools like PuTTY, Hercules and then moving to a Zolertia Z1 mote to drive the TD1204 over its serial port (at the end of the post!).

Note: You need to have a device registered in the TelecomDesign cloud or the SigFox backend for some of the following steps, but nevertheless is is interesting to watch and to take a peep inside.

 

SIGFOX Back-end


I started by browsing the web-based SIGFOX backend, by clicking on the Device tab (as shown below) we can see the devices associated to our account, my starter kit device appears listed there.



I work in Barcelona, so I was interested in checking if my workplace is under SIGFOX coverage area, so by clicking the Location tab at the left it is shown an approximate coverage map.  (btw, I have tried pushing a message while at home in Cerdanyola del Vallès, but it didn't reach the network, but generally in Barcelona the coverage is OK).  At first glance it made more sense to me to represent the light blue area as a circle rather than using a square, but as I'm not sure of how this is modeled, it is fine as it is at the moment.


 Then the moment of truth, let's see what happens when I long-press-and-hold the button... once or twice to be sure, the message board is updated showing the content of the test message... I don't understand what the data means (180c62, 190c62), but I have a good idea about the rest of the fields...


  • Delay: Time (in seconds) elapsed since the message was triggered and then received by the network station.
  • TAP: Station receiving the message, as these stations are fairly identified you can get the estimated location of your device (a way estimated location).
  • RSSI: Received Strength Signal Indication: as shown we have values ranging from -124/-128dBm, as it was already discussed in my previous post, the sensitivity value is expected to be quite low, as the wireless range is favored by the low data rate and bandwidth.  In the  TD1204 EB page the sensitivity value is stated to be close to -126dBm, as we are using a 5dBi external antenna we can expect a boost (in one occasion I got a RSSI value of -132dBm, so this approximation seems to be OK).
  • Signal (dB)
  • Freq (MHz): channel used in the transmission, as shown above the channel is changed for every retransmission attempt.
  • Rep: Numbers of retransmission attempts needed for the packet to actually arrive to the network.
  • Callbacks: Event triggered upon receiving the packet, below is an example of the callback generated by the user-button event (an email is sent every time to a given email address):
          [OK] - TAP 0146 - 1 second
     200 -
     {device} (name@mail.com)

The maximum transmission power of the radio transceiver is 14dBm (for the TD1204 DK), but it would be interesting to check if SIGFOX allows devices to be on the ETSI G3 sub-band (869.4-869.65 MHz 500mW), one thing pending to confirm (in my previous post I assumed so).

 

Hands-on: connecting SIGFOX to a Z1 mote 


So OK, enough of using the user button and the backend (we will return to this later when setting callbacks and stuff), now let's move to the meaty part of the testing: sending a custom string message.  After checking the TD 1204 reference manual, I found the required serial settings to connect the starter kit to the PC:
  • Speed 9600 bps.
  • 8 data bits.
  • 1 stop bit.
  • No parity, no hardware/software flow control.
I first tested the serial communication using Hercules and the result was OK as expected (remember to add a carriage return at the end of the string, more information about the command/response expected format is found in the TD1204 reference manual, section 2.4).

.

After verifying the serial communication then I moved to wiring the starter kit to the Z1 mote.

At first It seemed a good idea to cut-off the male USB connector of an USB male to mini-USB cable, strip the wires and solder those to the Z1 mote, wiring D+/D- to the UART1's RX/TX (P3.7/P3.6), and power the starter kit by soldering GND/VCC to the Z1's USBGND/USB+5V (requiring to power the Z1 through its micro-USB port)... but this was a rather bad idea, as I noticed when connecting the TD1204 to the PC that it uses a FTDI chip, which are normally slaves thus requiring a master to communicate.  The Z1 mote has a CP210x serial-to-USB converter too, but my original intention was to use raw serial communication using a free UART port of the Z1 mote, so its USB port (wired to UART0) can be kept as a programming/debugging port, avoiding to use the JTAG port instead.


So the next logical step (off course, without a doubt) was to void the warranty and take a peek inside the demo kit... I love voiding warranties :-)

Finding the FTDI reference (FT232R-L package) chip was easy, as suspected there's a battery charger/Modem enabling circuit, a 1000mAh LiPo battery and the user button on one side, on the other we can see a TD1202 radio transceiver and AT-modem (sending an AT&V command is also a good way to find out about board-specifics).




Next I needed to locate the serial RX/TX lines going to the TD1202 transceiver to bypass the FTDI, following the FTDI pin-out and the PCB trace I noticed there were 2 0Ohm resistors standing between the FTDI and the modem, a nice gesture as it only required to apply a little heat and lift-up the resistors instead of cutting the PCB.  

The location of the RX (red), TX (white) and GND (black) pads are shown above, as well as the location of the resistors.  We cross-wired the Z1 and TD1202 RX/TX lines, and the DGND pin of the Z1 to GND.


I could also directly power the TD1202 using the Z1's 3.3V power reference, but honestly I was more interested in testing the communication between the Z1 and the board, than worrying about how to power the device, so I kept using the mini-USB port to power up the TD1202 through the 5V delivered by the Z1 connected via USB as shown below... a work to be done later is to replace the LiPo battery with one that has a larger capacity, and hook it up to a solar panel, but that's material for another post.

 

I used a logic analyser to verify the communication between the Z1 and the TD1202 was OK, and programmed the Z1 mote using TinyOS with a simple serial test sending an AT\n command every second, hoping to receive the AT command echoed back and an OK from the AT-modem, the result is shown below.


Here's the snippet of code used for the test.  The TMP102 temperature sensor callback event is shown on purpose, it will be used later to forward temperature readings from the mote.


Maybe someday I'll write a driver in Contiki/TinyOS to allow a more flexible and API-like way to communicate with the TD120x, or just port my sub-1GHz based mote to native support SIGFOX, but for preliminary testing sending raw strings is acceptable.

As the serial communication is asserted I can dump now the logic analyser and just print out the responses from the TD120x to console by modifying the code, adding a first print after boot to check out device information such as version.


Z1 with a SIGFOX interface


After checking the TD120x documentation the command to send data is quite straightforward:
AT$SS=[HEX1][HEX2]... [HEX12]

As mentioned before, up to 12 bytes can be sent in any transaction, more than enough for sending a 16-bit temperature reading from the Z1's built-in TMP temperature sensor.

The sending command expects a number of even hexadecimal "symbols" to be sent, meaning if you have 0x123 the modem will return an error, as it expects something like 0x0123.  All data should be sent encoded as hexadecimal, and leading zeroes might be needed depending on your data format.

After wiring my temperature sensor callbacks to be forwarded to SIGFOX the following messages were received, showing the mote was close to 28.5ºC at the moment of the test.  Most of my messages are being sent close to the 868Mhz frequency, maybe SIGFOX operates solely on the G1 sub-band?



The code used for testing is available at Github.

Wrapping up...


If you like to outgrown the demo, you could add more motes and add radio communication, and use the TD120x-enabled mote as a Gateway with dual wireless interface: sub-1GHz and 2.4Ghz, allowing to forward messages to SIGFOX while locally using other network topologies and protocols, not limited by SIGFOX packet size/throughput, only pushing important data and events such as alarms, periodic readings and others.

So this is the end of the post, I still need to test the callbacks and customising the TD120x using the SDK ,but this post has grown too much already, so I'll leave more for later.


Sunday 11 May 2014

Stumbled on: Cheat Sheets every IT should have

As usually on any given Sunday, stumbling upon while downloading stuff and preparing dinner sometimes leads to find hidden internet gems like the shown below... that's why I decided to create a post event on every Sunday called "Stumbled on".

 Cheat Sheets every IT should have

First stumbled by Kingrm.
Source: Packetlife.net cheat sheets

CISCO IOS interior Routing Protocols, taken from link above

A comprehensive collection of cheat sheets with a nice wall poster (90x60 cms) size print and available in .PDF format.

Enjoy!


Wednesday 7 May 2014

GIT: change location of SVN URL if using git-svn

Taken from: theadmin.org, GIT wiki and wiki.kuali.org

Taken from @CommitStrip
Recently I moved my work environment to a VM sandbox, requiring to change also the location of the SVN-based repositories and server hosted locally.  As my work environment is GIT-based, I normally use git-svn to synchronize my work onto a SVN mirror, maintained mostly due to a client requirement as they still use SVN.

One would thought this would be as simple to run svn switch --relocate or just edit the .git/config file and change the svn-remote URL, but then again, this is SVN..

Just in case I backed-up the svn server and the .git/config file, then I tried the instructions below:

   Edit .git/config and change the URL in svn-remote tag  
   git svn fetch  
   Edit again the .git/config file and replace the URL with the old one.  
   git svn rebase -l  
   Change (again) the URL at .git/config file to the new one.  
   git svn rebase.  

But this yielded no result, when trying to rebase I got the following error:
Unable to determine upstream SVN information from working tree history
As explained Here this will only works if the fetch command actually fetch anything, it was not my case, so I tried the following:

   git svn info # double check UUID's  
   git config svn-remote.svn.rewriteRoot OLD_URL.  
   git config svn-remote.svn.url NEW_URL.  
   git svn fetch --parent.  
   git svn rebase.  

This did the trick, as explained below this will not break the history as the old URL will still be used in the commits, but it didn't matter to me.
Git-svn couples git commits to the origin SVN repository by embedding the original SVN url in the commit. Changing this url will change the Git commit SHA (basically rewrite all your history). Google results furnish various elaborate schemes for reconfiguring and patching up the Git repo, but the safest approach involves using built-in support for "rewriting" the Git-svn root url. This effectively tells Git to continue using the original SVN url for purposes of Git history, but use an independent URL (the new location) for actually retrieving and commit deltas (you will have to live with the old url in your commit history, but most likely you will be the only one that sees that).
 

Thursday 1 May 2014

Unboxing and testing the Thingsquare IoT kit


Some months ago the Thingsquare folks hosted a contest to help spreading the world abouth Thingsquare and their wireless mesh networking and connectivity solution to the Internet of Things (see chached details about the contest here)... well, luckily I was one of the winners of the The Thingsquare IoT Kit (a limited edition unavailable now), featuring:
  • USB cables.
  • Ethernet cable.
  • SmartRF06 evaluation boards, featuring a LCD, buttons and plenty of test points, with on-board accelerometer, light sensor and UART back-channel over USB.
  • Radio System on a Chip (SoC) boards(TI CC2538-based), featuring an ARM Cortex M3-based MCU system with 32K RAM, 512 KB flash,  alongside a 2.4GHz radio transceiver, IEEE 802.15.4 compatible.
  • An Olimex MOD-ENC28J60-based Ethernet connectivity router.
  • Login credentials for the Thingsquare server.
  • Cool stickers!. 
Running on top of Contiki operative system of course.

Here it is after unboxing:

Thingsquare's IoT kit unboxed

The setup was quite straight-forward: 

Just assemble the Router-labeled node together, bundling the ethernet board onto the intermediate assembly board, on top of the SmartRF06 board (quite a sandwich there), and plug-in the CC2538EM with the router label.  Once the router was assembled I only had to connect it to one of my router's free LAN port through the provided ethernet cable, power the evaluation board through the uUSB port (be sure to enable powering via USB by moving the SOURCE switch to USB, and to place the jumper to connect VDD and EB power pins on the SoC board). 

After powering the board, a green LED next to the ethernet board should lit up and the yellow one will start blinking, another green LED on the board will start blinking until obtaining an IPv4 address from the router, the it will stop blinking... I did not catch this at first (an engineers motto taken from Tropic Thunder: we don't read manuals, manuals read us!), I was expecting "something" to show up on the LED display but no feedback there (I was tempted to replace the board's display to discard a broken unit), but as I was already on my routers box management utility, I found the assigned IP address given by the DHCP server, and test connectivity to the board with an extended ping.

To assemble the remaining nodes just plug in the SoC boards on top of the SmartRF06 boards, and power as above.  

A quick photo of both nodes back-to-back is show below:

Router and device back-to-back

The nodes will display the follow progress messages over the LCD display:
Waiting for wireless network
Waiting for Internet DNS
Waiting for server connection
Register PIN ##### at thingsquare.com
 If everything goes well then you should get a PIN number for each node (except the Router).

Registering the device is quite simple, at the Thingsquare's demo page just register the device and name it, the node's LED display will be updated quickly afterwards, in case you are wondering mine's Luffy (you can expect the rest of the tripulation to jump in anytime):

The node registered and ready

The demo has some cool stuff, what I liked the most was to actual develop code on the web browser and then remotely compile and flash the node, allowing to pause/continue the device after being programmed, and commanding the device to blink on request to assert it is running, simple but always useful, specially when introducing people to the IoT world and needing to show some real hardware doing wireless "stuff" (do not under appreciate the commercial power of a blinking LED!). 

Thingsquare browser-based IDE


The setup was simply enough to have it ready in 5 minutes, the demo page is very straight-forward to follow and the code examples and shown features briefly show the capabilities and possibilities of  the system, below are some cool examples of a sensor metering system and an intelligent street lighting deployment.



The development kit is quite complete and it was a great addition to my collection: TI evaluation boards are well suited for testing, prototyping and the TI CC2538 support on Contiki is coming along just great, and as Thingsquare actively contributes to Contiki (heck, the CEO is Adam Dunkels), one can expect nodes and products based on this SoC to be a popular choice amongst developers.

I will continue testing, I missed to take some wireshark pcap screenshots, so hopefully I will update this anytime soon.