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).

Issues, Bugs, Feature Requests

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.

Installation

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)

Usage

netlinx-compile Support

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

Rake Tasks

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.

Command Line

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

Ruby Developer API

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

YAML Workspace Configuration

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

Directory Structure

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

Connection Settings

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

Additional Information

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.