Programowanie skryptowe

GENERAL INFORMATION

This documentation describes how a customized object can be programmed.

Requirements

You need LoxoneConfig 2.1 onwards for using PicoC-Scripts in the configuration-software. Please check out our newest beta-releases for using the scripts.

UNDERLYING

The programming language PicoC (http://code.google.com/p/picoc/) is used. PicoC is a very small C interpreter for scripting. It was originally written for scripting a UAV’s on-board flight system and it’s also very suitable for other robotic, embedded and non-embedded applications too.

PicoC Copyright

IMPORTANT

Note that the complete C specification can not be met!
The program code is interpreted. Therefore keep the code as low as possible. Avoid complex program structures.
Each program runs in a separate task, therefore, asynchronous to the SPS.
Outputs with printf will be written to the log window of Loxone Config.
Note also that with an own programming, the system can be lead to crash. Program your instructions carefully. In case of emergency an SD card must be created, so the system gets operational again.
If you want to run the program indefinitely, add in the program loops implicitly a sleep- function so that the program does not consume unnecessary CPU time.
An integer has 32 bits, little endian.
128kB are available for heap and stack. Use memory thrifty; do not forget to release memory.
All functions which return a pointer must reallocate the memory with free (), unless the pointer was passed as a parameter.
Time values are indicated in seconds since 1.1.2009 0 UTC clock.
Strings are encoded in UTF-8.
Use mathematical function sparsely – the processor in the Miniserver has no mathematical hardware unit.

Erroneous Program blocks (PicoC) causing the Miniserver to perform safety reboots or other problems will be deactivated by the Miniserver. Those blocks remain deactivated until fixed within Loxone Config.

The scripts only works if the Config file is saved into the Miniserver.

SPS OBJECTS

The program object has 16 inputs and outputs. You can insert it by chosing it under „General“ in the tab „My Project“.

The program also has an error output (TeQ), where eventual interpreter- error messages are released. This allows the detection of syntax errors.

The program code can be edited by double-clicking on the program-object.

AVAILABLE FUNCTIONS

In the following chapters all available functions are listed and all Miniserver specific functions are described. For all standard C functions plenty of information can be found in appropriate literature (e.g. www.cplusplus.com/reference/clibrary/).

C LIBRARY FUNCTIONS

char *getprogramname();
void printf(char *format, …);
char *sprintf(char *ptr, char *format, …);
void exit();
void *malloc(int size);
void *calloc(int num,int size);
void *realloc(void *ptr,int size);
void free(void *ptr);
int atoi(char *str);
float atof(char *str);
void strcpy(char *dst,char *src);
void strncpy(char *dst,char *src,int len);
int strcmp(char *str1,char *str2);
int strncmp(char *str1,char *str2,int len);
void strcat(char *dst,char *src);
char *strdup(char *str);
char* strstr(char *str,char *strfind);
int strfind(char *str,char *strfind,int pos);
int strlen(char *str);
void memset(void *ptr,int val,int len);
void memcpy(void *dst,void *src,int len);
int memcmp(void *ptr1,void *ptr2,int len);
void errorprintf(char *format,…);

MATHEMATICAL FUNCTIONS

float sin(float x);
Returns the sine of an angle of x radians.
float cos(float x);
Returns the cosine of an angle of x radians.
float tan(float x);
Returns the tangent of an angle of x radians.
float asin(float x);
Returns the principal value of the arc sine of x, expressed in radians. In trigonometrics, arc sine is the inverse operation of sine.
float acos(float x);
Returns the principal value of the arc cosine of x, expressed in radians. In trigonometrics, arc cosine is the inverse operation of cosine.
float atan(float x);
Returns the principal value of the arc tangent of x, expressed in radians. In trigonometrics, arc tangent is the inverse operation of tangent.
float sinh(float x);
Returns the hyperbolic sine of x.
float cosh(float x);
Returns the hyperbolic cosine of x.
float tanh(float x);
Returns the hyperbolic tangent of x.
float exp(float x);
Returns the base-e exponential function of x, which is the e number raised to the power x.
float fabs(float x);
Returns the absolute value of x
float log(float x);
Returns the natural logarithm of x.
float log10(float x);
Returns the common (base-10) logarithm of x.
float pow(float base,float exponent);
Returns base raised to the power exponent.
float sqrt(float x);
Returns the square root of x.
float round(float x);
Returns rounded value of x.
float ceil(float x);
Returns the smallest integral value that is not less than x.
float floor(float x);
Returns the largest integral value that is not greater than x.

EXTENDED C LIBRARY FUNCTIONS

int batoi(char *str);
float batof(char *str);
char* strstrskip(char *str,char *strfind);
char *index(char *,int);
int lineno();

SPS FUNCTIONS

Following Functions are available:

void setlogtext(char *str);
float getio(char *str);
int setio(char *str,float value);
int getinputevent();
float getinput(int input);
char *getinputtext(int input);
void setoutput(int output,float value);
void setoutputtext(int output,char *str);

FILE FUNCTIONS

FILE *fopen(char *filename,char *mode);
int fclose(FILE *f);
int fprintf(FILE *f,char *format, … );
int fputc(int character,FILE *f);
int fputs(char *str, FILE *f);
int fflush(FILE *f);
int fwrite (void *ptr,int size,int count,FILE *f);
int fgetc(FILE *f);
char *fgets(char *str,int num,FILE *f);
int fread(void *,int size,int count,FILE *f);
int fseek(FILE *f,long offset,int origin);
int remove(char *filename);
int rename(char *oldname,char *newname);
FILE* tmpfile();
char *tmpnam(char* str);

HTTP FUNCTIONS

char*httpget(char*address,char*page);

BUFFER FUNCTIONS

int getshort(void * p,int bBigEndian);
unsigned int getushort(void * p,int bBigEndian);
int getint(void * p,int bBigEndian);
unsigned int getuint(void * p,int bBigEndian);
float getfloat(void * p,int bBigEndian);
float getdouble(void * p,int bBigEndian);

STREAM-FUNKTIONEN

STREAM *stream_create(char* filename,int read,int append);
void stream_printf(STREAM* stream,char *format, …);
int stream_write(STREAM* stream,void* ptr,int size);
void stream_flush(STREAM* stream);
int stream_read(STREAM* stream,void* ptr,int size,int timeout);
int stream_readline(STREAM* stream,void* ptr,int maxsize,int timeout);
void stream_close(STREAM* stream);

DESCRIPTION OF EXTENDED C LIBRARY FUNCTIONS

atoi

int batoi(char *str);

Works like the atoi standard C function with the exception that blanks at the
beginning of parameter str are allowed.
Example:

atoi(“ 21”); // return value = NULL
batoi(“ 21”); // return value = 21

batof

float batof(char *str);

Works like the atof standard C function with the exception that blanks at the beginning of parameter str are allowed. Example:

atof(“ 2.1”); // return value = NULL

batof(“ 2.1”); // return value = 2.1

strstrskip

char* strstrskip(char *str,char *strfind);

Works like the strstr standard C function with the exception that the length of parameter strfind is added to the result pointer.
Example:

strstr(“das ist ein test”,”ein ”); // return value = “ein test”

strstrskip(“das ist ein test”,”ein ”); // return value = “test”

index

char *index(char *str,int charfind);

Returns a pointer to the first occurrence of character charfind in str, or a null pointer if charfind is not part of str.
Example:

index(“0123456789”,0x32); // return value = “23456789”

lineno

int lineno();]

