Files
file	EngduinoProtocol.cpp

file	EngduinoProtocol.h

Classes
struct	EngduinoPackage

class	EngduinoProtocolClass

Macros
#define	DEBUGG 0

#define	PRINTLN(...)

#define	PRINT(...)

#define	VERSION 30

#define	COMMUNICATION_PC_TERMINAL 1

#define	COMMUNICATION_BT_MODULE 2

#define	COM_SET_LEDS 10

#define	COM_SET_LED 11

#define	COM_SET_PINS_DIGITAL_TYPE 20

#define	COM_SET_PINS_ANALOG_TYPE 21

#define	COM_SET_PINS_DIGITAL_VALUE 22

#define	COM_SET_PINS_ANALOG_VALUE 23

#define	COM_SET_IR 40

#define	COM_SET_STATUS 90

#define	COM_GET_VERSION 100

#define	COM_GET_SENSORS 110

#define	COM_GET_TEMPERATURE 111

#define	COM_GET_ACCELEROMETER 112

#define	COM_GET_MAGNETOMETER 113

#define	COM_GET_LIGHT 114

#define	COM_GET_BUTTON 120

#define	COM_GET_PINS_DIGITAL_VALUE 130

#define	COM_GET_PINS_ANALOG_VALUE 131

#define	COM_GET_IR 160

#define	COM_GET_STATUS 190

#define	PACKAGE_TYPE_1 1

#define	PACKAGE_TYPE_2 2

#define	PACKAGE_TYPE_3 3

#define	PACKAGE_PACKAGE_TYPE 0

#define	PACKAGE_PACKAGE_COMMAND_ID 1

#define	PACKAGE_MAX_LENGTH 156

#define	PACKAGE_MAXNR_VALUES 56

#define	PACKAGE_START_CHR '{'

#define	PACKAGE_STOP_CHR '}'

#define	PACKAGE_DELIMITER_CHR ';'

#define	STATUS_OVERSAMPLING 0

#define	RES_OK 0

#define	RES_ERR -1

#define	RES_ERR_PACKAGE_HEADER -10

#define	RES_ERR_PACKAGE_NR_VALS -11

#define	RES_ERR_PACKAGE_VAL -12

#define	RES_ERR_PACKAGE_UNKNOWN_SENSOR_TYPE -13

#define	RES_ERR_PACKAGE_UNKNOWN_STATUS_KEY -14

#define	RES_ERR_PACKAGE_UNKNOWN_ANALOG_PIN -15

#define	NR_SENSORS 5

#define	TIME_STAMP 2.05

#define	MIN_TIME 20

#define	NR_SENSORS_BUF 8

#define	NR_TRAN_PINS 18

Enumerations
enum	{ SENSOR_ALL = 0, SENSOR_TEMP = 1, SENSOR_ACC = 2, SENSOR_MAG = 3, SENSOR_LIGHT = 4 }

enum	{ SENSOR_TEMP_BUF = 0, SENSOR_ACC_X_BUF = 1, SENSOR_ACC_Y_BUF = 2, SENSOR_ACC_Z_BUF = 3, SENSOR_MAG_X_BUF = 4, SENSOR_MAG_Y_BUF = 5, SENSOR_MAG_Z_BUF = 6, SENSOR_LIGHT_BUF = 7 }

enum	{ BUTTON_PRESSED = 0, BUTTON_RELEASED = 1 }

enum	{ PIN_TRAN_NONE = -1, PIN_TRAN_LOW_TO_HIGH = 1, PIN_TRAN_HIGH_TO_LOW = 2, PIN_TRAN_BOTH = 3 }

enum	{ PIN_TYPE_DIGITAL, PIN_TYPE_ANALOG }

Functions
	ISR (TIMER1_COMPA_vect)
	Timer 1 interrupt service routine. More...

