Accessing Simulation Objects

The state of the simulation objects can be controlled and monitored. It is possible to retrieve the value of each variable and each parameter of each simulation object. The value of each independent variable can be set from the environment while a simulation is running.

The communication between the building simulator and its environment are established by eventstreams which generate the necessary commands and convert the output of the building simulator into a user readable format.

The following kinds of eventstreams are available:

• a clock,
• file access to read and write values and commands from and respectively onto file,
• sockets, which provide ordinary Unix sockets and an abstraction of sensors and actuators.

The names of the eventstreams must be unique.

   
Accessing Time(s)

By the entry

'[ simclock,' Name '].'

in the configuration file a graphical display is started which displays three different times:

Simulation Day, Elapsed Simulation Time:

Simulation time passed since the building simulator started. Simulation time starts on day 1, at 0:00 00.

Wall Clock Time:

Time in the real world.

True Simulation Time:

True time in the building simulation, this time is e.g. used to compute the position of the sun.

All times are given in the format hh:mm ss.

The different times are updated about every second, but due to the limitations of the ERLANG timing concept, there is some imprecision and the updates are not synchronous. Do not be worried that real-time binding is violated if simulation time and wall clock time do not change synchronously, the real-time binding is maintained nevertheless.

   
Sockets

This kind of eventstreams provides access to a running simulation via sockets. Access can be from other programs as well as via the command telnet. telnet can be used in either line or character mode.

Via sockets it is not possible to send commands to be executed at a specific time.

Sockets provide a model of sensors and actuators corresponding to the testroom of AG Zimmermann, see [3]. Several connections can be established simultaneously on each socket and several sockets can be started with different sets of sensors/actuators.

There are four different subtypes of these eventstreams:

cache:

maintains a cache of values, hence responses from sensors will be faster than otherwise. Digital sensors start in eventmode.

nocache:

each access to a sensor is translated to a single access of the corresponding variable. No sensor starts in eventmode.

fault:

to be used with one of the previous types. Provides a simple error model of sensors and actuators. Fault classes supported are:

ok:

the sensor/actuator is ok (default)

silent:

no reaction on input via the socket takes place, nor are any values sent out.

notavailable:

reaction as accessing a non-available sensor/actuator takes place

constant:

The next value sent out or in is stored and used from then on as constant input or output.

Sensor/actuator names are as for the previous types. The fault class can be changed by setting one of the values ok, silent, notavailable, and constant .

inspect:

no mapping of sensors/actuators to variables need to be given. Instead sensor/actuator names have the form Object'/'Variable which can be translated trivially.

Sockets are declared in the configuration file using the following syntax:

'[ socket, ' Node ',' Host ',' Ports ',' Sensors '].'
Node	'localnode' | NodeName
Host	'localhost' | HostName
Ports	'[' Port ( ',' Port )* ']'
Port	'{' Name ',' Number ',' Type '}'
Name	<name>
Number	<portnumber>
Type	'[' 'cache' | 'nocache' | 'fault' | 'inspect' ']'
Sensors	'[' FileName (',' FileName)* ']'
FileName	<filename>

Starting sockets may take several seconds. At startup it is checked whether the tables providing the relation between sensor/actuator names and variables have to be reparsed and stored in an internal format.

An internal error can occur when several of these files are reparsed simultaneously. Restarting the building simulator until all files are parsed usually helps.

Sensors and Actuators are described as

Sensor	'[ sensor,' Name ', {' Object ',' Variable '}, Unit ',' Type '].'
Type	'analog' | 'digital'
Actuator	'[ actuator,' Name ', {' Object ',' Variable '},' IntRep ',' ExtRep '].'
IntRep	Unit |
'threepoint' | 'openclose' | 'realzeroone' |
'float' | 'time' | 'name'
ExtRep	'trigger' | 'threepoint' | 'twopoint' |
'realzeroone' | 'percentfloat' | 'string'

The Type of a sensor determines whether it can be run in eventmode (digital) or not (analog). The Unit of sensors determines how values are converted before sending them on the socket. The internal and external representation information of actuators is used to convert inputs from the socket.

   
Files

By the entries

$\parbox{0.7\textwidth}{ \texttt{'[~file\_shell~,' Name ',' Filename~'].'}\\ \texttt{'[~file\_file~,' Name ',' Filename ',' Filename~'].'}}$

in the configuration file eventstreams are started which can read commands to access the state of the simulation objects from file and and which can write output produced by the objects to the shell (file_shell) or onto file (file_file).

The input and output formats are the same.

An entry in a file has the following format, see below for periodic input:

's:io(' Time ',' Object ',' Variable ',' Command ').'
Time	'now' | Seconds |Compound
Compound	as for controlstream
Object	<name>
Variable	<name>
Command	'{' Value ',' Unit '}' | Number | 'get' | 'mon' | 'nom'

now is used as a special time, meaning to execute the command as soon as possible. Explicit times given are in simulation time, not in true time.

<name>s can be given as ERLANG-atoms or as strings enclosed in quotes. Value and Unit must be an appropriate value and a unit, respectively, for the variable accessed. The unit of each variable is given in the header file of the corresponding object, cf. $Simulator/def_*.hrl. Numerical values can be input without unit, but this is not suggested.

get is used to retrieve the current value of the variable once, mon is used to retrieve the value of the variable at each future change, i.e. to monitor the variable. nom is used to stop monitoring.

Setting and retrieving variables can be done periodically, too. Input syntax is:

's:io_period(' Time ',' Object ',' Variable ',' Command ',' Period').'
Period	'no_longer' | Seconds

The command is repeated with the given period, no_longer is used to stop further execution of a command accessing the same variable in the same way.