Returns the current line number in script.

getxmlvalue

char *getxmlvalue(char *str,int index,char* name);

Returns the value of name in str, or a null pointer if name is not part of str.
Parameters:
str:
XML-String to parse
index:
the index of occurence of name (first element is 0)
name:
XML-Attribute name to get
The memory where the returned pointer points to must be deallocated with function free().

Example:

getxmlvalue(“<XML name=\”test\”>”,0,”name”); // return value = “test”

getcpuinfo

int getcpuinfo();

Returns actual value of CPU usage in %.

getheapusage

int getheapusage();

Returns actual value of system heap in kB.

getmaxheap

int getmaxheap();

Returns maximum value of system heap in kB.

getspsstatus

int getspsstatus();

Returns actual number of cycles processed by SPS.

localwebservice

char *localwebservice(char *str);

Execute webservice and return a pointer to the answer XML string.

Parameters:
str:
webservice

The memory where the returned pointer points to must be deallocated with function free(). Example:

char* p = localwebservice(“dev/sps/status”);
free(p);

DESCRIPTION OF SPS FUNCTIONS

setlogtext

void setlogtext(char *str);

Writes the string contained in paramater str to the log window of Loxone Config.

getio

float getio(char *str);

Returns the value of the speciefied virtual input or a virtual output.