void	TIMER1_COMPA_vect (void) __attribute__((signal))

	EngduinoProtocolClass::EngduinoProtocolClass ()
	Constructor. More...

	EngduinoProtocolClass::~EngduinoProtocolClass ()
	Destructor. More...

void	EngduinoProtocolClass::begin (EngduinoLEDsClass eledsc, EngduinoAccelerometerClass eaccc, EngduinoThermistorClass etc, EngduinoMagnetometerClass emc, EngduinoLightClass elc, EngduinoButtonClass ebc, EngduinoIRClass *eirc)
	begin function - must be called before using other functions More...

void	EngduinoProtocolClass::end ()
	end function - turn off the LEDs and stop Protocol OS. More...

void	EngduinoProtocolClass::loadDefaults ()
	Initialize protocol variables and settings. More...

int	EngduinoProtocolClass::parsePackage (String str, byte outNrVals, long outVals)
	Splits string into array of values. More...

int	EngduinoProtocolClass::parsePackageHeader (byte communicationChannel, byte inNrVals, long inVals, struct EngduinoPackage outPackage, byte *outHeaderSize)
	Parse package header. More...

int	EngduinoProtocolClass::sendPackage (byte inNrVals, byte inCommandID, long *inVals)
	Send package over the active communication channel. More...

int	EngduinoProtocolClass::sendPackage (struct EngduinoPackage engPackage, byte inNrVals, byte inCommandID, long inVals)
	Send package over the active communication channel. More...

int	EngduinoProtocolClass::setLED (struct EngduinoPackage engPackage, byte nrVals, long inVals)
	Turn on or off small green LED. More...

int	EngduinoProtocolClass::setLEDs (struct EngduinoPackage engPackage, byte nrVals, long inVals)
	Set colours and brightness of RGB LEDs. More...

int	EngduinoProtocolClass::setGetIR (struct EngduinoPackage engPackage, byte nrVals, long inVals, uint8_t setGet)
	Set or Get data from IR communication. More...

int	EngduinoProtocolClass::setGetStatus (struct EngduinoPackage engPackage, byte nrVals, long inVals, uint8_t setGet)
	Set or Get status of the Engduino board. More...

int	EngduinoProtocolClass::setPinsType (struct EngduinoPackage engPackage, byte inNrVals, long inVals, uint8_t digAnalog)
	Set digital or analog pin type. More...

int	EngduinoProtocolClass::setPinsValue (struct EngduinoPackage engPackage, byte inNrVals, long inVals, uint8_t digAnalog)
	Set digital or analog pin value. More...

int	EngduinoProtocolClass::getVersion (struct EngduinoPackage *engPackage)
	Get Engduino board version and running sketch on it. More...

int	EngduinoProtocolClass::getSensor (struct EngduinoPackage engPackage, int sensorType, byte nrVals, long inVals)
	Get Engduino's sensor measurements. More...

int	EngduinoProtocolClass::getButton (struct EngduinoPackage engPackage, byte nrVals, long inVals)
	Get Engduino's button state. More...

int	EngduinoProtocolClass::getPinsValue (struct EngduinoPackage engPackage, byte inNrVals, long inVals, uint8_t digAnalog)
	Get digital or analog pin value. More...

void	EngduinoProtocolClass::mainLoop ()
	The main loop of Engduino protocol operating system. More...

Variables
EngduinoProtocolClass	EngduinoProtocol = EngduinoProtocolClass()

EngduinoProtocolClass	EngduinoProtocol

Detailed Description

This is the driver code for the Engduino protocol.

The Engduino protocol enables communication between the Engduino board and external devices, such as a personal computer or smart phone/tablet, over the small set of instructions/commands. Commands are represented by easy to understand ASCII strings with predefined definitions of different parameters. Commands can be sent over the terminal which supports UART communication e.g. Putty, HyperTerminal, Matlab, etc., or via Bluetooth. Bluetooth communication can be established between the Engduino Bluetooth extension board and a smart device (mobile phone, tablet, etc.) or a personal computer with Bluetooth port. In the case of Bluetooth communication, the Bluetooth extension board for Engduino must be used.

