TcMenu - Overview and quick start

Above: getting started video showing how to use our menu library with Arduino. Link to the Getting started with tcMenu Slides (from youtube video).

TcMenu is a complete menu solution for Arduino and mbed platforms that supports a wide range of input / display devices, and can be remotely controlled using embedCONTROL or using our Java Remote API on supported hardware. This page walks you through using tcMenu Designer to design and build an embedded application. We use a mix of screenshots from the Windows and Mac version, because although there are differences conceptually they are similar.

Your code will have access to the full power of IOAbstraction library and TaskManagerIO library. These two popular libraries make clean, event driven programming possible for embedded apps. TcMenu itself produces very clean code. Further, items can be stored to either onboard or i2c EEPROM.

Building your first menu

Step 1 - Get tcMenu Designer - Windows 10 and MacOS users

TcMenu Designer is available both from the Windows and Mac App Stores, or for you to locally download, should you require more version certainty. It can design menus and generate code for a wide range of input, display and remote control options. If you are running Windows 7, 8 or Linux there is a version available that works there too.

See the tcMenu Designer page to choose how to get the software

Step 2: Start the designer UI

Win10, MacOS note: When tcMenu Designer is not properly setup, a red banner appears in the properties area on the right, you absoltely must set up the sketches folder in settings / preferences before doing anything else. Without this permission to access the sketches directory, the designer will not be able to access your sketches / libraries folder.

On the main page we see several main areas, the main menu provides options to load and save menus, generate code and get help. You can add, remove and move around menu items from the MenuItem toolbar, when you do so you’ll see the structure change in the tree to the left.

Lastly, when root is selected, you can edit the project level properties. From here you can set the unique ID for the project. You can also set the board type we are aiming for (we support AVR, MKR, SAMD, ESP8266≤ ESP32, and mbed RTOS), the application name that will appear in the title area of the menu and is also sent to any remote controllers, and optionally a description.

Step 3: Load an example into tcMenu designer

Now choose an example menu design for a board that you already have (or the nearest one), there are examples for Uno/Mega, MKR/SAMD, ESP8266 and ESP32. The two simplest examples are the AnalogDfRobot and SimpleU8g2, these are very easy starting points.

On the Windows store version click the open button in the toolbar, on the Mac or Linux version select the examples from the File menu.

You should now see the following in the UI:

Step 4: Add a new menu item

Now press on the plus button in the menu item toolbar (below the menu tree on the left). The following will appear:

You do not change the ID unless you explicitly want to manage them yourself, it is automatically generated and unique.

Choose the type of item you want to add and press create. In this case we create a regular numeric editor.

Step 5: Edit the newly created item

When we select an item in the menu structure tree, its properties become editable on the right hand side. We can change the name, EEPROM storage location (usually by pressing Auto to get the next location), and any properties that are specific to that kind of item.

You can optionally create a callback function that will be notified of any change immediately. However, you can check the state of the menu item at any time using the getter function (for example getCurrentValue() for Analog and Enum items). In addition, you can change the state of a menu item at any time using the setter methods available on the MenuItem’s. For example on Analog item the method is setCurrentValue(..).

Step 6: Check EEPROM ranges don’t overlap

Before generating a menu, it’s a good idea to check that none of the EEPROM ranges or ID values overlap. To do this go to the Generator -> Check ID & ROM range item from the main menu / toolbar. You’ll see something similar to the following dialog. Note that there should be no red entries in the EEPROM layout, this signifies that there is an overlap.

On the right is a representation of the EEPROM memory layout, Each entry shows the start position and number of bytes needed. If the item is in green, it does not overlap with another value. However, any item in red signifies a memory clash. Once done, close the dialog.

Step 7: Generate the code

Now, we are ready to generate the code, from the main menu select Code -> Generate Code to bring up the following dialog.

On this screen we choose how we are going to interact with the menu, in terms of input, output and remote control. To change the plugin press on the plugin image representation selection. A new dialog appears with suitable choices for the selected board. When any option needs additional parameters, they appear to the right of the plugin information, generally speaking you must ensure that the plugin is properly configured before choosing to generate. Below is a list of the most popular choices along with a link to more information about how to configure them.

For input you can choose from:

• No input device
• Three switches for Up, Down and OK, controlled by IoAbstraction’s switches using the base input plugin
• A standard rotary encoder with centre button for OK using the base input plugin
• Analog Joystick for Up and Down with a button for OK

The displays supported are either:

• DfRobot shield for both input and output needing no configuration using the DfRobot shield plugin
• LiquidCrystal / HD44870 / LCD compatible displays using Liquid Crystal displays with tcMenu
• Any display supported by Adafruit_GFX such as 5110, OLED and TFT using the Adafruit_GFX driver
• On mbed RTOS 5/6 we have drivers for OLEDs using a fork of Adafruit_GFX for SSD1306/SH1106
• Any display supported by U8G2 using the U8G2 driver
• A custom display using your own renderer
• No display whatsoever.

Remote control capabilities

• Control the menu USB Serial, Bluetooth etc.
• Control the menu using Ethernet shield or ENC28J60.
• Control the menu using ESP WiFi.

There is a ready built remote controller app, .NET API and a Java API that controls a menu on an Arduino device over Ethernet and most Serial devices (incl. Bluetooth Serial).

Step 8: Compile and Upload to your board

At this point you now have code in the directory that you generated to. You’ll see several files:

• File ending with .ino or main.cpp - this is the main file with setup and loop methods.
• Files ending with _menu.cpp and _menu.h - these contain the menu structures and renderer.
• Several other plugin .cpp and .h files - these wire up the displays, input and remote technologies.

More documentation:

• Menu Item Types documentation
• Menu Manager and iteration documentation
• Designer UI worked example
• Back to tcMenu main page