IOCards Simulation System

by Manuel Vlez
Translation by Manolo Hernndez-Pea M. revised by Jaime Pirnie

www.opencockpits.com
- August 2004 -

SIOC user manual

ver 1.0

0. TABLE OF CONTENT

1. INTRO 1.1. IOCP protocol 1.2. Structure of the IOC simulation system 1.3. System based on events 1.4. IOCP server

2. IOCARDS SIMULATION SYSTEM -SIOC2.1. System variables 2.2. SIOC modules. Types of links to system variables 2.2.1. FSUIPC module 2.2.2. IOCP client module 2.2.3. IOCards connection module 2.2.3.1. 2.2.3.2. 2.2.3.3. 2.2.3.4. Connection Connection Connection Connection to to to to IOCards IOCards IOCards IOCards SW (switches) outputs displays encoders

2.3. CONFIG-SIOC software to define variables and scripts 2.3.1. Files options 2.3.2. Edition options 2.3.3. Other options 2.4. Programming scripts 2.4.1. 2.4.2. 2.4.3. 2.4.4. 2.4.5. 2.4.6. 2.4.7. Local variables ASIGNACIN command Function command Condition IF command (If condition X happens...) Condition ELSE command (In other case...) Never ending loops Examples

2.5. SIOC software. IOC server and application core.

Page 2

SIOC user manual

ver 1.0

1. INTRO

1.1. IOCP protocol The IOCP protocol (IOCards Protocol) provides a link between IOCards and other software running in different PCs. It works with the TCP/IP protocol and is possible to use it in a local network and on the internet. This protocol has many advantages in comparison with other ones that link hardware or modules with flight simulators: Much faster. Consumes less resources. Based in events. Doesnt need other applications (like WideFS) to link to other PCs. Multiplatform (MS Flight Simulator and X-Plane). Totally freeware (for non commercial use).

1.2. Structure of the IOC simulation system The IOC simulation system has been designed to cover things that IOCards can not solve, going farther away than the electronic concept. By using IOC, we are able to make all types of user defined simulations that affect not only to the electronics (IOCards) but to the flight simulation (or the modules associated with it). The system uses the IOCP protocol as the method of sending information and accessing the systems internal variables.

Page 3

SIOC user manual

ver 1.0

The core of SS-IOC is based on: - IOCP server able to generate any input or output for a variable created with IOC. - IOCP client module that accesses to other systems (like Fsimulator using IOCPserver.dll, or X-Plane using XLUIPC). - FSUIPC client module that accesses to other systems (like Fsimulator, Project Magenta). - Linking module to IOCards that directly controls the cards from the system. - Visual scripts programmer, with special functions, mathematical formulaes, timers, conditions, etc.

1.3. System based on events The whole system is based on events. An event can be defined as a group of operations that are executed when something happens. In our system, the events can be launched by several causes: 1) When a state or the value of an internal variable changes. 2) When a timer defines it. 3) When a change in the inputs happens. Cases 2 and 3 can be reduced to case 1: when a state or the value of an internal variable changes.

Page 4

SIOC user manual

ver 1.0

1.4. IOCP server The system SIOC turns around an IOCP server. Up to 10,000 IOCP variables can be defined in this software. Each variable can have an associated script which will be executed when the variable is enabled. In addition to the internal access of these variables, they can be accessed from any other client application connected to the server. The client will be able to launch an event due to a variable value or read the values. The events can be launched internally or by an external script. With the assignment command, the value of an internal variable can be modified and the associated script will be executed. The clients, when connected to the server, inform the server about which variables are the ones they are going to work with. The working block diagram would be:

EVENT

VAR value has been changed

END

Send new value of VAR to clients

Launch others events

RUN VAR script

NO

Client have this VAR in your list ?

YES

So, if there are no changes in the variables, no events are produced, and no information is sent (this is the reason why this protocol is much faster than other ones like FSUIPC).

Page 5

SIOC user manual

ver 1.0

