Introduction: Make Interactive Microcontroller Apps in Minutes
I/O pins along with numerous 5V, 3.3V and Ground pins are provided on a 34 pin edge-mounted socket tailored to work with those old floppy drive ribbon cables that you probably have buried in a box somewhere. Besides the floppy connector, a 10 pin header is available to connect in a daughterboard or motherboard configuration using SPI or I2C for communication.
Step 1: Programming the Aphid Board
The Aphid board can be programmed and debugged using the Spy-Bi Wire interface of a Launchpad board which, at four dollars and thirty cents, isn’t likely to break the bank. Plus the Launchpad interface incorporates serial I/O that can be used with a terminal as a debugging aid, or to communicate with a custom PC application.
Enough about the hardware--let's take a look at the code generator. We'll start by building a guitar tuner similar in functionality to the device described in the back half of Mossmann's blog . This device incorporates a separate voltage regulator as well as current limiting resistors and a transistor for each LED color. The RGB control lines are connected to pins 2.3, 3.7 and 3.6 respectively.
Enough about the hardware--let's take a look at the code generator. We'll start by building a guitar tuner similar in functionality to the device described in the back half of Mossmann's blog . This device incorporates a separate voltage regulator as well as current limiting resistors and a transistor for each LED color. The RGB control lines are connected to pins 2.3, 3.7 and 3.6 respectively.
Step 2: Menu Definition
I don't think I've ever met anyone who truly relishes learning yet another programming language syntax (especially with looming deadlines!), but this syntax is a bit different. This is not a general purpose programming language, but a highly targeted syntax known as a Domain Specific Language (DSL ). DSLs in general are powerful tools that can significantly amp up your ability to interface efficiently with the computer in front of you and their very limited scopes help to speed your mastery of them.
Now take a moment to look at the menu design file (image below) that was used to generate the menus for the tuner.
The menu file is a compact specification that tells the code generator a great deal about the way you will interact with the application. --in particular it:
<MenuName >{ [MenuCommand ]*
"MenuLine " [LineCommand ]*
}
MenuName
The menu name is always stated inside angle brackets whether it is defining the menu, or acting as the target of an action (e.g. switch to <DisplaySettingsMenu>). The top level menu is always named HomeMenu.
MenuCommand
MenuCommands can take the form of a no_cursor directive:
[no_cursor]
This tells the code generator that no cursor should be shown in this menu. More commonly, however, the MenuCommands will take the form of an event link which associates a button input with a particular action. Actions can be to switch to another menu e.g.:
[long_back-><DisplaySettingsMenu>]
This causes the state machine to switch to the DisplaySettingsMenu if the back button is held down for a full second or more.
Or an event link action can simply be used to trigger a call to a user-generated function e.g.:
[sel->(toggleStrobe)]
Possible events include:
sel, back, up, down, long_sel, long_back
MenuLine
MenuLines are character strings that indicate what will be shown on the display and also identifies fields that will be associated with variables via the LineCommands. Typically you will want to have the cursor enabled to indicate the currently selected line. When shown, the cursor appears as a greater-than sign in the first column, so you must be sure to leave a blank space in the first position of each line. Note also the comment line that helps keep track of the maximum line width--16 in this case, but this will depend on the display you are using. Fields are staked out by placing a string of characters that is unique within the line which will be matched by the associated LineCommands--note that you must be sure to size this field to contain the maximum number of characters for any possible field value.
LineCommand
The LineCommand is possibly the most complex part of the syntax, but, thankfully, this is the last one. The LineCommand always follows the line it is modifying and its job is to both define line-specific select event actions, and to associate fields with variables and to define the types of those variables so the generated code can handle the variables in a type-appropriate manner.
Line-specific select events are exactly like the menu-level events above except that here the select button event is the only one available as the other buttons are not typically associated with a particular line. If defined, a line-specific select event will override the menu-global select event if the cursor is located on the line in question.
Field variable associations take this form
[FieldString Direction Target :Type ]
FieldString
The FieldString we've already discussed--it is the line-unique character string that marks the location and length of a particular field within the MenuLine.
Direction
The Direction indicates whether we are associating a Target with a user input event (->), or a drawing event (<-) or both (<->).
Target
The Target can be a variable, a set or a draw function, or a variable and a value-changed-callback function.
Target Variable (<- | -> | <->): [min<->timer_minutes]
Target Set Function ( ->): [spd->(SetSpeed)]
Target Draw Function ( <- ): [nnn<-(DrawNum)]
Target Variable w/Callback (-> | <-> ): [xxx->SetContrast(LCD_Contrast)]
[strobeMode<->SetStrobeMode(strobeMode)]
Note that the in last case above (the bi-directional Variable w/Callback case), the value-changed callback is ignored in when drawing the field.
Type
The Type modifier is responsible for identifying the variable type and the limits or possible values.
Available types include binary coded decimal, signed or unsigned integer in 8, 16 or 32 bits, or 8-bit enumerations. The syntax for these types is as follows:
• BCD8, BCD16, BCD32
• U8, U16, U32
• S8, S16, S32
• enum
The type modifier has the form:
:Type (Limits )
Note that (Limits) are optional for all but enum types.
Examples:
:BCD8(0,0x99)
:U16(8,1000)
:enum("None", "Linear", "Log")
:S16(-1000,1000)
:U32
And that's it. That's the entire manual for the menu definition language!
Next we'll look at a the source code required to finish the guitar tuner. We'll remove the Mode input as it complicates the code a bit without offering much more from a learning standpoint. Also, the 3x mode worked far better than the other modes that we experimented with, so it doesn't make sense to offer them.
Now take a moment to look at the menu design file (image below) that was used to generate the menus for the tuner.
The menu file is a compact specification that tells the code generator a great deal about the way you will interact with the application. --in particular it:
• Defines the lines of text for one or more menus
• Defines fields within those lines that will be linked to variables in the program
• Defines commands that should be called when a field is changed, or when drawing a field
• Defines the types for associated variables as well as the limits or acceptable inputs for those fields
• Associates certain button inputs with commands to be executed or menus to be activated
<MenuName >{ [MenuCommand ]*
"MenuLine " [LineCommand ]*
}
MenuName
The menu name is always stated inside angle brackets whether it is defining the menu, or acting as the target of an action (e.g. switch to <DisplaySettingsMenu>). The top level menu is always named HomeMenu.
MenuCommand
MenuCommands can take the form of a no_cursor directive:
[no_cursor]
This tells the code generator that no cursor should be shown in this menu. More commonly, however, the MenuCommands will take the form of an event link which associates a button input with a particular action. Actions can be to switch to another menu e.g.:
[long_back-><DisplaySettingsMenu>]
This causes the state machine to switch to the DisplaySettingsMenu if the back button is held down for a full second or more.
Or an event link action can simply be used to trigger a call to a user-generated function e.g.:
[sel->(toggleStrobe)]
Possible events include:
sel, back, up, down, long_sel, long_back
MenuLine
MenuLines are character strings that indicate what will be shown on the display and also identifies fields that will be associated with variables via the LineCommands. Typically you will want to have the cursor enabled to indicate the currently selected line. When shown, the cursor appears as a greater-than sign in the first column, so you must be sure to leave a blank space in the first position of each line. Note also the comment line that helps keep track of the maximum line width--16 in this case, but this will depend on the display you are using. Fields are staked out by placing a string of characters that is unique within the line which will be matched by the associated LineCommands--note that you must be sure to size this field to contain the maximum number of characters for any possible field value.
LineCommand
The LineCommand is possibly the most complex part of the syntax, but, thankfully, this is the last one. The LineCommand always follows the line it is modifying and its job is to both define line-specific select event actions, and to associate fields with variables and to define the types of those variables so the generated code can handle the variables in a type-appropriate manner.
Line-specific select events are exactly like the menu-level events above except that here the select button event is the only one available as the other buttons are not typically associated with a particular line. If defined, a line-specific select event will override the menu-global select event if the cursor is located on the line in question.
Field variable associations take this form
[FieldString Direction Target :Type ]
FieldString
The FieldString we've already discussed--it is the line-unique character string that marks the location and length of a particular field within the MenuLine.
Direction
The Direction indicates whether we are associating a Target with a user input event (->), or a drawing event (<-) or both (<->).
Target
The Target can be a variable, a set or a draw function, or a variable and a value-changed-callback function.
Target Variable (<- | -> | <->): [min<->timer_minutes]
Target Set Function ( ->): [spd->(SetSpeed)]
Target Draw Function ( <- ): [nnn<-(DrawNum)]
Target Variable w/Callback (-> | <-> ): [xxx->SetContrast(LCD_Contrast)]
[strobeMode<->SetStrobeMode(strobeMode)]
Note that the in last case above (the bi-directional Variable w/Callback case), the value-changed callback is ignored in when drawing the field.
Type
The Type modifier is responsible for identifying the variable type and the limits or possible values.
Available types include binary coded decimal, signed or unsigned integer in 8, 16 or 32 bits, or 8-bit enumerations. The syntax for these types is as follows:
• BCD8, BCD16, BCD32
• U8, U16, U32
• S8, S16, S32
• enum
The type modifier has the form:
:Type (Limits )
Note that (Limits) are optional for all but enum types.
Examples:
:BCD8(0,0x99)
:U16(8,1000)
:enum("None", "Linear", "Log")
:S16(-1000,1000)
:U32
And that's it. That's the entire manual for the menu definition language!
Next we'll look at a the source code required to finish the guitar tuner. We'll remove the Mode input as it complicates the code a bit without offering much more from a learning standpoint. Also, the 3x mode worked far better than the other modes that we experimented with, so it doesn't make sense to offer them.
Step 3: Build It!
To build the guitar tuner, you simply need to place the soon-to-be-released beta code generator in your Code Composer Studio workspace folder, import the AphidCore library and add a build step for the menu specification file to your project.
When you first build the project you will get several errors regarding the variables and functions referenced in the menu definition file, but not yet declared in the source. A sample project includes app.h and app.c files that fleshes out the basic content common to all applications, so we just need to fill in the salient parts to make the program work. In most cases, this can be accomplished by copying and slightly modifying portions of code from one of the many example files TI provides for each of its microcontrollers. All of the modifications to the basic app.h and app.c are shown in the annotated images below, and you can visit the next page to download the complete app files, the menu definition file as well as gen.h and gen.c--the output from the code generator.
When you first build the project you will get several errors regarding the variables and functions referenced in the menu definition file, but not yet declared in the source. A sample project includes app.h and app.c files that fleshes out the basic content common to all applications, so we just need to fill in the salient parts to make the program work. In most cases, this can be accomplished by copying and slightly modifying portions of code from one of the many example files TI provides for each of its microcontrollers. All of the modifications to the basic app.h and app.c are shown in the annotated images below, and you can visit the next page to download the complete app files, the menu definition file as well as gen.h and gen.c--the output from the code generator.
Step 4: Roadmap & Source Code
We are putting the final touches on Aphid board and the associated software and code generation system and we will be making pre-production boards available in the March time frame with production boards available early this summer. All source code and hardware design files will be released as open source beginning with the pre-production run. Pricing will be driven largely by manufacturing costs, but it is estimated that the price will be be under $40 for the bare board. Laser cut cases and displays tested and verified to work with Aphid board will also be available for an additional fee.
Thanks for reading my instructable.