Example:

getio(“VI1”); // Returns the value of the virtual input VI1

setio

int setio(char *str,float value);

Sets the value of the speciefied virtual input or a virtual output.

Example:

setio(“VI1”,6.33); // Sets the value of the virtual input VI1 to 6.33

getinputevent

int getinputevent();

Returns a bitmask which contains the changes of inputs (bit 0 = first input of object, starts with text inputs followed by analog inputs).

A return value of 0x02 for example means that input 2 has changed.
(see example 1).

getinput

float getinput(int input);

Returns the value of the analog input specified in parameter input. (0 = first analog input) (see example 1).

getinputtext

char *getinputtext(int input);

Returns the string of the text input specified in parameter input. (0 = first text input).

setoutput

void setoutput(int output,float value);

Sets the specified analog output to the specified value. (0 = first analog output) (see example 1).

setoutputtext

void setoutputtext(int output,char *str);

Sets the spcified text output to the string specified in parameter str. (0 = first text output) (see example 1).

DESCRIPTION OF TIME FUNCTIONS

sleep

void sleep(int ms);

Sleep in milliseconds.

sleeps

void sleeps(int s);

Sleep in seconds.

getcurrenttime

unsigned int getcurrenttime();

Get UTC time in seconds since 1.1. 2009.

getyear

int getyear(unsigned int time,int local);

Get year of specified time. You can set the following parameters:

time:
UTC time in seconds since 2009

local:
Specifies time format: local time when 1, UTC when 0

getmonth

int getmonth(unsigned int time,int local);

Get month of specified time. You can set the following parameters:

time: UTC time in seconds since 2009
local: Specifies time format: local time when 1, UTC when 0

getday

int getday(unsigned int time,int local);

Get day of specified time. You can set the following parameters:

time: UTC time in seconds since 2009
local: Specifies time format: local time when 1, UTC when 0

gethour

int gethour(unsigned int time,int local);

Get hour of specified time. You can set the following parameters:

time: UTC time in seconds since 2009
local: Specifies time format: local when 1, UTC when 0

getminute

int getminute(unsigned int time,int local);

Get minute of specified time. You can set the following parameters:

time: UTC time in seconds since 2009
local: Specifies time format: local when 1, UTC when 0

getsecond

int getsecond(unsigned int time,int local)

Get second of specified time. You can set the following parameters:

time: UTC time in seconds since 2009
local: Specifies time format: local when 1, UTC when 0

gettimeval

unsigned int gettimeval(int year,int month,int day,int hour,int minutes,int seconds,int local);

Get UTC time in seconds since 2009. If parameters year, month, day, hour, minutes and seconds are UTC time, parameter local must be set to 0. If parameters year, month, day, hour, minutes and seconds are local time, parameter local must be set to 1.

convertutc2local

unsigned int convertutc2local(unsigned int timeutc);

Converts UTC time to localtime.

convertlocal2utc

unsigned int convertlocal2utc(unsigned int timelocal);

Converts local time to UTC time.

DESCRIPTION OF FILE FUNCTIONS

fseek

int fseek(FILE *f,long offset,int origin);

There is a difference to the standard C fseek function: origin must be 0, 1 or 2.
If somebody wants to use the standard C syntax he has to make the following definitions in PicoC script:

#define SEEK_CUR        0            // seek from current position
#define SEEK_SET        1            // seek from beginning of file
#define SEEK_END        2            // seek from end of file

For all other standard C file functions plenty of information can be found in appropriate literature (e.g. www.cplusplus.com/reference/clibrary/).

DESCRIPTION OF HTTP FUNCTIONS

httpget

char *httpget(char *address,char *page);

Downloads the specified page from the specified address. You can set the following parameters:

address: Server address e.g. “de.wikipedia.org”
page: Page on the specified server e.g.“/wiki/Intelligentes_Wohnen”

The memory where the returned pointer points to must be deallocated with function free().