Nano-RK

[[Image(timescope-board.png)]]

= FireFly TimeScope =

Have you ever wanted to throb a GPIO pin or hook an o-scope up to an LED for timing information? FireFly TimeScope is a utility built into all FireFly programmers that allows logic analyzer style debugging without interfering with  serial output or bogging down the microcontroller with the large blocking times required for serial, SPI or I2C data transfers.  Developers can assert and clear four different debugging gpio pins on the FireFly board that are captured by the programmer board and can be used to generate timing waveforms.  At the most basic level, this can be used to time various section of code.  APIs on the FireFly node can also use this interface to send 4 bits of high speed debugging data back to your computer to track state transitions.  The connections from the FireFly debugging board can even be linked to external logic devices that you wish to probe.  TimeScope will give you in the worst case a 258 microsecond sampling peroid (3.875KHz) due to the time it takes to send the three bytes of payload over the UART.  If signals do not occur back-to-back, then the factor limiting the resolution is the timestamping period of 36 microseconds (27.7KHz).

== How It Works ==

The USB FireFly programmer loads as two virtual serial port interfaces.  Normally, one serial port is used for debugging input and output while the second serial port can be used to download code to the FireFly board.  The code downloading is achieved using a dedicated processor on the programming board that translates serial commands into the AVR ISP flashing protocol.  The FireFly programming interface also connects various other GPIO pins from the main FireFly processor to the programming boards processor.  While not downloading, this second processor can monitor when pin changes occur on FireFly board and report these back to your PC over the second serial port.  We have a simple 3 byte serial protocol that sends the pin states along with a time stamp from the internal clock running on the programmer board.  The first byte can always be synchronized off of since it is the only byte with a 1 in the MSB.

[[Image(packet.png)]]

C3, C2, C1, and C0 stand for the different channels coming in and map to the NRK_DEBUG_0, NRK_DEBUG_1, NRK_DEBUG_2, and NRK_DEBUG_3 pins.  Mn is the nth bit of the most significant byte of the time stamp, while Ln refers to the nth bit of the least significant byte.  Whenever the there is a pin change or a timer overflow, a packet is transfered to the PC.

== How You Use It ==

 * '''Add debugging statements into your code'''

  * On the FireFly version 2.2 boards there are four debugging pins defined:

   * NRK_DEBUG_0, NRK_DEBUG_1, NRK_DEBUG_2 and NRK_DEBUG_3

  * They can be toggled as follows:

{{{

#!c

// toggle the pin state

nrk_gpio_toggle(NRK_DEBUG_3);

// set the pin

nrk_gpio_set(NRK_DEBUG_0);

// clr the pin

nrk_gpio_clr(NRK_DEBUG_2);

}}}

 * '''Download and run some code'''

  * As an example, try running the basic_tasks project

  * You will see here that not only do LEDs get toggled, but so do the NRK_DEBUG_x pins

 * '''Complile and Run TimeScope'''

  * You may wish to hold the FireFly board in reset before you run TimeScope so that you know that starting point of the waveform

  * Try running TimeScope as follows to generate a Decsim ascii waveform file:

{{{

> cd nano-RK/tools/TimeScope

> make

gcc -c -o main.o main.c -I.

gcc -o TimeScope main.o -I.

> ./TimeScope /dev/ttyUSB1 -DECSIM log.tra

}}}

  * In this example /dev/ttyUSB1 is the port that you normally program with and log.tra is the tracefile it will save

  * Be sure to close this when programming (press ctrl-c to kill it)

  * Below is a screenshot of it running with the normal terminal debugging on the right

[[Image(terminals.png,640)]]

 * '''View the data (Show You, Show Me)'''

  * TimeScope will generate two different data formats

   * Decsim ASCII as well as a raw ASCII format

  * Programs like [http://www.veripool.com/dinotrace/ DinoTrace] can be used to view the output

  * Below is a screenshot of dinotrace reading the waveform file from basic_task

[[Image(dinotrace.png,500)]]