TcMenu - Overview and quick start

A menu library and designer UI for Arduino

TcMenu is made up of a menu library for the Arduino platform, along with a designer UI and IoT remote control facilities. These include a remote control App (soon to renamed embedCONTROL), an API and a documented protocol. IOAbstraction library is used to provide event driven menus that can be controlled both on device and remotely. EEPROM storage is also supported for loading and saving state.

Building your first menu

Step 1 - For Windows 10 users

Take the latest version of “TcMenu Designer” from the Windows store, it is freely available from there. Once installed, acquire tcMenu library using an Arduino IDE.

Get directly from the Windows Store

Step 1 for MacOS

TcMenu Designer for MacOS is available in the mac AppStore. Once youve installed the designer, get tcMenu library using an Arduino IDE.

Step 1 (Windows 7, 8 and Linux ): download the designer from github.

Designer UI package from github

Step 1a (Windows): run the installer

Step 1 (MacOS): download the disk image then drag the designer app to Applications

Step 2: Start the downloaded designer UI

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’ll see the Arduino library installer status, when it is green all libraries are up to date. However, if it shows in red then libraries are out of date, they can be installed by pressing on the button.

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.

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. The following will appear:

You do not change the ID unless you expicitly 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 press Auto to get the next location, not setting manually) and properties that are specific to that kind of item.

All menu items are event based, so you can register a callback that will be notified of any change immediately. Alternatively, you can check the state of the menu item later if you don’t need to know about the change right away. You can also change the state of any menu item at any time using methods available on the MenuItem’s.

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 value overlap. To do this go to the Code -> Check ID & ROM range menu item from the main menu. You’ll see the following dialog. Note that there should be no red entries in the EEPROM layout, this signifies that there is an overlap.

Once you’ve checked over this close the dialog. We can be fairly sure now there is no overlap of ID or EEPROM values.

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.

Firstly, we need to set the board type we are aiming for, we support Uno, Mega, AVR, MKR, SAMD, ESP8266 and ESP32. This adjusts the generated code to be optimal for the board.

Next, we can set the application name, this will appear in the title area of the menu and is also sent to any remote controllers.

Then, we choose how we are going to interact with the menu, in terms of input, output and remote control. To change the option press the change button on the right of the current selection. A new dialog appears with suitable choices for the selected board. When any option needs additional parameters, they appear in the table at the bottom. Below is a list of the most popular choices and 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
• 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, the code will be generated into the directory you selected. Just load the sketch from that directory into your favourite Arduino IDE!

TcMenu - quick start video

Here is a youtube video showing some of the above steps.

Working with menus on the Arduino.

This is only a brief overview, see the link at the bottom of this page for a more detailed guide.

Each menu that you create in the UI will be available in the Arduino code as a global variable. Let’s say you created a menu called Foo, then it would be available in your sketch as menuFoo.

Checking if an item has changed

bool changed = menuFoo.isChanged();

You can load and save menu state to / from an eeprom abstraction. Many of the tcMenu examples include loading and saving to EEPROM. For details of how to create an EepromAbstraction AVR and Arduino EEPROM example and I2C AT24 EEPROM example.

menuMgr.load(eeprom);
menuMgr.save(eeprom);

Working with AnalogItem and EnumItem menus:

Setting a value:

menuFoo.setCurrentValue(newValue);

// without calling the callback (silent set)
menuFoo.setCurrentValue(newValue, true);    

Getting the current value:

int val = menuFoo.getCurrentValue();

Working with BooleanItem menus:

Setting the value:

menuFoo.setBoolean(newValue);

// without calling the callback (silent set)
menuFoo.setBoolean(newValue, true);

Getting the boolean value

bool b = menuFoo.getBoolean();

Working with FloatItem menus:

Setting the float value:

menuFloat.setFloatValue(1.23456);

// without calling the callback (silent set)
menuFloat.setFloatValue(1.23456, true);

Getting the float value:

float fl = menuFloat.getFloatValue();

Working with TextItem menus:

Setting the value:

const char * charString = "Wilma";
menuText.setTextValue(charString);

// without calling the callback (silent set)   
menuText.setTextValue(charString, true);

Getting the text value:

const char* text = menuText.getTextValue();

More detailed documentation

At this point you’ve probably worked out how to build the most simple menu with this library. Maybe you just want to get started, from here, alternatively, we’ve got a lot more documentation available. See the below list to get started!

Back to tcMenu main page

comments powered by Disqus