SAL Constraints and Recommendations

Important

When updating(not typos) a policy in this document. Please add a description to the Changes section.

Changes

The XML SAL object definitions have the following constraints:

Definitions

CSC

Commandable SAL Component

Naming Convention

Types (name of CSC): UpperCamelCase
Handling abbreviations and acronyms: Capitalize all letters of an abbreviation or acronym: Hence ATAOS, MTM1M3.

For TCS components, use prefix AT for AuxiliaryTelescope and MT for MainTelescope CSCs.

Methods/Topics: lowerCamelCase (note that these names are constructed of 2/3 parts

  1. CSC

  2. Optional

  3. Topic separated by underscores e.g MTHexapod_command_someInterestingThing)

attributes: lowerCamelCase

Enumerations:
Type name: UpperCamelCase (also known as PascalCase).

Also, recommend use of “Selector” at the end of the type name when creating new Enumeration types.

Literals: Also UpperCamelCase

Note

Already established CSCs will NOT need to update their names; they are grandfathered in. This naming convention applies to all CSCs created June 1, 2018 and forward.

Reserved words

The following list of words are reserved either by IDL or SQL parsing and may not be used as <EFDB_Name>’s in SAL topic definitions.

  • ABSTRACT

  • ACCESSIBLE

  • ADD

  • ALL

  • ALTER

  • ANALYZE

  • AND

  • ANY

  • AS

  • ASC

  • ASENSITIVE

  • ATTRIBUTE

  • BEFORE

  • BETWEEN

  • BIGINT

  • BINARY

  • BLOB

  • BOOLEAN

  • BOTH

  • BY

  • CALL

  • CASCADE

  • CASE

  • CATALOG_NAME

  • CHANGE

  • CHAR

  • CHARACTER

  • CHECK

  • COLLATE

  • COLUMN

  • COMPONENT

  • CONDITION

  • CONST

  • CONSTRAINT

  • CONSUMES

  • CONTEXT

  • CONTINUE

  • CONVERT

  • CREATE

  • CROSS

  • CURRENT_DATE

  • CURRENT_TIME

  • CURRENT_TIMESTAMP

  • CURRENT_USER

  • CURSOR

  • CUSTOM

  • DATABASE

  • DATABASES

  • DAY_HOUR

  • DAY_MICROSECOND

  • DAY_MINUTE

  • DAY_SECOND

  • DEC

  • DECIMAL

  • DECLARE

  • DEFA

  • DEFAULT

  • DELAYED

  • DELAY_KEY_WRITE

  • DELETE

  • DESC

  • DESCRIBE

  • DETERMINISTIC

  • DISTINCT

  • DISTINCTROW

  • DIV

  • DOUBLE

  • DROP

  • DUAL

  • EACH

  • ELSE

  • ELSEIF

  • EMITS

  • ENCLOSED

  • ENUM

  • ESCAPED

  • EVENTTYPE

  • EXCEPTION

  • EXISTS

  • EXIT

  • EXPLAIN

  • FACTORY

  • FALSE

  • FETCH

  • FINDER

  • FIXED

  • FLOAT

  • FLOAT4

  • FLOAT8

  • FOR

  • FORCE

  • FOREIGN

  • FROM

  • FULLTEXT

  • GENERATED

  • GET

  • GETRAISES

  • GRANT

  • GROUP

  • HAVING

  • HIGH_PRIORITY

  • HOME

  • HOUR_MICROSECOND

  • HOUR_MINUTE

  • HOUR_SECOND

  • I

  • IF

  • IGNORE

  • IMPORT

  • IN

  • INDEX

  • INFILE

  • INITIAL_SIZE

  • INNER

  • INOUT

  • INSENSITIVE

  • INSERT

  • INSERT_METHOD

  • INT

  • INT1

  • INT2

  • INT3

  • INT4

  • INT8

  • INTEGER

  • INTERFACE

  • INTERVAL

  • INTO

  • IO_AFTER_GTIDS

  • IO_BEFORE_GTIDS

  • IS

  • ITERATE

  • JOIN

  • KEY

  • KEYS

  • KEY_BLOCK_SIZE

  • KILL

  • LEADING

  • LEAVE

  • LEAVES

  • LEFT

  • LIKE

  • LIMIT

  • LINEAR

  • LINES

  • LOAD

  • LOCAL

  • LOCALTIME

  • LOCALTIMESTAMP

  • LOCK

  • LONG

  • LONGBLOB

  • LONGTEXT

  • LOOP

  • LOW_PRIORITY

  • MASTER_BIND

  • MASTER_SSL_VERIFY_SERVER_CERT

  • MATCH

  • MAXVALUE

  • MEDIUMBLOB

  • MEDIUMINT

  • MEDIUMTEXT

  • MIDDLEINT

  • MINUTE_MICROSECOND

  • MINUTE_SECOND

  • MOD

  • MODIFIES

  • MODULE

  • MULTIPLE

  • NATIVE

  • NATURAL

  • NOT

  • NOUT

  • NO_WRITE_TO_BINLOG

  • NULL

  • NUMERIC

  • OBJECT

  • OCTET

  • ON

  • ONEWAY

  • OPTIMIZE

  • OPTIMZER_COSTS

  • OPTION

  • OPTIONALLY

  • OR

  • ORDER

  • OUT

  • OUTER

  • OUTFILE

  • PARTITION

  • PRECISION

  • PRIMARY

  • PRIMARYKEY

  • PRIVATE

  • PROCEDURE

  • PROVIDES

  • PUBLIC

  • PUBLISHES

  • PURGE

  • RAISES

  • RANGE

  • READ

  • READONLY

  • READS

  • READ_WRITE

  • REAL

  • REFERENCES

  • REGEXP

  • RELEASE

  • RENAME

  • REPEAT

  • REPEATABLE

  • REPLACE

  • REQUIRE

  • RESIGNAL

  • RESTRICT

  • RETURN

  • REVOKE

  • RIGHT

  • RLIKE

  • SCHEMA

  • SCHEMAS

  • SECOND_MICROSECOND

  • SELECT

  • SENSITIVE

  • SEPARATOR

  • SEQUENCE

  • SET

  • SETRAISES

  • SHORT

  • SHOW

  • SIGNAL

  • SMALLINT

  • SPATIAL

  • SPECIFIC

  • SQL

  • SQLEXCEPTION

  • SQLSTATE

  • SQL_BIG_RESULT

  • SQL_CALC_FOUND_ROWS

  • SQL_SMALL_RESULT

  • SSL

  • STARTING

  • STORED

  • STRAIGHT_JOIN

  • STRING

  • STRUCT

  • SUPPORTS

  • SWITCH

  • TABLE

  • TERMINATED

  • THEN

  • TINYBLOB

  • TINYINT

  • TINYTEXT

  • TO

  • TRAILING

  • TRIGGER

  • TRUE

  • TRUNCATABLE

  • TYPEDEF

  • TYPEID

  • TYPEPREFIX

  • ULT

  • UNDO

  • UNION

  • UNIQUE

  • UNLOCK

  • UNSIGNED

  • UPDATE

  • USAGE

  • USE

  • USES

  • USING

  • UTC_DATE

  • UTC_TIME

  • UTC_TIMESTAMP

  • VALUEBASE

  • VALUES

  • VALUETYPE

  • VARBINARY

  • VARCHAR

  • VARCHARACTER

  • VARYING

  • VIRTUAL

  • VOID

  • WCHAR

  • WHEN

  • WHERE

  • WHILE

  • WITH

  • WRITE

  • WSTRING

  • XOR

  • YEAR_MONTH

  • ZEROFILL

