SAL User Guide

SAL_User_Guide

User Manual: Pdf

Open the PDF directly: View PDF .
Page Count: 55

Download
Open PDF In Browser	View PDF

Large Synoptic Survey Telescope (LSST)
LSST Service Abstraction Layer (SAL)
Software SDK Users Manual

Page 1 of 55

Change Record
Version

Date

Description

Owner name

V1.0

12/13/2013

Initial Draft

D. Mills

V2.0

06/06/2014

First Release

D. Mills

V2.3

06/05/2015

Added detail about large-file handling

D. Mills

V2.4

07/27/2015

Major revision to document XML schema use

D. Mills

V3.0

04/29/2016

Revisions for SAL V3 release

D. Mills

V3.5

02/23/2016

Revisions for SAL V3.5 release

D.Mills

V3.6

03/09/2018

Add lists of generic commands and events

D. Mills

Page 2 of 55

Table of Contents
LSST Service Abstraction Layer (SAL)

1

Software SDK Users Manual

1

1

5

Introduction

2. Installation

6

2.0.1 Installation from a tar archive release

6

2.0.2 Installation from Git repositories

7

2.0.3 Install location customization

7

2.1 Installation in a virtual machine

8

2.2 Standard usage

9

3. Data Definition

9

3.1 Telemetry Definition

10

3.2 Command Definition

11

3.3 Log Event Definition

12

3.4 Updating the XML definitions

13

4. Using the SDK

14

4.1 Recommend sequence of operations

15

4.1.1 Step 1 – Definition

16

4.1.2 Step 2 – Validation

16

4.1.3 Step 3 – Update Structure and documentation

16

4.1.4 Step 4 – Code Generation

17

4.2 salgenerator Options

22

4.3 SAL API examples

23

5. Testing

24

5.1 Environment

24

5.2 Telemetry

25

5.3 Commands

25
27

5.4 Events

Page 3 of 55

28

6. Application programming Interfaces

29

6.1. C++

29

6.2 Java

30

6.3 Python (pybind11 bindings)

31

7.0 SAL XML Schema
7.1 Telemetry
7.1.1 telemetrySetType

32
32
32
32

7.1.2 telemetryType

32
32

7.1.3 telemetryItemType

33
33

7.2 Commands
7.2.1 commandSetType

34
34
34

7.2.2 commandType

34
34

7.2.3 commandItemType

35
35

7.3 Events

36

7.3.1 eventSetType

36

7.3.2 eventType

36

7.3.3 eventItemType

37

8.0 Compiler Options and Link Libraries

Page 4 of 55

38

1 Introduction
This document briefly describes how to use the SAL SDK to generate application
level code to utilize the supported services (Commanding, Telemetry and Events).
The SAL SDK should be installed on a modern (x86_64) Linux computer.
The current baseline recommended configuration is 64-bit CentOS 7.3.
The following packages should also be installed prior to working with the SDK
(use either the rpm or yum package managers for CentOS, and apt-get , dpkg,
or synaptic for Debian based systems). Installation of system packages must be
done using sudo (eg sudo yum install , or sudo apt-get install).
- gcc-c++
- make
- ncurses-libs or ncurses-dev
- xterm
- xorg-x11-fonts- misc
- java-1.7.0-openjdk-devel
- maven
- python-devel
- swig
- git
- tk-devel
The distribution includes dedicated versions of the following packages
- OpenSplice
All the services are built upon a framework of OpenSplice DDS. Code may be autogenerated for
a variety of compiled and scripting languages, as well as template documentation, and
components appropriate for ingest by other software engineering tools.
A comprehensive description of the SAL can be found in doc/LSE74-html, navigate
to the directory with a web browser to view the hyper-linked documentation.
e.g.
firefox file:///path-to-installation/doc/LSE74-html/index.html

Page 5 of 55

2. Installation
A minimum of 800Mb of disk space is required, and at least 1Gb is recommended
to leave some space for building the test programs.
The default OpenSplice configuration requires that certain firewall rules are added,
alternatively, shut down the firewall whilst testing.
For iptables : this can be done(as root) with the following command
sudo /etc/init.d/iptables stop
For Ubuntu: use sudo ufw disable
firewalld : this can be done (as root) with the following commands
First, run the following command to find the default zone:
firewall-cmd --get-default-zone
Next, issue the following commands:
firewall-cmd --zone=public --add-port=250-251/udp --permanent
firewall-cmd --zone=public --add-port=7400-7413/udp --permanent
firewall-cmd --reload
Replace public with whatever the default zone says, if it is different.
The location of the OpenSplice configuration file is stored in the
environment variable OSPL_URI, and an extensive configuration tool
exists (osplconf), should customization be necessary.
2.0.1 Installation from a tar archive release
The tar archive format release includes a compatible version of OpenSplice
as well as the SAL toolkit.
Unpack the SAL tar archive in a location of choice (/opt is recommended),
e.g. in a terminal, replacing x.y.z with the appropriate version id
cd /opt
tar xzf [location-of-sdk-archive]/salSDK-x.y.z_x86_64.tgz
and then add the SDK setup command.
source /opt/setup.env
Page 6 of 55

