UPB (Universal Power Bus) Driver

RSS

The UPB Driver connects to a UPB (Universal Power Bus) network. Supports two-way communication, fade rates, channels, links, blinking, toggling, optional polling, and device discovery. By default the driver will auto discover your network, however if you provide an 'UPStartExport.upe' file auto-discovery is turned off. For optimal performance you can use UPStart to export a file called 'UPStartExport.upe' to the common program data folder, which the driver can use to learn the network instead of using auto-discover (this is optional).

Auto-Discovery -or- UPStart Export File:

By default the driver will auto discover your network. For optimal performance you can use UPStart to export a file called 'UPStartExport.upe' to the Common Program Data Folder, which the driver can use to learn the network instead of using auto-discover (this is optional).

If no UPStart export file is found, the driver will auto-discover all devices for the specified network id and all device names.

If an UPStart export file is found, the UPB network will be loaded from the file including the network id, all devices and links.

Device State Polling:

The driver periodically requests the state of devices:

On startup, each device will be polled for its state at an interval of one device per 1.5 seconds.
After all levels have been read, the polling interval drops down to the default of 45 seconds or the value specified in the PollingInterval configuration parameter.
When an activate/deactivate link command is sent or received, the driver will poll the state of each device having the link id after the maximum fade rate duration for the link id (plus 2 seconds).

This driver has been successfully tested with the following PIMs:

PCS PulseWorx Model PIM-U v5.47
Simply Automated UMC-DB9 v4.17

Manufacturer: Multiple Manufacturers

Primary Communications Port: Serial

Table of Contents [Hide/Show]

Configuration Settings
Events
   Light Level Changed
   Light On/Off State Changed
   Ready State Changed
   Link Activated
   Link Deactivate
Instance Properties
   FirmwareVersion
   UpbVersion
   PimNetworkID
   PimDeviceID
   Connected
   LightLevels
   LightOnOffs
   LightNames
   LinkNames
   DeviceDisplayName
   DeviceStartTime
   DeviceLifecycleStage
   DeviceIsRunningAndReady
Instance Methods
   SendRawCommand ( Number, String )
   TurnOnLight ( Number )
   TurnOffLight ( Number )
   TurnOnAllLights
   TurnOffAllLights
   SetLightLevel ( Number, Number )
   SetLightLevel ( Number, Number, Number )
   SetLightLevel ( Number, Number, Number, Number )
   TurnOnLightByName ( String )
   TurnOffLightByName ( String )
   SetLightLevelByName ( String, Number )
   SetLightLevelForDuration ( Number, TimeSpan, Number, Number )
   TurnOnLightForDuration ( Number, TimeSpan )
   SetLinkLevel ( Number, Number, Number )
   TurnOnLed ( Number, Number )
   TurnOffLed ( Number, Number )
   StopDeviceFade ( Number )
   StopLinkFade ( Number )
   BlinkDevice ( Number, Number )
   BlinkDevice ( Number, Number, Number )
   BlinkLink ( Number, Number )
   ToggleDevice ( Number, Number, Number )
   ToggleDevice ( Number, Number, Number, Number )
   ActivateLink ( Number )
   DectivateLink ( Number )
   SimulateReceivedData ( String )
   SetPropertyForDuration ( String, TimeSpan, Object, Object )
   SetPropertyForDuration ( String, Number, TimeSpan, Object, Object )

Configuration Settings

Serial Port Name : The name of the serial port that the UPB PIM is connected to. Ex. COM1
Network Id : The default UPB network id to communicate with. (1-255)
Polling Interval : (optional) The optional device state polling interval in seconds. The driver can poll the device state of devices, which is convenient if the switches are not set to report there state when the paddle is pressed. The default is 45 seconds.

Events

Light Level Changed

Occurs when the level of a UPB device changes.

Whenever Filter:

PropertyIndex : The index in the property's array. This is used for device properties that represent an array (or list) of values.

EventArgs:

Number Index : The index within the property array.
Number NewValue : The new property value.
Number PreviousValue : The previous property value.

Light On/Off State Changed

Occurs when the light changes from on to off or off to on. Any level greater than zero is considered on.

Whenever Filter:

PropertyIndex : The index in the property's array. This is used for device properties that represent an array (or list) of values.

EventArgs:

Number Index : The index within the property array.
Number NewValue : The new property value.
Number PreviousValue : The previous property value.

Ready State Changed

The device's running and ready state changed.

Whenever Filter:

none

EventArgs:

Number NewValue : The new property value.
Number PreviousValue : The previous property value.

Link Activated

Occurs when an activate link command is received.

Whenever Filter:

LinkID : (optional) The link ID.
DeviceID : (optional) The source device ID.

EventArgs:

Number LinkID : The link ID.
Number DeviceID : The source device ID.

Link Deactivate

Occurs when a deactivate link command is received.

Whenever Filter:

DeviceID : (optional) The source device ID.
LinkID : (optional) The link ID.

EventArgs:

Number DeviceID : The source device ID.
Number LinkID : The link ID.

Instance Properties

FirmwareVersion

Gets the firmware version.

Accessibility : Read Only

Type: Number

UpbVersion

Gets the version of the UPB specification the PIM device conforms to.

Accessibility : Read Only

Type: Number

PimNetworkID

Gets the network id that is assigned to the PIM.

Accessibility : Read Only

Type: Number

PimDeviceID

Gets the device id that is assigned to the PIM.

Accessibility : Read Only

Type: Number

Connected

Gets a value indicating if a connection is established with the UPB PIM.

Accessibility : Read Only

Type: Boolean

LightLevels

Gets the percent on level of the lights. 0-100

Accessibility : Read Only

Type: Array

LightOnOffs

Gets or sets the light to a fully on state or fully off.

Accessibility : Read Only

Type: Array

LightNames

Gets the names of the lights.

Accessibility : Read Only

Type: Array

LinkNames

Gets the names of the links.

Accessibility : Read Only

Type: Array

DeviceDisplayName

The display name for this device.

Accessibility : Read Only

Type: String

DeviceStartTime

The date and time when this device was started.

Accessibility : Read Only

Type: DateTime

DeviceLifecycleStage

The current lifecycle stage of the device. The stages in order are: Pending Start, Starting, Running, Stopping

Accessibility : Read Only

Type: Number

DeviceIsRunningAndReady

Indicates if the device is ready for use, ie it is in the Running lifecycle stage and all properties are valid and all methods are ready to be used.

Accessibility : Read Only

Type: Boolean

Instance Methods

SendRawCommand ( Number, String )

Sends a command that may otherwise not be supported by the driver.

Syntax

void SendRawCommand( Number preamble, String command )

Parameters

preamble : The packet preamble. One of 14=Transmit UPB Message, 12=Read PIM Registers. 17=Write PIM Regsiters.

command : The command string to send. The driver will append the command with a carriage-return.

TurnOnLight ( Number )

Turns on the specified device. Multi-channel devices may require using Set Light Level and specifying the channel number.

Syntax

void TurnOnLight( Number deviceID )

Parameters

deviceID : The id of the light.

TurnOffLight ( Number )

Turns off the specified node. Multi-channel devices may require using Set Light Level and specifying the channel number.

Syntax

void TurnOffLight( Number deviceID )

Parameters

deviceID : The id of the light.

TurnOnAllLights

Turns all lights on.

Syntax

void TurnOnAllLights( )

Parameters

none

TurnOffAllLights

Turns all lights off.

Syntax

void TurnOffAllLights( )

Parameters

none

SetLightLevel ( Number, Number )

Sets the specified light's level to the specified percent.

Syntax

void SetLightLevel( Number deviceID, Number percentOn )

Parameters

deviceID : The device id (1-250).

percentOn : The percent level to set the light to. Valid values: 0 to 100 where 0 is typically off and 100 is fully on.

SetLightLevel ( Number, Number, Number )

Sets the specified light's level to the specified percent at the specified fade rate.

Syntax

void SetLightLevel( Number deviceID, Number percentOn, Number fadeRate )

Parameters

deviceID : The device id (1-250).

percentOn : The percent level to set the light to. Valid values: 0 to 100 where 0 is typically off and 100 is fully on.

fadeRate : The rate at which to fade.

0 = 0 Seconds (Snap)

1 = 0.8 Seconds

2 = 1.6 Seconds

3 = 3.3 Seconds

4 = 5 Seconds

5 = 6.6 Seconds

6 = 10 Seconds