The main sketch implementing this protocol is: "..\examples\100.Engduino\Protocol\Protocol.ino"

Engduino package:

Start chr	Delimiter	End chr
{	;	}

Simplest Engduino package:
{PACKAGE_TYPE; COMMAND_ID; VAL1, ..., VALn}

Examples:
{1;10;1} or with defines {PACKAGE_TYPE_1; COM_SET_LEDS; GREEN} -> Turns on all RGB LEDs with green colour.

{1;100} or with defines {PACKAGE_TYPE_1; COM_GET_VERSION} -> Returns package as {1;100;VERSION}

{1;111;100} or with defines {PACKAGE_TYPE_1; COM_GET_TEMPERATURE; 100} -> Enables continuous mode on Temperature sensor. Package with measurement of temperature will be sent back on every 100 milliseconds. Sample: {1;111;27546} represents 27.546 degrees Celsius.

Function Documentation

void EngduinoProtocolClass::begin	(	EngduinoLEDsClass *	eledsc,
		EngduinoAccelerometerClass *	eaccc,
		EngduinoThermistorClass *	etc,
		EngduinoMagnetometerClass *	emc,
		EngduinoLightClass *	elc,
		EngduinoButtonClass *	ebc,
		EngduinoIRClass *	eirc
	)

begin function - must be called before using other functions

Parameters

eledsc	Pointer to the EngduinoLEDsClass object
eaccc	Pointer to the EngduinoAccelerometerClass object
etc	Pointer to the EngduinoThermistorClass object
emc	Pointer to the EngduinoMagnetometerClass object
elc	Pointer to the EngduinoLightClass object
ebc	Pointer to the EngduinoButtonClass object
eirc	Pointer to the EngduinoIRClass object

This function initializes Engduino protocol functionalities. It must be called with all input parameters representing Engduino objects. Objects themselves must to be initialized in user code with required users definitions.

void EngduinoProtocolClass::end ( )

end function - turn off the LEDs and stop Protocol OS.

Stop the timer 1 interrupt.

EngduinoProtocolClass::EngduinoProtocolClass ( )

Constructor.

C++ constructor for this class. Empty.

int EngduinoProtocolClass::getButton	(	struct EngduinoPackage *	engPackage,
		byte	inNrVals,
		long *	inVals
	)

Get Engduino's button state.

Parameters

engPackage	Pointer to an Engduino package structure
inNrVals	Number of input values
inVals	Array of input values

Returns: On success RES_OK, otherwise error code represents particular error.

This function will send button state or enables button interrupt, which will immediately send back any change in button state. Both edges can be configured as an interrupt source.

Input value table:

Input val.	Action
[0]	Read once
[-1]	Disable button interrupt
[1]	Send package on button press
[2]	Send package on button release
[3]	Send package on change of both button states

int EngduinoProtocolClass::getPinsValue	(	struct EngduinoPackage *	engPackage,
		byte	inNrVals,
		long *	inVals,
		uint8_t	digAnalog
	)

Get digital or analog pin value.

Parameters

engPackage	Pointer to an Engduino package structure
inNrVals	Number of input values
inVals	Array of input values
digAnalog	Digital or Analog flag

Returns: On success RES_OK, otherwise error code represents particular error.

This function will send pin state or enables pin on-transition interrupt, which will immediately send back any change of pin's transition. Both edges can be configured as an interrupt source. Parameters needs to be specified in KEY-VALUE pairs. Multiple pairs can be included in the same package.

Input value table:

Input val.	Action
[0]	Read once
[-1]	Disable pin interrupt
[1]	Send package on low to high transition
[2]	Send package on high to low transition
[3]	Send package on both transitions

