Documentation Center

Plug-ins User Guide

Version 5.2 | Published March 20, 2024 ©

viz_sealevel

The viz_sealevel plug-in allows Viz Engine to provide GPIO data coming from SeaLevel Devices for plug-ins and scripts.

Both SeaLevel PCI and ethernet Devices are supported. The GPIO data is provided in via SHM key/values and via message passing.

SHM Interface

Each GPIO pin is mapped to a SHM key.

Format

The pins are mapped with following format:

  • Inputs: Sealevel::<device-id>::I<pin-id>::<0 or 1>

  • Outputs: Sealevel::<device-id>::O<pin-id>::<0 or 1>

SMM Values in Viz Engine REST Interface

images/download/attachments/158761064/smm_view.png

Inputs

These SHM values are only for reading and are updated when a input pin changes. By registering to SHM changes this can then be used to perform tasks in scripting or plug-ins.

Outputs

These values are meant to set from inside scripts or plug-ins (for example to switch lights on and off).

Message Interface

The Viz Engine plug-in API supports communication via message passing which is similar to a REST API. Messages can be send via Request(location, message) in Viz Script.

List Devices

Location: /Extensions/Sealevel/devices
Response:

[
{
"id": "1",
"name": "410io_",
"status": "connected",
"status-description": "Connected"
}
]

Get Device Info

Location: /Extensions/Sealevel/devices/1
Response:

{
"id": "1",
"name": "410io_",
"status": "connected",
"status-description": "Connected",
"pins": [
{
"id": "0",
"is-input": true,
"value": 0
},
{
"id": "1",
"is-input": true,
"value": 0
},
{
"id": "2",
"is-input": true,
"value": 0
},
{
"id": "3",
"is-input": true,
"value": 0
},...
]
}

Register for Pin Changes

Location: /Extensions/Sealevel/devices/1/register
Response:

{
"error": false
}

If then a pin changes the script or plug-in would receive such a response:
Location: /Extensions/Sealevel/devices/1/change
Response:

{
"device": 1,
"pin": 1,
"value": true
}

Get All Pin Data for a Given Device

Location: /Extensions/Sealevel/devices/1/pins
 Response:

[
{
"id": "0",
"is-input": true,
"value": 0
},
{
"id": "1",
"is-input": true,
"value": 0
},
{
"id": "2",
"is-input": true,
"value": 0
}, ...
]

Get Pin Data for a Given Device and Pin

Location: /Extensions/Sealevel/devices/1/pins/0
Response:

{
"id": "0",
"is-input": true,
"value": 0
}

Set Pin Data for a Given Device and Pin

Location: /Extensions/Sealevel/devices/1/pins/0
Message:

{
"value": 1
}

Response:

{
"id": "0",
"is-input": true,
"value": 1
}

Configuration

To Configure this plugin create a file called {VizEngine-Config-dir}/extensions/Sealevel.json. This file is used for every running instance of Viz Engine. To have a specific config for a running instance you can create config files like {VizEngine-Config-dir}/extensions/Sealevel-{Instance-Number}.json.

Supported config parameters:

  • auto-reconnect: Automatically reconnect to device.

  • reconnect-interval: Interval for reconnecting.

  • discover-ethernet-devices: Automatically detect SeaLevel network devices.

  • ethernet-devices: Array of SeaMax devices connected via Ethernet.

    • address: IP address.

    • name: Assocciated name for this Card.

  • seaio-devices: Array of SeaIO device (PCI-Cards).

    • adapter: Adapter number for PCI-Card (For two installed PCI-Cards possible adapters would be 0 and 1).

    • name: Assocciated name for this Card.

  • serial-devices: Array of SeaMax devices connected via serial interface.

    • port: COM port for this device.

    • name: Assocciated name for this Card.

The Sealevel.json file would then look like this:

{
"auto-reconnect": true,
"discover-ethernet-devices": true
"ethernet-devices": [
{
"port": "COM1",
"name": "serial_card_0"
}
],
"reconnect-interval": 60000,
"seaio-devices": [
{
"adapter": 0,
"name": "pci_card_0"
}
],
"serial-devices": [
{
"port": "COM1",
"name": "serial_card_0"
}
]
}

Sample Scripts

List Devices

sub getDevices()
Request("/Extensions/Sealevel/devices", "")
end sub
 
sub onDevices(devices as Json)
if devices.Size == 0 Then
exit sub
end if
 
dim devCount as Integer = devices.Size - 1
for i = 0 to devCount
dim deviceObj as Json = devices.At(i)
Println(deviceObj.Dump())
Next
 
end sub
 
sub OnResponse(location as string, message as string)
if location == "/Extensions/Sealevel/devices" Then
dim j as Json
j.Load(message)
onDevices(j)
end if
end sub
 
 
getDevices()

Get Pin Values

sub getPinValue(devId as String, pinId as String)
Request("/Extensions/Sealevel/devices/" & devId & "/pins/" & pinId, "")
end sub
 
sub OnResponse(location as string, message as string)
dim j as Json
j.Load(message)
 
onPinValue(j.GetString("id"), j.GetInteger("value"))
end sub
 
sub onPinValue(pinId as String, value as Integer)
Println("Pin " & pinId & " value = " & value)
end sub
 
' Inputs
for i = 0 to 15
getPinValue("0", "" & i)
next
 
' Outputs
for i = 16 to 31
getPinValue("0", "" & i)
next

Set Output Pins

sub getPinValue(devId as String, pinId as String)
Request("/Extensions/Sealevel/devices/" & devId & "/pins/" & pinId, "")
end sub
 
sub setPinValue(devId as String, pinId as String, value as Integer)
dim payload as String = "{\"value\": " & value & "}"
Request("/Extensions/Sealevel/devices/" & devId & "/pins/" & pinId, payload)
end sub
 
sub OnResponse(location as string, message as string)
dim j as Json
j.Load(message)
 
onPinValue(j.GetString("id"), j.GetInteger("value"))
end sub
 
sub onPinValue(pinId as String, value as Integer)
Println("Pin " & pinId & " value = " & value)
end sub
 
setPinValue("0", "16", 1)
setPinValue("0", "18", 1)
 
' Outputs
for i = 16 to 31
getPinValue("0", "" & i)
next

Listen for Pin Changes

sub OnResponse(location as string, message as string)
 
if location.StartsWith("/Extensions/Sealevel/devices") and location.EndsWith("change") Then
dim j as Json
j.load(message)
onPinChanged(j.GetInteger("pin"), j.GetInteger("value"))
end if
end sub
 
sub onPinChanged(pinId as Integer, value as Integer)
Println("Pin " & pinId & " changed to " & value)
end sub
 
Request("/Extensions/Sealevel/devices/0/register", "")