Devices

The Devices link in the navigation bar displays a list of all devices discovered by Pathfinder Core PRO.

Each device entry in the list includes the following options:

Reference	Description
1	Clicking this link takes you directly to the device’s configuration web page.
2	If a different login is required by the device click this link to set the password.
3	Clicking this icon will remove this device from the system. See notes below for details.
4	The connection recycle icon should rarely, if ever, be used. Clicking this icon will cause Pathfinder to drop and reconnect its connection to the device.

Important Note: When a device is removed from the system, it will also remove all entries in the Audio and GPIO router for that device. It is important to note that if Livewire Discovery is enabled on the system page, the device may get re-discovered and added back into the list if it is still on the network.

Manually Adding Devices

Some devices cannot be discovered automatically. These include Axia OLED and LCD rackmount button panels. Additionally, you may want to add a device into the system without enabling the full network discovery engine. To add these into the system, click the Add button on the Devices dialog.

A dialog box will appear that allows you to define a range of IP addresses to scan and the investigation method to use.

Reference	Description
1	If you are adding a single device, type the same IP address in both boxes. The To box should auto-populate when you type an IP address into the IP Address box.
2	If you are adding an Axia audio or GPIO device, select Lwrp as the investigation type. See note below. If you are adding an Axia rackmount OLED or LCD panel, use the Lwcp investigation type.
3	Clicking Investigate will cause the system to try and contact a device on the requested IP address using the defined investigation type. If a device can be contacted and data can be discovered from the device, it will be added to the Devices list. Its routing resources will also be added to the requisite routers.

Virtual GPIO Node

Pathfinder Core PRO includes a virtual GPIO node which may be accessed by browsing to the GPIO navigation bar link under the System items.

This virtual node behaves very much like the GPIO portion of an Axia Livewire driver except that the number of ports is dynamically adjustable and includes a few additional features as described below.

When you first open the GPIO link it will recognize that the internal GPIO node has not been added to the devices table and will ask if you would like to add it. The node may only be used and/or configured after it has been added to the device list.

Click OK to discover and add the internal GPIO node into the device list. This will also discover the GPIO points into the GPIO router as well.

Reference	Description
1	Once the device has been added you will see the list of GPIO ports. By default, there are 4 ports in the system.
2	You can add additional GPIO ports by typing a new port count at the top of the screen and then clicking Update. This allows you to add any number of GPIO ports into the local virtual GPIO node.
3	Click the edit link to change the property values for any GPIO port. See the *Pathfinder Core PRO GPIO Properties* section below for details.

GPIO Refresher

It is important to understand the various ways GPIOs may be used in an Axia environment.

Software GPIOs with no source address assignment will simply allow closures to be directly tripped on either GPI or GPO by Pathfinder Core PRO
- Example: SRCA:””
If a source address field for a GPIO port uses a Livewire channel number in its address field, it will listen to and generate closures to and from an Axia Console over multicast
- Example: SRCA:9501
Finally, if the source address uses an IPAddress/port format it means that the GPIO port should use TCP to connect to the device at that IP Address, monitor the GPIs from the selected port on that device, and mirror those closures on this port’s GPOs; this is the method used by the PathfinderCore PRO GPIO router to route GPIO data across a network
- Example: SRCA:”172.16.1.23/8”

Pathfinder Core PRO GPIO Properties

By default, Pathfinder Core PRO’s GPIO node works in the same way as described above; clicking Edit in the GPIO table allows advanced users to manipulate advanced properties

Field	Description
Port Name	This allows you to type a unique name for this GPIO port.
MCast Mode	Selecting Node from the drop-down list allows the port to behave like a Livewire driver GPIO port when a Livewire channel number is typed in the source address. Specifically, the port will listen to GPIO messages from the console fader on which the Livewire channel number is loaded and change its GPO pins accordingly. Tripping the GPI pins of the port will send closures to the Axia Console. Selecting console allows the port to behave as if it were an Axia console. Therefore, GPIs that are tripped on this node will be sent to the GPOs of other GPIO ports on the network that have the same channel number assigned. Tripping a GPI on one of those other devices will cause the GPO on this port to change.
IRoute Mode	By default, this will be set to O. This property only applies to situations where an IP/Port or Livewire channel is used in the source address. When a GPI comes in from either of these sources, it is applied to a GPO on the port. This property allows you to change this behavior and apply the incoming GPI to either the GPI or to None which means it is ignored.
ORoute Mode	This property defines where inbound GPOs will be sent. By default, they are sent nowhere as this setting replicates other GPIO node functionality. When using IP/Port source addressing the Pathfinder Core PRO GPIO node is unique in that it will also subscribe to GPO changes for the port and these may be routed to I, O, or None. See note below.
Source Address	This field may be left blank if the closures will be used by Pathfinder and do not need to follow another port or console functionality. Alternatively, you may type a Livewire channel number or IP/Port value to this field. If you type an IP/Port value, you do not need to assign it in the configuration user interface. The GPIO router will allow you to manipulate this field much more easily by just making route changes.