Input value examples: (digAnalog = 0)
[1,0, 4,0, 6,0, ...] -> Will return KEY-VALUE pairs of digital pins D1, D4 and D6. E.g.: [1,0, 4,1, 6,0] Value 1 donates to HIGH state, value 0 to LOW state.

Input value examples: (digAnalog = 1)
[1,0, 3,0, 5,0, ...] -> Will return KEY-VALUE pairs of analog pins A1, A3 and A5. E.g.: [1,123, 3,1022, 5,862] Values represents pin's AD value in range [0 - 1023]. The value 1023 donates to 3.3V

Input value examples: (digAnalog = 0)
[6,1, 10,2, 12,3, ...] -> Will enables transition interrupts on pins D6, D10 and D12.

Transition mode:

Input val.	Action
[1]	PIN_TRAN_LOW_TO_HIGH
[2]	PIN_TRAN_HIGH_TO_LOW
[3]	PIN_TRAN_BOTH

int EngduinoProtocolClass::getSensor	(	struct EngduinoPackage *	engPackage,
		int	sensorType,
		byte	inNrVals,
		long *	inVals
	)

Get Engduino's sensor measurements.

Parameters

engPackage	Pointer to an Engduino package structure
sensorType	Chose from which sensor
inNrVals	Number of input values
inVals	Array of input values

Returns: On success RES_OK, otherwise error code represents particular error.

This function will send back measurements from chosen on-board sensor or multiple sensors at once. It also supports continuous sampling with a specified sampling interval. Active sensor is defined by "sensorType" variable e.g.: SENSOR_TEMP, SENSOR_ACC, SENSOR_ALL, ...

Input value examples:

Input val.	Action
[0]	Read once
[-1]	Stop continuous sampling if it is active
[>0]	Start continuous sampling with time interval in [ms]

int EngduinoProtocolClass::getVersion ( struct EngduinoPackage * engPackage )

Get Engduino board version and running sketch on it.

Parameters

engPackage Pointer to an Engduino package structure

Returns: On success RES_OK, otherwise error code represents a particular error.

This function will send back the version of the Engduino board and running sketch on it.

ISR ( TIMER1_COMPA_vect )

Timer 1 interrupt service routine.

This function needs to be called regularly from the main sketch. If there is a waiting task, it will be executed, otherwise the function will return immediately.

void EngduinoProtocolClass::loadDefaults ( )

Initialize protocol variables and settings.

Load default settings.

void EngduinoProtocolClass::mainLoop ( )

The main loop of Engduino protocol operating system.

This function needs to be called regularly from the main sketch. If there is a waiting task, it will be executed, otherwise the function will return immediately.

int EngduinoProtocolClass::parsePackage	(	String	str,
		byte *	outNrVals,
		long *	outVals
	)

Splits string into array of values.

Parameters

str	Input string representing Engduino package
outNrVals	Pointer to an output variable which holds the value of split strings into values type long
outVals	Pointer to an output array with values type long

Returns: Unconditional RES_OK

This function will split Engduino package into an array of values type long. String will be split by delimiter and then converted into long numbers. The number of split numbers will be also returned.

Example of Engduino package: {1;10;123} as an input parameter "str".

int EngduinoProtocolClass::parsePackageHeader	(	byte	communicationChannel,
		byte	inNrVals,
		long *	inVals,
		struct EngduinoPackage *	outPackage,
		byte *	outHeaderSize
	)

Parse package header.

Parameters

communicationChannel	Communication channel [PC_TERMINAL or BT_MODULE]
inNrVals	Number of input values of type long
inVals	Array of input values of type long
outPackage	Pointer to an output Engduino package structure
outHeaderSize	Pointer to an output variable holding the length of header. Header size depends on the package type.

Returns: On success RES_OK, otherwise error code represents particular error.

This function parses input array of values into the Engduino package structure. The first value in array always represents the package type. Other values in header depend on the package type. The simplest package type is PACKAGE_TYPE_1, which includes only a command ID. Other package types are more advanced and include additional header information like address, time stamp, acknowledge request, etc.

