Creating devices

What is a 'device'?

• Specification of compiler mode (binary is built locally or remotely, disabled) and how to compile the binary (usually, specification of a native compiler or cross compiler).
• GEB IEC-61131-3 libraries: binaries and include files that implement the IEC-61131-3 standard, with its standard libraries.
• Variables mapping: declaration of which ranges of 'directly represented variables' are mapped in this devices, and its implementation.
• Executable entry point and main execution loop: typically this will, among other device specific tasks, discover the available (user-defined) POUs and execute them.
• Other device specific support code (source and binary libraries).

Typical files

file	type	explanation
device.properties	O	Configuration file
libgebiec.a	GO	GEB IEC 61131 support binary (static) library
gebiec.h	G	GEB IEC 61131 standard libraries headers (implemented in libgebiec.a)
gebtime.h	G	GEB specific time related functions (implemented in libgebiec.a)
geblib.h	G	GEB IEC 61131 support functions (implemented in libgebiec.a)
gebdebug.h	G	GEB specific debug related functions (implemented in libgebiec.a)
gebdbgprot.h	G	GEB specific debug comm protocol functions (implemented in libgebiec.a)
geb.h	G	GEB public header files: interface to the device code.
gebarch.h	Os	Architecture/compiler dependent definitions (types and macros)
gebdrv.h	G	GEB gral mechanisms for var mapping (directly represented variables)
deviceio.c	Os	Device specific i/o code, variables mapping, time functions
gebud.h	Os	"User defined" functions: native libraries, code supplied by OEM
main.c	Os	Executable entry point, main loop.
build.bat	Os	Script for building binary (calls C compiler)
transfer.bat	Os	Script for transfering binary (only relevant if local build and remote run)
run.bat	Os	Script for local or remote running/debugging (if supported)
debugcomm.h	G	Low level communication for debugging (declaration)
debugcomm.c	Os	Low level communication for debugging (if supported)

More than one device can be declared in one device directory, in extra device_XXX.properties configuration files. The device name is specified in the configuration file, is should be unique inside an installation.

The name of OEM provided source code files are arbitrary; more device specific code can be added, as well as header files and binary libraries.

Creating a device, step by step

#

# mapped addresses : format according to norms (page 37) . we allow ranges
#    
# format of keys: ioaddress.ID.range  ioaddress.ID.comment
# where ID is an arbitrary (unique) alphanumeric identifier, and 'comment' is optional

# files in filesystem - for demonstration only
ioaddress.f1.range = %IW51.1-16  
ioaddress.f1.comment = Input Word (16 bits) in file
# 
ioaddress.m1.range=%IX1.1-16   
ioaddress.m1.comment=MODBUS DIGITAL COIL TABLE

4. Implement the device-specific required functions

4.a Variable mappings: directly represented (AT) variables

In the simplest implementation, you define (typically in gebarch.h) the constant

#define USE_DRVarModuleSimple

void geb_drv_set_int8(char d,char w,int ad0,int ad1,int ad2,int ad3,int8_t val);
int8_t geb_drv_get_int8(char d,char w,int ad0,int ad1,int ad2,int ad3);
void geb_drv_set_int16(char d,char w,int ad0,int ad1,int ad2,int ad3,int16_t val);
int16_t geb_drv_get_int16(char d,char w,int ad0,int ad1,int ad2,int ad3);
void geb_drv_set_int32(char d,char w,int ad0,int ad1,int ad2,int ad3,int32_t val);
int32_t geb_drv_get_int32(char d,char w,int ad0,int ad1,int ad2,int ad3);
void geb_drv_set_float(char d,char w,int ad0,int ad1,int ad2,int ad3,float val);
float geb_drv_get_float(char d,char w,int ad0,int ad1,int ad2,int ad3);

If not need more flexible mappings (more datatypes, or other addressing schemes) you can comment out the line #define USE_DRVarModuleSimple and provide your own implementation of the functions defined in gebdrv.h

See the deviceio.c in the included devices for examples and templates.

