Preparing for release 1.1, improved examples

Author: davetcc

examples/analogDfRobot/README.md

@@ -1,5 +1,7 @@
 ## Use a DF robot board to control the menu system
 
+To expediate the release, this example will now be in the next version of tcMenu
+
 This example assumes you've got an Uno / MEGA with the DF robot board.
 
 It uses a the switches that are connected to analog 0 and tries to keep as much in line with the DF robot spec as possible.
@@ -9,3 +11,4 @@ It has two menu items, one to control the PWM output of pin 9, one to read back
 I've assumed this will be built on either an Uno or MEGA boards, but should work equally well on any other Arduino board with only minor changes.
 
 To get started you can either run as per instructions, or just load the `analogDfRobot.emf` file into the designer, select Code / Generate and change to match your setup.
+

examples/ledFlashNoRemote/ledFlashNoRemote.ino

@@ -1,27 +1,58 @@
 #include "ledFlashNoRemote.h"
 #include <EepromAbstraction.h>
 
+/**
+ * This example controls the state of the built in LED using the menu. It also shows the
+ * status of analog pin A0 on the display too.
+ * 
+ * For more detail see the README.md file.
+ */
+
+// This example saves it's state to EEPROM using the inbuilt eeprom support in tcMenu
+// You could choose an At24C based I2C eeprom too. See the takeOverDisplay example.
 AvrEeprom eeprom;
 
+//
+// We register this function with task manager to be called every 200 millis and update the
+// menu item with the latest reading from pin A0.
+//
 void updateAnalogMenuItem() {
     menuA0Volts.setCurrentValue(analogRead(A0));
 }
 
 void setup() {
+    // needed in all sketches and generally added by the designer.
     setupMenu();
+    
+    // We want to control the LED_BUILTIN so we must set to output first.
     pinMode(LED_BUILTIN, OUTPUT);
+
+    // now load back the previous state from EEPROM.
     menuMgr.load(eeprom);
+
+    // and set up the task that will read A0 and update the menu item.
     taskManager.scheduleFixedRate(200, updateAnalogMenuItem, TIME_MILLIS);
 }
 
 void loop() {
+    // we must always call runLoop in loop, do nothing that takes a long time in loop.
+    // this is generally added by designer UI.
     taskManager.runLoop();
 }
 
+//
+// When the LED menu item is changed, this is the callback function. We just read the current
+// state and set the built in LED pin accordingly.
+//
 void CALLBACK_FUNCTION onLedChange(int id) {
     digitalWrite(LED_BUILTIN, menuBuiltInLED.getBoolean());
 }
 
+//
+// When the save menu item is pressed, this function is called, it updates the eeprom. In a real
+// life system you may want to do this on power down. See the below article:
+// https://www.thecoderscorner.com/electronics/microcontrollers/psu-control/detecting-power-loss-in-powersupply/
+//
 void CALLBACK_FUNCTION onSaveState(int id) {
     menuMgr.save(eeprom);
 }

examples/ledFlashNoRemote/ledFlashNoRemote.ino.backup

@@ -1,7 +1,15 @@
 ## Shows how to use Serial remote control with a simple menu
 
-This is a very simple menu with an example of how to configure remote control over the USB serial interface.
+This is a very simple menu with an example of how to configure remote control over the USB serial interface. Ethernet control is equally easy to use. Just create an ethernet instance as usual setting up IP address and MAC address and choose ethernet instead of serial in the code generator.
 
 You can for example use the Java API or the protocol to communicate with your Arduino from another device.
 
-We'll soon be writing an API in C# that is fairly much inline with the Java API.
+We'll soon be writing an API in C# that is fairly much inline with the Java API. This will give even more options for using tcMenu remotely.
+
+The files that are in this example:
+
+* `remoteControlSerial.cpp` & `.h` are generated by the menu designer, they should not be edited, include the header file whenever you want to work with the menu items.
+* `remoteControlSerial.ino` is the sketch, it will be modified by the designer as needed to add call back functions and required start up code.
+* `remoteControlSerial.emf` open in the designer UI, used by the designer to store the menu structure. It is not needed at runtime, only for loading the design into the designer.
+* `SerialTransport.cpp` and `.h` is the actual serial transport plug in that is copied by tcmenu into your project, do not edit is overwritten at next code generation.
+* `tcMenuLiquidCrystal.cpp` and `.h` is the actual plugin for the display, do not edit will be overwritten at next code generation.

examples/remoteControlSerial/README.md

@@ -0,0 +1,37 @@
+/*
+ * Copyright (c) 2018 https://www.thecoderscorner.com (Nutricherry LTD).
+ * This product is licensed under an Apache license, see the LICENSE file in the top-level directory.
+ */
+
+/**
+ * Serial remote capability plugin. This file is a plugin file and should not be directly edited,
+ * it will be replaced each time the project is built. If you want to edit this file in place,
+ * make sure to rename it first.
+ */
+
+#include "SerialTransport.h"
+#include "tcMenu.h"
+
+SerialTagValServer remoteServer;
+
+SerialTagValueTransport::SerialTagValueTransport() : TagValueTransport() {
+	this->serialPort = NULL;
+}
+
+void SerialTagValueTransport::close() {
+	currentField.msgType = UNKNOWN_MSG_TYPE;
+	currentField.fieldType = FVAL_PROCESSING_AWAITINGMSG;
+}
+
+void SerialTagValServer::begin(Stream* portStream, const char* namePgm) {
+	serPort.setStream(portStream);
+	connector.setName(namePgm);
+	taskManager.scheduleFixedRate(TICK_INTERVAL, []{remoteServer.runLoop();}, TIME_MILLIS);
+}
+
+SerialTagValServer::SerialTagValServer() : connector(&serPort, 0) {
+}
+
+void SerialTagValServer::runLoop() {
+	connector.tick();
+}

examples/remoteControlSerial/SerialTransport.cpp

@@ -0,0 +1,75 @@
+/*
+ * Copyright (c) 2018 https://www.thecoderscorner.com (Nutricherry LTD).
+ * This product is licensed under an Apache license, see the LICENSE file in the top-level directory.
+ */
+
+/**
+ * @file SerialTransport.h
+ * 
+ * Serial remote capability plugin. This file is a plugin file and should not be directly edited,
+ * it will be replaced each time the project is built. If you want to edit this file in place,
+ * make sure to rename it first.
+ */
+
+#ifndef _TCMENU_SERIALTRANSPORT_H_
+#define _TCMENU_SERIALTRANSPORT_H_
+
+#include <Arduino.h>
+#include "RemoteConnector.h"
+
+/**
+ * Serial transport is an implementation of TagValueTransport that works over a serial port
+ */
+class SerialTagValueTransport : public TagValueTransport {
+private:
+	Stream* serialPort;
+public:
+	SerialTagValueTransport();
+	virtual ~SerialTagValueTransport() {}
+	void setStream(Stream* stream) {this->serialPort = stream; }
+
+	virtual void flush()                   {serialPort->flush();}
+	virtual int writeChar(char data)       { return serialPort->write(data); }
+	virtual int writeStr(const char* data) { return serialPort->write(data); }
+
+	virtual uint8_t readByte()   { return serialPort->read(); }
+	virtual bool readAvailable() { return serialPort->available(); }
+	virtual bool available()     { return serialPort->availableForWrite();}
+	virtual bool connected()     { return true;}
+
+	virtual void close();
+
+};
+
+/**
+ * SerialTagValServer is the implementation of remote communication that provides
+ * remote menu capability for Serial streams.
+ */
+class SerialTagValServer {
+private:
+	SerialTagValueTransport serPort;
+	TagValueRemoteConnector connector;
+public:
+	/** Empty constructor - configured in begin */
+	SerialTagValServer();
+	/**
+	 * Begins serial communication on the given port. You must call begin on the stream first.
+	 * @param portStream the stream upon which to communicate, it must be already opened.
+	 * @param namePgm the local name of the application in PROGMEM
+	 */ 
+	void begin(Stream* portStream, const char* namePgm);
+	/**
+	 * Arranged internally don't call yourself.
+	 */ 
+	void runLoop();
+
+	/** returns the remote connector associated with the connection */
+	TagValueRemoteConnector* getRemoteConnector(int /*num*/) {return &connector;}
+};
+
+/**
+ * the global instance of the SerialTagValServer
+ */
+extern SerialTagValServer remoteServer;
+
+#endif /* _TCMENU_SERIALTRANSPORT_H_ */

examples/remoteControlSerial/SerialTransport.h

@@ -0,0 +1,47 @@
+/*
+    The code in this file uses open source libraries provided by thecoderscorner
+
+    DO NOT EDIT THIS FILE, IT WILL BE GENERATED EVERY TIME YOU USE THE UI DESIGNER
+    INSTEAD EITHER PUT CODE IN YOUR SKETCH OR CREATE ANOTHER SOURCE FILE.
+
+    All the variables you may need access to are marked extern in this file for easy
+    use elsewhere.
+ */
+
+#include <tcMenu.h>
+#include "remoteControlSerial.h"
+
+// Global variable declarations
+
+LiquidCrystal lcd(LCD_RS, LCD_EN, LCD_D4, LCD_D5, LCD_D6, LCD_D7, ioUsingArduino());
+LiquidCrystalRenderer renderer(lcd, LCD_WIDTH, LCD_HEIGHT);
+
+const char PROGMEM applicationName[] = "Serial Test";
+
+// Global Menu Item declarations
+const PROGMEM AnyMenuInfo minfoPushMe = { "Push Me", 6, 0xffff, 0, onPushMe };
+ActionMenuItem menuPushMe(&minfoPushMe, NULL);
+const char enumStrFood_0[] PROGMEM = "Pizza";
+const char enumStrFood_1[] PROGMEM = "Pasta";
+const char enumStrFood_2[] PROGMEM = "Salad";
+const char* const enumStrFood[] PROGMEM  = { enumStrFood_0, enumStrFood_1, enumStrFood_2 };
+const PROGMEM EnumMenuInfo minfoFood = { "Food", 5, 0xffff, 2, NO_CALLBACK, enumStrFood };
+EnumMenuItem menuFood(&minfoFood, 0, &menuPushMe);
+const PROGMEM TextMenuInfo minfoMyText = { "MyText", 4, 0xffff, 10, NO_CALLBACK };
+TextMenuItem menuMyText(&minfoMyText, &menuFood);
+const PROGMEM AnalogMenuInfo minfoA2Voltage = { "A2 Voltage", 3, 0xffff, 1024, NO_CALLBACK, 0, 200, "V" };
+AnalogMenuItem menuA2Voltage(&minfoA2Voltage, 0, &menuMyText);
+const PROGMEM AnalogMenuInfo minfoA1Voltage = { "A1 Voltage", 2, 0xffff, 1024, NO_CALLBACK, 0, 200, "V" };
+AnalogMenuItem menuA1Voltage(&minfoA1Voltage, 0, &menuA2Voltage);
+const PROGMEM AnalogMenuInfo minfoA0Voltage = { "A0 Voltage", 1, 0xffff, 1024, NO_CALLBACK, 0, 200, "V" };
+AnalogMenuItem menuA0Voltage(&minfoA0Voltage, 0, &menuA1Voltage);
+
+// Set up code
+void setupMenu() {
+    switches.initialise(ioUsingArduino(), true);
+    menuMgr.initForEncoder(&renderer, &menuA0Voltage, ENCODER_PIN_A, ENCODER_PIN_B, ENCODER_PIN_OK);
+    lcd.begin(LCD_WIDTH, LCD_HEIGHT);
+
+    remoteServer.begin(&Serial, applicationName);
+}
+

examples/remoteControlSerial/remoteControlSerial.cpp

@@ -0,0 +1 @@
+{"version":"1.00","projectName":"C:\\Users\\dave\\Documents\\Arduino\\libraries\\tcMenu\\examples\\remoteControlSerial\\remoteControlSerial.emf","author":"dave","lastEdited":{"seconds":1548498951,"nanos":445322400},"items":[{"parentId":0,"type":"analogItem","item":{"maxValue":1024,"offset":0,"divisor":200,"unitName":"V","name":"A0 Voltage","id":1,"eepromAddress":-1,"readOnly":false}},{"parentId":0,"type":"analogItem","item":{"maxValue":1024,"offset":0,"divisor":200,"unitName":"V","name":"A1 Voltage","id":2,"eepromAddress":-1,"readOnly":false}},{"parentId":0,"type":"analogItem","item":{"maxValue":1024,"offset":0,"divisor":200,"unitName":"V","name":"A2 Voltage","id":3,"eepromAddress":-1,"readOnly":false}},{"parentId":0,"type":"textItem","item":{"textLength":10,"name":"MyText","id":4,"eepromAddress":-1,"readOnly":false}},{"parentId":0,"type":"enumItem","item":{"enumEntries":["Pizza","Pasta","Salad"],"name":"Food","id":5,"eepromAddress":-1,"readOnly":false}},{"parentId":0,"type":"actionMenu","item":{"name":"Push Me","id":6,"eepromAddress":-1,"functionName":"onPushMe","readOnly":false}}],"codeOptions":{"embeddedPlatform":"ARDUINO","lastDisplayKey":2,"lastInputKey":1,"lastRemoteKey":2,"lastProperties":[{"name":"LCD_RS","latestValue":"8","subsystem":"DISPLAY"},{"name":"LCD_EN","latestValue":"9","subsystem":"DISPLAY"},{"name":"LCD_D4","latestValue":"4","subsystem":"DISPLAY"},{"name":"LCD_D5","latestValue":"5","subsystem":"DISPLAY"},{"name":"LCD_D6","latestValue":"6","subsystem":"DISPLAY"},{"name":"LCD_D7","latestValue":"7","subsystem":"DISPLAY"},{"name":"LCD_WIDTH","latestValue":"16","subsystem":"DISPLAY"},{"name":"LCD_HEIGHT","latestValue":"2","subsystem":"DISPLAY"},{"name":"LCD_PWM_PIN","latestValue":"-1","subsystem":"DISPLAY"},{"name":"PULLUP_LOGIC","latestValue":"true","subsystem":"INPUT"},{"name":"INTERRUPT_SWITCHES","latestValue":"false","subsystem":"INPUT"},{"name":"SWITCH_IODEVICE","latestValue":"","subsystem":"INPUT"},{"name":"ENCODER_PIN_A","latestValue":"2","subsystem":"INPUT"},{"name":"ENCODER_PIN_B","latestValue":"3","subsystem":"INPUT"},{"name":"ENCODER_PIN_OK","latestValue":"A3","subsystem":"INPUT"},{"name":"DEVICE_NAME","latestValue":"Serial Test","subsystem":"REMOTE"},{"name":"SERIAL_PORT","latestValue":"Serial","subsystem":"REMOTE"}]}}

examples/remoteControlSerial/remoteControlSerial.emf

@@ -0,0 +1,58 @@
+/*
+    The code in this file uses open source libraries provided by thecoderscorner
+
+    DO NOT EDIT THIS FILE, IT WILL BE GENERATED EVERY TIME YOU USE THE UI DESIGNER
+    INSTEAD EITHER PUT CODE IN YOUR SKETCH OR CREATE ANOTHER SOURCE FILE.
+
+    All the variables you may need access to are marked extern in this file for easy
+    use elsewhere.
+ */
+
+#ifndef MENU_GENERATED_CODE_H
+#define MENU_GENERATED_CODE_H
+
+#include<IoAbstraction.h>
+#include<Wire.h>
+#include<tcMenu.h>
+
+#include "tcMenuLiquidCrystal.h"
+#include <RemoteConnector.h>
+#include "SerialTransport.h"
+
+// all export definitions
+#define ENCODER_PIN_A 2
+#define ENCODER_PIN_B 3
+#define ENCODER_PIN_OK A3
+
+#define LCD_RS 8
+#define LCD_EN 9
+#define LCD_D4 4
+#define LCD_D5 5
+#define LCD_D6 6
+#define LCD_D7 7
+#define LCD_WIDTH 16
+#define LCD_HEIGHT 2
+#define LCD_PWM_PIN -1
+extern LiquidCrystal lcd;
+extern LiquidCrystalRenderer renderer;
+
+
+extern const char applicationName[];
+
+
+// all menu item forward references.
+extern ActionMenuItem menuPushMe;
+extern EnumMenuItem menuFood;
+extern TextMenuItem menuMyText;
+extern AnalogMenuItem menuA2Voltage;
+extern AnalogMenuItem menuA1Voltage;
+extern AnalogMenuItem menuA0Voltage;
+
+// all callback functions must have this define on them, it is what the menu designer looks for.
+#define CALLBACK_FUNCTION
+
+void CALLBACK_FUNCTION onPushMe(int id);
+
+void setupMenu();
+
+#endif // MENU_GENERATED_CODE_H

examples/remoteControlSerial/remoteControlSerial.h

@@ -0,0 +1,49 @@
+#include "remoteControlSerial.h"
+
+/*
+ * Shows how to use basic Serial remote communication using the inbuilt serial port
+ * For more details see the README.md file in this directory.
+ */
+
+//
+// This function is registered in setup to be called every 200 millis by task manager.
+// It updates the analog voltage menu items to show the values on each of the analog pins.
+// When we call the setCurrentValue (or setBooleanValue on booleans) not only is the menu
+// item updated on the display, but it's also marked as needing sending remotely as well.
+//
+void updateAnalogMenuItems() {
+    menuA0Voltage.setCurrentValue(analogRead(A0));
+    menuA1Voltage.setCurrentValue(analogRead(A1));
+    menuA2Voltage.setCurrentValue(analogRead(A2));
+}
+
+void setup() {
+    // for 32 bit boards we should wait for serial before proceeding.
+    while(!Serial);
+
+    // for serial communication, we only need to setup the speed here.
+    Serial.begin(115200);
+
+    // we are going to be toggling this so need to set it as output.
+    pinMode(LED_BUILTIN, OUTPUT);
+
+    // added by designer to initialise the menu.
+    setupMenu();
+
+    // task manager is asked to schedule the udpate function below every 200ms
+    taskManager.scheduleFixedRate(200, updateAnalogMenuItems);
+}
+
+void loop() {
+    // added by designer to run the taskManager. Don't put any long running tasks in loop.
+    taskManager.runLoop();
+}
+
+//
+// When the push me (action item) is pressed, this method is called back.
+// It purely inverts the current state of the built in LED.
+//
+void CALLBACK_FUNCTION onPushMe(int id) {
+    bool ledCurrent = digitalRead(LED_BUILTIN);
+    digitalWrite(LED_BUILTIN, !ledCurrent);
+}