int EngduinoProtocolClass::sendPackage	(	byte	inNrVals,
		byte	inCommandID,
		long *	inVals
	)

Send package over the active communication channel.

Parameters

inNrVals	Number of input values of type long
inCommandID	Command package ID
inVals	Array of input values of type long

Returns: On success RES_OK, otherwise error code represents particular error.

This function converts array of input variables into a string and sends package over the active communication channel (Serial or BT). The simplest package version is used.

Example of output format: {a;b;c;...x;y;z}

int EngduinoProtocolClass::sendPackage	(	struct EngduinoPackage *	engPackage,
		byte	inNrVals,
		byte	inCommandID,
		long *	inVals
	)

Send package over the active communication channel.

Parameters

engPackage	Pointer to an Engduino package structure
inNrVals	Number of input values of type long
inCommandID	Command package ID
inVals	Array of input values of type long

Returns: On success RES_OK, otherwise error code represents particular error.

This function converts the array of input variables into a string and sends package over the active communication channel (Serial or BT). Header fields will be added accordingly to the package type. Package Format: {a,b,c,...x,y,z}

int EngduinoProtocolClass::setGetIR	(	struct EngduinoPackage *	engPackage,
		byte	inNrVals,
		long *	inVals,
		uint8_t	setGet
	)

Set or Get data from IR communication.

Parameters

engPackage	Pointer to an Engduino package structure
inNrVals	Number of input values
inVals	Array of input values
setGet	Set or Get flag

Returns: On success RES_OK, otherwise error code represents particular error.

This function will send data over the IR communication or wait on data to be received. Timeout is specified by input parameter. After the timeout expiries, received data will be sent back over the active communication channel.