Format of <EFDB_Name> names: These should not have any embedded non alphanumeric characters or spaces, use _ as a delimiter if required (do not use +-.,:# etc)
e.g. myImportant_data_x is allowed

myImportant-data.x is NOT allowed

Format of <EFDB_Topic> names: These should not have any embedded non alphanumeric characters or spaces, use _ as a delimiter if required (do not use +-.,:# etc)

The first part of the name must be the subsystem involved, separated by a _ delimiter from the rest of the name.
e.g. MyImportantSubsystem_device1 is allowed

MyImportant_Subsystem.device1 is NOT allowed

Format of <Subsystem> names: These should not have any embedded non alphanumeric characters or spaces (only a-z, A-Z, 0-9)
e.g. ATHexaderService is allowed

AT_Header_Service is NOT allowed

Subsystem names (CSC aka Commandable SAL Component) must be listed in SALSubsystems.xml in ts_xml (at one time they needed to added to a file in ts_sal but that is no longer the case.).

The <Subsystem> and <Alias> tags for command’s and logevent’s must be consistent with the <EFDB_Name>
e.g.

<Subsystem>MyBut</Subsystem> <Alias>myCommand</Alias> <EFDB_Topic>MyBit_command_myCommand</EFDB_Topic>

ALL names must be less than 64 characters in length.

Timestamps

If a time-of-data is to be associated with an item it should be named

  • timestamp - for a single time applying to all data in a topic

  • timestampName1, timestampName2 etc - for specific times associated with more than one item in the topic

  • timestamp[n] - for an array of times associated with the array item(s) in a topic

  • timestampName1[n], timestampName2[m] - for multiple arrays of different times for different array sizes

The time(s) should be obtained using the SAL getCurrentTime() method, which returns a double precision value of TAI time in unix seconds with a resolution of at least 0.001 seconds.

Ignored Attributes in Topics

Deprecated in SAL 4.1 - Because topics with no fields are now allowed.

Many generic commands have an ignored attribute. This is due to a requirement from the API to not have empty topics. If you are adding a command to your CSC that does not require an attribute, it still must contain a “dummy” one. In order to maintain consistency across this use case, the attribute must be called value, be of type boolean, be given the following description: “Attribute required by the API, but is unused.” and have the following units: unitless.

Generic Commands and Events

The standard set of commands and events are included in the MagicDraw/EA UML SAL Template,

Each new CSC should use this template as a starting point.

State Enumeration

The following state transition enumerations are globally defined:

  • DisabledState = 1

  • EnabledState = 2

  • FaultState = 3

  • OfflineState = 4

  • StandbyState = 5

and are generated automatically by SAL and accessible via the language-specific library.

What this means: You do NOT need to generate a SummaryState enumeration in your Events xml file. You ONLY need to generate a DetailState enumeration in your Event xml file IF you are adding new states to your detail states. If you add new detail states to the DetailState enumeration, YOU MUST keep the original detail states in the enumeration. If this is not clear, please ask @ Dave Mills @Rob Bovill or @Andy Clements

After the salgenerator creates the code, you will have the following constants:
e.g.

SAL__STATE_DISABLED (C++, Java, and Python) SummaryState.ctl & DetailState.ctl (LabVIEW)

Custom Enumerations

Enumerations may also be declared on a per CSC basis, and will appear in the namespace of that CSC

e.g. for ATTCS in C++:

ATTCS_shared_SimpleSetA (declared globally) ATTCS_someEvent_SpecificSetA (datum specific)

Define it using the following format.

  1. In CSCName_Events.xml create an Enumeration tag just before the first SAlEvent tag in the file.

  2. Fill out the Enumeration with comma delimited values using the following naming format itemName_value.

  3. Repeat for as many enumerations as you require.

  4. Add the enumerations to ts_idl by creating a lsst.ts.idl.enums.{csc_name} module.

Warning

Some enumerations are defined inside of the topic themselves. This is a legacy method and no longer recommended or necessary.

Current SAL object tables

Can be found at http://project.lsst.org/ts/sal_objects

Generic commands

The following command set is defined for all CSC’s (although it is not mandatory to implement them all)

Note

The spelling must be exact as it is used for code generation

start, stop, enable, disable, standby, enterControl, exitControl, abort

Generic events

The following event set is defined for all CSC’s

Note

The spelling must be exact as it is used for code generation

appliedSettingsMatchStart, errorCode, settingVersions, summaryState

Standard Events

A LargeFileAnnouncement event consist off the following items:

  • long byteSize - size of file in bytes

  • string checkSum - md5 checksum of file contents

  • string generator - Name of generating application

  • string mimeType - Mime type of file

  • string url - cURL compatible URL used to reference the file

  • float version - x.y version of file Format

  • string<32> id - Extra identifying information about format/application

SAL Topic and Parameter Description and Unit fields

Changes

  • Added warning notice about check_unit and parsing July 9th, 2019

    • Improved clarity of unitless parsing language and structure

  • Policy added June 19th, 2019

Policy

    1. XML will have the <Units> and <Description> fields defined for each parameter in a topic

      1. Dimensionless parameters (e.g. IP Address, Humidity, any string-type, etc) will use unitless as the <Units> field value.

    1. Units will be SI

    1. We will use astropy names for the names of the units in the topics except as noted in subsection a of section A of this policy.

    1. We will use astropy unit format - when possible, going forward

    1. We will use astropy unit format - when possible, going forward

    1. For Complex units - they must be able to be parsed by astropy

There is a table in the EFD where the topic/parameter and units are paired up - this will be generated from the XML (via salgenerator)

It will not be possible to enforce the same units for each CSC (i.e. the cryostat uses Kelvins, EAS using celsius) - we will “try” to make them the same

For a list of the astropy’s SI, please go here: http://docs.astropy.org/en/stable/units/index.html#module-astropy.units.si

Astrophysics units: http://docs.astropy.org/en/stable/units/index.html#module-astropy.units.astrophys

Many units may be used with prefixes, which are documented here: http://docs.astropy.org/en/stable/units/standard_units.html#prefixes

An easy way to tell if a particular unit is valid is to try to make an astropy.units.Quantity:

import astropy.units

def check_unit(unit_str):
    astropy.units.Quantity(f"1 {unit_str}")

check_unit("deg") # OK
check_unit("not_a_unit") # raises ValueError

Warning

Astropy allows for units such as “deg22” which corresponds to degrees to the 22nd power. These units may not make sense but are valid according to the astropy parser.

SAL Interface Template

Currently there’s a template that includes all generic events and command, current design is in the repository: https://stash.lsstcorp.org/projects/TS/repos/ts_xml/browse/scripts/SAL_Interface_TemplateMD.mdzip

Commands:

_images/command_uml.png

Events:

_images/event_uml.png

Datatype and Enumerations:

_images/data_type_and_enumeration_uml.png