USB communication

Introduction

The ioNode's micro-USB port allows flashing it from a computer, but that's not the only use.

The ability to communicate easily with a host computer offers many possibilities including logging, monitoring, control and user interfacing.

The 'scom' library allows very 'raw' access to this, offering many different usage possibilities. On the other hand, the 'scli' library provides a much higher level of abstraction. SCLI is actually a 'USB command-line interface' framework, allowing us to define commands and parse their arguments with ease.

Note: like most tutorials, this makes use of eloop and the substrate system.

How it works

The ioNode features a USB-to-UART chip. One side of the chip is wired to the first UART (UART0) of the atmega1284p microcontroller. The other side of the chip is hooked to a micro-B USB connector.

From the point of view of a host computer, this makes the ioNode appear as just another 'serial port' device (COM ports on windows or /dev/ttyUSB on linux).

This means that "talking through USB" is in fact extremely simple - we just need to use the UART0.

Note: UART communication makes use of AVR interrupts - don't forget to call 'sei()' (to enable interrupts) after your initialization (unless you're using the substrate system, which takes care of calling it for you).

The scom library

The scom library makes it relatively easy to read and write through USB.

Basic usage

Let's see how to use the scom library to read and write through USB.

Initialization

First, we need to initialize scom by calling 'scom_init', which requires a RX buffer and possibly some callbacks:

/* Initialize SCOM
 * rxbuf -> Pointer to a buffer to be used by scom
 * rxbuf_size -> Size of the buffer pointed to by 'rxbuf'
 * rx_callback -> Callback function to be called when a byte is received (x is the received byte)
 * overflow_callback -> Callback function to be used when a receive overflow occurs (x is the received byte)
 */
void scom_init(uint8_t *rxbuf, uint8_t rxbuf_size, void (*rx_callback)(uint8_t x), void (*overflow_callback)(uint8_t x))

Writing

We can then send data by calling either 'scom_write' for a single byte:

/* Send a single byte
 * d -> Byte to send
 */
void scom_write(uint8_t d)

or 'scom_send' for an array of bytes:

/* Send an array of bytes
 * d -> Pointer to array of bytes to send
 * s -> Number of bytes to send
 */
void scom_send(uint8_t *d, uint8_t s)

Reading

Once interrupts are enabled, our 'rx_callback' will get called everytime a byte is received through the UART:

/* Receive callback
 * x -> Byte received through UART
 */
void example_rx_callback(uint8_t x)
{
    // do something with 'x'...
}

When a byte is received, it is also stored in the RX buffer that was supplied to 'scom_init' earlier. If that buffer completely fills up, our 'overflow_callback' will also get called for every byte that can't be stored into it (due to being full).

Both of these functions (rx_callback & overflow_callback) will be called directly from the interrupt service routine, which means they must execute in the shortest time possible so as not to block any other interrupts.

When some data from the RX buffer has been processed and can be discarded to free up the buffer, we can call the following:

/* Free up some data from the RX buffer
 * s -> Number of bytes to free
 */
void scom_consume(uint8_t s)

Note: don't call this method from within an interrupt routine, it may take longer than expected and block other interrupts. Basically, don't call this from your rx_callback or overflow_callback!

Example

Here is a complete example using scom:

dfe.conf:

name: scom_example
type: app
mmcu: atmega1284p
freq: 10000000
deps:
  - eloop
  - scom

scom_example.c:

 1 #include <scom/scom.h>
 2 
 3 #include "substrate.h"
 4 
 5 // RX Buffer for SCOM
 6 #define RXBUF_SIZE 128
 7 uint8_t rxbuf[RXBUF_SIZE];
 8 
 9 // RX Callback
10 void on_rx(uint8_t x)
11 {
12     // Received a byte, simply echo it back
13     scom_write(x);
14 }
15 
16 // Overflow Callback
17 void on_overflow(uint8_t x)
18 {
19     // RX Buffer is full!
20 }
21 
22 // Initialization
23 void init()
24 {
25     // Initialize SCOM
26     scom_init(rxbuf, RXBUF_SIZE, on_rx, on_overflow);
27 
28     // Initialize Substrate
29     substrate_init();
30 
31     // Send 'hello\n'
32     scom_send((uint8_t *)"hello\n", 6);
33 }
34 
35 // Main Loop
36 void loop()
37 {
38     // Update Substrate
39     substrate_loop();
40 
41     // Don't keep any data in the RX Buffer
42     if(scom_rxbuf_pos) { scom_consume(scom_rxbuf_pos); }
43 }

Text-mode Terminal (scom_term)

If you will be exchanging text-based messages, maybe the 'scom_term' abstraction is a better fit for you.