Input value examples: SET (setGet = 0)
[69,110,103,100,117,105,110,111] -> "Engduino"
Array "inVals" represents letters (ASCII values; http://www.asciitable.com/) separated by delimiter.

Input value examples: GET (setGet = 1)
[1000] -> Timeout is set on 1000us (1ms); Max timeout is 65535us

int EngduinoProtocolClass::setGetStatus	(	struct EngduinoPackage *	engPackage,
		byte	inNrVals,
		long *	inVals,
		uint8_t	setGet
	)

Set or Get status of the Engduino board.

Parameters

engPackage	Pointer to an Engduino package structure
inNrVals	Number of input values
inVals	Array of input values
setGet	Set or Get flag

Returns: On success RES_OK, otherwise error code represents particular error.

This function will set or get Engduino configuration. Parameters needs to be specified in KEY-VALUE pairs. Multiple pairs can be included in the same package.

Input value examples: SET (setGet = 0)
[0,12, 1,23, 6,0, ...] -> Set status variable 0 to a value 12, Set status variable 1 to a value 23, Set status variable 6 to a value 0.

Input value examples: GET (setGet = 1)
[0, 1, 6] -> Will return KEY-VALUE pairs for status variables 0, 1 and 6. E.g.: [0,12, 1,23, 6,0]

int EngduinoProtocolClass::setLED	(	struct EngduinoPackage *	engPackage,
		byte	inNrVals,
		long *	inVals
	)

Turn on or off small green LED.

Parameters

engPackage	Pointer to an Engduino package structure
inNrVals	Number of input values
inVals	Array of input values

Returns: On success RES_OK, otherwise error code represents particular error.

This function parses input value and turn on of off small green LED.

Input value examples:

Input val.	Action
[0]	Turn off LED
[>= 1]	Turn on LED

int EngduinoProtocolClass::setLEDs	(	struct EngduinoPackage *	engPackage,
		byte	inNrVals,
		long *	inVals
	)

Set colours and brightness of RGB LEDs.

Parameters

engPackage	Pointer to an Engduino package structure
inNrVals	Number of input values
inVals	Array of input values

Returns: On success RES_OK, otherwise error code represents particular error.

This function parses input values into the RGB colours and brightness. The function supports many different options on how to manipulate with LEDs. From turning on a single LED to a full RGB specter on each LED.

Input value examples:

NrOfParameters	Value	Action
1 - [colour]	[0-7]	Set colour of all LEDs
2 - [ledID, colour]	[0-15, 0-7]	Set colour of one LED
3 - [cR, cG, cB]	[0-15, 0-15, 0-15]	Set RGB colour of all LEDs
4 - [ledID, cR, cG, cB]	[0-7, 0-15, 0-15, 0-15]	Set RGB colour of one LED
16 - [c0, c1, ... , c15]	[0-15, 0-15, ..., 0-15]	Set colours specific colours of all LEDs
32 - [c0, ..., c15, b0, ..., b15]	[0-7, ..., 0-7, 0-15, ..., 0-15]	Set specific colours and brightness of all LEDs
48 - [r0, g0, b0, ... , r15, g15, b15]	[0-15, ..., 0-15]	Set specific RGB colours of all LEDs

int EngduinoProtocolClass::setPinsType	(	struct EngduinoPackage *	engPackage,
		byte	inNrVals,
		long *	inVals,
		uint8_t	digAnalog
	)

Set digital or analog pin type.

Parameters

engPackage	Pointer to an Engduino package structure
inNrVals	Number of input values
inVals	Array of input values
digAnalog	Digital or Analog flag

Returns: On success RES_OK, otherwise error code represents particular error.

This function will set pins type. Parameters needs to be specified in KEY-VALUE pairs. Multiple pairs can be included in the same package.

Pin Type:

Value	Type
[0]	INPUT
[1]	OUTPUT

Input value examples: (digAnalog = 0)
[1,0, 10,0, 12,1, ...] -> Set D1 and D10 as INPUT and D12 as output

Input value examples: (digAnalog = 1)
[3,0, 5,1, ...] -> Set A3 as INPUT and A5 as output

int EngduinoProtocolClass::setPinsValue	(	struct EngduinoPackage *	engPackage,
		byte	inNrVals,
		long *	inVals,
		uint8_t	digAnalog
	)

Set digital or analog pin value.

Parameters

engPackage	Pointer to an Engduino package structure
inNrVals	Number of input values
inVals	Array of input values
digAnalog	Digital or Analog flag

Returns: On success RES_OK, otherwise error code represents particular error.

This function will set pins value. Parameters needs to be specified in KEY-VALUE-VALUE block. The KEY is a pin number. The first VALUE donates to a pin value and the second VALUE donates to a pulse width in milliseconds. Multiple blocks can be included in the same package. In the case of passing only one block, only KEY-VALUE block is allowed, representing pin number and pin value without pulse width. Be carful that a pin is already initialized as an output!

Pin value:

Value	Type
[0]	LOW
[1]	HIGH
[0-255]	PWM duty cycle

Pulse width:

Value	Type
[< 1]	No pulse
[> 1]	Pulse duration in milliseconds

Input value examples: (Special case - digAnalog = 0)
[4,1] -> Set D4 on HIGH state.

Input value examples: (digAnalog = 0)
[4,0,0, 6,1,2500, 8,0,560, ...] -> Set D4 on HIGH state, set D6 on HIGH state for 2500 milliseconds and set D8 on LOW state for 560 milliseconds. After the pulse duration expire the state of the pin will be inverted.

Input value examples: (digAnalog = 1)
[5,96,0 13,239,1000 ...] -> Set D5# and D13# as PWM outputs. The second value in a block represents the duty cycle: between 0 (always off) and 255 (always on). The third value represents active duration. After duration expire the PWM output will be set to zero.

EngduinoProtocolClass::~EngduinoProtocolClass ( )

Destructor.

C++ destructor for this class. Empty.

Files

Classes

Macros

Enumerations

Functions

Variables

Detailed Description

Function Documentation