netlinx-workspace

A library for working with AMX NetLinx Studio workspaces in Ruby.

This library provides a developer API for working with NetLinx Studio workspaces in Ruby. It also adds compiler support to the netlinx-compile gem for these workspaces.

APW Target Version

This library targets NetLinx .apw version 4.0 (created by NetLinx Studio 4).

Any bugs and feature requests should be reported on the GitHub issue tracker:

https://github.com/amclain/netlinx-workspace/issues

Pull requests are preferred via GitHub.

Mercurial users can use Hg-Git to interact with GitHub repositories.

netlinx-workspace is available as a Ruby gem.

1. Install Ruby 2.0.0 or higher.

   • Windows: Use RubyInstaller and make sure ruby/bin is in your system path.
   • Linux: Use rbenv.

2. Open the command line and type:

    gem install netlinx-workspace
    gem install netlinx-compile (optional for compiler support)

Installing this gem automatically enables support for netlinx-compile to compile NetLinx Studio workspace (.apw) files.

netlinx-workspace comes with a set of rake tasks that can be used by adding require 'netlinx/rake/workspace' to your project's Rakefile. Type rake --tasks on the command line to view the available tasks.

netlinx-workspace is available from the command line. A list of options can be displayed by executing netlinx-workspace --help.

A Ruby API is provided for developers looking to integrate the netlinx-workspace library into thier own tools. See the netlinx-workspace API documentation.

netlinx-workspace has the ability to generate a NetLinx Studio Workspace (.apw) file from a workspace.config.yaml text file. The advantage of using YAML is that a workspace can easily be defined and maintained without the use of a proprietary GUI editor. This means developers are free to use whichever text editor they please, like sublime-netlinx, to maintain a NetLinx workspace. Automated tools can generate, maintain, and analyze this file as well.

To generate a template workspace config file, execute netlinx-workspace --create.

systems:
  -
    name: Client - Room
    connection: 192.168.1.2
    touch_panels:
      -
        path: Touch Panel.TP4
        dps:  10001:1:0
    ir:
      -
        path: IR.irl
        dps:  5001:1:0

In order to simplify the configuration file, assumptions are made as to where project files are located:

include/
ir/
module/
touch_panel/
system_name.axs
workspace.config.yaml

The include directory is automatically scanned for .axi files, and the module directory is scanned for .tko and .jar files. .axs modules are ignored, as they should be tested and compiled independently before being included in a project. However, it is encouraged to place the .axs module source code file in the module directory as a courtesy so that other developers can fix bugs and make updates if necessary.

Since touch panel and IR files can have a device address (DPS) attached, these files are explicitly listed in the system. Multiple addresses can be defined by using a YAML array.

ir:
  -
    path: Cable Box.irl
    dps: ['5001:5:0', '5001:6:0', '5001:7:0', '5001:8:0']

In the case of multiple systems, the root directory of each system may need to be offset from the workspace directory. This can be achieved by using the root key.

systems:
  -
    name: Room 101
    root: room_101
    connection: 192.168.1.2
    touch_panels:
      - path: Room_101.TP4
        dps:  10001:1:1
  -
    name: Room 201
    root: room_201
    connection: 192.168.1.3
    touch_panels:
      - path: Room_201.TP4
        dps:  10002:1:2

room_101/include/
room_101/ir/
room_101/module/
room_101/touch_panel/
room_101/Room 101.axs

room_201/include/
room_201/ir/
room_201/module/
room_201/touch_panel/
room_201/Room 201.axs

workspace.config.yaml

The connection key supports a variety of options for configuring a system's connection to the master controller:

# IP address. Default ICSLan port 1319 is used.
connection: 192.168.1.2

# IP address with specific ICSLan port number.
connection: 192.168.1.2:1234

# IP address with specific ICSLan port number.
connection:
  host: 192.168.1.2
  port: 1234

# Serial port. Default baud rate 38,400 is used.
connection: COM2

# Serial port with baud rate.
connection: COM2:57600

# Serial port with multiple port settings.
connection:
  port: com2
  baud_rate: 115200
  data_bits: 7
  parity: even
  stop_bits: 2

Examples of workspace configuration files can be found in the spec\workspace\yaml directory of this library. These files show all of the keywords that are available.