7 = 20 Seconds

8 = 30 Seconds

9 = 1 Minute

10 = 2 Minute

11 = 5 Minute

12 = 10 Minute

13 = 15 Minute

14 = 30 Minute

15 = 1 Hour

SetLightLevel ( Number, Number, Number, Number )

Sets the specified light's level to the specified percent at the specified fade rate.

Syntax

void SetLightLevel( Number deviceID, Number percentOn, Number fadeRate, Number channel )

Parameters

deviceID : The device id (1-250).

percentOn : The percent level to set the light to. Valid values: 0 to 100 where 0 is typically off and 100 is fully on.

fadeRate : The rate at which to fade.

0 = 0 Seconds (Snap)

1 = 0.8 Seconds

2 = 1.6 Seconds

3 = 3.3 Seconds

4 = 5 Seconds

5 = 6.6 Seconds

6 = 10 Seconds

7 = 20 Seconds

8 = 30 Seconds

9 = 1 Minute

10 = 2 Minute

11 = 5 Minute

12 = 10 Minute

13 = 15 Minute

14 = 30 Minute

15 = 1 Hour

channel : The channel, which is defined by device type. 6 and 8 button keypads define the button LEDs as channels. (0-255).

TurnOnLightByName ( String )

Turns on the specified node.

Syntax

void TurnOnLightByName( String name )

Parameters

name : The name of the light.

TurnOffLightByName ( String )

Turns off the specified node.

Syntax

void TurnOffLightByName( String name )

Parameters

name : The name of the light.

SetLightLevelByName ( String, Number )

Sets the specified node's level to the specified percent.

Syntax

void SetLightLevelByName( String name, Number percentOn )

Parameters

name : The name of the light.

percentOn : The percent level to set the light to. Valid values: 0 to 99 where 0 is typically off and 99 is fully on.

SetLightLevelForDuration ( Number, TimeSpan, Number, Number )

Sets a light's level for a duration of time and then sets the light to a subsequent level.

Syntax

void SetLightLevelForDuration( Number iD, unknown duration, Number initialPercentOn, Number finalPercentOn )

Parameters

iD : The id of the light.

duration : The amount of time to wait before setting the light level to the specified subsequent light level.

initialPercentOn : The percent level to set the light to.

finalPercentOn : The percent level to set the light to after the duration has passed.

TurnOnLightForDuration ( Number, TimeSpan )

Turns a light fully on for a duration of time and then turns the light off.

Syntax

void TurnOnLightForDuration( Number iD, unknown duration )

Parameters

iD : The id of the light.

duration : The amount of time to wait before turning off the light.

SetLinkLevel ( Number, Number, Number )

Sets a group of linked device components to the specified percent level at the specified fade rate.

Syntax

void SetLinkLevel( Number linkID, Number percentOn, Number fadeRate )

Parameters

linkID : The link id (1-250).

percentOn : The percent level to set the light to. Valid values: 0 to 100 where 0 is typically off and 100 is fully on.

fadeRate : The rate at which to fade.

0 = 0 Seconds (Snap)

1 = 0.8 Seconds

2 = 1.6 Seconds

3 = 3.3 Seconds

4 = 5 Seconds

5 = 6.6 Seconds

6 = 10 Seconds

7 = 20 Seconds

8 = 30 Seconds

9 = 1 Minute

10 = 2 Minute

11 = 5 Minute

12 = 10 Minute

13 = 15 Minute

14 = 30 Minute

15 = 1 Hour

TurnOnLed ( Number, Number )

Turns on the specified LED indicator.

Syntax

void TurnOnLed( Number deviceID, Number ledID )

Parameters

deviceID : The device id (1-250).

ledID : The LED to turn off. On a 6 button keypad, 1=On, 3=A, 4=B, 5=C, 6=D, 7=Off. On an 8 button keypad, 1=E, 2=F, 3=G, 4=H, 5=I, 6=J, 7=K, 0=L.

TurnOffLed ( Number, Number )

Turns off the specified LED indicator.

Syntax

void TurnOffLed( Number deviceID, Number ledID )

Parameters

deviceID : The device id (1-250).

ledID : The LED to turn off. On a 6 button keypad, 1=On, 3=A, 4=B, 5=C, 6=D, 7=Off. On an 8 button keypad, 1=E, 2=F, 3=G, 4=H, 5=I, 6=J, 7=K, 0=L.

