UCCONFIG

Header file for UCConfig module. More...

Files
file	ucconfig.h
	Header file for UCConfig module.

Macros
#define	UCCONFIG_KEY_LENGTH   4
	The length of the key which the PC needs to send to enter Config mode.
#define	UCCONFIG_KEY_1   2
	Key character 1.
#define	UCCONFIG_KEY_2   4
	Key character 2.
#define	UCCONFIG_KEY_3   6
	Key character 3.
#define	UCCONFIG_KEY_4   8
	Key character 4.
#define	UCCONFIG_FIFO_SIZE   32
	The size of the FIFO used by the module, don't change this.
#define	UCCONFIG_FRAME_END   22
	The frame and character.
#define	UCCONFIG_SET_MEMORY_ADDRESS   12
	Command used to initiate setting the memory address pointer.
#define	UCCONFIG_SET_WRITE_FRAME   13
	Command used to initial writing data.
#define	UCCONFIG_READ_FRAME   14
	Command used to initial reading data.
#define	UCCONFIG_TERMINATE   15
	Command used to exit from commmand mode.
#define	UCCONFIG_AT_ADDRESS   16
	Command used get the current memory addresss pointer.
#define	UCCONFIG_ACK   17
	Command used to acknowledge a command.
#define	UCCONFIG_NACK   18
	Command used to not acknowledge a command.
#define	UCCONFIG_NULL   19
	ASCII character used for NULL.
#define	UCCONFIG_NOT_USED   20
	ASCII character used for Not used.
#define	UCCONFIG_NEWLINE   10
	ASCII character used for new line, UC needs to send this so python module can easly pick end of command.
#define	UCCONFIG_LENGTH_ZERO   21
	ASCII character used for zero length data frames.
#define	UCCONFIG_TYPE_NONE   11
	ASCII character used for none types.
#define	UCCONFIG_TYPE_UINT8_T   12
	ASCII character used for uint8_t types.
#define	UCCONFIG_TYPE_INT8_T   13
	ASCII character used for int8_t types.
#define	UCCONFIG_TYPE_UINT16_T   14
	ASCII character used for uint16_t types.
#define	UCCONFIG_TYPE_INT16_T   15
	ASCII character used for int16_t types.
#define	UCCONFIG_TYPE_UINT32_T   16
	ASCII character used for uint32_t types.
#define	UCCONFIG_TYPE_INT32_T   17
	ASCII character used for int32_t types.
#define	UCCONFIG_TYPE_FLOAT   18
	ASCII character used for float types.
#define	UCCONFIG_TYPE_CHAR   19
	ASCII character used for char types.
#define	UCCONFIG_ACTIVE_MODE_TIMEOUT   0xFFFF
	Number of loop iterratios before automattically exits from active mode.
#define	UCCONFIG_get(X, Y)
	UCCONFIG_GET() is the function macro used to get the value of any variable type in flash. More...

Functions
void	UCCONFIG_setup (uint8_t(*flash_read)(uint16_t address), void(*flash_write)(uint8_t byte, uint16_t adrress), void(*serial_write)(uint8_t byte))
	Set up the module, this should be called before any other module function will work. More...
void	UCCONFIG_listen (uint8_t receivedByte)
	Listens to serial communication and sets module in config mode if correct key is sent. More...
void	UCCONFIG_loop (void)
	Runs config mode if the key has been received. More...
void	UCCONFIG_setAddressOffset (uint16_t address)
	Set the memory address offset of the flash memory pointer (optional) More...
void	UCCONFIG_setOnEnter (void(*on_enter)(void))
	Sets the function which is called when config mode is entered (optional) More...
void	UCCONFIG_setOnExit (void(*on_exit)(void))
	Sets the function which is called when config mode is exited (optional) More...
void	UCCONFIG_setOnFirstWrite (void(*on_first)(void))
	Sets the function which is called when the first byte is written to the UC from PC. More...
void	ucconfig_get_c (char *data, uint16_t address)
	Get a character from the given memory address. More...
void	ucconfig_get_u8 (uint8_t *data, uint16_t address)
	Get a uint8 from the given memory address. More...
void	ucconfig_get_8 (int8_t *data, uint16_t address)
	Get a int8 from the given memory address. More...
void	ucconfig_get_u16 (uint16_t *data, uint16_t address)
	Get a uint16 from the given memory address. More...
void	ucconfig_get_16 (int16_t *data, uint16_t address)
	Get a int16 from the given memory address. More...
void	ucconfig_get_u32 (uint32_t *data, uint16_t address)
	Get a uint32 from the given memory address. More...
void	ucconfig_get_32 (int32_t *data, uint16_t address)
	Get a int32 from the given memory address. More...
