By dave | April 20, 2018

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

menu designer UI download site on github

Get the designer from GitHub

Step 1a (Windows): run the installer

menu designer UI being installed on Windows

Install the designer app

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

Step 2: Start the downloaded designer UI

menu designer UI on Windows

Designer UI running on Windows

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

load an example menu structure

Load an example menu structure

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:

DfRobot project loaded into designer

Designer UI showing DfRobot project

Step 4: Add a new menu item

Now press on the plus button in the menu item toolbar. The following will appear:

add menu item

Adding a new menu item

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

edit a menu item

Editing the new menu 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.

edit a menu item

Editing the new menu item

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.

code generator within menu designer

Generating code from the designer

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:

The displays supported are either:

Remote control capabilities

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

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.