StopDeviceFade ( Number )

Stop fading a dimmer-type device that is currently fading.

Syntax

void StopDeviceFade( Number deviceID )

Parameters

deviceID : The device id (1-250).

StopLinkFade ( Number )

Stop fading a group of linked device components on dimmer-type devices that is currently fading.

Syntax

void StopLinkFade( Number linkID )

Parameters

linkID : The link id (1-250).

BlinkDevice ( Number, Number )

Blink a device on and off at a specified rate. Not all devices support the blink command.

Syntax

void BlinkDevice( Number deviceID, Number blinkRate )

Parameters

deviceID : The device id (1-250).

blinkRate : The blink rate (0=stop blinking, 1=fastest, 255=slowest).

BlinkDevice ( Number, Number, Number )

Blink a device channel on and off at a specified rate. Not all devices support the blink command.

Syntax

void BlinkDevice( Number deviceID, Number blinkRate, Number channel )

Parameters

deviceID : The device id (1-250).

blinkRate : The blink rate (0=stop blinking, 1=fastest, 255=slowest).

channel : The channel, which is defined by device type. 6 and 8 button keypads define the button LEDs as channels. (0-255).

BlinkLink ( Number, Number )

Blink a group of linked device components on and off at a specified rate. Not all devices support the blink command.

Syntax

void BlinkLink( Number linkID, Number blinkRate )

Parameters

linkID : The device id (1-250).

blinkRate : The blink rate (0=stop blinking, 1=fastest, 255=slowest).

ToggleDevice ( Number, Number, Number )

Toggle the specified device between its current state and the opposite state one or more times at a specified rate. Not all devices support the toggle command.

Syntax

void ToggleDevice( Number deviceID, Number count, Number toggleRate )

Parameters

deviceID : The device id (1-250).

count : The number of times to toggle the device. (0-255)

toggleRate : The toggle rate (0=stop toggling, 1=fastest, 255=slowest).

ToggleDevice ( Number, Number, Number, Number )

Toggle the specified device's channel between its current state and the opposite state one or more times at a specified rate. Not all devices support the toggle command.

Syntax

void ToggleDevice( Number deviceID, Number count, Number toggleRate, Number channel )

Parameters

deviceID : The device id (1-250).

count : The number of times to toggle the device. (0-255)

toggleRate : The toggle rate (0=stop toggling, 1=fastest, 255=slowest).

channel : The channel, which is defined by device type. 6 and 8 button keypads define the button LEDs as channels. (0-255).

ActivateLink ( Number )

Activate the specified link.

Syntax

void ActivateLink( Number linkID )

Parameters

linkID : The link id to activate (1-250).

DectivateLink ( Number )

Deactivate the specified link.

Syntax

void DectivateLink( Number linkID )

Parameters

linkID : The link id to activate (1-250).

SimulateReceivedData ( String )

Simulate data being received from the serial port. The data will be processed as if it were actually received as incoming data from the serial ports. This is useful for testing.

Syntax

void SimulateReceivedData( String data )

Parameters

data : The data to simulate being received.

SetPropertyForDuration ( String, TimeSpan, Object, Object )

Sets a property for a duration of time and then sets the property to a subequent value asynchronously. This action returns after setting the first value and the timer and subsequent property set run in the background. Subsequent sets of the same property will reset the timer if the subsequent value has not yet been set. This is an advanced feature, be sure to set the property name correctly.

Syntax

void SetPropertyForDuration( String propertyName, unknown duration, Object initialValue, Object finalValue )

Parameters

propertyName : The name of the property to set.

duration : The amount of time to wait after setting the initial value to set the subsequent value.

initialValue : The value to set the property to initially.

finalValue : The value to set the property to after the duration of time has passed.

SetPropertyForDuration ( String, Number, TimeSpan, Object, Object )

void SetPropertyForDuration( String propertyName, Number arrayIndex, unknown duration, Object initialValue, Object finalValue )

Parameters

propertyName : The name of the property to set.

arrayIndex : The property's array index to set.

duration : The amount of time to wait after setting the initial value to set the subsequent value.

initialValue : The value to set the property to initially.

finalValue : The value to set the property to after the duration of time has passed.