void	ucconfig_get_float (float *data, uint16_t address)
	Get a float from the given memory address. More...

Detailed Description

Header file for UCConfig module.

This module depends on three other common libraries for its usage:

• string11.h
• flashWrite.h
• fifo8.h

This module is part of a larger project. Documentation is being developed.

Author

Stuart Ianna

Version

0.1

Date

December 2018

Copyright

GNU GPLv3

Warning

None

Bug:

None

Todo:

Documentation

Compilers

• arm-none-eabi-gcc (15:4.9.3+svn231177-1) 4.9.3 20150529 (prerelease)

Example

A full example of UC_config using the STM32f1 internal flash memory as storage

#include <stm32f103cb_core.h>
#include <ucconfig.h>
#include "variables.h"

/******************************************************************************/
    //Example usage of UCConfig module
    //UC Config can write data to flash EEPROM modules from PC at runtime.
    //This avoids the need for recompilation when changing program parameters
    //
    //The example uses the USB Driver for the STM32F1, this functionallity
    //can be changed to USART by passing appropriate function pointers.
/******************************************************************************/

//For this example the inital flash page used is 120
#define FLASH_PAGE 120

//Function to be called when new serial data is available to be read.
void serialReceived(uint8_t b);

//Function to write a single byte at a given address to internal flash.
void flashWrite(uint8_t byte,uint16_t address);

//Function to read a single byte at a given address from internal flash.
uint8_t flashRead(uint16_t address);

//Function which is called when the first write operation occurs
void onFirstWrite(void);

//Function which is called when config mode is exited.
//This function is used to load the values for all below variables
void exitingConfigMode(void);

//Bunch of variable for demonstration
uint8_t u8;
int8_t s8;
uint16_t u16;
int16_t s16;
uint32_t u32;
int32_t s32;
float f;
char c;

int main(void){

    //Always need setup the USB callbacks when using USB
    //Equivalently, USART would be set up here
    USB_coms(SYSTICK);

    //Set serial Received to be called when new data is available through USB
    USB_setGet(&serialReceived);

    //Setup GPIO for some flashing magic
    //The pin flashes when the config module is activly reading or writing
    pinSetup(GPIO_DO,PORTC,PIN13);

    //If an external EEPROM was used, it would need to be set up here first,
    //along with I2C or whichever peripheral it requires.
    //Internal flash is used here so no setup is required.

    //Setup UCCONFIG module, pass the three function pointers
    UCCONFIG_setup(&flashRead,&flashWrite,&USB_put);

    //Optionally, set the memory offset if flash which is used. No offset needed 
    //here so 0 is passed
    UCCONFIG_setAddressOffset(0);

    //Optionally, a function can be called when config mode is entered
    UCCONFIG_setOnFirstWrite(&onFirstWrite);

    //Optionally, a function can be called when config mode is entered
    UCCONFIG_setOnExit(&exitingConfigMode);

    //Set inital pin state high (LED off)
    pinHigh(PORTC,PIN13);

    //Exit config mode sets all the variables, call it here to populate themn
    //from flash
    exitingConfigMode();


    while(1){

        delayms(2000);
        //The loop is what 'enters' config mode, it should be somewhere in the main loop or
        //on a timer callback
        UCCONFIG_loop();

        prints("U8 =");
        printl(u8);

        prints("S8 =");
        printl(s8);
        delayms(100);

        prints("U16 =");
        printl(u16);

        prints("S16 =");
        printl(s16);
        delayms(100);

        prints("U32 =");
        printl(u32);

        prints("S32 =");
        printl(s32);
        delayms(100);

        prints("F =");
        printl(f);

        prints("C =");
        printl(c);

        printl("");
    }
}

//Repopulate all variable from values in flash
//This is called on inital setup and when config mode is exited.
void exitingConfigMode(void){

    UCCONFIG_get(&u8,U8);
    UCCONFIG_get(&s8,S8);
    UCCONFIG_get(&u16,U16);
    UCCONFIG_get(&s16,S16);
    UCCONFIG_get(&u32,U32);
    UCCONFIG_get(&s32,S32);
    UCCONFIG_get(&f,F);
    UCCONFIG_get(&c,C);
}

//This is called when data is received.
void serialReceived(uint8_t b){

    //Need to call UCCONFIG_listen() here. So the module can intercept and
    //become active when the correct key is received via serial.
    UCCONFIG_listen(b);

}

//Function to write to flash
void flashWrite(uint8_t byte,uint16_t address){

    //Notice a delay is provided here to ensure there is enough time
    //for the flash memory to be written

    //A fancy flash (active low) is also demonstrated
    pinLow(PORTC,PIN13);
    FLASH_write(FLASH_PAGE,address,byte);
    delayms(10);
    pinHigh(PORTC,PIN13);
    return;
}