Here, you can send complex text using format strings. Also, you don't need to implement a callback function to handle every character. Instead, scom_term will call back your function for every line of text that is received. Finally, this will be called as part of the main loop, NOT in the interrupt handler, which means much less complexity.

One important difference to note here is the need to periodically update the scom_term system by repeatedly calling 'scom_term_update' from your main loop.

Initialization

Let's start by initializing scom_term by calling 'scom_term_init'. This time, only a single callback is required, which will be called for each line of text received through the UART:

/* Initialize SCOM Terminal
 * rx_callback -> Callback function to be called when a line of text is received (x is the text, s is the length)
 */
void scom_term_init(uint8_t (*rx_callback)(uint8_t *x, uint8_t s))

Writing

Sending text is easier with 'scom_term':

/* Send some text
 * fmt -> Format string
 */
void scom_term_printf(char *fmt, ...)

Please have a look at format strings to get more details about what can be printed.

Reading

Once interrupts are enabled, our 'rx_callback' will get called everytime a full line of text is received through the UART:

/* Receive callback
 * x -> Pointer to text
 * s -> Size of text in bytes
 * Return value: number of bytes consumed
 */
uint8_t example_rx_callback(char *x, uint8_t s)
{
    // do something with 'x'...

    return 0;
}

Because this rx_callback will be called from the main loop (and not some interrupt routine), we can call 'scom_consume' directly from it if we need to. However if we do, we must indicate it by returning a non-zero value.

Most cases should return 0 and let 'scom_term' manage the RX buffer itself.

History

The 'scom_term' abstration also includes input history management.

To push a line of text to the history, use the following:

/* Push history
 */
void scom_term_hist_push(char *s, uint8_t l)

Example

Let's now have a look at a complete example using scom_term:

dfe.conf:

name: scom_example
type: app
mmcu: atmega1284p
freq: 10000000
deps:
  - eloop
  - scom

scom_example.c:

 1 #include <scom/term.h>
 2 
 3 #include "substrate.h"
 4 
 5 uint8_t ask_name;
 6 
 7 // RX Callback
 8 uint8_t on_rx(char *x, uint8_t s)
 9 {
10     if(ask_name)
11     {
12         scom_term_printf("hello there, %t! nice to meet you!\n", x, s);
13         ask_name = 0;
14     }
15 
16     return 0;
17 }
18 
19 // Initialization
20 void init()
21 {
22     // Initialize SCOM Terminal
23     scom_term_init(on_rx);
24 
25     // Initialize Substrate
26     substrate_init();
27 
28     // Send 'hello\n'
29     scom_term_printf("hello\n");
30     scom_term_printf("what is your name? ");
31     ask_name = 1;
32 }
33 
34 // Main Loop
35 void loop()
36 {
37     // Update Substrate
38     substrate_loop();
39 
40     // Update SCOM Terminal
41     scom_term_update();
42 }

The scli library (Serial Command-Line Interface)

Instead of using 'scom' directly (or even the 'scom_term' abstraction), most applications will use the 'scli framework.

Once initialized, scli handles lines of text received over USB, matching them against a set of registered commands. If the command is found, its associated handler function is called to perform any actual work. The handler can parse arguments easily using mechanisms provided by the scli framework.

The scli framework also takes care of displaying a 'hello' message upon boot, as well as displaying a customizable prompt to the user on each line.

Two basic commands are included in scli and automatically provided:

  • clear -> Clears the screen by printing a large number of empty lines.
  • help -> Displays the list of available commands

How to use

To use scli, we first need to initialize it by calling scli_init. Then we need to update it by calling scli_update repeatedly from our main loop.

We can choose to do this ourselves, but obviously it is recommended to use the provided substrate generator to make things easier.

Obviously, we will need to add 'scli' to our dependencies in dfe.conf before anything:

name: scli_example
type: app
mmcu: atmega1284p
freq: 10000000
deps:
  - eloop
  - scli

Without substrate

If you're not using the substrate system, the example below shows how to use scli:

 1 #include <scli/scli.h>
 2 #include <avr/interrupt.h>
 3 
 4 // Initialization
 5 void init()
 6 {
 7     // Initialize Serial Command Line Interface
 8     scli_init();
 9 
10     // Enable Interrupts
11     sei();
12 }
13 
14 // Main Loop
15 void loop()
16 {
17     // Update SCLI
18     scli_update();
19 }

With substrate

If using the substrate system, just add 'uses :scli' to your substrate file.

substrate:

uses :scli

That's it! Just make sure you initialize and update your substrate (the usual stuff).

 1 #include "substrate.h"
 2 
 3 // Initialization
 4 void init()
 5 {
 6     // Initialize substrate
 7     substrate_init();
 8 }
 9 
10 // Main Loop
11 void loop()
12 {
13     // Update substrate
14     substrate_update();
15 }

