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.
-
Install Ruby 2.0.0 or higher.
- Windows: Use RubyInstaller and make sure ruby/bin is in your system path.
- Linux: Use rbenv.
-
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.