//Function to read from flash
uint8_t flashRead(uint16_t address){

    return FLASH_read(FLASH_PAGE,address);
}

void onFirstWrite(void){

    //The internal flash memeory on stm32f1 can only be set once before it needs to be erased
    //Erase it here when first byte operation occurs
    //More pages could be cleared if more flash was needed.
    FLASH_clearPage(FLASH_PAGE);
}

The example variables are populated from the python modules variables.yml

# Example UC config file demonstrating correct variable layout.
# There are six required parameters for each variable 
#   name - The name of the variable, must conform to C naming convention. 
#   desc - A description of the variable, used to populate C header file comments and GUI. 
#   value - The variable value flashed to the microcontroller. 
#   dataType - A valid C type for the variable, options are:
#       uint8_t - Unsigned 8-bit integer. 
#       int8_t - Signed 8-bit integer. 
#       uint16_t - Unsigned 16-bit integer. 
#       int16_t - Signed 16-bit integer. 
#       uint32_t - Unsigned 32-bit integer. 
#       int32_t - Signed 32-bit integer. 
#       float -  Floating point, up to four decimal point percision. 
#       char - An ASCII character - valid from ASCII 32 to ASCII 127. 
#   max - The maximum allowed value, should be less the variable type's maximum. 
#   min - The minimum allowed value, should be less the variable type's minimum. 

- dataType: uint8_t
  desc: Example unsigned 8 bit integer
  max: 255
  min: 0
  name: U8
  value: 20

- dataType: int8_t
  desc: Example signed 8 bit integer
  max: 127
  min: -127
  name: S8
  value: -30

- dataType: uint16_t
  desc: Example unsigned 16 bit integer
  max: 65535
  min: 0
  name: U16
  value: 532

- dataType: int16_t
  desc: Example signed 16 bit integer
  max: 32767
  min: -32767
  name: S16
  value: -2355

- dataType: uint32_t
  desc: Example unsigned 32 bit integer
  max: 4294967295
  min: 0
  name: U32
  value: 500000

- dataType: int32_t
  desc: Example signed 32 bit integer
  max: 2147483647
  min: -2147483647
  name: S32
  value: 123

- dataType: float
  desc: Example float, 4 decimal point percision
  max: 214748
  min: -214748
  name: F
  value: 12.5943

- dataType: char
  desc: Example character, ASCII
  max: 127
  min: 32
  name: C
  value: 64

The python module generates the header file which is included in the example program

#ifndef UCCONFIG_GEN_H
#define UCCONFIG_GEN_H

#define U8  0x0

#define S8  0x1

#define U16  0x2

#define S16  0x4

#define U32  0x6

#define S32  0xa

#define F  0xe

#define C  0x12

#endif

Macro Definition Documentation

#define UCCONFIG_get	(		X,
			Y
	)

Value:

_Generic((X),                                \
                                    char*:     ucconfig_get_c,      \
                                    uint8_t*:  ucconfig_get_u8,     \
                                    int8_t*:   ucconfig_get_8,      \
                                    uint16_t*: ucconfig_get_u16,    \
                                    int16_t*:  ucconfig_get_16,     \
                                    uint32_t*: ucconfig_get_u32,    \
                                    int32_t*:  ucconfig_get_32,     \
                                    float*:    ucconfig_get_float,  \
                                    default:   ucconfig_get_u8      \
                                                               )(X,Y)

UCCONFIG_GET() is the function macro used to get the value of any variable type in flash.

This function works in conjuction with generated header file. See module example usage.

Parameters

X	The pointer to the data containter for the variable, the value located in flash is stored in the containter.
Y	The address the data is located at.

Warning

There is no type checking of the variable fetched. Make sure that at the given memory location there is that type of variable.

Definition at line 183 of file ucconfig.h.

Function Documentation

void ucconfig_get_16	(	int16_t *	data,
		uint16_t	address
	)

Get a int16 from the given memory address.

This function is utilised in the marco expansion of UCCONFIG_get(). It should not be called manually

Parameters

data	Pointer to a int16 to store the data in.
address	Address in flash to read the data from.

Warning

Don't call this function manually

Definition at line 135 of file ucconfig.c.

void ucconfig_get_32	(	int32_t *	data,
		uint16_t	address
	)

Get a int32 from the given memory address.

This function is utilised in the marco expansion of UCCONFIG_get(). It should not be called manually

Parameters

data	Pointer to a int32 to store the data in.
address	Address in flash to read the data from.

Warning

Don't call this function manually

Definition at line 147 of file ucconfig.c.