Not only is this much cleaner and easier, but doing this through substrate has another great advantage: many other libraries provide SCLI commands and will auto-inject them through substrate if scli is 'used'.

Creating commands

To register a new command, we will use the 'scli_def_cmd' function:

/* Define a new command
 * c -> Pointer to scli_cmd structure
 * cmd -> Command name
 * handler -> Callback function for the command
 */
void scli_def_cmd(struct scli_cmd *c, char *cmd, void (*handler)(char **args, uint16_t *args_len))

When our command is used, scli will call our handler function, passing it two pointers.

These pointers can be used with the generic str_next_arg function (provided by the util library) to extract any arguments that may have been passed to our command:

 1 #include <scli/scli.h>
 2 #include <util/str.h>
 3 
 4 #include "substrate.h"
 5 
 6 // Structure to hold our example command
 7 struct scli_cmd example_cmd;
 8 
 9 // Handler function for our example command
10 void example_cmd_handler(char **args, uint16_t *args_len)
11 {
12     char *arg;
13     uint16_t len;
14     uint16_t i;
15 
16     // Run through all arguments
17     i = 0;
18     while(str_next_arg(args, args_len, &arg, &len))
19     {
20         // Echo back individual arguments
21         scli_printf(" argument %i -> %t\n", i, arg, len);
22 
23         // Increase argument counter
24         i = i + 1;
25     }
26 }
27 
28 // Initialization
29 void init()
30 {
31     // Initialize substrate
32     substrate_init();
33 
34     // Register our example "echo" command
35     scli_def_cmd(&example_cmd, "echo", example_cmd_handler);
36 }
37 
38 // Main Loop
39 void loop()
40 {
41     // Update substrate
42     substrate_loop();
43 }

If we're using the substrate, commands can be registered in a nicer way (no need to declare a structure to hold the command) directly from there:

register_scli_cmd cmd: 'echo', meth: :example_cmd_handler

This removes the need to call 'scli_def_cmd' with a pre-allocated scli_cmd structure.

Like most things in the substrate, it doesn't matter where you place this 'register_scli_cmd' - it will work the same whether you place it before or after.

Setting a hello message

Having a 'hello' message be displayed after initialization is often a nice addition for an external interface.

We can achieve this simply by calling 'scli_init_m' instead of the classic 'scli_init'. This other version of the initialization function expects a format string hello message that will be displayed just after initialization completes.

 4 // Initialization
 5 void init()
 6 {
 7     // Initialize Serial Command Line Interface with hello message
 8     scli_init_m("Hello there!\nThis is a neat CLI, have fun :)");
 9 
10     // Enable Interrupts
11     sei();
12 }

Of course, if you're using the substrate system, things are much easier - just add the 'hello' parameter to your substrate:

uses :scli, hello: 'Hello there!\nThis is a neat CLI, have fun :)'

Changing the prompt

By default, scli has an empty ("") prompt. This can be changed at any moment by calling 'scli_set_prompt' (or 'scli_set_prompt_n' if the prompt string is not zero-terminated):

/* Change the scli prompt
 * prompt -> Pointer to the prompt string
 */
void scli_set_prompt(char *prompt)
/* Change the scli prompt
 * prompt -> Pointer to the prompt string
 * len -> Length of the prompt string
 */
void scli_set_prompt_n(char *prompt, uint8_t len)

Again, this can also be done through the substrate:

uses :scli, hello: 'Hello there!\nThis is a neat CLI, have fun :)', prompt: ' ~> '

Command whitelisting

The substrate system allows other firmware elements (libraries) to register commands with SCLI (only if SCLI is included in the target, otherwise nothing is done).

However, there may be times where we don't want all of those extra commands. For such cases, the 'cmd_whitelist' parameter allows restricting which commands will be loaded by passing it a whitelist - an array of commands that should be allowed:

uses :scli, hello: 'Hello there!\nThis is a neat CLI, have fun :)', prompt: ' ~> ', cmd_whitelist: [ :pwm_set, :vfs_mount, :vfs_ls ]

Talking to the device from a linux host

Once our application is ready, we can build it, flash it into an ioNode and start talking to it - but how?

On linux, many solutions exist for actually using this '/dev/ttyUSB'. The one we use here at Dooba most of the time is GNU Screen, which is easy to use and readily available in all major linux distributions (just try 'apt-get install screen' or 'yum install screen' or something like that :D).

By default, the scom stack (on top of which scli stands) is configured to operate at 19200 baud. This means that in order to talk to it, we must run screen as follows (assuming our ioNode is '/dev/ttyUSB0'):

screen /dev/ttyUSB0 19200

To exit, you can use the 'CTRL+a d' keyboard sequence. An interesting list of keyboard sequences for screen can be found here: https://www.gnu.org/software/screen/manual/screen.html#Default-Key-Bindings