|Tutorial - Using CmdArduino||| Print ||
|Written by Akiba|
|Friday, 23 July 2010|
The Arduino Command Line Interface, aka CmdArduino, is a simple shell that can be run on an Arduino. It's nothing fancy and its main purpose is to allow users to easily call their functions on a running Arduino via a simple serial terminal. It also allows users to pass in arguments from the command line into the functions they wrote so they can easily toggle pins, set blinking speed, set pwm duty cycles, or whatever else might need command line user input. Using it is fairly simple and just requires unzipping the files into the "Arduino/libraries" sub-directory in the Arduino program folder. The following is a tutorial that goes into more detail about how to implement CmdArduino in a sketch and easily add user functions to the command table.
Before we start, I need to mention that you'll need to use a serial terminal program to access the Arduino. The Serial Monitor built into the Arduino IDE does not allow carriage returns, ie: the Enter key, to be passed through the serial interface. For Windows, I'd recommend using a free program like Teraterm Pro or RealTerm . For Linux, I'd recommend picocom . And for Mac, you can simply use the "screen" command built into Mac OSX. You don't really need all that fancy scripting either ;)
Now, let's get started...
You’ll find that there are multiple examples. This tutorial will be skipping between different examples but I’d personally recommend starting from the beginning. Let’s start off with Example 1 (cmd_line_ex1_hello).
Example 1 is your standard “hello world” example, but applied to the command line interface. The goal of this example is just to print “hello world” when you type “hello” at the command line. Let’s dissect the code. Here's a shot of what it does:
It's a very simple sketch, but it demonstrates how a function can be called from a command line shell running on the Arduino. Now let's take a look at some of the important points of implementing CmdArduino in your sketch. Here's the complete code listing, minus comments, from Example 1:
Let's dissect this code:
1) The first thing you need to do is include the Cmd library into the sketch. This tells the sketch that the functions being called can be found in the files inside the Cmd folder. You would add this at the top of the sketch:
2) The next thing that needs to be done is to initialize the Cmd library. The main thing to do is to set up the serial port speed. You can use any of the standard serial port speeds. In this case, I’m using 57,600 bits per second.
3) You’ll also see that the commands are added in the setup() portion of the code. The cmdAdd function takes two arguments. The first argument is the “friendly” name that gets used on the command line. The second argument is the name of the function in the sketch that will get executed when you type in the “friendly” name at the command line. You can add multiple commands to the command line, but in this example, we’re only adding one.
4) In the loop() portion of the code, the function cmdPoll() is called. It just checks to see if any commands have been typed into the command line.
5) This is the actual function that will get executed when you type “hello” at the command line. The “friendly” name and the function name do not need to match. In this example, they do, but in other examples, you’ll see that they’re completely different. One thing you’ll probably notice is that the function has a specific format. All functions that get called from the command line need to have this particular format because the command line will use the two function arguments to send data into the function. Let’s take a look at the function arguments and why they’re needed:
void hello(int arg_cnt, char **args)
The only problem is that this is of limited use. At the command line, you could type in the function name and the function would get executed. That’s fine for something like the “hello” function that prints “hello world” because its static. But in many cases, you’ll want to pass in command line arguments to the function you’re calling. An example would be a function that changes the PWM duty cycle of an LED (cmd_line_ex4_pwm).
and having the LED turn on at a fixed brightness, the function becomes much more useful when you can also send in a command line argument. If you could change the PWM duty cycle on the fly, then you can experiment with different brightnesses to see which one suits your application:
If you could support command line arguments, then you can experiment with the different brightnesses dynamically rather than having to re-code the function and download it into the board.
void func_name(int arg_count, char **args)
because it scares people off. However I’m hoping that a bit of explanation will help clear things up.
CMD >> args 3 45 67 hello world i love you yayAs the implementor of the function, its up to you to decide which arguments you want to use and which to ignore.
One more thing that you need to know to use the arguments that get passed into the function is that the numeric arguments are passed in as ASCII strings. They’ll need to be converted to integers to be used in the actual application. I’ve also implemented a function that does this:
int cmdStr2Num(string, base);The string variable is just the numeric string that you want to convert to a usable integer value and the base is the numeric base you want to use for the conversion. So for a decimal number, you’ll want base=10 and for a hexadecimal number, you’ll want base=16. Here’s an example of how to use it. It’s actual Example 3 (cmd_line_ex3_led_blink) from the library:
led_blink_delay_time = cmdStr2Num(args, 10);If you run Example 3 and type this in at the command line:
blink 100then the command line arguments passed into the led_blink function look like this:
args = “blink”
We’ll need to convert the ASCII string “100” to a usable integer and to do that, the function “cmdStr2Num” is used as shown above. Once we have a usable integer, then we can use it inside the sketch. You’ll also see an example of how to control PWM from the command line in Example 4.
Note: You'll notice that the source code has a .cpp extension but is really written in C. There was some weird error messages for the Arduino Serial library when I compiled with a .c extension as opposed to when I used a .cpp extension. There's probably something I'm missing, but since I'm still getting used to the Arduino dev environment (it's only my second day using an Arduino, ya know), I decided to go with the .cpp extension. This will probably get fixed in a later release.
written by Greg Peek, July 24, 2010
written by Jan, December 01, 2010
written by Michael Kors Handbags Sale , February 03, 2012
written by miceuz, January 28, 2013
|< Prev||Next >|