I think that there’s a lot of people that might not understand how to use the command line shell that comes inside the FreakUSB release. Here’s a quick tutorial about how to add your own custom command to it.

Here’s the original code. I’m using the Tokyo Hackerspace development board and it already has a couple of commands, mostly for playing with the RGB LED. We’re going to add a command to toggle a GPIO.  

First I’m going to add the function prototype. The function prototype is used to tell the compiler that the function will be defined later on in the code. The compiler works from top to bottom and since we have the command table near the top of the code, the compiler will complain if I add a command with a function definition that the compiler doesn’t know about. By adding the prototype, we’re telling the compiler that the function exists and will be defined shortly.

After that, we’re going to add an entry in the command table. The command table is defined in the header file and just has two fields: the command name and the name of the function that it needs to jump to. The command name is the “friendly name” that is entered in the command line and we need to enter the function name in the next field. For instance, I defined the name “tog” so at the command line, I just need to enter “tog” and press enter. The code will jump to the function associated with “tog”, or cmd_pin_toggle.

After adding the command, then I’m going into the “main” function and adding some code to initialize my function. My function will just toggle a pin, so I need to configure the pin to be an output and set the initial value to 0. The other code above the “while” loop is also initialization code which handles initializing the USB interface, the USB driver, and the command line parser. The while loop is an infinite loop that will just call the functions defined within it forever.

And finally, I’m adding the actual function here. The function requires two arguments, argc (argument count) and argv (or argument values). Argc will inform the function of the total number of arguments entered into the command line. There will always be at least 1 argument which is the command name (“tog” in this case). Argv is a string list (string array for those used to programming) which consists of all arguments entered into the command line, separated by a space (space delimited). The number of strings in the list is equal to argc. The first string in the argv list is the command name and anything after that is parsed based on a space. Hence, if you entered “tog 1” at the command line, then you will have 2 strings in your list:

argv[0] = “tog”
argv[1] = “1” (ASCII)

In this function, I’m also converting the argument after the command name (argv[1]) to an integer from its ASCII representation using a C library (strtol). Once I have the value, then I can use standard C comparisons to toggle the pin based on the value.

Here’s some screenshots of the command line. First you need to connect to the board using a terminal program. Then you can type commands into the shell: