my_funcs.cpp

/******************************************************************
 Example program illustrating basic Arduino usage of itch

 glitch - Grammar Lexer and Interactive Terminal Command sHell

 Copyright 2018, 2019, Brendan McLearie
 Distributed under MIT license - see LICENSE.txt
 See also README.txt

 File: my_funcs.cpp
 - Illustrative code performing the action and lookup calls from
   itch.
******************************************************************/

#include <Arduino.h>
// Include the related header file
#include "my_funcs.h"

// Include the header of the code files generated by glitch
// This picks up any enums and string lists defined by your grammar
// and includes the parser in your project
#include <out.h>

// Other parts of your program. In this case a global array of "leds"
// bounded by LED_COUNT and setting a default value for sequence_duration
#include <string.h> // C string functions - avoid Arduino "String" types

#define LED_COUNT 3
uint32_t sequence_duration = 10; // seconds

struct MY_LEDS leds[LED_COUNT] = {
	"RED", 48,
	"GREEN", 49,
	"YELLOW", 46,
};

/*
 * Validate if a LED number is in the global array leds[]
 * Return the pin_num if found
 * Return 0 if not found
 */
uint8_t ValidLEDNumber(uint8_t num) {
	for (uint8_t i = 0; i < LED_COUNT; i++) {
		if (leds[i].pin_num == num) {
			return num;
		}
	}
	return 0; 	// not valid
}

/*
 * Look up a LED name in the global array leds[]
 * Ignore case
 * Returns:
 * - the pin_num if found
 * - 0 if not found
 */
uint8_t GetLEDPinByName(const char* name) {
	for (uint8_t i = 0; i < LED_COUNT; i++) {
		if (strcasecmp(leds[i].led_name, name) == 0 ) {
			return leds[i].pin_num;
		}
	}
	return 0; 	// not valid
}

/*
 * Do a lazy LED flashing sequence on the LED specified by parameter led_pin
 * Uses the *Callback() function to write output to the user through itch
 */
void DoCMD_LAZY(uint8_t led_pin, void(*Callback)(const char*)) {
	uint32_t time_on = 1500; //msec
	uint32_t time_off = 500;
	uint32_t time_start = millis();
	Callback("Starting CMD_LAZY Sequence");
	while(millis() < (time_start + (sequence_duration * 1000))) {
		digitalWrite(led_pin, HIGH);
		delay(time_on);
		digitalWrite(led_pin, LOW);
		delay(time_off);
	}
	Callback("Done");
}

/*
 * Do a panic LED flashing sequence on the LED specified by parameter led_pin
 * Uses the *Callback() function to write output to the user through itch
 */
void DoCMD_PANIC(uint8_t led_pin, void(*Callback)(const char*)) {
	uint32_t time_on = 50; //msec
	uint32_t time_off = 50;
	uint32_t time_start = millis();
	Callback("Starting CMD_PANIC Sequence");
	while(millis() < (time_start + (sequence_duration * 1000))) {
		digitalWrite(led_pin, HIGH);
		delay(time_on);
		digitalWrite(led_pin, LOW);
		delay(time_off);
	}
	Callback("Done");
}

/*
 * Do a crazy LED flashing sequence on the LED specified by parameter led_pin
 * Uses the *Callback() function to write output to the user through itch
 */
void DoCMD_CRAZY(uint8_t led_pin, void(*Callback)(const char*)) {
	uint32_t time_start = millis();
	Callback("Starting CMD_CRAZY Sequence");
	while(millis() < (time_start + (sequence_duration * 1000))) {
		digitalWrite(led_pin, HIGH);
		delay(random(50,150));
		digitalWrite(led_pin, LOW);
		delay(random(50,300));
	}
	Callback("Done");
}

/*
 * Set the state of a numbered LED specified by parameter param1_int
 *  to the state specified by enum parameter LED_COMMAND
 * For states that are sequences, and for simplicity,
 *  this function blocks for SEQUENCE_DURATION seconds.
 * Called by itch "through" out_user_code.cpp on %action SET_LED_STATE_BY_NUM
 * Parameters:
 * - param1_int: the requested LED number
 * - LED_COMMAND: enum index of array led_command_strings described in the grammar
 *   and included in out.h
 * - *Callback(const char *): function to write a string back to itch for output
 */
void MyFuncSetLEDStateByNum(int16_t param1_int, uint16_t LED_COMMAND, void(*Callback)(const char*)) {
	if(ValidLEDNumber(param1_int)) {
		pinMode(param1_int, OUTPUT);
		switch(LED_COMMAND) {
			case CMD_ON:
				Callback("Setting pin to digital HIGH");
				digitalWrite(param1_int, HIGH);
				break;
			case CMD_OFF:
				Callback("Setting pin to digital LOW");
				digitalWrite(param1_int, LOW);
				break;
			case CMD_LAZY:
				DoCMD_LAZY(param1_int, Callback);
				break;
			case CMD_PANIC:
				DoCMD_PANIC(param1_int, Callback);
				break;
			case CMD_CRAZY:
				DoCMD_CRAZY(param1_int, Callback);
				break;
			default:
				// In theory not essential - itch has already parsed the command
				// However, good practice and a great habit for picking up bugs
				Callback("(MyFuncSetLEDStateByNum) No case for parameter LED_COMMAND");
				break;
		}
	} else {
		//not valid LED num
		Callback("Invalid LED Number");
	}
}

/*
 * Set the state of a named LED specified by parameter char* LED_NAME
 *  to the state specified by enum parameter LED_COMMAND
 * For states that are sequences, and for simplicity,
 *   this function blocks for SEQUENCE_DURATION seconds.
 * Called by itch "through" out_user_code.cpp on %action SET_LED_STATE_BY_NUM
 * Parameters:
 * - char* LED_NAME: the requested led name (null terminated C string)
 * - LED_COMMAND: enum index of array led_command_strings described in the grammar
 *   and included in out.h
 * - *Callback(const char *): function to write a string back to itch for output
 */
void MyFuncSetLEDStateByName(char* LED_NAME, uint16_t LED_COMMAND, void(*Callback)(const char*)) {
	uint8_t pin = GetLEDPinByName(LED_NAME);
	if (pin) {
		// Name search resulted in a pin != 0
		// Pass it on to MyFuncSetLEDStateByNum where the fun happens
		// This call also demonstrates how to pass the Callback to another function - simple!
		MyFuncSetLEDStateByNum(pin, LED_COMMAND, Callback);
	} else {
		// pin == 0
		// Itch should have already used %lookup-list LED_NAME LookupLEDName
		//	to validate the name. However its good practice to expect and
		//	be able to handle exceptions. Great for bug catching too.
		Callback("(MyFuncSetLEDStateByName) Name not found - this shouldn't happen!");
	}
}

/*
 * Say (i.e. echo) the param1_string using the Callback function pointer.
 * Demonstrates a basic use of a simple grammar that passes a param-string
 * Called "through" the corresponding function written by glitch in out_user_code.cpp
 * Parameters:
 * 	- char* param1_string: a null terminated c string
 *  - *Callback(const char *): function to write a string back to itch for output
 */
void MyFuncSay(char* param1_string, void(*Callback)(const char*)) {
	Callback(param1_string);
}

/*
 * Say (i.e. echo) parameter param1_string using the Callback function pointer
 *  with the emphasis specified by an enum SAY_HOW.
 * Demonstrates the use of a grammar that references an %enum-array-instance
 *  constructed from the grammar by glitch (in out.h) and given lexical context
 *  by the grammar directive %3 enum-array SAY_HOW
 * Called "through" the corresponding function written by glitch in out_user_code.cpp
 * Parameters:
 *  - SAY_HOW: enum index into say_how_strings[] (out.h)
 * 	- char* param1_string: a null terminated c string - the string to "say"
 *  - *Callback(const char *): function to write a string back to itch for output
 */
void MyFuncSayWith(uint16_t SAY_HOW, char* param1_string, void(*Callback)(const char*)) {
	switch(SAY_HOW) {
		case SAY_UPPER:
			// Normal null terminated c-strings - use the avr-libc string routine
			//  rather than the Arduino string functions that operate on Arduino Strings
			Callback(strupr(param1_string));
			break;
		case SAY_LOWER:
			// Normal null terminated c-strings - use the avr-libc string routine
			//  rather than the Arduino string functions that operate on Arduino Strings
			Callback(strlwr(param1_string));
			break;
		default:
			// In theory not essential - itch has already parsed the command
			// and looked up the enum string array However, good practice and
			// a great habit for picking up bugs
			Callback("(MyFuncSayWith) No case for parameter SAY_HOW");
			break;
	}
}

/*
 * String lookup functions called by itch:
 * - The directive %lookup-list LED_NAME LookupLEDName tells itch to call your
 *   code for an answer on the validity of a string entered for parsing
 * - In the example grammar "%2 lookup LED_NAME" gives the lexical context
 * - The code therefore needs to return a true (1) or false (0) answer
 * - In this example case: is the lookup_string a valid LEDName?
 * Parameters:
 *  - char* lookup_string: a null terminated c string
 * Returns:
 *  1 if lookup_string is found in global array leds[]
 *  0 if lookup_string is not found global array leds[]
*/
uint8_t MyFuncLookupLEDName(char *lookup_string) {
	// Existing function provides this - reuse it.
	if(GetLEDPinByName(lookup_string)) {
		return 1;
	} else {
		return 0;
	}
}

/*
 * Just for Fun
 */
void MyFuncLEDChase(int16_t param1_int, int16_t param2_int, void(*Callback)(const char*)) {
	uint32_t time_on = param1_int; //msec
	uint32_t time_off = param2_int;
	uint32_t time_start = millis();
	Callback("Starting CHASE Sequence");
	while(millis() < (time_start + (sequence_duration * 1000))) {
		for (uint8_t i = 0; i < LED_COUNT; i++) {
			pinMode(leds[i].pin_num, OUTPUT);
			digitalWrite(leds[i].pin_num, HIGH);
			delay(time_on);
			digitalWrite(leds[i].pin_num, LOW);
			delay(time_off);
		}
	}
	Callback("Done");
}