Important Note: By manipulating IRoute Mode and ORoute Mode, it is possible to make a multicast or unicast GPIO route where one port’s inputs and outputs mirror another port.

RestApi

PathfinderCore PRO also allows for the addition of Rest API devices which can be used to send rest api commands to a rest api enabled device. In order to add a rest api device, click on the devices link and then click the plus icon. This will display the Address to Investigate dialog.

From the Investigation Type drop down, select Rest API. The dialog will change to show a name and a URL field.

Enter a name for the device and the http address to which to send rest api commands. Alternate ports may be used by adding a colon and the port number:

After clicking Investigate, the device will be added to the system.

You will notice that for rest api devices, you will see an edit link instead of a web page link. The edit link will bring up a dialog for customizing the message header used by each rest api command:

The <UsernamePassword> chunk will be replaced by a basic authentication conversion of the user name and password. If no user name and password is defined, the Authorization may be removed. Currently this device only supports basic authentication. You can use this dialog to add custom header messages if they are needed by the rest api device.

The ChangeLogin link allows you to assign a username and password to be used by rest api commands in the Authorization portion of the header.

Sending a command to the Rest API device

Once the device has been added to the system, it will be available in logic flows.

The SendToRestApi property needs to be structured in a specific way. The property value to send needs to have an operator (usually GET or PUT), a path, and optionally, some data. Note that the path portion should be only the data after the device path. For example:

PUT /my/path/url hello

When the device sends data it will prepend the device path when it sends to the device so that the http command becomes:

PUT http://172.16.1.97:4013/my/path/url hello

The data portion is optional and depends on the specification of the api you are trying to communicate with.

For example, a logic flow that sends to a rest api device when a button is pushed might look like:

SAP property memory slots and string builder memory slots can also be useful to build rest api commands according to the device’s specification and then pass the command through to the device whenever the memory slot changes.

Receiving data from the Rest API device

Please review the rest api technical details for more information on the pitfalls of using rest api to capture information from a device. In this case you would use the example above to send a request to the device probably using the GET operator. The information that is returned can be found in three read only properties (only seen if a start point is selected):

Response code returns the http response code that results from the last message sent. For example, it might return 200 if the request succeeded. Or it might return 404 if the path was not found. For more information on http response codes, see: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status.

The response data property will contain the actual data returned from the command. In many cases you may need a regex to filter the data for what you want to match in the logic flow.

The Response Success property will return true or false depending on whether the last rest api command was successful or not.

Rest API technical details

While rest APIs are currently very popular (thus the reason we are adding them to PathfinderCore PRO), we regard them as generally ill-suited for many broadcast applications.

For example, we recently did some work with a product whose control protocol was exclusively Rest API. One of the first things our customer wanted to do was have PathfinderCore Pro do an action whenever a user pressed a button. The problem is that in order to detect that button push we would have needed to poll at 2.5 times the minimum amount of time the button might be held down. For computers, this is not difficult until you start considering 25 buttons to a device and deployments of 600 to 700 devices. Now you have a situation where you are spending massive amounts of compute cycles on messages which basically say "nothing has changed".

The point of that story is to say that applications that need low latency responses to state changes do not scale well with non-event driven protocols like Rest API. The consumer of such protocols needs to be cognizant of the CPU load ramifications for what they are doing. Currently, if the user wants to poll, they would need to use an interval timer and a logic flow. We may at some point add a way to pre-program parameters that should be polled which would simplify that task, but we opted not to in this incarnation because of the potential abuse possibilities described above.

If all you care about is triggering a change and perhaps getting a response back that the change was made, then Rest APIs work well. But if real-time state change information is required, then care needs to be taken and other options employed if available.

This article provides a great analogy using a General and his army to illustrate the differences between REST and a socket-based architecture:

https://www.pubnub.com/blog/websockets-vs-rest-api-understanding-the-difference/

In short: Use this feature with care.