SYSBoard Controller – Plugin System

30th January 2019 from Version 1.94

Concept

A SYSBoardController 'Plugin' is a way of integrating a 3rd party system (usually

hardware), with the SYSBoardController.
The 'Plugin' itself is a standard dll that you can write to hook into the I/O
functions of the SYSBoardController, and your dll is the link between your 3rd
party system and the SYSBoardController.

File Naming

Plugin dll's are placed in the folder \SYSBoard Interface\Plugins\

All plugin dll's should follow the naming : SA_PLUGIN_[unique name].dll

for example : SA_PLUGIN_PololuMaestro.dll

If Plugins are enabled in the SYSBoardController the folder \SYSBoard

Interface\Plugins\ and all subfolders are scanned for files named:
SA_PLUGIN_?.dll

You may create subfolders with \Plugins to store Config or Log files.

Enabling the Plugin System

The main plugin system is enabled in the SYSBoardController via the

“Enable Interface Plugins” checkbox.
After enabling this checkbox any available plugins will be loaded.
You should press SAVE to save this selection.
Alternatively you can manually update the \SYSBoard Interface\CONFIG.INI
[SETTINGS]
ENABLE_INTERFACE_PLUGINS=1

Implementation
Plugin communication consists of two types of Function and Procedure calls.
1) Calls from your dll to the SYSBoardController.
2) Calls from the SYSBoardController to your dll.

It is important that you Export the output calls in your dll so that they can be
triggered by the SYSBoardController.

Exports SYSBoardController_Initialize
SYSBoardController_Loop
SYSBoardController_Output
SYSBoardController_Servo_Output
SYSBoardController_Get_Input_State
SYSBoardController_Finalize

Please Note : Any code examples in this document are written in Delphi.
You will need to translate the syntax as required.
Calls TO the SYSBoard Controller

function IO_Initialize_STDCALL
(IO_board_id, IO_board_type, IO_board_desc : pchar;
IO_switch_count, IO_output_count, IO_analogue_count,
IO_servo_count, IO_7seg_count,
IO_switch_start, IO_switch_end,
IO_output_start, IO_output_end,
IO_analogue_start, IO_analogue_end,
IO_servo_start, IO_servo_end : word) : smallint
stdcall external 'SYSBoard_Plugin.dll';

Used to register a plugin board with the controller.

After calling this function the registered board will be displayed on the
status tab and a unique ID will be returned, used to identify the board in
future calls.

function IO_Process_Switch_STDCALL
(IO_unique_id, IO_switch, IO_direction : word) : smallint;
stdcall external 'SYSBoard_Plugin.dll';

Used to send switch pressed to the controller.

These can be assigned to switch functions on the Inputs tab.
RC = 0 : Process Call Received.

function IO_Process_Analogue_STDCALL
(IO_unique_id : word; IO_axis,IO_value : integer) : smallint;
stdcall external 'SYSBoard_Plugin.dll';

Used to send axis data to the controller.

These can be assigned to dimmers and axis functions.
RC = 0 : Process Call Received.

function IO_Finalize_STDCALL
(IO_unique_id : word) : smallint;
stdcall external 'SYSBoard_Plugin.dll';

Used to Unregister the plugin board with the controller;

RC = 0 : Process Call Received.

Procedure IO_Log_STDCALL
(IO_level : integer; IO_msg : pansichar);
stdcall external 'SYSBoard_Plugin.dll';

Used to write a text message to the SYSBoard Controller Plugin Log window
(and Log File if enabled)
IO_Level : 0 = INFO 1 = WARNING 2 = ERROR

procedure IO_MSG_Event_STDCALL
(IO_Msg : integer; IO_Data : double);
stdcall external 'SYSBoard_Plugin.dll';

Used to send generic predetermined messages to the SYSBoardController.

The above calls are defined in the main SYSBoard_Plugin.dll

They can be loaded statically, or dynamically via Loadlibray + GetProcAddress.
Calls FROM the SYSBoard Controller

Exports SYSBoardController_Initialize
SYSBoardController_Loop
SYSBoardController_Output
SYSBoardController_Servo_Output
SYSBoardController_Get_Input_State
SYSBoardController_Finalize

The exported functions are used by the Sysboard Controller to call your
plugin. You should EXPORT the above calls in your plugin.

procedure SYSBoardController_Initialize; stdcall

Called by the controller on startup or when the plugins are enabled.

procedure SYSBoardController_Loop; stdcall

Called by the controller every output loop pass.

This can be used to perform scan function in your dll.

procedure SYSBoardController_Finalize; stdcall

Called by the controller on Shutdown or when the plugins are disabled.

For the following calls :

Check the Unique ID matches your stored ID returned from the
IO_Initialize call. Return 0 for Success. Return -1 for Ignored.
function SYSBoardController_Output
(IO_unique_id, IO_Output : word; IO_State : integer) : smallint;
stdcall

Called by the controller when an output state needs to be set.

function SYSBoardController_Servo_Output
(IO_unique_id, IO_Output : word;
IO_Value, IO_Acceleration : integer) : smallint;
stdcall

Called by the controller when a servo position needs to be set.

function SYSBoardController_7Seg_Output
(IO_unique_id, IO_Output : word; IO_Value : PChar) : smallint;
stdcall

Called by the controller in a timer that defaults to 300ms.

It contains values based the IO_OUTPUT ident.
IO_Output = 1 = MCP CRS1 IO_Output = 8 = FLT Alt
IO_Output = 2 = MCP SPD IO_Output = 9 = LDG Alt
IO_Output = 3 = MCP HDG IO_Output = 10 = DC AMPS
IO_Output = 4 = MCP ALT IO_Output = 11 = DC VOLTS
IO_Output = 5 = MCP VS IO_Output = 12 = AC AMPS
IO_Output = 6 = MCP CRS IO_Output = 13 = AC VOLTS
IO_Output = 7 = MCP SPD Flash IO_Output = 14 = CPS FREQ

function SYSBoardController_Get_Input_State
(IO_unique_id, IO_Switch : word) : smallint; stdcall

Called by the controller when an input state needs to be read.

(usually during initialization)
Additional Info
SYSBoardController_Initialize is called by the Controller on startup or when the
plugins checkbox is enabled.

You can place any initialization that your plugin requires here…
Initialize variable…
Setup the link to the hardware…
Etc

Once you have establish a connection to the hardware you should call
function IO_Initialize_STDCALL. To register the device with the Controller.

IO_board_id = Your Unique Serial of the board.

IO_board_type = 4 digit ‘alpha’ identifying the board function.
This could be used to apply specific button mapping to a board.
(Currently unused).
IO_board_desc = 30 char Board name / Description. Ie SYS1-128I-64O

IO_switch_count, IO_output_count, IO_analogue_count,

IO_servo_count, IO_7seg_count = board specific
IO_switch_start, IO_switch_end = specific to the board ie 1-128
IO_output_start, IO_output_end = specific to the board ie 1-64
IO_analogue_start, IO_analogue_end = specific to the board ie 8-32
IO_servo_start, IO_servo_end = specific to the board ie 8-32

Return = Unique ID
This should be stored and used as a reference in future calls.

SYSBoardController_Loop - called by the controller every output loop.

SYSBoardController_Finalize is called by the Controller on shutdown.

You can clean up your plugin variables here…

Disconnect hardware etc.

Type Definitions used

byte = 1 byte
word = 2 byte Unsigned
integer = 4 byte Signed
smallint = 2 byte Signed