void ucconfig_get_8	(	int8_t *	data,
		uint16_t	address
	)

Get a int8 from the given memory address.

This function is utilised in the marco expansion of UCCONFIG_get(). It should not be called manually

Parameters

data	Pointer to a int8 to store the data in.
address	Address in flash to read the data from.

Warning

Don't call this function manually

Definition at line 122 of file ucconfig.c.

void ucconfig_get_c	(	char *	data,
		uint16_t	address
	)

Get a character from the given memory address.

This function is utilised in the marco expansion of UCCONFIG_get(). It should not be called manually

Parameters

data	Pointer to a character to store the data in.
address	Address in flash to read the data from.

Warning

Don't call this function manually

Definition at line 110 of file ucconfig.c.

void ucconfig_get_float	(	float *	data,
		uint16_t	address
	)

Get a float from the given memory address.

This function is utilised in the marco expansion of UCCONFIG_get(). It should not be called manually

Parameters

data	Pointer to a float to store the data in.
address	Address in flash to read the data from.

Warning

Don't call this function manually

Definition at line 153 of file ucconfig.c.

void ucconfig_get_u16	(	uint16_t *	data,
		uint16_t	address
	)

Get a uint16 from the given memory address.

This function is utilised in the marco expansion of UCCONFIG_get(). It should not be called manually

Parameters

data	Pointer to a uint16 to store the data in.
address	Address in flash to read the data from.

Warning

Don't call this function manually

Definition at line 128 of file ucconfig.c.

void ucconfig_get_u32	(	uint32_t *	data,
		uint16_t	address
	)

Get a uint32 from the given memory address.

This function is utilised in the marco expansion of UCCONFIG_get(). It should not be called manually

Parameters

data	Pointer to a uint32 to store the data in.
address	Address in flash to read the data from.

Warning

Don't call this function manually

Definition at line 141 of file ucconfig.c.

void ucconfig_get_u8	(	uint8_t *	data,
		uint16_t	address
	)

Get a uint8 from the given memory address.

This function is utilised in the marco expansion of UCCONFIG_get(). It should not be called manually

Parameters

data	Pointer to a uint8 to store the data in.
address	Address in flash to read the data from.

Warning

Don't call this function manually

Definition at line 116 of file ucconfig.c.

void UCCONFIG_listen

(

uint8_t

receivedByte

)

Listens to serial communication and sets module in config mode if correct key is sent.

This function should be placed in the output stream of the serial communication. See module example

Parameters

receivedByte

A single byte recieved through serial communication.

Definition at line 1007 of file ucconfig.c.

void UCCONFIG_loop

(

void

)

Runs config mode if the key has been received.

This function should be placed in the programs main loop or on a timer callback (see example)

Definition at line 84 of file ucconfig.c.

void UCCONFIG_setAddressOffset

(

uint16_t

address

)

Set the memory address offset of the flash memory pointer (optional)

This module initialises with memory pointer based at position 0. A offset can be supplied to charge the inital position of config parameters in flash.

Parameters

address

The offset to be used.

Definition at line 159 of file ucconfig.c.

void UCCONFIG_setOnEnter

(

void(*)(void)

on_enter

)

Sets the function which is called when config mode is entered (optional)

The function must be of type specified. Use a wrapper to call different function types (see example)

Parameters

on_enter

The function to be called.

Definition at line 97 of file ucconfig.c.

void UCCONFIG_setOnExit

(

void(*)(void)

on_exit

)

Sets the function which is called when config mode is exited (optional)

The function must be of type specified. Use a wrapper to call different function types (see example)

Parameters

on_exit

The function to be called.

Definition at line 101 of file ucconfig.c.

void UCCONFIG_setOnFirstWrite

(

void(*)(void)

on_first

)

Sets the function which is called when the first byte is written to the UC from PC.

The function must be of type specified. Use a wrapper to call different function types (see example)

Parameters

on_first

The function to be called.

Definition at line 105 of file ucconfig.c.

void UCCONFIG_setup	(	uint8_t(*)(uint16_t address)	flash_read,
		void(*)(uint8_t byte, uint16_t adrress)	flash_write,
		void(*)(uint8_t byte)	serial_write
	)

Set up the module, this should be called before any other module function will work.

See module example

Parameters

flash_read	Function pointer to a function which reads one byte from a memory address. The address can be no longer than 16 bits wide
flash_write	Function pointer to a function which writes one byte to the memory address specified
serial_write	Funtions pointer to a function which writes one byte to a serial output stream such as USART or USB. This should be the same stream to which the PC uses to communicate with the UC

Warning

Flash read and write function usually take time to execture (~10ms). This module does not supply a delay for this execution. A delay should be probided in the main program. (see module example)