By dave | March 30, 2018

TcMenu Designer UI documentation

Introduction

TcMenu is a framework for generating menu based applications on the Arduino platform. Typically a TcMenu application will be designed using the TcMenu Generator UI also on TcMenu Designer on Windows 10 Store, then generated based on the parameters you specify.

TcMenu embedded library is written in a modular way for the Arduino platform; giving unprecedented levels of control over how the menu is displayed, input acquisition and external control of the menu. The designer UI hides this behind easy to use configuration that supports a wide range of devices.

Menu Designer UI is an embedded form designer that you use to generate a menu. Once the menu is designed the code generator is initiated to build the embedded app, next moving to the IDE to write the code. It is capable of incremental round trip development between form designer and IDE. Any changes you make to the sketch in between are kept as the utility tries not to alter existing code in the sketch.

Downloading the TcMenu Generator UI

TcMenu Designer on Windows 10 Store

TcMenu Generator UI releases on github

Answering questions and getting help

Get help from the community forum for tcMenu
You can also contact us about commercial support on tcMenu

Overview of the TcMenu generator UI

In this section we look at how to build a menu based application using the generator UI; which is recommended for most people and by far the easiest way to get started.

The TcMenu generator UI is available for most desktop platforms and is released and natively packaged on Windows 8 / 10 and MacOS High Sierra or above. It should work fine on Linux but is not yet packaged for it. You can get the UI and the embedded code from git hub: [https://github.com/davetcc/tcMenu].

Once you’ve got the application running, a screen very similar to below will appear, where you can create and edit TcMenu’s.

Screen shot of TcMenu Generator main window

Screen shot of TcMenu Generator main window

Looking at the window above, we go through the major areas:

  1. The menu tree view, this shows the hierarchical shape of the menu. To start with we only have one element called ROOT; but we can create more menus using the toolbar + button, including sub menus.
  2. The menu tree control toolbar, containing functions to add a new item to the tree, remove the selected item, duplicate an item, and move items up and move items down within the current group.
  3. The prototype view shows an approximation of what the menu would look like if it were drawn onto a LiquidCrystal (20x4) display. This is only approximate but gives a good idea of how it will look.
  4. The editor area where the currently selected item can be changed, any changes are immediately applied to the tree and prototype view.
  5. At the very top is the menu bar, with the functions to load and save menu configurations, undo and redo changes and generate code. At any time Help/documentation or F1 opens this page and Help/about gives full version information.

The editor area of the main window

In the editor area (4) are the properties of the selected menu item. Notice the ID is not editable. The IDs are internally generated and are used to uniquely identify components. Each type of item has slightly different fields, but all fields have:

  • Name - the human readable name of the item, will be display in the menu.
  • Eeprom Address - the storage area in the eeprom (-1 for not stored). Pressing the auto button will find the next available slot in the range.
  • onChange function - the name of the function that will be called when the menu changes (NoCallback means not used).
  • Read only - to indicate if the item can be changed manually
  • Local only - to indicate if the item is allowed to be sent remotely

See this fuller list of TcMenu types and available fields

The add item window

Ensure root is selected in the tree (1) and press the + button from the toolbar (2) to add a new item. You should see something similar to this dialog:

Add item diailog

The Add item dialog

The above dialog is used to create a new menu item, in area (A1) we choose the type of item and we can optionally change the chosen ID (A2). Normally, just use the ID that’s populated as it is guaranteed unique.

Once an item is created, it is edited by changing the fields in the editor area (4), as you type in here, the prototype is immediately updated to reflect the changes. To remove an item press the - button on the toolbar, the duplicate button makes a copy of the currently selected item, and up / down move the item to the desired position in the current submenu.

There are other functions to generate code, but we’ll get something to generate first.

Worked example: Building a timer

For this example we will create a menu that has two top level menu items; a counter which counts down from the selected value, and a Boolean switch that turns on or off the countdown. It will also have a submenu with one menu item to control the notification method. So lets draw this out conceptually below

menu root
  +- countdown, integer values 0 to 1000 seconds
  +- enabled, boolean YES, NO.
  +- settings (sub menu)
      +- alert (one of SOUND, LIGHT, BOTH)

Getting started and adding the countdown item

Create a new Arduino project in your sketches area, start a new project in the TcMenu editor and save it into the new Arduino project directory. It will create an EMF file with the chosen name in that directory.

Ensure Root is selected in the tree and press the + button from the toolbar (2). We want a numeric item so choose “Analog Item” as the type. Once you press ok a new menu item should be created and selected in the tree.
In the editor area (4) change:

  • Change the name field to Countdown.
  • We don’t want to save this value to eeprom, so leave it at -1.
  • Maximum value is the maximum zero based value allowable. Set this to 1000.
  • Offset is an amount that is added to the current value for display only. Set to 0.
  • Divisor is applied for display purposes only. Set to 2. 0 or 1 is no divisor.
  • Unit is for display purposes and appears directly after the number. In this case set to “s”.

Adding the enabled field

We are now ready to create the second item. Again press the + button from the toolbar (2) to create a second item, this time choose BooleanMenuItem as the type and press create. In the editor area (4):

  • Change the name field to Enabled.
  • Leave the eeprom setting at -1.
  • Set the naming to YES / NO.

Adding the submenu and the notification field.

Now, we create the submenu by choosing the + button again, this time choose Sub menu as the type and press create. Change the name to Settings and leave all other fields as is.

Ensuring the newly created submenu is selected, press the + button again, this time choose Enumeration item and press create. In the editor area:

  • Change the name field to Notification
  • Change the eeprom to 2
  • Change the function to onNotificationChange
  • In the Values area, press the Add button to add a new entry to the combo
  • Double click to edit the newly created value, and change to Sound
  • Add another item and change it to Light
  • Add another item and change it to Both

At this point we have finished creating the menu, we now move on to generating code.

Eeprom Ranges and generating code

When generating eeprom values, note that values 0 and 1 are reserved for a “magic key”. This is so that load knows if the eeprom is still intact at startup. If you need to change the magic key it’s defined in the tcMenu headers.

Before generating code, it is advisable to check the ID and eeprom ranges, to ensure there are no overlaps. To do this, from the Code menu choose “Show ID and Rom Layout”; which will pop up the following dialog:

TcMenu generator ID and Rom Layout dialog

On the left you see the IDs laid out in numeric order, and on the right the rom layout. If there are any overlaps in the rom, I.E. a value that overlaps with another, it is highlighted in red. Any overlaps should be changed before generating code.

Generating code for Arduino

Finally, we get to generating the code for Arduino. Choose Code/Generate Code from the menu. You should see a dialog similar to the following:

Code generation window

Code generation window - click for full size

Once this dialog appears you’ll notice it’s split into roughly two areas, the platform and hardware choices, and the properties that need to be defined for those choices.

Adjusting the Platform choices

  • At the very top is the directory where the Arduino .INO file will be generated, it’s based on where you saved the menu file. Any existing INO file in that directory will be backed up before adjusting it.
  • Embedded Platform sets the type of board to be targeted. Currently, only arduino is supported. The display and input are filtered down so only compatible technologies are left.
  • Display type chooses the type of display to use, for example LiquidCrystalIO for HD44870 displays, U8G2 for OLED / Monochrome units or Adafruit_GFX for graphical units.
  • Input technology the method of input to be used, at the moment UP/DOWN switches, Rotary encoder, Analog Joystick or no input. See the quick start guide if you need example circuits for this.
  • Remote capabilities here you can choose to add remote capabilities to your menu, so it can be controlled remotely using either the Controller app, our Java API or writing to the protocol, Ethernet2, UipEthernet, ESP WiFi and most forms of Serial (anything extending from Stream) are supported.

Properties to define

Once all the above choices are set, you need to define the parameters that will be used by these plugins. In order to do this, you need to fill in the properties table (lower part of dialog) with your values. Notice each row in the list has a description along with the variable name, so you know what it’s for. These values will be saved into your project file (don’t forget to press save after leaving the generator)!

Starting Code generation

Press the generate button, a new window should popup, that logs the code generation run. Once complete the menu files and the sketch should be generated. Further, you should see output in the text area similar but not identical to:

08:18:17 - Starting Arduino generate: /Users/dave/Documents/Arduino/timerExample
08:18:17 - INO Previously existed, backup existing file
08:18:17 - Writing out header file: /Users/dave/Documents/Arduino/timerExample/timerExample.h
08:18:18 - Finished processing header file.
08:18:18 - Writing out source CPP file: /Users/dave/Documents/Arduino/timerExample/timerExample.cpp
08:18:18 - Finished processing source file.
08:18:18 - Making adjustments to /Users/dave/Documents/Arduino/timerExample/timerExample.ino
08:18:18 - found include in INO
08:18:18 - found setup in INO
08:18:18 - found runLoop in INO
08:18:18 - found callback for onContrastChange
08:18:18 - found callback for on12VStandby
08:18:18 - found callback for onVolumeChange
08:18:18 - found callback for onChannelChange
08:18:18 - No changes to the INO file, not writing out
08:18:18 - Process has completed, make sure the code in your IDE is up-to-date.
08:18:18 - You may need to close the project and then re-open it to pick up changes..

At this point, as long as all the properties were defined above, and the circuit is built, you should have a functioning menu to build in your favorite IDE!

Hope you enjoy using TcMenu!

Back to tcMenu main page

Other pages within this category

comments powered by Disqus

We use cookies to analyse traffic and to personalise content. We also embed Twitter, Youtube and Disqus content on some pages, these companies have their own privacy policies.

Please see our privacy policy should you need more information or wish to adjust your settings.

Send a message
X

This message will be securely transmitted to Nutricherry LTD servers.