NOTE: the behaviour of the AT mapping has changed in version 3. Now all the AT variables in the project are allocated in a global heap, and they are read/written from/to IO devices by calling the above functions only at the start/end of the execution cycle. This implies that now IO reading/writing is not performed each time an AT var is accesed, but only before and after the cycle execution. This also implies that POUs execution works with a snapshot of the IO vars, there are no asynchronous changes due to IO inputs varying during execution - as it should be.

4.b Variable persistence: RETAIN variables

The device must implement these three functions:

/* loads data from disk, flash, etc - this will be called by Geb - returns negative if error, 0 if no data */
int readRetainData(unsigned char *buffer, int len);

/* saves retain data - returns negative if error  */
int writeRetainData(unsigned char * buffer,int len); 

/* delete all persisted data from flash/disk - to force a cold reboot - this should be called in case of fatal error */
void deleteRetainData(void);  

4.c Time related functions

Because this is highly device specific, we define a simple time API via these straightforward functions (declared in geb.h), that the device manufacturer must implement:

/*
 Gets the current time counter read, in ticks (not necessarily a real time clock) 
 The meaning of the fields is totally arbitrary, they are opaque placeholders, to be interpreted 
 by the device code itself in the  function dev_elapsed_time()
*/
void dev_time(int32_t  *hi,uint32_t *lo);

/* 
 Gets the real time elapsed since the timestamp (data stored from a previous dev_time call) till now.
 The implementation should decide on the time unit and inform it in the 'unit' argument.
      unit=  0=usec (10e-6 secs)  1=msec (10e-3 secs - RECOMMENDED)  2: seconds  unit=-1: not implemented
*/
int32_t dev_elapsed_time(int32_t  ts_hi,uint32_t ts_lo, int *unit);

/* Gets current calendar time - optional -  month 1=january - fill all with zero if not implemented */
void dev_datetime(int16_t *year,int16_t *mon,int16_t *mday, int16_t *hour, int16_t *min,int16_t * sec,int16_t *msec);

/* 
  Tries to sleep usecs micro-seconds - usually a resolution of milliseconds is enough. 
  Returns the usecs slept. 
*/
int dev_usleep(int usec);

4.d Low level communication for debugger

If the device supports on-hardware debugging, debugcomm.c should implement the functions declared in debugcomm.h. The example provided in debugcomm_sample.c should work for any environment that supports TCP/IP sockets API (Linux and Windows included).

5. Regenerate (recompile) the geb library libgebiec.a

6. Implement your entry point and main code

6.a Implement global special functions

The OEM code must implement a few functions defined and commented in geb.h.

/**
* Handle an event, for example writing to stdout or to a log file.
* There are several different event types
*       0: Fatal error     (this should probably call deleteRetainData() to force a  cold reboot)
*       1: Error (non fatal)
*       2: Warning / Info
*       3: Debug
*/
void gebEvent(const char* s, int type);

/**
*  Handler for out-of-range errors. Tyically implemented in main.c, this should trigger a fatal error.
*/
void outOfRange(long v, long vmin, long vmax, const char *msg);

6.b Implement main loop, invoking hooks

The main execution code and execution loop should call the following function at the appropiate points:

/* hook for performing actions in different points of the execution cycle */
#define GEB_WHERE_STARTING        0 /* prior to entering the main loop */
#define GEB_WHERE_LOOP            1 /* inside loop, not running pou - this could be called very often */
#define GEB_WHERE_CYCLE_START     2 /* prior to execution of group of programs (cycle start) */
#define GEB_WHERE_CYCLE_END       3 /* after execution of group of programs (cycle end) */
#define GEB_WHERE_END_OF_PROGRAM  4 /* inside program, just before ending*/
#define GEB_WHERE_END_OF_FUNC_FB  5 /* inside funciton or FB (not program) pou, just before ending */
#define GEB_WHERE_ENDING          6 /* exiting main loop */
#define GEB_WHERE_SUSPENSION     10 /* debugging: suspended (called repeteadly) */
void geb_hook(int where,bool debugmode);

6.c Implement hook function

Typically you should copy the geb_hook in common_f.c 6.d Implement main function

It's important to call follow the pattern in example main.c at start:

gebInit(); /* should be called early, even before parsing command line args */
if(! parseArgs(argc,argv)) return 1;