to your bash login profile.
2.0.2 Installation from Git repositories
Use a git client of your preference to check out the required branch of the following repositories
https://github.com/lsst-ts/ts_sal
https://github.com/lsst-ts/ts_opensplice
and then add the SDK setup command.
source /opt/setup.env
to your bash login profile.
2.0.3 Install location customization
If you chose to install the SDK in a location other than /opt, then you will need
to edit the first line of the setup.env script to reflect the actual location.
e.g.
LSST_SDK_INSTALL=/home/saltester
The standard location for the OpenSplice package is in the same directory as the SDK,
But you can install it elsewhere as long as you edit the OSPL_HOME environment variable to
reference the actual path.
Another important environment variable is SAL_WORK_DIR. This is the directory
in which you will run the SAL tools, and in which all the output files and libraries
will be generated. By default this will be the “test” subdirectory in LSST_SDK_INSTALL, but
you can change SAL_WORK_DIR to redefine it if required.
ALL THE salgenerator STEPS MUST BE RUN FROM THE SAL_WORK_DIR DIRECTORY
If you will be running SAL applications in parallel with other users on your subnet, it is
advisable to partition your network traffic so as not to interfere with each others activities.
This can be done by setting the environment variable LSST_DDS_DOMAIN to a unique
string value for each user.
Also retrieve ts_xml and copy the appropriate subsystem definitions to your working directory.
e.g. cp ts_xml- master/sal_interfaces/mysubsystem/*.xml test/.

Page 7 of 55

Where test is the working directory specified by the SAL_WORK_DIR environment variable.
Add the invocation of setup.env to your bash login profile
source /sal-install-directory-path/setup.env

The most common SDK usage consists of simple steps :
1) Define Telemetry, Command or Log activity (either using the SAL VM, or manually
with an ascii text editor). For details of the SAL VM interface , please refer to
Document-xxxxx.
The current prototypes for each subsystem can be used as a baseline, eg for the dome
subsystem
cd $SAL_WORK_DIR
cp $SAL_HOME/scripts/xml-templates/dome/*.xml .

2) Generate the interface code using 'salgenerator'
3) Modify the autogenerated sample code to fit the application required.
4) Build if necessary, and test the sample programs
Example makefiles are provided for all the test programs. The list of
libraries required to link with the middleware can be found in section 8.0

2.1 Installation in a virtual machine
The SDK has been tested in a Virtual Machine environment (VirtualBox).
To set up a VM appropriately for this usage :
1. In VM configuration , choose Bridged Adaptor for the network device
2. Add a sal user account during OS installation, the user should be an administrator
3. Choose Gnome Desktop + Development tools during OS installation
4. From VM menu , install Guest Additions
Page 8 of 55

5. Once the OS has booted, enable the network
6. Verify the network is ok.
7. sudo yum install xterm xorg-x11-fonts- misc java-1.7.0-openjdk-devel boost-python
boost-python-devel maven python-devel tk-devel
8. Configure (or disable) iptables and firewalld
eg systemctl disable iptables
systemctl disable firewalld
system stop iptables
system stop firewalld

2.2 Standard usage
Normal usage of the SDK comprise four main steps
1.Define Telemetry, Command, and Event datatypes (either using the SAL VM website
interface, or an asci or XML editor). In some cases the XML from another subsystem might
provide a useful bootstrap. See the ts_xml repository.
2. Generate the interface code using the ‘salgenerator’
3. Modify the autogenerated sample code to fit the application required
4. Build and test the sample programs
Example makefiles are provided for all the test programs. The list of libraries required to link an
application with the middleware can be found in section 8.0

3. Data Definition
In all XML data definition files the IDL_Type keyword is used to specify the datatype of each
field. The following datatypes are supported:






short
long (this is a 4 byte integer, and is represented as int on Linux 64-bit)
long long (8 byte integer)
unsigned short
unsigned long (this is a 4 byte integer, and is represented as int on Linux 64-bit)

Page 9 of 55










unsigned long long (8 byte integer)
float
double
char , specify length using the Count tag
boolean
octet (sequence of unsigned bytes)
string, specify length using the Count tag
numeric arrays, use the Count tag with any numeric type

If there is a time-of-data associated with an item, then it should be named “timestamp”,
and be of type double. The time should be TAI time as returned by the getCurrentTime
method. If more than one timestamp is needed in a topic, then they should be named
“timestamp-name1, timestamp-name2 etc”. If an array of times is required, then the type
should be “double timestamp[size]”.

3.1 Telemetry Definition
A very simple XML schema is used to define a telemetry topic.
The topic is the smallest unit of information which can be exchanged using the SAL
mechanisms.

The following Reserved words may NOT be used in names and will flag an error at
the validation phase (once the SAL System Dictionary is finalized, the item names
will also be validated for compliance with the dictionary).
Reserved words : bstract any attribute boolean case char component const consumes context
custom dec default double emits enum eventtype exception factory false finder fixed float
getraises home import in inout interface limit local long module multiple native object octet
oneway out primarykey private provides public publishes raises readonly sequence setraises
short string struct supports switch true truncatable typedef typeid typeprefix union unsigned uses
valuebase valuetype void wchar wstring

Page 10 of 55

e.g.

hexapod
2.5
A Developer
hexapod_LimitSensors

liftoff

0.054
short


18


limit

0.054
short

18



3.2 Command Definition

Page 11 of 55

The process of defining supported commands is similar to Telemetry using XML.
The command aliases correspond to the ones listed in the relevant subsystem ICD.
e.g.

hexapod
2.5
salgenerator
hexapod_command_configureAcceleration
configureAcceleration
drive
acceleration


http://sal.lsst.org/SAL/Commands/hexapod_command_configureAcceleration.html

xmin 
 
double
 
1


xmax
 
double
 
1



Note : The generic lifecycle commands should NOT be included , they are automatically generated during the
salgenerator validation and/or UML to XML processing. The current generic command set is {start, stop, enable,
disable, abort, enterControl, exitControl, standby,SetValue}

3.3 Log Event Definition
Events are defined in a similar fashion to commands. e.g
The Log Event aliases are as defined in the relevant ICD.
e.g.
Page 12 of 55


hexapod
2.4
salgenerator
hexapod_logevent_limit
limit
http://sal.lsst.org/SAL/Events/hexapod_logevent_limit .html

prio rity
Severity of the event
long
NA
1


axis
 
string
 
1


limit
 
string
 
1


type
 
string
 
1



Note : The generic lifecycle events should NOT be included , they are automatically generated
during the salgenerator validation and/or UML to XML processing. The current generic event
set is SettingVersions, SummaryState, DetailedState, ErrorCode, AppliedSettingsMatchStart.

3.4 Updating the XML definitions
The XML definitions of the SAL objects for each subsystem are maintained in
a github repository (https://github.com/lsst-ts/ts_xml).

Page 13 of 55

When subsystem developers update the XML definitions for their interfaces, they should create a
new feature branch in the github repository and put the modified version into it. Once the
feature(s) have been fully tested, the corresponding changes are made made to the appropriate
ICD. Once the ICD has been approved by the Change Control Board, the modified XML will be
merged into the master branch and assigned an official release number. The master (release)
branch is used to generate the SAL runtime libraries which can be used by other subsystems for
integration testing. The master branch is also used by the Continuous Integration Unit
Testing framework.
The XML definition files for the subsystem you are developing should be checked out of the
github repository to ensure you are working with the latest version.
For convenience the full set of current definition files in also included in each SAL SDK
Release (in lsstsal/scripts/xml-templates).
The XML definition files should be copied to the SAL_WORK_DIR directory before
using the SAL tools.
The SAL tools must be run from the SAL_WORK_DIR directory.

4. Using the SDK
Before using the SDK , make sure that all the directories in the SAL_WORK_DIR and
The SAL installation directory are owned by you
e.g.
cd $SAL_WORK_DIR
chown –R : *

Once Telemetry/Command/Events have been defined , either using the SAL VM or hand edited,
e.g. for skycam, interface code and usage samples can
be generated using the salgenerator tool. e.g.
salgenerator skycam validate
salgenerator skycam sal cpp
would generate the c++ communications libraries to be linked with any user code which needs
to interface with the skycam subsystem.
Page 14 of 55

The "sal" keyword indicates SAL code generatio n is the required operation,
the selected wrapper is cpp (GNU G++ compatible code is generated, other options
are java, isocpp and python).
C++ code generation produces a shared library for type support and another
for the SAL API. It also produces test executables to publish and subscribe to all
defined Telemetry streams, and to send all defined Commands and log Events.
Java code generation produces a .jar class library for type support and another
for the SAL API. It also produces .jar libraries to test publishing and subscribing to
all defined Telemetry streams, and to send all defined Commands and log Events.
The “python” option generates an import'able library. Simple example scripts to perform the
major functions can be found later in this document.
The “labview” keyword indicates that a LabVIEW compatible shared library and Monitor task
should be built (the “sal cpp” step must previously have been run).
The “maven” keyword indicates that a Maven project should be built for the subsystem. This will
be placed in $SAL_WORK_DIR/maven/[subsystem]_[version], The “sal java” step must
previously have been run).

4.1 Recommend sequence of operations
1. Create the XML Telemetry , Command, and Event definitions
2. Use the salgenerator validate operation
3. Use the salgenerator html operation
4. Use the salgenerator sal operation
5. Verify test programs run correctly
6. Build the SAL shared library / JAR for the subsystem
7. Begin simulation/implementation and testing

Page 15 of 55

4.1.1 Step 1 – Definition
Use an XML editor to create/modify the set of subsystem xml files. Each file should be
appropriately named and consists of a either Telemetry, Command,
or Event definitions. The current prototypes for each subsystem can be
found at https://github.com/lsst-ts/ts_xml.

4.1.2 Step 2 – Validation
Run the salgenerator tool validate option for the appropriate subsystem.
e.g.

salgenerator mount validate

The successful completion of the validation phase results in the
creation of the following files and directories.
idl-templates – Corresponding IDL DDS topic definitions
idl-templates/validated – validated and standardized idl
idl-templates/validated/sal – idl modules for use with OpenSplice
sql – database table definitions for telemetry
xml – XML versions of the all telemetry definitions

4.1.3 Step 3 – Update Structure and documentation
Run the salgenerator html option for the appropriate subsystem.
e.g.

salgenerator mount html

The successful completion of the html phase results in the
creation of the following files and directories which may be
Page 16 of 55

used to update the SAL online configuration website. (See SAL VM
documentation for upload details).
html – a set of directories, one per .idl file, with web forms for editing online
a set of index-dbsimulate web page forms
a set of index-simulate web page forms
a set of sal-generator web page forms

4.1.4 Step 4 – Code Generation
Run the salgenerator tool using the sal option for the appropriate subsystem.
The sal option requires at least one target language to also be specified.
The current target languages are cpp, isocpp, java and python.

Depending upon the target language , successful completion of the code
generation results in the following output directories (e.g for mount)
e.g.

salgenerator mount sal cpp

cpp mount:

- common mount support files
cpp
isocpp
java

mount/cpp:
ccpp_sal_mount.h
libsacpp_mount_types.so
Makefile.sacpp_mount_types
sal_mount.cpp
sal_mountDcps_impl.cpp
sal_mount.idl
sal_mountDcps.cpp
sal_mountDcps_impl.h
sal_mountSplDcps.cpp
Page 17 of 55

- main include file
- dds type support library
- type support makefile
- item access support
- type class implementation
- type definition idl
- type support interface
- type implementation headers
- type support I/O

sal_mountDcps.h
sal_mount.h
sal_mountSplDcps.h
src

- type interface headers
- type support class
- type I/O headers

mount/cpp/src:
CheckStatus.cpp
CheckStatus.h
mountCommander.cpp
mountController.cpp
mountEvent.cpp
mountEventLogger.cpp
Makefile.sacpp_mount_cmd
Makefile.sacpp_mount_event
sacpp_mount_cmd
sacpp_mount_ctl
sacpp_mount_event
sacpp_mount_eventlog
sal_mount.h
sal_mountC.h
sal_mount.cpp

mount_TC:

- specific to particular telemetry stream

cpp
isocpp
java
python
mount_TC/cpp:
src
standalone
mount_TC/cpp/src:
Page 18 of 55

- test dds status returns
- test dds status headers
- command generator
- command processor
- event generator
- event logger
- command support makefile
- event support makefile
- test program
- test program
- test program
- test program
- SAL class headers
- SAL C support
- SAL class

CheckStatus.cpp
CheckStatus.h
mount_TCDataPublisher.cpp
mount_TCDataSubscriber.cpp

- check dds status class
- check dds status header
- Actuators data publisher
- Actuators data subscriber

mount_TC/cpp/standalone:
Makefile
Makefile.sacpp_mount_TC_sub
Makefile.sacpp_mount_TC_pub
sacpp_mount_sub
sacpp_mount_pub
src

- subscriber makefile
- publisher makefile
- test program
- test program

mount_TC/cpp/standalone/src:

e.g.

salgenerator mount sal java
java mount/java:
classes
mount
Makefile.saj_mount_types
saj_mount_types.jar
sal_mount.idl
src
mount/java/classes:
full set of java .class type support files
mount saj_mount_types.manifest

Page 19 of 55

- compiled type classes
- generated java types
- makefile fior types
- type support classes
- validated sal idl

mount/java/classes/mount:
full set of .java type support files
mount/java/mount:

mount/java/src :
ErrorHandler.java
mount_cmdctl.run
mount_event.run
mountCommander.java
mountController.java
mountEvent.java
mount_EventLogger.java
Makefile.saj_mount_cmdctl
Makefile.saj_mount_event

- run command tester
- run event tester
- commander source
- command processor source
- event generator source
- event logger source
- command class makefile
- event class makefile

mount_TC/java: - specific to particular telemetry stream
Makefile
src
standalone
mount_TC/java/src:
ErrorHandler.java
mount_TCDataPublisher.java

- error handler class source
- publisher class source

mount_TCDataSubscriber.java
org

- subscriber class source

mount_TC/java/src/org:

Page 20 of 55

lsst
mount_TC/java/src/org/lsst:
sal

mount_TC/java/src/org/lsst/sal:
sal_mount.java

- sal class for mount

mount_TC/java/src/org/lsst/sal/mount:
Actuators
mount_TC/java/src/org/lsst/sal/mount/Actuators:
mount_TC/java/standalone:
mount_TC.run
Makefile
Makefile.saj_mount_TC_pub
Makefile.saj_mount_TC_sub
saj_mount_TC_pub.jar
saj_mount_TC_sub.jar

- run test programs
- publication class makefile
- subscription class makefile
- telemetry publication class
- telemetry subscription class

Once the java has been generated it is also possible to create a Maven project for ease of
distribution. Use the command e.g.
salgenerator mount maven
will create and build a maven project and save it in
$SAL_WORK_DIR/maven/mount_[sal- version-number]

e.g. salgenerator mount sal python
mount/cpp/src :

Page 21 of 55

Makefile_sacpp_mount_python
SALPY_mount.cpp
SALPY_mount.so

- Boost.python wrapper
- import'able python library

4.2 salgenerator Options
The salgenerator executes a variety of processes, depending upon the options
selected.

validate
html
labview
sal [lang]
lib
sim
tcl
icd
maven
verbose
db

- check the XML files, generate validated IDL
- generate web form interfaces and documentation
- generate LabVIEW interface
- generate SAL C++, Java, or Python wrappers
- generate the SAL shared library for a subsystem
- generate simulation configuration
- generate tcl interface
- generate ICD document
- generate a maven project (per subsystem)
- be more verbose ;-)
- generate telemetry database table

for db the arguments required are
db start-time end-time interval
where the times are formatted like “2008-11-12 16:20:01“
and the interval is in seconds

Page 22 of 55

4.3 SAL API examples
The SAL code generation process also generates a comprehensive set of test programs so that
correct operation of the interfaces can be verified.
Sample code is generated for the C++, Java, and Python target languages currently.
The sample code provides a simple command line test for
publishing and subscription for each defined Telemetry type
issuing and receiving each defined Command type
generating and logging for each defined Event type.
In addition , GUI interfaces are provided to simplify the launching of Command and Event
tests.
The procedure for generating test VI’s for the LabVIEW interface is detailed in Appendix X.
At present this is an interactive process, involving lots of LabVIEW dialogs.

Page 23 of 55

5. Testing
5.1 Environment
To check that the OpenSplice environment has been correctly initialized; in a terminal, type
idlpp
should produce
Usage: idlpp [-c preprocessor-path] [-b ORB-template-path]
[-n ] [-d directory] [-i]
[-P dll_macro_name[,]] [-o (dds-types | custom-psm | no-equality)] 

To check that the SAL environment has been correctly initialized ; in a terminal type
salgenerator
should produce
SAL generator tool - Usage :
salgenerator subsystem flag(s)
where flag(s) may be
validate
sal
lib
tcl
html
labview
maven
db

-

check the XML Telemetry/Command/LogEvent definitions
generate SAL wrappers for cpp, java, isocpp, python
generate shared library
generate tcl interface
generate web form interfaces
generate LabVIEW low-level interface
generate a maven repository
generate telemetry database table

Arguments required are
db start-time end-time interval
where the times are formatted like "2008-11-12 16:20:01"
and the interval is in seconds
sim
icd
link

Page 24 of 55

- generate simulation configuration
- generate ICD document
- link a SAL program

verbose

- be more verbose ;-)

Verify that the network interface is configured and operating correctly.
Make sure that Firewalld is properly configured (or disabled by issuing
the systemctl stop firewalld command as root).

5.2 Telemetry
Once the salgenerator has been used to validate the definition files and generate the
support libraries, there will be automatically built test programs available.
In all cases , log and diagnostic output from OpenSplice will be written to the
files
ospl-info.log and ospl-error.log
in the directory where the test is run.
The following locations assume code has been built for the skycam sub system support,
there will be separate subdirectories for each Telemetry stream type.
For C++
skycam_/cpp/standalone/sacpp_skycam_pub - publisher
skycam_/cpp/standalone/sacpp_skycam_sub - subscriber
start the subscriber first, then the publisher.
For java
skycam_/java/standalone/skycam_.run
- start publisher and subscriber

5.3 Commands
The following locations assume code has been built for mount su bsystem support
For C++
mount/cpp/src/sacpp_mount_[command]_commander
mount/cpp/src/sacpp_mount_[command]_controller

- to send commands
- to process commands

start the controller first, wait for it to print Ready, then run the commander

Page 25 of 55

For java
mount/java/src/mount_cmdctl.run

- starts command processor

In addition a gui can be used to send all supported subsystem commands (with am associated
processor to demonstrate reception of same). To start the gui e.g. for hexapod subsystem
For C++
command_test_gui hexapod
This script is on the PATH, so you should be able to run it from the command line.
The gui provides a window to select the command to run. If a command has optional values
/modifiers, then a subwindow will open to allow their values to be entered.
A terminal window show the messages from a demo command processor which simply
prints the contents of commands as they are received.

Page 26 of 55

Page 27 of 55

5.4 Events
The following locations assume code has been built for mount subsystem support
For C++
mount/cpp/src/sacpp_mount_[event]_send
mount/cpp/src/sacpp_mount_[event]_log

- to generate events
- to log the events

start the event logger first and then the send.
For java
mount/java/src/mount_events.run

- starts events processor

In addition a gui can be used to send all supported subsystem commands (with an associated
processor to demonstrate reception of same). To start the gui e.g. for hexapod subsystem
For C++
logevent_test_gui hexapod
This script is on the PATH so you should be able to run it from the command line.

Page 28 of 55

The gui provides a window to select the event to generate.. If an event has optional values
/modifiers, then a subwindow will open to allow their values to be entered.
A terminal window show the messages from a demo event processor which simply
prints the contents of events as they are received.

6. Application programming Interfaces
6.1. C++
Includes :
#include 
#include 
#include 
#include "SAL_mount.h"
#include "ccpp_sal_mount.h"
#include "os.h"
#include "example_main.h"
using namespace DDS;
using namespace ;

// substitute the actual subsystem name here

Public :
int putSample( data);
- publish telemetry sample
int getSample( data);
- read next telemetry sample
int putSample_( *data); - publish telemetry sample (C)
int getSample_(*data); - read next telemetry sample (C)
void salTypeSupport(char *topicName);
- initialize type support
void salTelemetryPub(char *topicName);
- create telemetry publisher object
void salTelemetrySub(char *topicName);
- create telemetry subscriber object
void salEvent(char *topicName);
- create event object
int getResponse(::ackcmdSeq data);
- read command ack
int getEvent(::logeventSeq data);
- read event data
void salShutdown();
- tidyup
void salCommand();
- create command object
void salProcessor();
- create command processor object

Page 29 of 55

int issueCommand( ::command data);
int issueCommandC( _commandC *data);
int ackCommand( int cmdSeqNum, long ack,
long error, char *result );
int acceptCommand( ::commandSeq data);
int acceptCommandC( _commandC *data);
int checkCommand( int cmdSeqNum );
int cancelCommand( int cmdSeqNum );
int abortCommand( int cmdSeqNum );
int waitForCompletion( int cmdSeqNum ,unsigned int timeout );
int setDebugLevel( int level );
int getDebugLevel( int level );
int getOrigin();
int getProperty(stringproperty, stringvalue);
int setProperty(stringproperty, stringvalue);
int getPolicy(stringpolicy, stringvalue);
int setPolicy(stringpolicy, stringvalue);
void logError(int status);
salTIME currentTime();
int logEvent( char *message, int priority );

- send a command
- send a command (C)
- acknowledge a command
- read next command
- read next command (C)
- check command status
- cancel command
- abort all commands
- wait for command to complete
- change debug info level
- get current debug info level
- get origin descriptor
- get configuration item
- set configuration item
- get middleware policy item
- set middleware policy item
- log middleware error
- get current timestamp
- generate a log event

6.2 Java
Includes :
import .*;
import org.lsst.sal.;
Public :
public
public
public
public
public
public
public
public
public
public
public
public
public
public
public
public
public
public
public
public

//substitute actual subsystem name here
//substitute actual subsystem name here

void salTypeSupport(String topicName)
int putSample( data)
int getSample( data)
void salTelemetryPub(String topicName)
void salTelemetrySub(String topicName)
void logError(int status)
SAL_()
int issueCommand( command data )
int ackCommand( int cmdId, int ack, int error, String result )
int acceptCommand( .command data )
int checkCommand( int cmdSeqNum )
int getResponse(ackcmdSeqHolder data)
int cancelCommand( int cmdSeqNum )
int abortCommand( int cmdSeqNum )
int waitForCompletion( int cmdSeqNum , int timeout )
int getEvent(logeventSeqHolder data)
int logEvent( String message, int priority )
int setDebugLevel( int level )
int getDebugLevel( int level )
int getOrigin()

Page 30 of 55

- initialize type support
- publish a telemetry sample
- read next telemetry sample
- create telemetry publisher
- create telemetry subscriber
- log middleware error
- create SAL object
- send a command
- acknowledge a command
- read next command
- check command status
- read command ack
- cancel a command
- abort all commands
- wait for command to complete
- read next event data
- generate an event
- set debug info level
- get debug info level
- get origin descriptor

public
public
public
public
public
public

int getProperty(String property, String value)
int setProperty(String property, String value)
void salCommand()
void salProcessor()
void salShutdown()
void salEvent(String topicName)

- get configuration item
- set configuration item
- create a command object
- create command processor object
- tidyup
- create event object

6.3 Python (pybind11 bindings)
Each Telemetry/Command/Event datatype is wrapped like this
(arrays are mapped to numpy arrays).
py::class_(m,"atcs_command_OffsetC")
.def(py::init<>())
.def_readwrite("device", &atcs_command_OffsetC::device)
.def_readwrite("property", &atcs_command_OffsetC::property)
.def_readwrite("action", &atcs_command_OffsetC::action)
.def_readwrite("value", &atcs_command_OffsetC::value)
.def_readwrite("offsetX", &atcs_command_OffsetC::offsetX)
.def_readwrite("offsetY", &atcs_command_OffsetC::offsetY)
;

Commands , Events, and Telemetry calls are wrapped like this, every C++ method has a
corresponding python binding.
.def(
.def(
.def(
.def(
)

"issueCommand_enable",
"acceptCommand_enable",
"ackCommand_enable",
"waitForCompletion_enable",

Page 31 of 55

&SAL_atcs::issueCommand_enable )
&SAL_atcs::acceptCommand_enable )
&SAL_atcs::ackCommand_enable )
&SAL_atcs::waitForCompletion_enable

7.0 SAL XML Schema

7.1 Telemetry
7.1.1 telemetrySetType

7.1.2 telemetryType

Page 32 of 55

7.1.3 telemetryItemType

Page 33 of 55

7.2 Commands
7.2.1 commandSetType

7.2.2 commandType

Page 34 of 55

7.2.3 commandItemType

Page 35 of 55

7.3 Events
7.3.1 eventSetType

7.3.2 eventType

Page 36 of 55

7.3.3 eventItemType

Page 37 of 55

8.0 Compiler Options and Link Libraries
The following compiler options are required when compiling application code
For subsequent linking with the SAL and DDS middleware.
CFLAGS/CXXFLAGS : -m64 -D_REENTRANT –fPIC –Wno-write-strings
Subsystems with duplicate instantiations (e.g. Hexapods) also require
-DSAL_SUBSYSTEM_IS_KEYED

and the following include paths will be required
-I$(OSPL_HOME)/include
-I$(OSPL_HOME)/include/sys
-I$(OSPL_HOME)/include/dcps/C++/SACPP
-I$(SAL_HOME)/include
-I$(SAL_WORK_DIR)/include
-I../../-subsys-/cppsrc
Where -subsys- is the subsystem name e.g. hexapod
The following libraries are required when linking an application to use the SAL
and DDS middleware. For an application that communicates with multiple
subsystems, the SAL libraries for each must be included.
SAL : libSAL_[subsystem-name].so , libsacpp_[subsystem-name]_types.so
DDS : libdcpssacpp.so , libdcpsgapi.so , libddsuser.so , libddskernel.so ,
libddsserialization.so , libddsconfparser.so , libddsdatabase.so , libddsutil.so,
libddsos.so, libddsconf.so
Other : libdl.so , libpthread.so
Appropriate linker path directives are
-L$(OSPL_HOME)/lib -L$(SAL_HOME)/lib

Page 38 of 55

9.0 LabVIEW test VI generation
If you have multiple LabVIEW verisons installed, or if LabVIEW is installed in a non default
location, you can use the environment variable LABVIEW_HOME to control where the SDK
looks for the LabVIEW header files.
e.g.

export LABVIEW_HOME=/opt/natinst
would expect to find headers in /opt/natinst/LabVIEW_20[xx]_64

Run the salgenerator steps in order
salgenerator [subsystem] validate
salgenerator [subsystem] sal cpp
salgenerator [subsystem] labview
The generation of the LabVIEW test VI’s is an interactive process. The LabVIEW
Shared library import is used to automatically generate VI’s to interact with the
Salgenerator produced SALLV_[subsystem].so library.
NOTE : It is vital to COMPLETELY DELETE the entire destination directory and it’s
Contents so that wizard can create it’s output directory afresh. For example if you choose
To place the results in /home/me/sal/test/tcs/labview/lib, then you should run the following command
BEFORE starting the LabVIEW tools.
rm –fr /home/me/sal/test/tcs/labview/lib

Page 39 of 55

1. Start LabVIEW and select the Tools->Import->Shared Library (.so) option

2. Choose either New or Update option and specify the path to the library
and then click Next. Proceed through the rest of the dialogs as illustrated below.
Generally selecting the default and clicking Next is appropriate.
The only non-standard option is in the “Configure Include Paths…” dialog
where you must enter the
BUILD_FOR_LV=1
Option in the Preprocessor options section.

Page 40 of 55

Page 41 of 55

Page 42 of 55

Page 43 of 55

Page 44 of 55

Page 45 of 55

Page 46 of 55

Page 47 of 55

Click Finish on the dialog.

Page 48 of 55

Page 49 of 55

When the LabVIEW import library wizard has completed it is necessary to run another
LSST provided VI to finish the generation process.

Use the LabVIEW File->Open dialog to locate ts_SALLabVIEW/main.vi

Click OK to run the main.vi VI. It will open a mostly empty interface.

Page 50 of 55

Click the Run icon.

Click OK and select the subsystem IDL file. The correct file should be found in the
[subsystem]/labview directory of the SAL_WORK_DIR tree.

Page 51 of 55

Click OK to select it.

Click OK
Another file dialog then appears for you to select the .lvlib containing the VI’s.
This should be located in the [subsystem]/labview/lib directory of the SAL_WORK_DIR
tree.
Page 52 of 55

Click OK.
There will then be an extensive period where multiple windows flash on the screen as
each VI is individually processed. Finally a library contents window will appear.

Page 53 of 55

Another extensive period will follow where each VI is processed again (you will see
them being removed and re-added to the list one-by-one.
Finally the process completes and the main LabVIEW window will reappear.
Once the VI’s has been built, you can manually test them by running them against
either each other , or against the C++/Java/Python test programs.
Regardless of which option you choose, the LabVIEW environment must be
set up first by

Page 54 of 55

1. Running the SALLV_[subsystem]_Monitor daemon in a terminal
(this executable manages the shared memory used to mediate
the transfer of data to and from LabVIEW). The daemon will have been
built in the [SAL_WORK_DIR]/[subsystem]/labview directory.

2. Run the [subsystem]_shm_connect VI and leave it open

3. Depending upon the required function, an initialization VI should be run
i.e. for command receivers , run [subsystem]_shm_salProcessor_[name],
for event receivers , run [subsystem]_shm_salEvent_[name],
and for Telemetry receivers , run [subsystem]_shm_salTelemetrySub.
4. After an application has completed all it’s SAL mediated communications, it
is essential to call the [subsystem]_shm_release VI to clean up.

Page 55 of 55



---

Source Exif Data:

File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.5
Linearized                      : No
Page Count                      : 55
Language                        : en-US
Tagged PDF                      : Yes
Creator                         : Microsoft® Word 2013
Create Date                     : 2018:04:10 14:53:22-07:00
Modify Date                     : 2018:04:10 14:53:22-07:00
Producer                        : Microsoft® Word 2013

EXIF Metadata provided by EXIF.tools