2. IOCARDS SIMULATION SYSTEM -SIOC-

2.1. System variables Programming the SIOC system is based in its variables definitions and the associated scripts (events). Each variable is defined by its number (from 0 to 9999). Any client connected to the SIOC server and that requires information about variable #0134, is making reference to the variable defined with that number. The client will be informed about any modification in the value of the variable. In addition, any modification in the variable ordered by the client will produce the execution of the corresponding event and the associated script. In addition of the identification number, each variable can have a description and an initial value (optional). This value will be considered when the program starts running. To access to the rest of modules managed by SIOC, variables have a special feature: they can be linked to that modules, so any change in the variable will affect to the module, and any action in the modules will affect the linked variables (and its scripts). The way to control the SIOC modules is through the linked variables.

When we define a link, the software will ask to introduce the module data we want to use. In the example, when we link the variable to the IOCards switches module (SW IOCards), the software asks for the input number associated to the

Page 6

SIOC user manual

switch and its type.

ver 1.0

Variables always store an integer value in the range -2147483648 to 2147483647. If we want to save decimal values, well have to make a conversion. For example, if we want to save the number 1.0345, we would save 10000 times this value: 10345. If we want to recover it, we would have to divide it by 10000. This is this way due to the IOCP protocol specifications.

2.2. SIOC modules. Types of links to system variables There are three basic modules which we can to link with our variables: FSUIPC, IOCP and IOCards. We can also define a variable with no module link. Any change in this variable wont affect to any module. The way of working with modules is always the same: variables take their values as a result of an event launched by a module and then the corresponding script is executed; or when the variables states change, the event is launched and the corresponding module is informed. So, we have three different types of links: delivery or output, reception or input and bi-directional or input/output.

2.2.1. FSUIPC module With this module we will connect directly with Flight Simulator (FSUIPC must be installed) or with WideFS. Other software (like Project Magenta) can be running at the same time. SIOC variables can be linked to this module in two modes: delivery to FSUIPC or reception from FSUIPC. In the first case (delivery to FSUIPC) we have to define the destination offset (with $ before the number, i.e. $0B00), the destination FSUIPC variable lenght (described in the SDK information at Pete Dowson website) and, optionally, an initial value. In this mode, once the event has been launched with its script, the value of the variable will be sent to the corresponding offset. In the second case (reception from FSUIPC) we have to define the origin offset and its length. The system reads periodically (refresh time is set in the *.ini file) and if the offset value is different from the one read in the previous loop, an event is sent to the associated variable, the new variable value will be the one read from the FSUIPC offset value and the corresponding script will be executed. As the information from FSUIPC may be codified, is interesting to include in the scripts the functions that convert the values in a format to be used by another variable.

Page 7

SIOC user manual

ver 1.0

2.2.2. IOCP client module This module (included in the SIOC) is different from the IOCP server (also included). When we talk about variables of the SIOC IOCP server, we talk about SIOC variables; but when we talk about IOCP client module, we are talking about other variables that are located in another server. We will access these variables with our client module. SIOC can be connected to any IOCP server by setting the IP address and the TCP/IP port in the *.ini configuration file. The server could be XPLUIPC for XPlane (SIOC could then access to X-Plane variables), IOCPServer.dll for Flight Simulator, or any other IOCP server in our local network or in the internet, including additional SIOC systems. The link between this module and the variables is a bidirectional mode: when the variable change, the client informs the server about the change; and when the server sends a notification about a variable to the client, the corresponding event is launched. When we define our variable, we have to set the destination variable identification number, and if we want, an initial value.

2.2.3. IOCards connection module This module directly links SIOC with an IOCards system connected to the same PC. This is not the only way to connect with an IOCards system as we can also connect the IOCards IOCP client to the SIOC IOCP server. Depending on how we define the connection with IOCards, variables will act in a different way. We can have connections with delivery and reception of information.

2.2.3.1. Connection to IOCards SW (switches) In this case, variables will connect directly to IOCard master card inputs. We have to define the input number and its type (same values as the ones defined in the IOCards software). This is a reception type connection, so SIOC will launch an event when there is a change in the input value. The variable will be 0 when the input is disabled, and will be 1 when enabled. When the event and its corresponding script is launched, the user can define commands for whatever action he wants to make.

2.2.3.2. Connection to IOCards outputs As previously, the variable will connect directly to the IOCard Master card outputs. Then we have to define the number of the output.

Page 8

SIOC user manual

ver 1.0

The type of connection in this case is delivery, and the script is launched just before sending the command enabled/disabled to the variable. To make the module understand the variable must be disabled, the value for the associated variable must be 0; if the variable must be enabled, the value must be any different from 0.

2.2.3.3. Connection to IOCards displays This connection will control the displays cards through the associated variables. The type of connection is delivery. We have to define the first figure identification number and the number of figures. Optionally we can define the type which will define alternative ways of working. The associated variable will store the number to be represented with the displays. The script is launched before the value is displayed on the display.

2.2.3.4. Connection to IOCards encoders This one is a reception type connection. When a rotary-encoder is turned, the event will be launched, and the variable value will be the increment/decrement generated by the encoder. When the encoder stops, the variable will change to 0. The variable is changed twice, but the script is only launched when the variable value is different from 0. For this connection we have to define the encoder initial input in master card, the acceleration and the type of encoder (same parameters than the ones in IOCards software).

2.3. CONFIG-SIOC software to define variables and scripts With this software the user can define how SIOC will operate, defining the variables we are interested in, the links to different modules and the parameters. Additionally, we can include specific commands for each variable that will be executed when the corresponding event is launched. The software shows a tree form diagram with several levels. The first level is the variable definition and then the commands in the order they will be executed. Another condition levels can be defined under the commands, but they will be only executed if the condition is complied.

Page 9

SIOC user manual

ver 1.0

We can edit the variables and commands through the options menu or directly from the menu that popup when the right button on the mouse is clicked.

2.3.1. Files options We can create a new file, open an existing configuration (and save as...) and exit the program. file, save the present

2.3.2. Editing options We can edit the variables and commands through the options menu or directly from the menu that pops up when the right button on the mouse is clicked. When creating a new variable, the software will show a square where well define the variable or commands. When we click on a variable or command, it will be darkened. When we double click on the square, a form will appear and we will be able to select different options. In this form, only the mandatory options will be accessible. The rest will be shown blurred. When we click OK in the form, it will adopt another shape, corresponding with the variable or command configuration. So we can check at a glance what type of variables and command we are working with. To insert a new variable, we have to select an existing one and then select the option insert variable. The new variable will be placed just above the one selected, and with a square shape. We will follow the same procedure to insert a new command (with the option insert command). When a variable is selected, we can create a command (create command). A square will appear indented under the selected variable. This will mean that this command is part of the script corresponding with the variable. From this point, we

Page 10

SIOC user manual

ver 1.0

can insert or create new commands that will build the script. The order of execution will be the order in the tree, from up to down. In the case of commands with condition clauses, we can create indented commands (once selected the first one). These additional commands will be only executed when the condition is true. To delete any variable or command, we will select it and then select delete (eliminar). If the line we want to delete has indented commands the program will advise about it.

2.3.3. Other options Other available options are to expand and collect the branches of the tree. This buttons will expand and collect the whole tree. If we only want to expand one branch, we will do it by clicking on the +, the branch will expand. Another option is change the language. Once selected, well have to restart the software.

2.4. Programming scripts For each variable, we can define a sequence of commands that will be executed when the event corresponding with the variable is launched. We can use assignments and use conditionals functions and commands. We can also use variables for timing purposes and temporary values.

2.4.1. Local variables When a script starts, some local variables are automatically created. Their values only last as long as the script is running and they store temporary values. There are two types of local variables: reals and Booleans: The real ones store real values, decimals or integers, positive or negatives, in the range 5.0 x 10^-324 a 1.7 x 10^308. There are three real local variables, defined as L0, L1 and L2. The Booleans ones store the value of a condition that can be true or false. They are mainly used to build complex conditions from simple ones (in the conditional commands only one condition is allowed). There are three boolean variables, defined as C0, C1 and C2. For example, to define a condition like if L0>5 and L0<10, we would define C0 = L0>5, C1 = L0<10, C0 = C0 AND C1. C0 would be true or false if the previous conditions are complied. By default, the values for the real variables are 0 and false for the Booleans ones.

Page 11

SIOC user manual

ver 1.0

2.4.2. ASIGNACIN command This command is used to store the value of a variable (or the result of operations between variables) into another one. The first parameter is the destination variable (a local one or one in the server). If it is a local boolean variable, the rest of parameters can only be conditions with variables or values or a direct storage of another boolean variable. If the destination variable is one of the server variables, it will take that value. If the value is different from the one it had just before, the associated event will be launched in that point of the script. In the folding menu, we can see the available variables for each operation, taking into account that for an assignment in a variable script, the variable can never be the destination of an assignment (infinite loop). The rest of parameters can be local variables, server variables or real constant values (integers or decimals, positives or negatives). In this case the variable will take the value of the operation made with the parameters. If the destination variable is a server one and the value to be stored is not an integer, it will be automatically rounded. We can apply the following operators: + , - , * , / , AND , OR (the last two with numeric variables make binary operations). For conditions we can use: > , >= , = , <= , < , AND , OR.

2.4.3. FUNCIN command This command operates on a local or server variable. There are functions defined for each type of variables: ROUND : makes a round of the variable or constant that it has as a parameter, storing the result in the referred variable. If the variable is a server one, the function can activate an event in the specific point of the variable. For example L0=ROUND( L1 ) ) SETBIT : enables the bit indicated in the parameter (through a variable or a integer constant). If the variable is a server one, the function can activate an event in the specific point of the variable. For example L0=SETBIT( 5 ), bit #5 changes to 1 and the rest is not affected. CLEARBIT : disables the bit indicated in the parameter (through a variable or a integer constant). If the variable is a server one, the function can activate an event in the specific point of the variable. For example L0=CLEARBIT( 5 ): bit #5 changes to 0 and the rest is not affected. NOT : changes the boolean value of the variable. If the value is true, it

Page 12

SIOC user manual

will change to false ( i.e. NOT(C0) ). TOOGLE : Not implemented yet. TIMER : Not implemented yet.

ver 1.0

2.4.4. CONDICIN IF command (If condition X happens...) This command lets us to execute a group of commands if the condition is complied. The group of commands will be defined for those command lines indented under the IF command. The parameters for this command can be: a condition between variables and constants, or a boolean variable (if it is true, the condition is true), or 2 boolean variables related with AND or OR (that would be true if the final result is true). If the condition is not complied (false), then the process will continue with the following command in the script.

2.4.5. CONDICIN ELSE command (In other case...) This command also lets us to execute a group of commands. Its always following a CONDITION IF command. If the condition if is not complied, then the else one would be executed, and the opposite.

Page 13

SIOC user manual

ver 1.0

2.4.6. Never ending loops A dangerous case when programming is the never ending loop. This happens when events are launched in a recurrent way, when an event starts another one and this starts the first one again. The execution never ends. The process only stops when an overflow error happens.

2.4.7. Examples With all variables, commands, function... well be able to build complex simulations. Configurations www.opencockpits.com and examples from our members will be published at

2.5. SIOC software. IOC server and application core. SIOC.EXE is the software that reads the configuration file and starts the IOC server and the different modules. The basic parameters of the software are defined in configuration file. The file explains the use of each parameter. the SIOC.INI

SIOC.EXE can be run in the same PC as the simulator or in another one, connecting both PCs through the FSUIPC client or the IOCP client (defining the corresponding TCP/IP parameters). The state of the IOCP server and all the active modules will be shown on the screen.

Page 14