


Network Working Group                                            M. Ertl
Internet-Draft                                                       ESP
Intended status: Informational                              May 23, 2010
Expires: November 24, 2010


       Protocol for Stage Illumination, for use over IP networks
                           draft-mertl-psi-00

Abstract

   This memo describes a protocol that builds upon UDP/IP to transport
   illumination and control data for stage, architectural and other
   illumination requirements.

   It may be understood as a spiritual successor of the traditional DMX
   (Digital MultipleX) specification series, removing it's limitations
   and adding flexibility and usability enhancements like auto-discovery
   and metadata, among other useful features.

Status of this Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at http://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on November 24, 2010.

Copyright Notice

   Copyright (c) 2010 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   (http://trustee.ietf.org/license-info) in effect on the date of
   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect
   to this document.  Code Components extracted from this document must



Ertl                    Expires November 24, 2010               [Page 1]

Internet-Draft       Protocol for Stage Illumination            May 2010


   include Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.


Table of Contents

   1.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  4
   2.  Description  . . . . . . . . . . . . . . . . . . . . . . . . .  4
     2.1.  Groups . . . . . . . . . . . . . . . . . . . . . . . . . .  8
     2.2.  Clusters . . . . . . . . . . . . . . . . . . . . . . . . .  8
     2.3.  Current Values . . . . . . . . . . . . . . . . . . . . . .  9
     2.4.  Safe Values  . . . . . . . . . . . . . . . . . . . . . . .  9
     2.5.  Message length . . . . . . . . . . . . . . . . . . . . . .  9
   3.  Design . . . . . . . . . . . . . . . . . . . . . . . . . . . .  9
     3.1.  System-independent representation (transfer syntax)  . . .  9
     3.2.  Versioning . . . . . . . . . . . . . . . . . . . . . . . . 10
     3.3.  Identifier for nodes: IN (Identification Number) . . . . . 10
     3.4.  Message types  . . . . . . . . . . . . . . . . . . . . . . 11
     3.5.  Headers  . . . . . . . . . . . . . . . . . . . . . . . . . 14
       3.5.1.  Message header . . . . . . . . . . . . . . . . . . . . 14
       3.5.2.  Node header  . . . . . . . . . . . . . . . . . . . . . 17
       3.5.3.  Sentence Header  . . . . . . . . . . . . . . . . . . . 19
     3.6.  Word Types . . . . . . . . . . . . . . . . . . . . . . . . 21
     3.7.  Constants  . . . . . . . . . . . . . . . . . . . . . . . . 27
       3.7.1.  Conventions  . . . . . . . . . . . . . . . . . . . . . 27
       3.7.2.  Protocol version . . . . . . . . . . . . . . . . . . . 28
       3.7.3.  Bases for constants  . . . . . . . . . . . . . . . . . 28
       3.7.4.  Message types  . . . . . . . . . . . . . . . . . . . . 29
       3.7.5.  Node Options . . . . . . . . . . . . . . . . . . . . . 31
       3.7.6.  Sentence Options . . . . . . . . . . . . . . . . . . . 39
       3.7.7.  Sentence types . . . . . . . . . . . . . . . . . . . . 48
       3.7.8.  Detailed Reactor Status  . . . . . . . . . . . . . . . 54
       3.7.9.  Channel status . . . . . . . . . . . . . . . . . . . . 56
       3.7.10. Reactor types  . . . . . . . . . . . . . . . . . . . . 58
       3.7.11. Channel types  . . . . . . . . . . . . . . . . . . . . 59
     3.8.  Dynamics . . . . . . . . . . . . . . . . . . . . . . . . . 60
       3.8.1.  Discovery Phase  . . . . . . . . . . . . . . . . . . . 61
       3.8.2.  Initialization Phase . . . . . . . . . . . . . . . . . 63
       3.8.3.  Normal Operation . . . . . . . . . . . . . . . . . . . 64
   4.  Discussion . . . . . . . . . . . . . . . . . . . . . . . . . . 67
   5.  Refresh rate . . . . . . . . . . . . . . . . . . . . . . . . . 70
   6.  Routing Considerations . . . . . . . . . . . . . . . . . . . . 70
   7.  Security Considerations  . . . . . . . . . . . . . . . . . . . 71
   8.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . . 72
   9.  References . . . . . . . . . . . . . . . . . . . . . . . . . . 72
     9.1.  Normative References . . . . . . . . . . . . . . . . . . . 72
     9.2.  Informative References . . . . . . . . . . . . . . . . . . 72



Ertl                    Expires November 24, 2010               [Page 2]

Internet-Draft       Protocol for Stage Illumination            May 2010


   Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 73


















































Ertl                    Expires November 24, 2010               [Page 3]

Internet-Draft       Protocol for Stage Illumination            May 2010


1.  Introduction

   This document contains the specification of a protocol for stage
   illumination.  The intent of this protocol is to be as useful and
   easy to use as [DMX512-A] while doing away with the severe
   limitations of DMX in terms of flexibility, structure and speed,
   while also adding several convenience and management features.  The
   most important ones being:

   o  virtually unlimited number of nodes

   o  automated (re-)discovery of all nodes at any time

   o  larger and distinct data fields, including metadata

   o  fully bidirectional communication, including reception of data by
      the PSI Master

   o  ability to conglomerate individual PSI Reactors into Groups for
      improved transfer efficiency, as well as simultaneous unicast
      addressing as individual PSI Reactors, in any combination

   o  ability to use a very wide range of readily available, even stock,
      components as transport medium, leading to immediate adaptability
      to any environment

   o  may be run alongside other traffic, enabling the use of DHCP, or
      HTTP configuration in PSI Reactors, over the same network
      infrastructure

   o  while not recommended, PSI may be run across a preexisting,
      general network infrastructure including domestic networks without
      interfering (within limits of bandwidth requirements)



   Comments are solicited and should be addressed to the author.


   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
   document are to be interpreted as described in [RFC2119].


2.  Description

   The PSI operates on top of existing protocols, namely UDP/IP.  It is
   bidirectional and geared towards the typical environment found in



Ertl                    Expires November 24, 2010               [Page 4]

Internet-Draft       Protocol for Stage Illumination            May 2010


   stage lighting systems.  The theoretical maximum number of nodes is
   given by the IN (Identification Number) that is eight bytes in size
   (see Section 3.3).  In practice, bandwidth and memory limits are
   expected to set the actual limit for any given installation.  A small
   number, usually exactly one, of controlling nodes, referred to as
   "PSI Masters", query, prepare, and send values to a potentially vast
   number of other nodes, referred to as "Reactors".  Even though a PSI
   Master may have multiple network interfaces for various reasons like
   limiting bandwidth requirements, the entirety of Reactors connected
   to all it's interfaces is normally available as a whole, and is
   referred to as "Nexus".  A PSI Master implementation may however
   choose to split the Nexus in any way deemed useful.  In addition to
   data, information about all Reactors is gathered by the PSI Master,
   and can be presented to the user to aid in management and other
   tasks.  Especially useful for this are the user-defined string and
   the user-defined numbers, because they may be used to indicate
   physical whereabouts and other distinguishing properties of any
   Reactor, in addition to a similar set of data that is vendor-
   specific.

   Because the PSI does not use the underlying networks in
   unconventional ways, it will coexist peacefully, within bandwidth
   limits, with any other protocol running over the same networks.  This
   enables, for example, the use of HTTP for configuration interfaces
   and DHCP for IP address assignment.  Because a Nexus does not change
   behavior much during normal operation, even streaming media may be
   run alongside PSI.

   To achieve a significant degree of flexibility and safety, it does
   not suffice to assign a channel number through the index of the data
   inside the data stream, like it is done in DMX ([DMX512-A]) , nor on
   a per-Reactor basis.  While that method has the advantage of lower
   overhead, it has several disadvantages.  One is that each message
   needs to contain every single channel, at least up to the one
   actually intended for changing.  If channel 512 is supposed to be
   changed, all 511 previous channels must be sent as well, even if they
   are not even assigned to any device.

   Additionally, a damaged, missing or misplaced value can not be
   detected, so that transmission errors may easily lead to incorrect
   settings in the receiving devices.  Explicit channel numbers, on the
   other hand, allow for selectively sending data for arbitrary channels
   and in any order and make sure that a datum received truly is
   intended for a particular channel, instead of possibly being the
   result of a transmission error.
   Additionally, UDP's checksumming is automatically used, and any
   intrinsic error detection and correction methods offered by the
   network are also taken advantage of.  For example, PSI's expected



Ertl                    Expires November 24, 2010               [Page 5]

Internet-Draft       Protocol for Stage Illumination            May 2010


   primary deployment platform, Ethernet, uses a 32-bit checksum that
   provides a great deal of reliability to received data.  The addition
   of a 16-bit checksum in the extended options of DMX proves the
   necessity of such reliability.  While DMX needs to cope with legacy
   devices and thus can only make this checksum optional, it always has
   been mandatory in Ethernet.
   In addition to that, PSI binds each channel to a specific Reactor,
   which is not possible with DMX.  This way, the user can at any given
   time check and control, through the PSI Master, which Reactor
   contains any given channel, while in DMX this can only be achieved by
   physically examining every single device.  The PSI Master allows the
   user to spot and resolve conflicts without moving, and without
   changing settings in Reactors.  This is especially convenient because
   settings like these otherwise necessarily make use of vendor-specific
   interfaces, requiring the user to first study the device
   documentation before being able to make the necessary changes.  The
   PSI puts this configuration into the PSI Master, where the user
   actually is located.

   If a device needs to be replaced, the use of DMX requires that the
   new device is configured to mimic the replaced one.  This will lead
   to problems if the replaced device supported functions the new one
   doesn't support, like assignment of non contiguous channel numbers.
   In such a case the entire controlling sequence, and / or other,
   completely unrelated devices, would need to be changed resp.
   reconfigured, resulting in a lengthy and error-prone management
   effort.
   Through explicit assignment of channel numbers, paired with binding
   of channels to their containing devices, a change like that can be
   done easily: it only requires the physical replacement of the device
   in question and reassignment of that device's channels to the new
   device.  If the PSI Master provides an abstract channel plane that is
   above the physical devices, then the logical arrangement created on
   top of the plane never needs to be touched.  This means that any
   logical arrangement may be used, unchanged, on any Nexus, as soon as
   an appropriate abstract plane has been created through the PSI
   Master.

   While DMX controllers may also support such an abstract plane (called
   "soft patching"), they can only map logical channels to DMX channels,
   without real relation to physical devices present.  This therefore
   still leaves the problem of non contiguous channel ranges possibly
   forcing reconfiguration of many unrelated devices, on top of the need
   to change the soft patching.  So, with DMX the user needs to maintain
   an updated list of all devices present, plus their configuration, to
   be able to configure new devices and to manage the soft patching,
   whereas the PSI Master automatically maintains this list.  The list
   available from a PSI Master therefore is instantly available and,



Ertl                    Expires November 24, 2010               [Page 6]

Internet-Draft       Protocol for Stage Illumination            May 2010


   more importantly, always up to date.  PSI creates this list on each
   restart from the devices actually present, and is able to flag
   removed devices and list newly added devices, without changing the
   current configuration.  Newly (re-)appearing devices can also be
   dynamically added to the appropriate list, without changing the
   currently loaded patching.

   The meta datatypes defined by PSI allow for a defined and therefore
   universal way to gather detailed information about the devices
   present on any given Nexus.  These include vendor and device type,
   channel counts, and data types as well as user assigned identifiers
   and comments and detailed status information, allowing for a
   continuous overview of the entire Nexus.

   Another advantage is the availability of larger data types, which are
   particularly useful for devices like scanners, moving heads and
   anything requiring finer resolution than the brightness of a lamp
   does.  The development of (non-standard) 16-bit DMX by interpreting
   two consecutive 8-bit values as single 16-bit value shows that such
   larger data types are needed in many cases.  Should even larger or
   different data be required, PSI provides additional data types in a
   well-defined and universal way, allowing for easy use of, for
   example, 64-bit values.

   If a channel cannot handle the full range of possible values offered
   by the Word type required, it informs the PSI Master of it's value
   boundaries so it's limitations can be honored.  A channel MUST
   tolerate reception of values outside these boundaries, and in
   response switch to Safe Values and set the appropriate Reactor
   Status.

   Additionally, devices requiring unconventional data types may be
   employed without reinterpreting stock data types, by using the
   variable length data types defined by PSI.  These may be used for
   images or similar data, but their actual interpretation completely
   depends on the device using them.

   Each message sent to the PSI Master also contains a crude status
   indicator, allowing for quick notification about unusual
   circumstances, possibly automatically triggering more detailed
   inquiries and / or other measures by the PSI Master.  This is
   especially useful in large installations, because such a Nexus cannot
   normally be satisfactorily presented as a whole.  Since the PSI
   Master always possesses complete and up to date information, it is
   able to actively notify the user of any irregularities in all cases.






Ertl                    Expires November 24, 2010               [Page 7]

Internet-Draft       Protocol for Stage Illumination            May 2010


2.1.  Groups

   Groups are used to efficiently handle installations that are composed
   of many Reactors with few channels each.  Sending data to each of
   them in a separate message may unduly impact the available bandwidth,
   so it may make sense to handle a number of such Reactors in a single
   broadcast or multicast message (see Section 3.4).  To do so, an
   identifier is assigned to all Reactors that the new Group shall
   contain.  This identifier may then used whenever a message applies to
   more than one member of the Group.  Use of this identifier allows all
   Reactors that are not part of the specific Group to quickly notice
   that fact and thus discard the message without having to process it
   any further.  A message directed at members of a Group contains the
   usual identifiers for the individual Reactors and may therefore
   convey totally different data to each member.

2.2.  Clusters

   Clusters are Groups applying the same data to all members (indicated
   by the flag PSI_NO_FM_CLUSTER being set).  From PSI's point of view,
   a Cluster is exactly the same as a Group.  However, from the user's
   point of view, both are distinct.  While Groups serve to more
   efficiently utilize bandwidth in case of large numbers of Reactors
   with few channels, Clusters serve to efficiently apply the same data
   values to multiple Reactors, so these Reactors may have a large
   number of channels but need to be reasonable similar to each other,
   especially in terms of channel configuration.  Therefore, a PSI
   Master that implements Clusters should distinguish Clusters and
   Groups, and apply sanity checks whenever the user adds members to a
   Cluster.  Specifically, Clusters composed of Reactors using different
   channel configurations or data types should require explicit user
   confirmation.  It may allow this regardless, because the Cluster flag
   MAY be used to convey general instructions (like Node Options), or to
   set only a limited subset of channels that may be applicable to all
   Reactors in the Cluster.  For example, all Reactors in a Cluster may
   have a channel that is mapped at number 10 and uses 32 bit data.  So
   even though the remaining channels of the clustered Reactors may
   differ, this single channel may be assigned values using a Cluster
   message.  The PSI Master SHOULD check if there are any matching
   channels in all clustered Reactors when a new one is added to the
   Cluster, and inform the user of the result.  It MAY offer the user a
   filter to display only the matching channels.

   Also, the CLUSTER flag need not be used in all, even most, messages
   sent to a Reactor.  It is perfectly acceptable to, for example, use
   this flag only to assign values to a single channel out of many, and
   to do so only occasionally.  Of course, the more this flag is used,
   the higher transmission efficiency will be.



Ertl                    Expires November 24, 2010               [Page 8]

Internet-Draft       Protocol for Stage Illumination            May 2010


2.3.  Current Values

   The Current Values are what is being sent by the PSI Master to a
   Reactor.  They are the result of calculations and / or inputs of any
   sort.  Because they can be any value of the possible value range,
   they are not suited for continued use in case of loss of control.
   Instead, Safe Values must be used in that case.

2.4.  Safe Values

   The Safe Values are specific to each channel.  They are designed to
   be used whenever a channel receives no updates from the PSI Master,
   and can be used continuously without posing danger for the device or
   audience.

2.5.  Message length

   Because fragmenting of messages leads to greater impact of packet
   loss, it should normally be avoided.  In order to keep IP from
   fragmenting messages, the default maximum message length should be
   1400, since 1500 is the normal MTU for Ethernet, allowing some room
   for different configurations.

   A Reactor implementation MAY allow the user to change this maximum,
   in response to the actual network performance, but it SHOULD NOT be
   less than 1400.  In fact, the maximum message length of Reactors may
   be significantly larger by default, because the PSI Master is free to
   stay well below the maximum, and therefore can adapt, possibly
   automatically, to network loss rate.  On the other hand, the PSI
   Master's maximum message length may change, and an information
   message is sent to the Reactors, during normal operation, so that the
   Reactors do not need to be manually reconfigured to stay below a
   certain size.

   An embedded platform therefore is free to choose it's absolute
   maximum message length, so that it can use static buffers, but
   advertise less than that if deemed reasonable.


3.  Design

   This section describes the construction of messages sent over the
   media.

3.1.  System-independent representation (transfer syntax)

   Experience using large and heterogeneous data networks has shown that
   reliable and easily adjustable communication between devices requires



Ertl                    Expires November 24, 2010               [Page 9]

Internet-Draft       Protocol for Stage Illumination            May 2010


   a well-defined standard.  Especially, standardizing the endianness
   does not suffice.  Instead, a system- and language-independent data
   representation is required.  A number of such representations have
   been examined for use as basis for PSI, and unaligned CDR was chosen
   (see Section 4 for details).

   CDR does not specify the endianness of bit fields, so they are
   defined by PSI to match the endianness of the remainder of the
   message.

3.2.  Versioning

   Even though multiple versions are not planned, and should not be
   created without proper deliberation, every PSI message, including
   discovery messages, contains a version field.  It MUST be checked by
   every receiver against it's list of supported versions to determine
   how the remainder of the message needs to be interpreted.  If a
   Reactor supports more than one version, it SHOULD respond using the
   version used by the PSI Master.  If the Reactor does not support the
   version used by the PSI Master, it discards its messages.  For every
   message received in an incompatible version, the Reactor sends a
   Version Mismatch message (see Section 3.7.4) to the sender.  The PSI
   Master must flag any version differences for the user to see, and do
   so prominently for incompatibilities.
   Likewise, a Reactor that doesn't use it's preferred version should,
   if it provides other indicators to the user, indicate a warning, and
   an error if it does not have a compatible version to use.  A node may
   support any number of different versions, and allow the user to
   selectively disable their use, and to specify which is the preferred
   version.

   In order for a node running any protocol version to be able to detect
   and report version incompatibilities as well as to send Version
   Mismatch messages to the sender, the message header needs to maintain
   the structure and contents described in this memo for all versions
   created.  It therefore MUST be modified only in ways that keep the
   structure in place, like by appending to the basic format.  The
   contents of the basic structure must be made as meaningful as
   possible.

3.3.  Identifier for nodes: IN (Identification Number)

   Each node needs to be uniquely identifiable and thusly referable
   within the entire Nexus, for example by a number.  The uniqueness of
   this identifier is very important to guarantee the correct
   functioning of the installation.  To facilitate this without
   requiring lengthy and error-prone configuration of each Reactor, it
   needs to even be globally unique.  Since PSI is geared towards



Ertl                    Expires November 24, 2010              [Page 10]

Internet-Draft       Protocol for Stage Illumination            May 2010


   Ethernet, making use of the MAC-address of the first NIC found in the
   node makes sense, as it is globally unique already.  Regardless, the
   user may assign the INs in any way convenient as long as they are
   unique within the Nexus.
   Despite the MAC address of Ethernet and most other media types being
   six bytes in length, this field is defined to be 8 bytes in length to
   accommodate the 8 byte MAC format (EUI-64) and to facilitate other
   uses, like multiple personalities (PSI Master and Reactor).  The MAC
   byte sequence is filled in in canonical format, with the OUI and the
   remainder of the MAC separated by as many filler bytes with the value
   0xFF (and, if necessary, bits with value 1), that both the OUI and
   the remainder of the MAC address occupy the outmost bytes.  This
   conversion therefore is compatible with the IEEE's suggested
   practice, albeit making no distinction between MAC-48 and EUI-48.
   Since this number has no corresponding data type, it is defined as
   sequence of 8 bytes.  This is no problem in this case, because
   sequences of bytes are stored the same on all architectures, meaning
   that no endian issues arise from this (see Section 3.1 for details).
   Through the IN, identification of nodes does not depend on IP address
   assignment, so that may be done through DHCP.
   In the event that a single node runs more than one personality (PSI
   Master / Reactor) at the same time, each of them MUST use a
   different, unique, IN.  In a Nexus using the 6 byte MAC format
   exclusively, this can be accomplished easily by using the two filler
   bytes as an index.  Alternatively, and especially when using the 8
   byte MAC format, the user may assign artificial INs in any way
   convenient, provided they are unique within the Nexus.

3.4.  Message types

   PSI uses a number of basic message types that are further split by
   direction (to or from the PSI Master).  This allows for quick
   checking whether the received message can be intended for the
   receiving node at all.  For example, a *_FM_* message can not be
   intended for a PSI Master, not even by other PSI Masters.
   Additionally, the meaning of some message types differs depending on
   direction.  Any message may only contain those elements (like
   sentence types, Node Options, etc.), that apply to it's direction,
   because some differ greatly, or even conflict, depending on
   direction.  Therefore it is necessary to check for the proper
   direction before using data from a received message.

   The various existing and allowed message types are as follows:

   o  Unicast message

      This is the basic message type and is usable for all nodes.  It is
      sent directly to a single node and therefore creates little



Ertl                    Expires November 24, 2010              [Page 11]

Internet-Draft       Protocol for Stage Illumination            May 2010


      processing overhead for any other nodes.  Additionally, the entire
      content of the message is meaningful to the receiving node, so no
      irrelevant portions require processing.  Therefore, messages of
      this type must only contain information for a single node.
      However, they may be spread over multiple Node Sections.  Use of
      the flag NODE_FINISHED is optional and does not influence the
      transmission efficiency.  The unicast message uses no GID so this
      field is omitted in the message header.  It is possible to send
      this message type as multicast or broadcast, using multiple Node
      Sections with different TINs.  However, this method creates
      processing overhead for all (matching) nodes and should thus be
      avoided in favor of the more appropriate message types using a
      GID.

      The allowed contents differ depending on direction for this
      message type, see Constants (Section 6).


   o  Multicast message

      By using this message type the multicast capability of the
      transport layer may be utilized to send, relatively targeted,
      messages to a Group.  In theory, this could be a middle ground
      between unicast and broadcast, though in practice this may require
      careful address and GID assignment.  If used, it can reduce the
      impact of Groups on CPU usage in nodes; there is otherwise no
      difference between this and a broadcast message.

      The allowed contents differ depending on direction for this
      message type, see Constants (Section 6).


   o  Broadcast message

      This message type is intended for use in conjunction with Groups,
      so that the bandwidth can be used more efficiently in
      installations with many Reactors of only few channels each.  A
      message of this type therefore can contain multiple Node Sections
      encapsulating contents for different nodes.  As in unicast
      messages, it is allowed to send multiple Node Sections for the
      same node in a single message.  To increase efficiency, the last
      node header preceding data for any specific node SHOULD have the
      flag NODE_FINISHED set, so the node can discard the remainder of
      the message immediately.  It is recommended that all Node Sections
      applying to any specific node be consecutive, since that further
      reduces overhead for all but the last node addressed in the
      message.




Ertl                    Expires November 24, 2010              [Page 12]

Internet-Draft       Protocol for Stage Illumination            May 2010


      The allowed contents differ depending on direction for this
      message type, see Constants (Section 6).


   o  Discovery message

      This is a special message type that must not contain additional
      data.  It's use is restricted to, depending on direction, inform
      PSI Masters of newly appearing Reactors, or to instruct all
      Reactors present to send discovery messages, allowing a new or
      restarted PSI Master to build and maintain an inventory of the
      Nexus (See Section 3.8 for details).  Another use is to directly
      contact a PSI Master in case it ceased sending messages to a
      Reactor without apparent reason.  This way, the Reactor can
      initiate being (re-)added to the PSI Master's inventory if, for
      example, the PSI Master has been restarted but no global discovery
      request has been made, or in case the Reactor has missed it (it
      may have been disconnected from the network at that time).
      A Reactor receiving a discovery message SHOULD switch to Safe
      Values; channels using Safety Sequence MUST do so, cease
      operation, ensure safety if at all possible and also MUST discard
      any progress through their Safety Sequences.
      This message may therefore be sent, depending on the sending
      node's requirements, as uni-, multi, or broadcast, and is
      therefore not further subdivided.


   o  Version Mismatch message

      This is a special message type that must not contain additional
      data.  It's use is to inform the receiver that the sender does not
      support the protocol version that was used to contact the sender.
      The version field contains a version supported by the sender.  If
      the sender supports multiple versions, then the first Version
      Mismatch message contains it's preferred, default version.  If the
      sender receives another incompatible message, then it sends the
      next version that it supports, until it starts over at the
      preferred version.
      The receiver of such a message will check if it supports the
      version indicated, and if it does, then it will establish
      communication using that version.  If it does not, it will collect
      all versions supported by the sender by sending messages to the
      sender.  The list is complete if the sequence has repeated at
      least once, possibly more often to allow for duplication, loss and
      out of order delivery.  The receiver may then check this list
      against it's own support list and pick the version that is nearest
      to the beginning of both node's lists, or by any other criteria,
      if multiple matching versions exist.  This way, it is ensured that



Ertl                    Expires November 24, 2010              [Page 13]

Internet-Draft       Protocol for Stage Illumination            May 2010


      communication is established eventually, and also that, if more
      than one possible match exists, the version picked is always the
      same.

      The reason this is done this way is to have as few message types
      and contents that must be maintained compatibly across all
      versions as possible.  Using Node Specification to list all
      supported versions in order of preference, for example, would not
      only fix that Word type, but also force the entire structure of at
      least the unicast message to be essentially fixed.


3.5.  Headers

   PSI uses three headers that represent different layers of the
   protocol and are related in a strictly hierarchical manner.

3.5.1.  Message header

   The message header represents the highest layer of the PSI.  Every
   message must have exactly one message header, as it contains all
   necessary information like protocol version, source and the type of
   the message.  Additionally, it allows for checking the completeness
   of the received message in terms of length.  The method of specifying
   the source of the message instead of it's destination is uncommon and
   stems from the requirement that the protocol must be able to send
   information for different Reactors in a single message, in order to
   reduce the message overhead for Reactors with only minimal data
   requirements (like those with only a couple of channels).  Otherwise
   messages, and therefore Ethernet frames, would need to be sent for
   even a single channel.  This way, messages for several Reactors may
   be sent as directed broadcast or multicast, significantly reducing
   the number of messages that need to be sent.  The downside of this is
   that broadcasts place a processing burden on all connected nodes,
   since they will need to interpret the message until they can conclude
   that it does not contain information for them.  The increasing
   processing power of embedded equipment likely will reduce the impact
   of this, but likewise will the increasing bandwidth of even commodity
   networks reduce the impact of sending many, tiny messages.  In the
   end, it will depend on the particular circumstances and thus should
   be kept in mind when setting up the PSI Master's configuration.

   To further alleviate this problem, PSI uses an additional data field
   in the message header of broadcast and multicast messages, the Group
   IDentification (GID).  Through use of the GID, not every Reactor
   needs to check each received broadcast / multicast message for
   relevant information.  Instead, it may abort the check if the GID in
   the received header does not match any of the GIDs assigned to the



Ertl                    Expires November 24, 2010              [Page 14]

Internet-Draft       Protocol for Stage Illumination            May 2010


   Reactor, if there are any.
   Only messages of type PSI_MT_xx_MULTICAST and PSI_MT_xx_BROADCAST
   contain a GID-field.

   A PSI Master implementation MAY allow for such conglomeration, be it
   manual and / or automatic.  In any case, such conglomeration may be
   changed at any time, including Reactors being assigned different
   GIDs.  If a PSI Master allows for conglomeration, it MUST also
   provide means of disabling it, being part of the unicast-only mode of
   operation (see Routing Considerations Section 6).

   Over the wire format:

    0                   1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |    Version    |     Type      |         Message Length        |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   | : . Message Length (ctd.) . : |              SIN              |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                          SIN (ctd.)                           |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |          SIN (ctd.)           | : . : . : . :GID: . : . : . : |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   | : . : . :GID (ctd.) : . : . : |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

   Legend:
   : . XYZ . : = bytes that only exist when certain flags are set

   The PSI message header.

                                 Figure 1

   Detailed description of the header fields:

   Version: 8 bit

      This field contains the version of the sending PSI stack.  This is
      used to determine if the message can be interpreted, and if so,
      how.  See Section 3.2 for details.


   Message type: 8 bit

      This field specifies the type of the message.  The basic types are
      subdivided into two subtypes each, that define the message
      direction (from the PSI Master or to the PSI Master); see



Ertl                    Expires November 24, 2010              [Page 15]

Internet-Draft       Protocol for Stage Illumination            May 2010


      Section 3.4 for a list and descriptions.  These subtypes differ in
      what their contents may be, and also allow testing for logical
      correctness.  For example, a message sent to the PSI Master cannot
      be intended for it if it is of subtype "from PSI Master".  This is
      especially important in the case of broadcast messages, because it
      allows faster weeding out of irrelevant messages.

      Additionally, the endianness and the size of all length fields in
      the message is defined through bits 1 and 2, respectively, of this
      field:

      For all message types, bit 1 of the "message type" field indicates
      the endianness of the entire message (including bit fields): if
      bit 1 is set, then the message is in big endian format, otherwise
      the message is in little endian format.  The receiver therefore
      only needs to convert if the sender uses the other format.  An
      implementation MAY allow the user to choose which endian type to
      use for sending, regardless of the architecture's natural format.
      For example, if most Reactors use one format while the PSI Master
      uses the other one, the PSI Master could be configured to use the
      predominant format for sending, instead of it's native format.

      For all message types, bit 2 of the "message type" field indicates
      the size of all length fields in the entire message: if bit 2 is
      set, then the length fields are 32 bits in size, otherwise their
      size is 16 bit.
      This is done because in nearly all cases, the maximum message size
      will be around one Ethernet MTU, or at least well below the 65536
      bytes possible using 16 bits, so for each length field, two bytes
      less bandwidth are required.  Since the message components (Node
      Sections and Sentences) can only be smaller than the total message
      length, their length fields will never need to be larger than the
      one of the message header.  In the uncommon case when truly large
      chunks of data need to be sent in one message, then 32 bits may be
      used for all length fields.  In that case, the additional bytes
      for the length fields will not impact performance due to the large
      amount of data to be sent.

      Thus, including the message direction (bit 0, see Section 3.7.3),
      the most significant 3 bits are used as flags.


   Message length: 16 / 32 bit

      This field contains the length of the message in bytes, including
      the message header with the length field itself.  The receiver
      compares it to the number of bytes received to see if the message
      is complete.



Ertl                    Expires November 24, 2010              [Page 16]

Internet-Draft       Protocol for Stage Illumination            May 2010


   SIN: 8 byte

      This is the Source Identification Number and contains the sender's
      IN (see Section 3.3).  It informs the receiver of the source of
      the message.  It is used, depending on the message type, for
      checking (for example, if the sender actually is allowed /
      supposed to send a particular message type or contents to the
      receiver) or, especially in case of Discovery messages, to
      maintain the list of PSI Masters in the Reactors, and the list of
      Reactors in the PSI Master(s).


   GID: 32 bit

      The Group ID is specific to broadcast- and multicast message
      types.  It narrows the scope of the message to only a small subset
      of the receiving Reactors.  By simply comparing the GID to the
      list of GIDs assigned to itself, a Reactor can decide if it needs
      to interpret the remainder of the message at all.  If a Reactor
      has no GIDs assigned, it may ignore multicast- and broadcast
      messages if they are identified as such by their type, since they
      cannot contain information for that Reactor.

      Assignment of GIDs is done by the PSI Master and may be changed
      during normal operation, for example when Reactors vanish or new
      Reactors appear.  The field's size of 32 bit allows for about 4.2
      billion unique Groups, which suffices for even large systems.

3.5.2.  Node header

   The node header is used to identify the target Node and marks the
   beginning of a Node Section.  Each message, except for Discovery
   messages, may contain any number of Node Sections that, depending on
   the message type, may apply to the same node and / or to different
   nodes.  To facilitate easy jumping across irrelevant (to any
   particular Node) sections, and to allow for checking completeness and
   correctness, each node header contains the length of the entire Node
   Section.  It also contains the Target Identification Number ("TIN")
   as well as a field for options that govern the intended use of the
   data grouped under this header, or represent simple instructions for
   the entire node.  Due to the last part, a node header may be
   solitary, meaning it does not need to be followed by any Sentence
   Headers (Section 3.5.3).








Ertl                    Expires November 24, 2010              [Page 17]

Internet-Draft       Protocol for Stage Illumination            May 2010


   Over the wire format:

    0                   1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                         Node Options                          |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |         Section Length        + : . Section Length (ctd.) . : |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                              TIN                              |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                          TIN (ctd.)                           |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

   Legend:
   : . XYZ . : = bytes that only exist when certain flags are set

   The PSI node header.

                                 Figure 2

   Detailed description of the header fields:

   Node Options: 32 bit

      This is a bit field that contains instructions for the use of the
      data contained in the current Node Section, as well as self-
      contained instructions and information.  This usually are queries
      that apply to the entire node, or the flags NODE_FINISHED and
      REACTOR_ACCEPTED.  A description of all Node Options is found in
      Section 3.7.5.


   Section Length: 16 / 32 bit

      Similar to the length field of the message header (Section 3.5.1),
      this field contains the length of the Node Section, including the
      node header and the length field itself.  It allows for checking
      for completeness and correctness, and easy jumping across parts
      not interesting to the particular node.  Since the next Node
      Section starts, relative to the start of the length field, at an
      offset of exactly the amount of bytes named in the field, this
      weeding out can be done relatively easily.








Ertl                    Expires November 24, 2010              [Page 18]

Internet-Draft       Protocol for Stage Illumination            May 2010


   TIN: 8 byte

      This is the Target Identification Number and contains the target's
      IN (Section 3.3).  It defines the intended receiver for the
      current Node Section.  If the TIN in any given Node Section does
      not match the receiver's IN, it must not be interpreted or
      otherwise used.  In this case, a simple jump across the entire
      Node Section makes sense, using the length field, to not waste CPU
      time.  An implementation MAY also choose to process the Node
      Section the normal way and just discard the extracted data
      afterwards, for example if a thorough consistency check is
      desired.  The method chosen has no effect on the data transferred
      or other nodes.

      If the CLUSTER flag is set, the TIN field MUST NOT be present.

3.5.3.  Sentence Header

   The Sentence Header contains information that applies to the actual
   data transferred, in order to precisely identify them.  It controls
   which type of Words make up the subordinate sentence.  Any given
   sentence must contain only Words of the same type, but a Node Section
   may contain any number (including zero) of sentences of any type.

   Over the wire format:

    0                   1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   | Sentence Type |               Sentence Options                |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |Se. Opt. (ctd.)|        Sentence Length        + :S. L.(ctd.): |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   | :S. L.(ctd.): |
   +-+-+-+-+-+-+-+-+

   Legend:
   : . XYZ . : = bytes that only exist when certain flags are set

   The PSI sentence header.

                                 Figure 3

   Detailed description of the header fields:







Ertl                    Expires November 24, 2010              [Page 19]

Internet-Draft       Protocol for Stage Illumination            May 2010


   Sentence Type: 8 bit

      The sentence type specifies the type of the Words making up the
      current sentence.  It is the same for all Words of any given
      sentence and can thus be used, in combination with the sentence
      Length field, to compute the Word count.  This saves an additional
      field for the Word count.  See Section 3.6 for a description of
      all Word types.


   Sentence Options: 32 bit

      This field is, like the Node Options field, a bit field, that
      specifies the data contained in the current sentence as well
      giving instructions to their use.  It is especially used to govern
      the use of generic Word types like Node Specification and Channel
      Specification.  Additionally, it may contain requests or
      instructions that are to be applied to the data contained in the
      sentence.  This way, the PSI Master can use a single sentence of
      type Channel Number to request all information about the channels
      specified, as well as switch the channels between Safe Values and
      Current Values.  By using Words of one of the Data Word types, new
      values may be assigned to the specified channels at the same time.
      In messages to the PSI Master, this field merely specifies the use
      of the generic Word types.


   Sentence Length: 16 / 32 bit

      Like the length fields in the message- and node headers, this
      field contains the number of bytes used by the current sentence,
      including the Sentence Header and it's length field.  Contrary to
      the lengths of Node Sections and Messages, it is not meant to
      facilitate jumping across the sentence, since the relevance of any
      particular sentence has already been established by the previous
      examination of the preceding node header.  Instead, this field
      describes the number of Words contained in the sentence.  To be
      consistent with the other length fields and to allow for easy
      checking of consistency, it contains the total byte count.
      If the length of the current Word type, which is given in the
      sentence type, is fixed, then the number of Words contained can be
      derived through simple division, allowing further check for
      consistency of Word type and sentence length.  If the length of
      the current Word type is variable, like for example the Reactor
      Status, the sentence may contain only exactly one Word, with the
      sentence length representing the actual length.  This restriction
      stems from the deliberation that Words of variable length will be
      used only occasionally, with their length possibly becoming



Ertl                    Expires November 24, 2010              [Page 20]

Internet-Draft       Protocol for Stage Illumination            May 2010


      comparatively large.  Therefore, the overhead of a complete
      Sentence Header per Word is acceptable in this case.  Since the
      majority of Words transferred is of fixed length however, the
      introduction of an additional length field for each Word would
      cause comparatively large overhead, while it's usefulness would be
      restricted to comparatively few and seldom used Words and thus
      marginal.  Especially with small Words, like channel numbers, the
      overhead would be 100% of the actual data and therefore not
      justified.

3.6.  Word Types

   To further explain the structure of PSI messages, this section lists
   and describes the types of Words used.  The sequence described is the
   sequence as seen on the network.  The ordering of bytes and other
   issues are governed by the transfer syntax (Section 3.1) and
   therefore not explicated here.  Channel number sizes are given by the
   appropriate Sentence Option.  The Word type used, in conjunction with
   the data boundaries, defines the resolution to use, so the PSI Master
   knows which range of values is allowed for the channel and can scale
   the values appropriately.  Values within the Word type but outside
   the defined boundaries MUST make the channel switch to Safe Values
   and setting of the appropriate Reactor Status.

   While a PSI Master MUST implement all of these types except where
   mentioned otherwise, a Reactor only needs to implement the types of
   PSI_Word_Data that it actually uses.

   Boolean Data Word: PSI_Word_DataB

      This data Word consists of the channel number and the actual,
      boolean, datum.
      These two syllables are sent in the sequence "channel number,
      datum".


   Signed 8 bit Data Word: PSI_Word_DataS8

      This data Word consists of the channel number and the actual,
      signed, datum, with a width of 8 bits.
      These two syllables are sent in the sequence "channel number,
      datum".


   Unsigned 8 bit Data Word: PSI_Word_DataU8

      This data Word consists of the channel number and the actual,
      unsigned, datum, with a width of 8 bits.



Ertl                    Expires November 24, 2010              [Page 21]

Internet-Draft       Protocol for Stage Illumination            May 2010


      These two syllables are sent in the sequence "channel number,
      datum".


   Signed 16 bit Data Word: PSI_Word_DataS16

      This data Word consists of the channel number and the actual,
      signed, datum, with a width of 16 bits.
      These two syllables are sent in the sequence "channel number,
      datum".


   Unsigned 16 bit Data Word: PSI_Word_DataU16

      This data Word consists of the channel number and the actual,
      unsigned, datum, with a width of 16 bits.
      These two syllables are sent in the sequence "channel number,
      datum".


   Signed 32 bit Data Word: PSI_Word_DataS32

      This data Word consists of the channel number and the actual,
      signed, datum, with a width of 32 bits.
      These two syllables are sent in the sequence "channel number,
      datum".


   Unsigned 32 bit Data Word: PSI_Word_DataU32

      This data Word consists of the channel number and the actual,
      unsigned, datum, with a width of 32 bits.
      These two syllables are sent in the sequence "channel number,
      datum".


   Signed 64 bit Data Word: PSI_Word_DataS64

      This data Word supplies 64 bit for a signed datum.
      The syllables are sent in the sequence: "channel number, datum".


   Unsigned 64 bit Data Word: PSI_Word_DataU64

      This data Word supplies 64 bit for an unsigned datum.
      The syllables are sent in the sequence: "channel number, datum".





Ertl                    Expires November 24, 2010              [Page 22]

Internet-Draft       Protocol for Stage Illumination            May 2010


   Floating point Data Word: PSI_Word_DataFP

      This data Word supplies 32 bit for a floating point datum.
      The syllables are sent in the sequence: "channel number, datum".


   Double floating point Data Word: PSI_Word_DataDFP

      This data Word supplies 64 bit for a floating point datum.
      The syllables are sent in the sequence: "channel number, datum".


   Quadruple floating point Data Word: PSI_Word_DataQFP

      This data Word supplies 128 bit for a floating point datum.
      The syllables are sent in the sequence: "channel number, datum".


   Data Word of variable length: PSI_Word_Data_Opaque

      This Word allows the transfer of unspecified data.  It may be used
      for exotic systems that cannot be reasonably covered using the
      other Word types.  It is necessary to note that no processing of
      the supplied data is performed, so that device-dependent issues
      are left for the communicating nodes to solve themselves.  Merely
      the channel number is transferred as usual.  Because the
      interpretation depends entirely on the receiver, these generic
      types are just asking for trouble and should be used only when
      truly necessary.

      This is one of the Word types that have no fixed length and
      therefore may only occur once per sentence, requiring a sentence
      per Word.  The reason is that the sentence length is used to
      convey the number of bytes making up the Word, which therefore
      represent the syllables of this type of sentence.  See also
      Section 3.5.3.

      It must be noted that the number of bytes is prepended implicitly
      by the transfer syntax, and thus in addition to the sentence
      length field.  Therefore, the Sentence Length field needs to also
      contain the number of bytes for the implicit length field so that
      the message length is calculated correctly.  By implicitly
      prepending the actual Word length, 32 bits of overhead are
      created.  The receiver implicitly uses and removes the added
      length field.  To facilitate custom structuring of the contents,
      the encoding used is sequence.
      The syllables are sent in the sequence: "channel number, Word
      length (implicit), data bytes".



Ertl                    Expires November 24, 2010              [Page 23]

Internet-Draft       Protocol for Stage Illumination            May 2010


   Data Word for device-specific data: PSI_Word_Data_Plain

      This Word differs from PSI_Word_Data_Opaque only in that it does
      not contain a channel number.
      The syllables are sent in the sequence: "Word length (implicit),
      data bytes".


   Data Word for plain Channel Number: PSI_Word_Channel_Number

      This Word contains only one syllable, representing a channel
      number.  It is used in conjunction with Sentence Options to send
      instructions to and to query information about the channel(s)
      named.
      The syllables are sent in the sequence: "channel number".


   Data Word for Text: PSI_Word_Text

      This is another Word without fixed length, and is thus only
      allowed to occur once per sentence because it's length is given by
      the Sentence Length.  It is used, for example, for the user-
      assigned textual ID; it's syllables are single bytes that contain
      purely text data.  It is converted appropriately if needed by any
      specific system architecture.  In addition to the data and
      termination bytes, the transfer syntax prepends the actual number
      of bytes, creating an overhead of four bytes that also needs to be
      taken into account in the Sentence Length.
      The syllables are sent in the sequence: "channel number, Word
      length (implicit), data bytes".

      The encoding used is UTF-8 ([RFC3629]) (the sender MAY use plain
      ASCII), and it SHOULD be encoded using the string type.


   Generic Data Word for numbers: PSI_Word_Generic_32

      This Word also has no fixed length, and is given by the Sentence
      Length.  It is used for transferring numbers like the user-
      assigned numeric IDs.  All syllables are 32 bits wide and thus the
      Sentence Length always is a multiple of four bytes.  Therefore it
      can be used to calculate the number of syllables and no additional
      field is needed to store the actual length.
      The syllables are sent in the sequence: "datum, datum,...".







Ertl                    Expires November 24, 2010              [Page 24]

Internet-Draft       Protocol for Stage Illumination            May 2010


   Data Word for Reactor Status: PSI_Word_Reactor_Status

      This Word also has no fixed length, and is given by the Sentence
      Length.  It is used for transferring detailed status information
      about a Reactor.  All syllables are 8 bits wide and thus the
      Sentence Length can be used to calculate the number of syllables
      and no additional field is needed to store the actual length.
      The syllables are sent in the sequence: "datum, datum,...".


   Data Word for channel status: PSI_Word_Channel_Status

      This Word contains two syllables: a channel number and the channel
      status, that is encoded as bit field of 16 bits.
      The syllables are sent in the sequence: "channel number, channel
      status".


   Data Word for Safety Sequence: PSI_Word_Safety_Sequence

      This Word is used to convey the sequence required to change the
      value of a channel that requires extra safety.  It has a variable
      length and thus must only occur once per sentence.  It's component
      syllables are 32 bits in size and thus the Sentence Length can be
      used to calculate the number of syllables, without the need for an
      additional length field.  The first syllable is the channel
      number; all following syllables are the numbers to send, in the
      same sequence as given in this Word, to activate the channel.
      The syllables are sent in the sequence: "channel number, sequence
      component 0, sequence component 1,...".

      Any such channel MUST NOT change it's value if the sequence is not
      received fully, out of order, or numbers not in the sequence are
      received.  To change the value of such a channel, the sequence
      MUST be split into individual messages containing Words of this
      type, but only a single component of the sequence at a time.  The
      value that the channel is supposed to switch to MUST be sent with
      the same message, in a separate sentence of the Word type as the
      channel's data type, with every component of the sequence.  All
      messages that contain parts of the sequence MUST contain the same
      target value.  If the target value in one of the messages does not
      match the previous, then, even if the sequence component itself
      matches the one expected, any sequence progress MUST be discarded
      and the value MUST NOT be changed.

      This is done to ensure that no single erroneous packet can trigger
      a value change (unless the sequence length is 1, which is allowed
      but strongly discouraged).  However, multiple channels, including



Ertl                    Expires November 24, 2010              [Page 25]

Internet-Draft       Protocol for Stage Illumination            May 2010


      channels using Safety Sequence, may be served in a single message.
      Because any packet may get lost or received incorrectly, to ensure
      that the sequence has been advanced, the flag PSI_NO_FM_SENDACK
      may be used.

      Additionally, a channel using Safety Sequence MUST NOT advance the
      sequence when it is using Safe Values, like after receiving
      PSI_SO_FM_GOSAFE or PSI_NO_FM_GOSAFE.

      The actual length of the sequence is left to be assigned by the
      users of the system, governed to their safety requirements, so an
      implementation MUST NOT expect any specific length.  A device MAY
      include a default sequence deemed reasonable by the vendor, but it
      MUST allow the user to change the sequence, including it's length.
      A length of 1 MUST NOT be used as default, and an implementation
      MUST warn the user about the safety implications of setting it to
      that length.  A length of zero MUST make the channel ignore any
      value changes it may receive, effectively disabling it.  A
      sequence MUST NOT contain any single number more than once, so
      that duplicated or reordered packets can not advance the sequence.
      Whenever the sequence received does not match the required
      sequence, the receiver MUST discard all parts received already,
      and restart at the beginning.  The numbers 0 and 0xFFFFFFFF (all
      bits set) MUST reset the receiver, and therefore cannot be used as
      part of a sequence.  This is done so that any channel using Safety
      Sequence can safely be reset without knowing the sequence that has
      been assigned to it.

      Note: it would be possible to add explicit numbering to each part
      of the sequence, but because the sequence length will always be
      small compared to the available number space, this seems to be
      unnecessary overhead, adding to the overhead already created by
      splitting.
      A preliminary suggestion is for a channel implementation to have
      room for a length of at least 20 per channel.  Any PSI Master
      implementing Safety Sequence is expected to allow for longer
      sequences.

      Implementation of this type is completely optional.


   Data Word for channel counts: PSI_Word_Channel_Count

      This Word is composed of three syllables, each 64 bit in size,
      specifying the counts of the various channel types in a Reactor.
      The syllables are sent in the sequence: "input channel count, in/
      out channel count, output channel count".




Ertl                    Expires November 24, 2010              [Page 26]

Internet-Draft       Protocol for Stage Illumination            May 2010


   Generic Word for Node Specification: PSI_Word_Node_Specification

      This Word only contains a single value of 32 bits.  It's meaning
      is defined by the Sentence Options.  This method was chosen to not
      have to define a large number of Words that differ in name only.
      The syllables are sent in the sequence: "node specification".


   Generic Word for Channel specification:
   PSI_Word_Channel_Specification

      This Word contains two syllables: the channel number and a channel
      specification of size 32 bit.  Like PSI_Word_Node_Specification,
      the actual meaning is given by the Sentence Options.
      The syllables are sent in the sequence: "channel number, channel
      specification".

3.7.  Constants

   This section lists and explains the constants used in PSI.  Since
   only the values of the constants are transferred between nodes, an
   implementor may choose to use any convenient naming and assignment
   scheme.


3.7.1.  Conventions

   The conventions used in this document are as follows:


   o  Naming

      All constants are prefixed with "PSI" to emphasize their belonging
      to the PSI, and to avoid collision and confusion with other
      constants.  An underscore ("_") separates the specification of the
      general usage in the form "AB".  Following another underscore is
      the direction in form "CD", if the constant is defined for more
      than one direction.  A further underscore separates this from the
      general meaning of the constant, usually given by an acronym "E".
      Thus, constant names are constructed like this:

      PSI_AB_CD_E (directional constant), like PSI_ST_TM_WD32 PSI_AB_E
      (nondirectional constant), like PSI_CR_8

      Values for AB:

      PV: Protocol Version
      MT: Message Type



Ertl                    Expires November 24, 2010              [Page 27]

Internet-Draft       Protocol for Stage Illumination            May 2010


      NO: Node Option
      SO: Sentence Option
      ST: Sentence Type
      RT: Reactor Type
      RS: Reactor Status
      CT: Channel Type
      CS: Channel Status

      Values for CD:

      FM: From PSI Master
      TM: To PSI Master

      Constants that have different application (like single or
      conglomerate constants) are named in a way to show their meaning,
      and are prefixed with "PSI".


   o  Values

      Especially bit constants are given in the form "bit X", specifying
      the bit that is set, counting the MSB of the field as bit 0.
      Other constants, especially large ones, are given as hexadecimal,
      prefixed by the conventional "0x".

3.7.2.  Protocol version


   PSI-32 Bit: PSI_PV_0

   This is the protocol described here.
   It is defined as 0.

3.7.3.  Bases for constants

   To ease readability and structure, there are a few constants serving
   as base for others.  The bases are chosen in a way to allow the
   constants of every area to start from 0 by adding the base as offset.

   Type base for 'direction from PSI Master': PSI_TYPE_BASE_FM

      This is the base for all constants that depend on the message
      direction, identifying data coming from the PSI Master.
      It's value is 0.







Ertl                    Expires November 24, 2010              [Page 28]

Internet-Draft       Protocol for Stage Illumination            May 2010


   Type base for 'direction to PSI Master': PSI_TYPE_BASE_TM

      This is the base for all constants that depend on the message
      direction, identifying data sent to the PSI Master.
      It's value is "bit 7", dividing the available number space by
      half.


   Type base for 'message from the PSI Master': PSI_MT_BASE_FM

      This is the base for all message types that are sent by the PSI
      Master.
      It's value is PSI_TYPE_BASE_FM.


   Type base for 'message from the PSI Master': PSI_MT_BASE_TM

      This is the base for all message types that are sent to the PSI
      Master.
      It's value is PSI_TYPE_BASE_TM.


   Type base for sentences in messages coming from the PSI Master:
   PSI_ST_BASE_FM

      This is the base for sentence types that are used in messages sent
      by the PSI Master.
      It's value is PSI_TYPE_BASE_FM.


   Type base for sentences in messages sent to the PSI Master:
   PSI_ST_BASE_TM

      This is the base for sentence types that are used in messages sent
      to the PSI Master.
      It's value is PSI_TYPE_BASE_TM.

3.7.4.  Message types

   The following constants identify the message types as described in
   Section 3.4.  The direction of the message is identified by use of
   the appropriate constant.  The meaning of a message may differ
   depending on it's direction, so this is not only important for
   plausibility checking.

   As described in Section 3.5.1, including the message direction (bit
   0), the most significant 3 bits are used as flags.




Ertl                    Expires November 24, 2010              [Page 29]

Internet-Draft       Protocol for Stage Illumination            May 2010


   Messages from the PSI Master:

   Normal (unicast) message: PSI_MT_FM_NORMAL

      This designates the most basic type of data message.  The message
      is directed at a single Reactor only and therefore does not
      contain a field for a GID.  It may, however, contain multiple Node
      Sections.
      It's value is (PSI_MT_BASE_FM+0).


   Multicast message: PSI_MT_FM_MULTICAST

      This type designates a message intended for multicasting.
      Contrary to the unicast message, it contains a field for a GID.
      It's value is (PSI_MT_BASE_FM+1).


   Broadcast message: PSI_MT_FM_BROADCAST

      This type designates a message intended for broadcasting.  Like
      the multicast message, it contains a field for a GID.
      It's value is (PSI_MT_BASE_FM+2).


   Discovery message: PSI_MT_FM_DISCOVERY

      This type designates a PSI Master to Reactor Discovery message.
      It does not contain information besides the message header itself.
      It's value is (PSI_MT_BASE_FM+3).


   Version mismatch message: PSI_MT_FM_VERSION_MISMATCH

      This type designates a PSI Master to Reactor version mismatch
      message.  It does not contain information besides the message
      header itself.  The version field indicates the next supported
      version.
      It's value is (PSI_MT_BASE_FM+4).


   Messages to the PSI Master:

   Normal (unicast) message: PSI_MT_TM_NORMAL

      This message is directed at a single PSI Master.  This is the
      usual case even in the presence of multiple PSI Masters.
      It's value is (PSI_MT_BASE_TM+0).



Ertl                    Expires November 24, 2010              [Page 30]

Internet-Draft       Protocol for Stage Illumination            May 2010


   Multicast message: PSI_MT_TM_MULTICAST

      This type designates a message intended for multicasting.
      Contrary to the unicast message, it contains a field for a GID.
      It's value is (PSI_MT_BASE_TM+1).


   Broadcast message: PSI_MT_TM_BROADCAST

      This type designates a message intended for broadcasting.  Like
      the multicast message, it contains a field for a GID.
      It's value is (PSI_MT_BASE_TM+2).


   Discovery message: PSI_MT_TM_DISCOVERY

      This type designates a Reactor to PSI Master Discovery message.
      It does not contain information besides the message header itself.
      It's value is (PSI_MT_BASE_TM+3).


   Version mismatch message: PSI_MT_TM_VERSION_MISMATCH

      This type designates a Reactor to PSI Master version mismatch
      message.  It does not contain information besides the message
      header itself.  The version field indicates the next supported
      version.
      It's value is (PSI_MT_BASE_FM+4).

3.7.5.  Node Options

   This section describes the constants defined for Node Options.  The
   Node Options are encoded as bit field to conserve bandwidth.

   Node Options for messages from the PSI Master:

   These Node Options are valid coming from the PSI Master.  They may be
   combined in any number, with certain exceptions.  This way it is
   possible to request all possible information about a Reactor with a
   single message.  Some requests may result in more data to be sent
   than the current maximum message length.  Unless a single Word
   exceeds the maximum message length (an error; truncation is only
   possible for non-essential things like vendor-specific information),
   the reply is split accross multiple messages, using proper sentences.







Ertl                    Expires November 24, 2010              [Page 31]

Internet-Draft       Protocol for Stage Illumination            May 2010


   Query the Reactor's status: PSI_NO_FM_RSREQ

      This flag makes the Reactor send a detailed status message to the
      PSI Master.
      It's value is "bit 31".


   Query the Reactor's Identification Number: PSI_NO_FM_INREQ

      This flag makes the Reactor send a message.  Since the IN is part
      of the message header (see Section 3.5.1), any message that needs
      to be sent to the PSI Master anyway will do.  If no message needs
      to be sent at that time, an empty message of type PSI_ST_TM_WN is
      sent.
      It's value is "bit 30".


   Query vendor specific information: PSI_NO_FM_VSIREQ

      This flag is used to request transmission of vendor specific
      information like vendor name, device name, model number, etc. to
      the PSI Master.  The Reactor sends both the vendor string (using
      the generic text message Word PSI_ST_TM_WT) and the vendor numbers
      (using the generic 32 bit Word PSI_ST_TM_WG32), if any.  If
      nothing has been set, an empty sentence of the respective type is
      sent.
      It's value is "bit 29".


   Query user specific information: PSI_NO_FM_USIREQ

      This flag is used to request transmission of all user specific
      information.  Like PSI_NO_FM_VSIREQ, the Reactor sends both the
      user string (using the generic text message Word PSI_ST_TM_WT) and
      the user numbers (using the generic 32 bit Word PSI_ST_TM_WG32),
      if any.  If nothing has been set, an empty sentence of the
      respective type is sent.
      It's value is "bit 28".


   Query channel counts: PSI_NO_FM_CCREQ

      This flag is used to request transmission of the number of
      channels of each type (Output, InOut, Input) to the PSI Master.
      Channels using Safety Sequence count as Output or InOut, according
      to their properties.
      It's value is "bit 27".




Ertl                    Expires November 24, 2010              [Page 32]

Internet-Draft       Protocol for Stage Illumination            May 2010


   Query all data types: PSI_NO_FM_DTREQ

      This flag is used to request transmission of the data types of all
      channels to the PSI Master.  If the resulting list is longer than
      the maximum message length, it may be split into separate
      messages.
      It's value is "bit 26".


   Query all channel boundaries: PSI_NO_FM_DBREQ

      This flag is used to request transmission of the boundaries of all
      channels to the PSI Master.  If the resulting list is longer than
      the maximum message length, it may be split into separate
      messages.
      It's value is "bit 25".


   Query all channel types: PSI_NO_FM_CTREQ

      This flag is used to request transmission of the types of all
      channels to the PSI Master.  If the resulting list is longer than
      the maximum message length, it may be split into separate
      messages.
      It's value is "bit 24".


   Query all channel states: PSI_NO_FM_CSREQ

      This flag is used to request transmission of the status of all
      channels to the PSI Master.  If the resulting list is longer than
      the maximum message length, it may be split into separate
      messages.
      It's value is "bit 23".


   Query the Reactor's type: PSI_NO_FM_RTREQ

      This flag is used to request transmission of the Reactor's type to
      the PSI Master.
      It's value is "bit 22".


   Query all Safe Values: PSI_NO_FM_SVREQ

      This flag is used to request transmission of the Safe Values for
      all channels to the PSI Master.  If the resulting list is longer
      than the maximum message length, it may be split into separate



Ertl                    Expires November 24, 2010              [Page 33]

Internet-Draft       Protocol for Stage Illumination            May 2010


      messages.
      It's value is "bit 21".


   Query all data values: PSI_NO_FM_VREQ

      This flag is used to request transmission of the Current Values of
      all channels to the PSI Master.  If the resulting list is longer
      than the maximum message length, it may be split into separate
      messages.
      It's value is "bit 20".


   Query GIDs: PSI_NO_FM_GIDREQ

      This flag is used to request transmission of all GIDs assigned to
      it to the PSI Master.
      It's value is "bit 19".


   Query maximum message length: PSI_NO_FM_MMLREQ

      This flag is used to request transmission of the Reactor's maximum
      message length to the PSI Master.  This SHOULD be at least around
      1400 bytes, but MAY be significantly larger.  The PSI Master MUST
      NOT send messages larger than this to the Reactor (including group
      messages), but may send any size below this.  If a Reactor's
      maximum message size changes, it MUST set the PSI_RS_REREAD_ALL
      status.
      Note that even though the Reactor must know the PSI Master's
      maximum message length, there is no corresponding request flag.
      That is because the PSI Master will send this information by
      itself, usually alongside it's REACTOR_ACCEPTED message.  If for
      some reason the Reactor has not received this information despite
      a REACTOR_ACCEPTED message, it must resume sending discovery
      messages.
      It's value is "bit 18".


   Request to use the Current Values: PSI_NO_FM_GODATA

      If this flag is set, and the Reactor is currently using Safe
      Values, it will start using the Current Values as soon as
      possible, usually after reception of values for every channel.  In
      any case, a Reactor MUST NOT start using Current Values if a
      timeout occurred, or if it has not actually received values, or
      the values received are not valid (anymore).  If it is sent in a
      message containing data Words, then the values received are



Ertl                    Expires November 24, 2010              [Page 34]

Internet-Draft       Protocol for Stage Illumination            May 2010


      applied immediately.  If the same message has the flag
      PSI_NO_FM_GOSAFE set, then that MUST be given precedence.
      PSI_SO_FM_GOSAFE, if set in this message or previously, overrides
      this flag on a per-channel basis, but does not clear it.
      Therefore, PSI_NO_FM_GODATA applies to these channels as soon as
      PSI_SO_FM_GODATA is received, unless it has been cleared meanwhile
      by PSI_NO_FM_GOSAFE or a timeout occurred.  As an exception,
      channels using Safety Sequence MUST discard received data unless
      they are set to use Current Values.  This flag may be sent at any
      time, but is restricted to Output and InOut Reactors.
      It's value is "bit 17".

      Note: because there is no guarantee that any message sent actually
      reaches the receiver, this flag SHOULD be repeated as long as it
      is supposed to be in effect.  This can easily be done by setting
      this flag in all Node Sections.  Alternatively, the Reactor's
      status may be queried, or replies that can doubtlessly be
      attributed to requests having been sent in this same sentence may
      also be taken as acknowledgement.  Furthermore, the flag
      PSI_NO_FM_SENDACK may also be used.


   Request to use the Safe Values: PSI_NO_FM_GOSAFE

      If this bit is set, all Output and InOut channels MUST be switched
      to their respective Safe Values, regardless of the remaining
      content of the sentence or other Sentence Options.  This MUST only
      be reverted upon reception of PSI_NO_FM_GODATA.  This flag MUST be
      applied regardless of the state of the channels, even if they have
      already been individually set to use Safe Values.  This means that
      when a channel gets set to use Current Values by use of
      PSI_SO_FM_GODATA, it will still continue using Safe Values until
      PSI_NO_FM_GODATA is sent to it's Reactor.  Channels using Safety
      Sequence MUST clear any progress made through their sequence, and
      cease operation or otherwise ensure safety if at all possible.
      This flag SHOULD be used whenever a PSI Master cannot generate new
      values for any channel of that Reactor, for example if input
      channels that are used to generate the values cease providing
      data.  It MUST be used if the PSI Master detects an internal or
      external problem that could result in incorrect values being
      generated.
      It may also be used prior to shutting down the PSI Master, or
      before a Reactor is removed from the PSI Master's inventory.
      It is valid for all Reactor types and may be sent at any time and
      combined with all other flags; if PSI_NO_FM_GODATA is set then
      that is ignored, PSI_NO_FM_GOSAFE always taking precedence.  Input
      Reactors ignore this flag.
      It's value is "bit 16".



Ertl                    Expires November 24, 2010              [Page 35]

Internet-Draft       Protocol for Stage Illumination            May 2010


      Note: because there is no guarantee that any message sent actually
      reaches the receiver, this flag must be repeated as long as it is
      supposed to be in effect.  This can easily be done by setting this
      flag in all Node Sections.  Alternatively, the Reactor's status
      may be queried, or the flag PSI_NO_FM_SENDACK may be used, so a
      correspondingly set PSI_NO_TM_ACK suffices.


   Node Section applies to all Group members: PSI_NO_FM_CLUSTER

      This flag is used to indicate that the current Node Section is to
      be interpreted by all receiving Reactors that are members of the
      Group specified, and MUST only be used in messages of type
      broadcast or multicast.  A Node Section that has this flag set has
      no TIN field.  This flag exists to increase efficiently in case
      there are several Reactors that are supposed to receive identical
      data.  Normally, this will be the case for functionally similar
      Reactors, but because it may be combined with any flag except
      PSI_NO_FM_ACK, PSI_NO_FM_REACTOR_ACCEPTED and
      PSI_NO_FM_NODE_FINISHED, it is not limited to sending data (see
      Section 2.2).  While Reactors MUST implement it, implementation
      and use of this flag MAY be omitted for PSI Masters.
      It's value is "bit 15".


   Reply to a Discovery message: PSI_NO_FM_REACTOR_ACCEPTED

      If this flag is set, the PSI Master has added the Reactor to it's
      inventory.  The PSI Master sends a message with this flag set for
      each Discovery Message it receives, until the Reactor ceases
      sending further Discoveries.  This ensures that even if an
      arbitrary number of Discovery messages and / or replies get lost,
      every Reactor in the Nexus is known to the PSI Master, and has
      received a reply, in the end.  Therefore, once the PSI Master does
      not receive any Discovery messages anymore, the initial Discovery
      Phase has completed (except if a connection is so lossy that no
      Discoveries reach the PSI Master before the timeout; in this case
      the Reactor will eventually be discovered as if it had been added
      later).
      It's value is "bit 14".

      This means that

      *  prior to receipt of a reply by a Reactor, the PSI Master has
         received at least one Discovery message from that Reactor and
         therefore knows of it and that





Ertl                    Expires November 24, 2010              [Page 36]

Internet-Draft       Protocol for Stage Illumination            May 2010


      *  upon arrival of a Discovery message at the PSI Master the
         sending Reactor may not yet have received a reply, or the
         Discovery may already have been on it's way before the Reactor
         received the reply.  Since this cannot be known, another reply
         must be sent.  See Section 3.8 for details.


   Request to send a confirmation: PSI_NO_FM_SENDACK

      The receiving Reactor MUST acknowledge, after having executed
      them, all Node Sections that have this flag set.  This is done by
      sending each of them back (keeping the FM types) inside a Node
      Section that has the flag PSI_NO_TM_ACK set.  Only those data and
      requests must be contained that were actually used and executed.
      Doing this may be especially worthwhile in case of channels using
      Safety Sequence, so the advancement can be monitored.
      It's value is "bit 13".


   Confirmation of executing a request: PSI_NO_FM_ACK

      This flag indicates that the PSI Master has received and executed
      one or more requests by a Reactor.  The Node Section with this
      flag set contains all requests and data that were executed or used
      (keeping the TM types).  This kind of acknowledge is sent when
      PSI_NO_TM_SENDACK is set.
      It's value is "bit 12".


   End of relevant message content: PSI_NO_FM_NODE_FINISHED

      If this flag is set in a Node Section it indicates that this is
      the last Node Section containing data for the specific Reactor.
      The Reactor therefore does not need to interpret the remainder of
      the message, if any.  However, for error detection, the entire
      message still needs to be checked, meaning that it must have been
      received in full and the length data must match each other.  If
      this is not the case, then the message must be discarded and no
      information or requests contained in it must be used or executed
      because it is not clear which part the error actually affects.
      It's value is "bit 11".


   Node Options for messages to the PSI Master:

   The following Node Options are valid going to the PSI Master.  With
   certain exceptions, they may be combined arbitrarily.




Ertl                    Expires November 24, 2010              [Page 37]

Internet-Draft       Protocol for Stage Illumination            May 2010


   Reactor status OK: PSI_NO_TM_SOK

      If this flag is set, there are no issues at all.  It therefore
      must only be set if none of the other Reactor status bits
      (PSI_NO_TM_Sx) is set.
      It's value is "bit 31".


   Non-critical information: PSI_NO_TM_SNCI

      If this flag is set, there is non-critical information, so a
      status inquiry is recommended.  The correct functioning of the
      Reactor is not affected.  This is the case, for example, when the
      Reactor has been switched to Safe Values.  If this flag is set,
      PSI_NO_TM_SOK must not be set.
      It's value is "bit 30".


   Non-critical error: PSI_NO_TM_SNCE

      If this flag is set, there is a non-critical error, so a status
      inquiry is strongly recommended.  This is the case, for example,
      if the Reactor has started using Safe Values due to a timeout.  If
      this flag is set, PSI_NO_TM_SOK must not be set.
      It's value is "bit 29".


   Critical error: PSI_NO_TM_SCE

      If this flag is set, there is a critical error that may affect the
      Reactor's operation and possibly damage it.  Therefore, a status
      inquiry is required to query the exact problem(s).  This is the
      case, for example, if channels stop functioning or another
      hardware or software error has been detected.  If this flag is
      set, PSI_NO_TM_SOK must not be set.
      It's value is "bit 28".


   Status unchanged: PSI_NO_TM_SUNCH

      The Reactor's status is not OK, but has not changed since the last
      status inquiry; another inquiry is not required, but allowed at
      any time.  If this flag is set, then PSI_NO_TM_SOK must not be
      set.
      It's value is "bit 27".






Ertl                    Expires November 24, 2010              [Page 38]

Internet-Draft       Protocol for Stage Illumination            May 2010


   Request to send a confirmation: PSI_NO_TM_SENDACK

      The PSI Master MUST confirm all Node Sections marked with this
      flag after having executed them.  This is done by sending each of
      them back (keeping the TM types) inside a Node Section that has
      the flag PSI_NO_FM_ACK set.  Only those data and requests must be
      contained that were actually used and executed.
      It's value is "bit 26".


   Confirmation of executing a request: PSI_NO_TM_ACK

      This flag indicates that the Reactor has received and executed one
      or more requests by the PSI Master.  The Node Section with this
      flag set contains all requests and data that were executed or used
      (keeping the FM types).  This kind of acknowledge is sent when
      PSI_NO_FM_SENDACK is set.
      It's value is "bit 25".


   End of relevant message content: PSI_NO_TM_MASTER_FINISHED

      If this flag is set in a Node Section it indicates that this is
      the last Node Section containing data for the specific PSI Master.
      The PSI Master therefore does not need to interpret the remainder
      of the message, if any.  However, for error detection, the entire
      message still needs to be checked, meaning that it must have been
      received in full and the length data must match each other.  If
      this is not the case, then the message must be discarded and no
      information or requests contained in it must be used or executed
      because it is not clear which part the error actually affects.
      It's value is "bit 24".

3.7.6.  Sentence Options

   This section describes the constants defined for Sentence Options.
   The Sentence Options are encoded as bit field to conserve bandwidth.
   The definitions of channel number sizes apply to all Words within any
   given sentence.  Every node MUST be able cope with all sizes, but the
   smallest size possible to SHOULD always be used.  Especially, if
   there is a substantial number of channels below any specific size
   definition in the same sentence as one or more above that size
   definition, they SHOULD be split into separate sentences so the
   smaller type can be used for the lower channels.

   Sentence Options for messages from the PSI Master:

   These Sentence Options are valid coming from the PSI Master.  They



Ertl                    Expires November 24, 2010              [Page 39]

Internet-Draft       Protocol for Stage Illumination            May 2010


   may be combined in any number, with certain exceptions.  This way it
   is possible to request all possible information about channels using
   a single message.

   Status request: PSI_SO_FM_SREQ

      When this bit is set, the Reactor will send the status of the
      channels given in the sentence.  Normally, it is used in sentences
      of type Channel Number, but it may be used with any type that
      contains a channel number.  It is valid for all channel types and
      may be sent at any time.
      It's value is "bit 31".


   Value request: PSI_SO_FM_VREQ

      If this bit is set, the Reactor will send the Current Values of
      the channels given in the sentence (for output channels, the value
      assigned last is sent).  Normally, it is used in sentences of type
      Channel Number, but it may be used with any type that contains a
      channel number.  It is valid for all channel types and may be sent
      at any time.
      It's value is "bit 30".


   Safe Value request: PSI_SO_FM_SVREQ

      If this bit is set, the Reactor will send the Safe Values for the
      channels given in the sentence.  Normally, it is used in sentences
      of type Channel Number, but it may be used with any type that
      contains a channel number.  It is valid only for channels of type
      Output and InOut, and may be sent at any time.  Channels using
      Safety Sequence send either of the cancellation values given in
      Section 3.6 at Word type "PSI_Word_Safety_Sequence".
      It's value is "bit 29".


   Query the data types used: PSI_SO_FM_DTREQ

      When this bit is set, the Reactor will send the Data Types (that
      define the Word type to be used) of the channels given in the
      sentence.  It may be used only in Words of type Channel Number,
      because the type of Data Word to be used is not known yet.
      Likewise, the use of the flag PSI_SO_FM_GODATA is not allowed,
      because for lack of knowledge of the Data Types, no data can have
      been sent.  Use of the flag PSI_SO_FM_GOSAFE is allowed.  This
      Option is valid for all channel types and may be sent at any time.
      Because a channel using Safety Sequence always uses an additional



Ertl                    Expires November 24, 2010              [Page 40]

Internet-Draft       Protocol for Stage Illumination            May 2010


      data Word, that needs to be returned.  A channel using Safety
      Sequence MUST discard any progress through the sequence if this
      Option is received, and ensure safety if at all possible.
      It's value is "bit 28".

      Note: Replies to PSI_SO_FM_SVREQ or PSI_SO_FM_VREQ allow deducing
      the Word Type used, so using this flag is not strictly necessary.


   Query Safety Sequence: PSI_SO_FM_SSREQ

      When this bit is set, the Reactor will send the Safety Sequences
      for the channels given in the sentence.  Because the sequence is
      not supposed to be known yet, it may only be used with Words of
      type Channel Number.  It's use is restricted to channels using
      Safety Sequence and may be sent at any time.  A channel using
      Safety Sequence MUST discard any progress through the sequence if
      this Option is received, and also cease operation and ensure
      safety if at all possible.
      It's value is "bit 27".


   Query channel type: PSI_SO_FM_CTREQ

      If this bit is set, the Reactor will send the types of the
      channels given in the sentence.  Because the channel details
      cannot be known yet, it may only be used with Words of type
      Channel Number.  The use of PSI_SO_FM_GODATA is not allowed in
      this sentence, since no data values can have been sent yet.  Use
      of PSI_SO_FM_GOSAFE is allowed.  It may be used with all channel
      types and may be sent at any time.
      It's value is "bit 26".


   Query the data boundaries: PSI_SO_FM_DBREQ

      If this bit is set, the Reactor sends the minimum and maximum
      values that are meaningful to the channels listed in the sentence.
      This bit may be used with any Word type that contains a channel
      number, and may be sent to channels of all types and at any time.
      Even though use of this flag is technically optional, and it is
      expected that for most channels the boundaries will be given by
      the Word type, it should be used because that is not necessarily
      the case.  Therefore it is important for correctly calculating
      values to send, especially since a receiver may use any method for
      fitting the data received into it's storage (discarding the
      superfluous bits is suggested).
      It's value is "bit 25".



Ertl                    Expires November 24, 2010              [Page 41]

Internet-Draft       Protocol for Stage Illumination            May 2010


   Defines channel numbers to be 8 bit: PSI_SO_FM_CN8

      This bit defines the size of all channel numbers in the sentence
      to be 8 bit in size.  It may only be used in conjunction with
      Words actually containing channel numbers, and must not be
      combined with any other channel number definition.
      It's value is "bit 24".


   Defines channel numbers to be 16 bit: PSI_SO_FM_CN16

      This bit defines the size of all channel numbers in the sentence
      to be 16 bit in size.  It may only be used in conjunction with
      Words actually containing channel numbers, and must not be
      combined with any other channel number definition.
      It's value is "bit 23".


   Defines channel numbers to be 32 bit: PSI_SO_FM_CN32

      This bit defines the size of all channel numbers in the sentence
      to be 32 bit in size.  It may only be used in conjunction with
      Words actually containing channel numbers, and must not be
      combined with any other channel number definition.
      It's value is "bit 22".


   Defines channel numbers to be 64 bit: PSI_SO_FM_CN64

      This bit defines the size of all channel numbers in the sentence
      to be 64 bit in size.  It may only be used in conjunction with
      Words actually containing channel numbers, and must not be
      combined with any other channel number definition.
      It's value is "bit 21".


   Maximum message length information: PSI_SO_FM_MMSINFO

      This flag is valid only in conjunction with a Word of type
      PSI_Word_Node_Specification, that contains the maximum message
      length of the PSI Master.  A Reactor MUST NOT send messages larger
      than that to the PSI Master, but may send any size below.  The PSI
      Master MAY change this at any time during normal operation,
      usually as part of adapting to packet loss.  It then sends a
      message with this flag, and usually also the flag
      PSI_NO_FM_SENDACK set.  This way, and because the PSI Master
      controls the length of it's own messages, it is in full control of
      the maximum message sizes that are sent, and therefore the



Ertl                    Expires November 24, 2010              [Page 42]

Internet-Draft       Protocol for Stage Illumination            May 2010


      Reactors do not need to be reconfigured to adapt to new network
      conditions.
      The PSI Master's maximum message length SHOULD be around 1400
      bytes, at least initially, to allow configuration information to
      be sent as complete as possible, but MAY become significantly
      larger and also smaller in response to network packet loss.
      This means that Words without fixed length, like vendor- and user-
      specific information, should be well below 1400 bytes in length,
      because otherwise they may be truncated, or sending may abort with
      an error.  Don't be unnecessarily chatty! ;)
      It's value is "bit 20".


   Assignment of Group IDs: PSI_SO_FM_GIDSET

      This bit may only be used in conjunction with Words of type
      PSI_Word_Node_Specification, that contain the GIDs to be used.
      Multiple Words may be used to assign as many GIDs.  Any sentence
      having this flag set clears and replaces all GIDs assigned
      previously, if any.  Use of this flag in an empty sentence removes
      all assigned GIDs.  Execution must be acknowledged (see
      PSI_NO_TM_ACK).  Use of this flag is optional.
      It's value is "bit 19".


   Additional assignment of Group IDs: PSI_SO_FM_GIDADD

      This bit may only be used in conjunction with Words of type
      PSI_Word_Node_Specification, that contain the GIDs to be added.
      Multiple Words may be used to add as many GIDs.  Any sentence
      having this flag set adds the GIDs listed to any GIDs that were
      assigned previously; how to handle duplicates is left to the
      implementor.  Execution must be acknowledged (see PSI_NO_TM_ACK).
      Use of this flag is optional.
      It's value is "bit 18".


   Removal of Group IDs: PSI_SO_FM_GIDREM

      This bit may only be used in conjunction with Words of type
      PSI_Word_Node_Specification, that contain the GIDs to be removed.
      Multiple Words may be used to remove as many GIDs.  Any duplicates
      must also be removed from the list.  Use of this flag in an empty
      sentence removes all assigned GIDs.  Execution must be
      acknowledged (see PSI_NO_TM_ACK).  Use of this flag is optional.
      It's value is "bit 17".





Ertl                    Expires November 24, 2010              [Page 43]

Internet-Draft       Protocol for Stage Illumination            May 2010


   Request to use Current Values: PSI_SO_FM_GODATA

      If this flag is set, and the channels listed are currently using
      Safe Values, they will start using the Current Values as soon as
      possible, usually after reception of the first value.  In any
      case, a channel MUST NOT start using Current Values if a timeout
      occurred, or if it has not actually received values, or the values
      received are not valid (anymore).  This flag may be used with any
      Word type containing a channel number, and at any time, but is
      restricted to Output and InOut channels.  If it is set in a
      sentence containing data Words, then the values received are
      applied immediately.  If the same sentence has the flag
      PSI_SO_FM_GOSAFE set, then that MUST be given precedence.
      PSI_NO_FM_GOSAFE, if set in this message or previously, overrides
      this flag, but does not clear it.  Therefore, PSI_SO_FM_GODATA is
      applied as soon as PSI_NO_FM_GODATA is received, unless it has
      been cleared meanwhile by PSI_SO_FM_GOSAFE or a timeout occurred.
      As an exception, channels using Safety Sequence MUST discard
      received data unless they are set to use Current Values.
      It's value is "bit 16".

      Note: because there is no guarantee that any message sent actually
      reaches the receiver, this flag SHOULD be repeated as long as it
      is supposed to be in effect.  This can easily be done by setting
      this flag in all sentences.  Alternatively, the channels status
      may be queried, or replies that can doubtlessly be attributed to
      requests having been sent in this same sentence may also be taken
      as acknowledgement.  Furthermore, the flag PSI_NO_FM_SENDACK may
      also be used.


   Request to use Safe Values: PSI_SO_FM_GOSAFE

      If this bit is set, all channels listed in this sentence MUST be
      switched to their respective Safe Values, regardless of the
      remaining content of the sentence or other Sentence Options.  This
      MUST only be reverted upon reception of PSI_SO_FM_GODATA.  This
      flag MUST be applied regardless of the state of the Reactor, even
      if the Reactor as a whole has already been set to use Safe Values.
      This means that when the Reactor gets set to use Current Values by
      use of PSI_NO_FM_GODATA, channels having received this flag
      continue using Safe Values until PSI_SO_FM_GODATA is sent to them.
      Channels using Safety Sequence MUST clear any progress made
      through their Safety Sequence, and cease operation or otherwise
      ensure safety if at all possible.  This flag MUST be used whenever
      a PSI Master cannot generate new values for a channel, for example
      if an Input channel that is used to generate the value ceases
      providing data.  It is valid for all channel types (Input channels



Ertl                    Expires November 24, 2010              [Page 44]

Internet-Draft       Protocol for Stage Illumination            May 2010


      ignore it) and may be sent at any time and combined with all other
      flags; if PSI_SO_FM_GODATA is set then that is ignored,
      PSI_SO_FM_GOSAFE always taking precedence.
      It's value is "bit 15".

      Note: because there is no guarantee that any message sent actually
      reaches the receiver, this flag must be repeated as long as it is
      supposed to be in effect.  This can easily be done by setting this
      flag in all sentences.  Alternatively, the channel's status may be
      queried, or the flag PSI_NO_FM_SENDACK may be used, so a
      correspondingly set PSI_NO_TM_ACK suffices.


   Assignment of new values: PSI_SO_FM_VSET

      This flag must only be used in sentences containing data Words and
      makes the Reactor assign the new values to the corresponding
      channels.  Except for channels using Safety Sequence, this applies
      regardless of the current state of the Reactor: the values are
      applied even if the Reactor or channels are set to use Safe
      Values.  As soon as these conditions are removed, the values are
      used as long as no timeout occurs.  Channels using Safety Sequence
      MUST discard any values sent to them unless they are set to use
      Current Values and have no other prohibitive states.  This flag is
      valid for Output and InOut channels only.
      It's value is "bit 14".


   Sentence Options for messages to the PSI Master:

   These Sentence Options are valid in messages sent to the PSI Master.
   Contrary to those coming from the PSI Master, and except for being
   combined with a channel number definition, they are mutually
   exclusive because they define the meaning of generic Words.

   Words contain Current Values: PSI_SO_TM_VINFO

      This flag means that the Words in this sentence contain the
      Current Values of the respective channels.
      It's value is "bit 31".


   Words contain Safe Values: PSI_SO_TM_SVINFO

      This flag means that the Words in this sentence contain the Safe
      Values for the respective channels.  A Reactor must only send
      these values when requested, to minimize chances for erroneously
      applying incorrect values.  Therefore the PSI Master must check



Ertl                    Expires November 24, 2010              [Page 45]

Internet-Draft       Protocol for Stage Illumination            May 2010


      that there actually are pending requests (PSI_SO_FM_SVREQ) for the
      channels listed, that have not yet timed out, and otherwise
      discard the values.
      It's value is "bit 30".


   Words contain Data Type information: PSI_SO_TM_DTINFO

      This flag means that the Words in this sentence contain the data
      types used by the channels listed.  These need to be known before
      values can be sent or received.
      It's value is "bit 29".


   Words contain Channel Type information: PSI_SO_TM_CTINFO

      This flag means that the Words in this sentence contain the types
      of the channels listed.  These need to be known before values can
      be sent or received.
      It's value is "bit 28".


   Words contain data boundary information: PSI_SO_TM_DBINFO

      This flag means that the Words in this sentence contain the
      boundaries of the channels listed.  These should be known before
      values are sent or received.
      In order to prevent proliferation of Word types, the same types as
      used for data values are used.  Therefore for each channel, two
      data Words of the same type are sent consecutively within the same
      sentence, both containing the channel number.  The first Word
      contains the minimum value and the second one contains the maximum
      value in the value syllable.  The overhead created by sending the
      channel number a second time is tolerable because this kind of
      sentence is used only upon initialization of the Nexus and thus
      does not impact normal operation.
      It's value is "bit 27".


   Defines channel numbers to be 8 bit: PSI_SO_FM_CN8

      This bit defines the size of all channel numbers in the sentence
      to be 8 bit in size.  It may only be used in conjunction with
      Words actually containing channel numbers, and must not be
      combined with any other channel number definition.
      It's value is "bit 26".





Ertl                    Expires November 24, 2010              [Page 46]

Internet-Draft       Protocol for Stage Illumination            May 2010


   Defines channel numbers to be 16 bit: PSI_SO_TM_CN16

      This bit defines the size of all channel numbers in the sentence
      to be 16 bit in size.  It may only be used in conjunction with
      Words actually containing channel numbers, and must not be
      combined with any other channel number definition.
      It's value is "bit 25".


   Defines channel numbers to be 32 bit: PSI_SO_TM_CN32

      This bit defines the size of all channel numbers in the sentence
      to be 32 bit in size.  It may only be used in conjunction with
      Words actually containing channel numbers, and must not be
      combined with any other channel number definition.
      It's value is "bit 24".


   Defines channel numbers to be 64 bit: PSI_SO_TM_CN64

      This bit defines the size of all channel numbers in the sentence
      to be 64 bit in size.  It may only be used in conjunction with
      Words actually containing channel numbers, and must not be
      combined with any other channel number definition.
      It's value is "bit 23".


   Maximum message length information: PSI_SO_TM_MMSINFO

      This flag is valid only in conjunction with a Word of type
      PSI_Word_Node_Specification, that contains the maximum message
      length of the Reactor.  A PSI Master MUST NOT send messages larger
      than that to the Reactor, but may send any size below.  Even
      though not normally necessary, the Reactor MAY change this during
      normal operation, usually after user configuration changes.  In
      that case, it MUST set the status PSI_RS_REREAD_ALL so the PSI
      Master will request the information anew.
      The maximum message length SHOULD be at least around 1400 bytes,
      but MAY be significantly larger.
      It's value is "bit 22".


   Word contains Reactor type: PSI_SO_TM_RTINFO

      This flag means that the Word in this sentence contains the type
      of the Reactor.  This needs to be known before values can be sent
      or received.
      It's value is "bit 21".



Ertl                    Expires November 24, 2010              [Page 47]

Internet-Draft       Protocol for Stage Illumination            May 2010


   Words contain Group information: PSI_SO_TM_GIDINFO

      This flag means that the Words in this sentence contain the GIDs
      that currently are assigned to the Reactor.  These need to be
      known before broadcast or multicast messages can be sent.
      It's value is "bit 20".


   Words containing vendor specific information: PSI_SO_TM_VSINFO

      This flag means that the Words in this sentence contain vendor
      specific information; the sentence type is either PSI_ST_TM_WT or
      PSI_ST_TM_WT.
      It's value is "bit 19".


   Words containing user specific information: PSI_SO_TM_USINFO

      This flag means that the Words in this sentence contain user
      specific information; the sentence type is either PSI_ST_TM_WT or
      PSI_ST_TM_WT.
      It's value is "bit 18".

3.7.7.  Sentence types

   The sentence type defines the type of the Words that the sentence
   consists of.

   Sentence types for messages from a PSI Master:

   Sentence of boolean Data Words: PSI_ST_FM_WDB

      This type identifies a sentence consisting of Words of type
      PSI_Word_DataB.
      It's value is (PSI_ST_BASE_FM+0).


   Sentence of signed 8 bit Data Words: PSI_ST_FM_WDS8

      This type identifies a sentence consisting of Words of type
      PSI_Word_DataS8.
      It's value is (PSI_ST_BASE_FM+1).


   Sentence of unsigned 8 bit Data Words: PSI_ST_FM_WDU8

      This type identifies a sentence consisting of Words of type
      PSI_Word_DataU8.



Ertl                    Expires November 24, 2010              [Page 48]

Internet-Draft       Protocol for Stage Illumination            May 2010


      It's value is (PSI_ST_BASE_FM+2).


   Sentence of signed 16 bit Data Words: PSI_ST_FM_WDS16

      This type identifies a sentence consisting of Words of type
      PSI_Word_DataS16.
      It's value is (PSI_ST_BASE_FM+3).


   Sentence of unsigned 16 bit Data Words: PSI_ST_FM_WDU16

      This type identifies a sentence consisting of Words of type
      PSI_Word_DataU16.
      It's value is (PSI_ST_BASE_FM+4).


   Sentence of signed 32 bit Data Words: PSI_ST_FM_WDS32

      This type identifies a sentence consisting of Words of type
      PSI_Word_DataS32.
      It's value is (PSI_ST_BASE_FM+5).


   Sentence of unsigned 32 bit Data Words: PSI_ST_FM_WDU32

      This type identifies a sentence consisting of Words of type
      PSI_Word_DataU32.
      It's value is (PSI_ST_BASE_FM+6).


   Sentence of signed 64 bit Data Words: PSI_ST_FM_WDS64

      This type identifies a sentence consisting of Words of type
      PSI_Word_DataS64.
      It's value is (PSI_ST_BASE_FM+7).


   Sentence of unsigned 64 bit Data Words: PSI_ST_FM_WDU64

      This type identifies a sentence consisting of Words of type
      PSI_Word_DataU64.
      It's value is (PSI_ST_BASE_FM+8).








Ertl                    Expires November 24, 2010              [Page 49]

Internet-Draft       Protocol for Stage Illumination            May 2010


   Sentence of floating-point Data Words: PSI_ST_FM_WDFP

      This type identifies a sentence consisting of Words of type
      PSI_Word_DataFP.
      It's value is (PSI_ST_BASE_FM+9).


   Sentence of double floating-point Data Words: PSI_ST_FM_WDDFP

      This type identifies a sentence consisting of Words of type
      PSI_Word_DataDFP.
      It's value is (PSI_ST_BASE_FM+10).


   Sentence of quadruple floating-point Data Words: PSI_ST_FM_WDQFP

      This type identifies a sentence consisting of Words of type
      PSI_Word_DataQFP.
      It's value is (PSI_ST_BASE_FM+11).


   Sentence of one opaque Data Word with variable length: PSI_ST_FM_WDO

      This type identifies a sentence consisting of at most one Word
      with variable length of type PSI_Word_Data_Opaque.
      It's value is (PSI_ST_BASE_FM+12).


   Sentence of one plain Data Word with variable length: PSI_ST_FM_WDP

      This type identifies a sentence consisting of at most one Word
      with variable length of type PSI_Word_Data_Plain.
      It's value is (PSI_ST_BASE_FM+13).


   Sentence of generic 32 bit Data Words: PSI_ST_FM_WG32

      This type identifies a sentence consisting of Words of type
      PSI_Word_Generic_32.
      It's value is (PSI_ST_BASE_FM+14).


   Sentence without content: PSI_ST_FM_WN

      This type identifies a sentence containing no Words.  It's main
      purpose is for debugging.
      It's value is (PSI_ST_BASE_FM+15).




Ertl                    Expires November 24, 2010              [Page 50]

Internet-Draft       Protocol for Stage Illumination            May 2010


   Sentence of Channel Numbers: PSI_ST_FM_WCN

      This type identifies a sentence consisting of Words of type
      PSI_Word_Channel_Number.  It' value is (PSI_ST_BASE_FM+16).


   Sentence of one Text Data Word with variable length: PSI_ST_FM_WT

      This type identifies a sentence consisting of at most one Word
      with variable length of type PSI_Word_Text.
      It's value is (PSI_ST_BASE_TM+17).


   Sentence types for messages to a PSI Master:

   Sentence of boolean Data Words: PSI_ST_TM_WDB

      This type identifies a sentence consisting of Words of type
      PSI_Word_DataB.
      It's value is (PSI_ST_BASE_TM+0).


   Sentence of signed 8 bit Data Words: PSI_ST_TM_WDS8

      This type identifies a sentence consisting of Words of type
      PSI_Word_DataS8.
      It's value is (PSI_ST_BASE_TM+1).


   Sentence of unsigned 8 bit Data Words: PSI_ST_TM_WDU8

      This type identifies a sentence consisting of Words of type
      PSI_Word_DataU8.
      It's value is (PSI_ST_BASE_TM+2).


   Sentence of signed 16 bit Data Words: PSI_ST_TM_WDS16

      This type identifies a sentence consisting of Words of type
      PSI_Word_DataS16.
      It's value is (PSI_ST_BASE_TM+3).


   Sentence of unsigned 16 bit Data Words: PSI_ST_TM_WDU16

      This type identifies a sentence consisting of Words of type
      PSI_Word_DataU16.
      It's value is (PSI_ST_BASE_TM+4).



Ertl                    Expires November 24, 2010              [Page 51]

Internet-Draft       Protocol for Stage Illumination            May 2010


   Sentence of signed 32 bit Data Words: PSI_ST_TM_WDS32

      This type identifies a sentence consisting of Words of type
      PSI_Word_DataS32.
      It's value is (PSI_ST_BASE_TM+5).


   Sentence of unsigned 32 bit Data Words: PSI_ST_TM_WDU32

      This type identifies a sentence consisting of Words of type
      PSI_Word_DataU32.
      It's value is (PSI_ST_BASE_TM+6).


   Sentence of signed 64 bit Data Words: PSI_ST_TM_WDS64

      This type identifies a sentence consisting of Words of type
      PSI_Word_DataS64.
      It's value is (PSI_ST_BASE_TM+7).


   Sentence of unsigned 64 bit Data Words: PSI_ST_TM_WDU64

      This type identifies a sentence consisting of Words of type
      PSI_Word_DataU64.
      It's value is (PSI_ST_BASE_TM+8).


   Sentence of floating-point Data Words: PSI_ST_TM_WDFP

      This type identifies a sentence consisting of Words of type
      PSI_Word_DataFP.
      It's value is (PSI_ST_BASE_TM+9).


   Sentence of double floating-point Data Words: PSI_ST_TM_WDDFP

      This type identifies a sentence consisting of Words of type
      PSI_Word_DataDFP.
      It's value is (PSI_ST_BASE_TM+10).


   Sentence of quadruple floating-point Data Words: PSI_ST_TM_WDQFP

      This type identifies a sentence consisting of Words of type
      PSI_Word_DataQFP.
      It's value is (PSI_ST_BASE_TM+11).




Ertl                    Expires November 24, 2010              [Page 52]

Internet-Draft       Protocol for Stage Illumination            May 2010


   Sentence of one opaque Data Word with variable length: PSI_ST_TM_WDO

      This type identifies a sentence consisting of at most one Word
      with variable length of type PSI_Word_Data_Opaque.
      It's value is (PSI_ST_BASE_TM+12).


   Sentence of one plain Data Word with variable length: PSI_ST_TM_WDP

      This type identifies a sentence consisting of at most one Word
      with variable length of type PSI_Word_Data_Plain.
      It's value is (PSI_ST_BASE_TM+13).


   Sentence of generic 32 bit Data Words: PSI_ST_TM_WG32

      This type identifies a sentence consisting of Words of type
      PSI_Word_Generic_32.
      It's value is (PSI_ST_BASE_TM+14).


   Sentence without content: PSI_ST_TM_WN

      This type identifies a sentence containing no Words.  It's main
      purpose is for debugging.
      It's value is (PSI_ST_BASE_TM+15).


   Sentence of Channel Numbers: PSI_ST_TM_WCN

      This type identifies a sentence consisting of Words of type
      PSI_Word_Channel_Number.
      It's value is (PSI_ST_BASE_TM+16).


   Sentence of one Text Data Word with variable length: PSI_ST_TM_WT

      This type identifies a sentence consisting of at most one Word
      with variable length of type PSI_Word_Text.
      It's value is (PSI_ST_BASE_TM+17).


   Sentence of one Reactor status Word of variable length:
   PSI_ST_TM_WRS

      This type identifies a sentence consisting of at most one Word
      with variable length of type PSI_Word_Reactor_Status.
      It's value is (PSI_ST_BASE_TM+18).



Ertl                    Expires November 24, 2010              [Page 53]

Internet-Draft       Protocol for Stage Illumination            May 2010


   Sentence of channel status Words: PSI_ST_TM_WCS

      This type identifies a sentence consisting of Words of type
      PSI_Word_Channel_Status.
      It's value is (PSI_ST_BASE_TM+19).


   Sentence of one Safety Sequence Word of variable length:
   PSI_ST_TM_WSS

      This type identifies a sentence consisting of at most one Word
      with variable length of type PSI_Word_Safety_Sequence.
      It's value is (PSI_ST_BASE_TM+20).


   Sentence of Channel Counts: PSI_ST_TM_WCC

      This type identifies a sentence consisting of Words of type
      PSI_Word_Channel_Count.
      It's value is (PSI_ST_BASE_TM+21).


   Sentence of generic Node Specification Words: PSI_ST_TM_W_N_S

      This type identifies a sentence consisting of Words of type
      PSI_Word_Node_Specification.
      It's value is (PSI_ST_BASE_TM+22).


   Sentence of generic Channel Specification Words: PSI_ST_TM_W_C_S

      This type identifies a sentence consisting of Words of type
      PSI_Word_Channel_Specification.
      It's value is (PSI_ST_BASE_TM+23).

3.7.8.  Detailed Reactor Status

   This section describes the detailed status as sent via
   PSI_Word_Reactor_Status by the Reactor.

   Reactor status OK: PSI_RS_OK

      This constant means that there are no issues.  It must not be
      combined with others.
      It's value is 0.






Ertl                    Expires November 24, 2010              [Page 54]

Internet-Draft       Protocol for Stage Illumination            May 2010


   Reactor uses Safe Values due to lack of data: PSI_RS_SAFE

      This constant means that the PSI Master has not yet sent a value
      for all channels, so the Reactor still uses Safe Values for these
      channels.  All other channels are already using the Current
      Values.
      It's value is 1.


   Reactor uses Safe Values due to a timeout: PSI_RS_TO_SAFE

      This constant means that no values have been received for too
      long, resulting in a timeout: the Reactor has switched to Safe
      Values.  The PSI Master must send PSI_NO_FM_GODATA to the Reactor
      to change this status.
      It's value is 2.


   Reactor uses Safe Values due to an overshoot: PSI_RS_OS_SAFE

      This constant means that values have been received that are
      outside a channel's boundaries: the Reactor has switched to Safe
      Values.  The PSI Master must send PSI_NO_FM_GODATA to the Reactor
      to change this status.
      It's value is 3.


   Reactor uses Safe Values due to request: PSI_RS_SET_SAFE

      This constant means that the PSI Master has requested the Reactor
      to switch it's channels to Save Values (see PSI_NO_FM_GODATA).  If
      no new values arrive, a timeout will occur in addition.  The PSI
      Master must send PSI_NO_FM_GODATA to change this status.
      It's value is 4.


   Software error occurred: PSI_RS_SWFAIL

      This constant means that the Reactor has encountered a software
      problem that may affect it's functionality.  This does not include
      problems in channels.
      It's value is 5.


   Hardware error occurred: PSI_RS_HWFAIL

      This constant means that the Reactor has encountered a hardware
      problem that may affect it's functionality.  This does not include



Ertl                    Expires November 24, 2010              [Page 55]

Internet-Draft       Protocol for Stage Illumination            May 2010


      problems in channels.
      It's value is 6.


   Problem with some channels: PSI_RS_CHANNELS

      This constant means that one or more channel is faulty.  The PSI
      Master needs to query each channel's status to see which channels
      report which problems.
      It's value is 7.


   Overheat condition: PSI_RS_OVERHEAT

      This constant means that the Reactor has overheated and reduced
      function as much as possible.  If the condition is allowed to
      persist, the Reactor MAY optionally develop hardware damage or
      switch off, so communication may cease at any time.
      It's value is 8.


   PSI Master uses incorrect data types: PSI_RS_REREAD_DT

      At least one channel is being fed using an incorrect data type so
      the data cannot be used.  The PSI Master must correct the problem,
      possibly requiring (re-)reading of the data types.
      It's value is 9.


   Reactor configuration changed: PSI_RS_REREAD_ALL

      This constant means that changes have been made to the Reactor
      that may have invalidated information previously queried.
      Therefore the Reactor has switched to Safe Values, and the PSI
      Master must re-read all information.  This may occur, for example,
      when channels are added, removed or swapped.  As long as the PSI
      Master has not queried the data anew, no data are accepted.
      It's value is 10.

3.7.9.  Channel status

   This section describes channel status values.  They are binary
   constants intended to be put into the channel status bit field of the
   Word PSI_Word_Channel_Status.  If the status of a channel changes to
   anything non-OK, then the Reactor status must reflect this by adding
   PSI_RS_CHANNELS.  Also, if there is a change, the flag
   PSI_NO_TM_SUNCH must be cleared.




Ertl                    Expires November 24, 2010              [Page 56]

Internet-Draft       Protocol for Stage Illumination            May 2010


   Channel status OK: PSI_CS_OK

      If this flag is set, then the channel works normally.
      It's value is "bit 15".


   The channel uses Safe Value due to lack of data: PSI_CS_SAFE

      If this flag is set, then the channel has not yet been fed a value
      and therefore is using it's Save Value.
      It's value is "bit 14".


   The channel uses Safe Value due to timeout: PSI_CS_TO_SAFE

      If this flag is set, then the channel has not been fed data for a
      while, so a timeout occurred and the channel has switched to it's
      Safe Value.
      It's value is "bit 13".


   The channel uses Safe Value due to value overshoot: PSI_CS_OS_SAFE

      If this flag is set, then the channel has been fed values outside
      it's boundaries, so it has switched to it's Safe Value.  It's
      value is "bit 12".


   The channel uses Safe Value due to request: PSI_CS_SET_SAFE

      If this flag is set, then the channel has been switched to it's
      Safe Value.  It's value is "bit 11".


   Software error: PSI_CS_SWFAIL

      If this flag is set, then the channel is faulty due to a software
      problem.
      It's value is "bit 10".


   Hardware error: PSI_CS_HWFAIL

      If this flag is set, then the channel is faulty due to a hardware
      problem.
      It's value is "bit 9".





Ertl                    Expires November 24, 2010              [Page 57]

Internet-Draft       Protocol for Stage Illumination            May 2010


   Overheat condition: PSI_CS_OVERHEAT

      If this flag is set, then the channel has overheated and reduced
      functionality as much as possible.  If the condition persists, the
      channel may develop hardware failure.
      It's value is "bit 8".


   Channel does not exist: PSI_CS_VIRTUAL

      If this flag is set, then the channel does not physically exist.
      This is no error: it merely indicates that no physical channel has
      been assigned to a logical one.
      It's value is "bit 7".


   Channel status unknown: PSI_CS_UNKNOWN

      If this flag is set, then the channel hardware has no way of
      checking it's functioning, so it's status is not known.  If this
      is the case, PSI_CS_OK MUST NOT be returned.
      It's value is "bit 6".

3.7.10.  Reactor types

   This section describes the constants for the different Reactor types.

   Output Reactor: PSI_RT_OUTPUT

      This constant means that the Reactor possesses only Output
      channels, not generating any data.  This is the most common
      Reactor type like dimmers single spots LASER systems, pyro
      effects, etc..  Output channels always allow reading of their
      Current Values.
      It's value is 0.


   Input Reactor: PSI_RT_INPUT

      This constant means that the Reactor possesses only Input
      channels, generating data but not consuming any.  Reactors of this
      kind include touch boards, fader panels, etc..
      It's value is 1.








Ertl                    Expires November 24, 2010              [Page 58]

Internet-Draft       Protocol for Stage Illumination            May 2010


   Combined Input and Output Reactor: PSI_RT_INOUT

      This constant means that the Reactor possesses both Input and
      Output channels.  Reactors of this type may be non-transparent
      bidirectional protocol converters, sensor/actor combinations,
      etc..  Output Reactors always allow reading back their values, so
      they do not belong to this type.  Reactors having only channels of
      type PSI_CT_NONE also do not belong to this type.
      It's value is 2.


   Reactor without function: PSI_RT_NONE

      This constant means that the Reactor possesses only channels of
      type PSI_CT_NONE or no channels at all.  Reactors of this type may
      be testing equipment like protocol analyzers that are able to
      connect to a PSI Master but do not generate or consume channel
      data.
      It's value is 3.

3.7.11.  Channel types

   This section describes the constants representing the channel types.

   Output channel: PSI_CT_OUTPUT

      This constant means that the channel consumes data and outputs
      them in some way.  Most channels are of this type, like dimmer
      channels or control channels of foggers.  Channels of this type
      always allow reading out their Current Values.
      It's value is 0.


   Input channel: PSI_CT_INPUT

      This constant means that the channel creates data, for example in
      a fader panel.
      It's value is 1.


   Combined Input- and Output channel: PSI_CT_INOUT

      This constant means that the channel both creates and consumes
      data.  Because it also outputs values, it MUST have a Safe Value
      that can be read by the PSI Master in the usual way.  Because pure
      Output channels always allow reading out their Current Values,
      they do not belong to this type.
      It's value is 2.



Ertl                    Expires November 24, 2010              [Page 59]

Internet-Draft       Protocol for Stage Illumination            May 2010


   Channel without function: PSI_CT_NONE

      This constant means that the channel has no function, and can
      neither consume nor create data.  This type may be used for
      testing; logical channels that are not assigned to a physical
      channels may also have this type.  Data sent to channels of this
      kind will be discarded, queries for Safe Values, etc. get ignored.
      It's value is 3.


   Channel using Safety Sequence: PSI_CT_SAFETY

      This constant means that the channel controls something that
      requires extra safety measures; erroneous changes must be avoided
      at nearly all costs.  This may be a pyro effect, a LASER
      controller, high-voltage effects, motors, etc..  It requires
      correct reception of a sequence of 32 bit values to accept data.
      The sequence required may be queried using PSI_SO_FM_SSREQ.  Any
      Reactor containing channels of this type MUST ensure safety if at
      all possible whenever it receives a query about it's properties
      (like data type and even vendor information), because that
      indicates that the PSI Master does not (anymore) know how to
      access that channel, and therefore whatever value it currently
      uses may be invalid and thus potentially dangerous.
      It's value is 4.

3.8.  Dynamics

   This section describes the dynamical behavior of PSI.  Only those
   components relevant to the discussion are looked at; for a complete
   list, refer to Section 3.

   Note that if a message requests information, the reply must be sent
   as soon as possible: the node should not wait for possible further
   requests that might allow conglomeration of replies.  However, if
   there already are replies that have not yet been sent, then the node
   may do such conglomeration.  In any case, the replies generated last
   MUST be placed behind the previous ones, so that the sequence will
   always be retained.  This is especially important if for some reason
   values for the same channel are put into the same message, since
   otherwise outdated values would be mistaken for the most recent ones.
   If the same request is received more than once, and the previous
   requests have not yet been processed, then only the most recent one
   needs to be processed.  However, a node must not wait to see if there
   may be duplicate requests.

   The periodic status inquiries are an exception to the above: the PSI
   Master may delay sending of these requests for some tenths of seconds



Ertl                    Expires November 24, 2010              [Page 60]

Internet-Draft       Protocol for Stage Illumination            May 2010


   if no other messages, to which the requests could be added, are ready
   to be sent.  However, the Reactors must still reply immediately.

3.8.1.  Discovery Phase

   The use of Reactor-specific channel numbers and the resulting
   explicit addressing of individual Reactors necessitates that the PSI
   Master be informed about every single Reactor in the Nexus.  Since,
   however, the Reactors also do not know about the PSI Master, neither
   side can contact the other directly to create that knowledge.
   Because of that, the broadcast mechanism is used.  After the PSI
   Master starts up, it will send messages of type PSI_MT_FM_DISCOVERY
   for a while (this SHOULD be between two seconds and one minute, but
   implementations MAY allow the user to change these settings).  During
   this time, it does not reply to any messages coming from the
   Reactors.  The large number of messages sent ensures that every
   Reactor that can be reached will receive at least one.  Through
   reception of the Discovery message from the PSI Master, Reactors are
   informed that the PSI Master does not yet know about them, so they
   must inform it about themselves.  Because the Discovery message
   contains the PSI Master's IN, the Reactors can identify the specific
   PSI Master in case there are more than one; the PSI Master's IP
   address is delivered as well, so it can be used for subsequent
   messages.

   Upon reception of a message of type PSI_MT_FM_DISCOVERY, a Reactor
   MUST start sending messages of type PSI_MT_TM_DISCOVERY.  These
   messages are sent to the PSI Master as normal unicast, until it
   acknowledges their reception.  To avoid having one Reactor clog the
   network, a Reactor SHOULD wait between 10 and 100 milliseconds
   between sending each such message.

   After sending the Discovery messages, the PSI Master SHOULD wait
   between two and ten seconds (it MAY allow the user to configure other
   times), while it receives and acknowledges replies from Reactors.
   Because a possibly huge amount of messages may have been generated,
   resulting in massive packet loss, this timeout is reset whenever a
   reply is received.  This way, all Reactors will eventually be
   acknowledged.  The Discovery Phase ends when no replies have been
   received for the specified time.
   The acknowledgements sent by the PSI Master are messages of type
   PSI_MT_FM_NORMAL, PSI_MT_FM_MULTICAST or PSI_MT_FM_BROADCAST,
   containing at least one Node Section that has the flag
   PSI_NO_FM_REACTOR_ACCEPTED set (this MUST be set in the first Node
   Section for the respective Reactor).  By using the multicast or
   broadcast types, multiple Reactors can be acknowledged using a single
   message.  Additionally, all elements that are available during normal
   operation may be used as well, so the acknowledgement message may be



Ertl                    Expires November 24, 2010              [Page 61]

Internet-Draft       Protocol for Stage Illumination            May 2010


   used to request information or to send data.  It must be noted,
   however, that due to the remaining Reactors that have not yet been
   acknowledged and therefore are still sending Discovery messages,
   messages may get dropped.  Therefore, it usually is advisable to only
   request information after the Discovery Phase has finished.
   Network latency can make the PSI Master receive a Reactor's Discovery
   message after the Reactor has received an acknowledgement by the PSI
   Master.  Because the PSI Master can not know if the Reactor actually
   received the acknowledge or not, it must send an acknowledge whenever
   it receives a Discovery message.  The Reactor must therefore be
   prepared to handle this, for example by discarding previous or excess
   acknowledgements.

   The result is "at least once" semantics.  Every message is
   idempotent, so that the entire process can be restarted by either
   side at any time, while the number of (identical) messages received
   by either side has no influence on the outcome.

   Because the PSI Master ceases sending Discovery messages before
   starting to acknowledge any Reactors, and alternate routes should not
   exist, a Reactor will not normally receive a Discovery message after
   an acknowledgement.  Regardless, every Reactor MUST start sending
   Discovery messages whenever it receives a Discovery message from a
   PSI Master.  This is required because the PSI Master may have been
   restarted, or the Discovery Phase may have been triggered for other
   reasons.

   Whenever a Reactor is (re)started, it MUST begin sending Discovery
   messages in a similar way as when it has received a Discovery message
   from a PSI Master.  Since the Reactor does not yet know the PSI
   Master, it must send these messages as broadcast.  Whenever a PSI
   Master receives such a message, it MUST acknowledge it in the normal
   way.  By doing so, Reactors that appear during normal operation can
   be taken care of.
   Whenever a Reactor has not received any messages from the PSI Master
   for at most two minutes (this may be user-configurable), it may try
   sending unicast Discovery messages to the IP address last used by the
   PSI Master.  If that is not known, or the PSI Master does not reply
   during that time, the Reactor MUST revert to sending broadcast
   Discovery messages, because the PSI Master's IP address may have
   changed (the unicast step MAY be skipped).  This may happen when the
   PSI Master has been restarted, and completed it's Discovery Phase,
   while it or the Reactor were disconnected from the network.  This
   method allows for that, so the Reactor will be taken care of after
   the connection has been reestablished.

   This way, all nodes can be relatively certain that, in case one gets
   restarted, the respective partner knows that the connection needs to



Ertl                    Expires November 24, 2010              [Page 62]

Internet-Draft       Protocol for Stage Illumination            May 2010


   be recreated.  It cannot be 100% reliably be ensured if one takes
   into account that restarts may get masked by certain combinations of
   cabling disconnects and duplicated, old packets, but even then there
   is no real problem, because the IN is unique.  If two or more
   Reactors receive swapped IP addresses after a restart, and the PSI
   Master erroneously sends messages to the wrong Reactor, this will be
   noticed by the receiving Reactor because it's IN does not match the
   TIN from the message.  In the simplest case, it will just ignore the
   entire message, so the PSI Master will not receive any replies and
   regard the Reactor as lost.  The erroneously contacted Reactor MAY
   also start sending Discovery messages to the PSI Master after a while
   to alert it of the swap, or the PSI Master MAY send Discovery
   messages to Reactors that don't respond.  In any case it is ensured
   that no incorrect data are used.

   Reactors do not send a reply after receiving the acknowledgement from
   the PSI Master; they just cease sending Discovery messages.  This
   means that the PSI Master does not know if the Reactor has received
   the acknowledgement, or if it was disconnected or has failed.
   However, this information is automatically gathered later, by way of
   the periodic status inquiries.


   Note: whenever a Reactor sends Discovery messages, it MUST conform to
   the interval mentioned above.

3.8.2.  Initialization Phase

   After the Discovery Phase has completed, an Initialization Phase
   starts.  It is used to query information about all Reactors that have
   been discovered.
   Every Reactor is characterized by a number of properties describing
   it's function and uses.  The PSI Master sends a number of queries to
   the Reactor to collect this information.  All such information may be
   queried in a single message, or be distributed across several
   messages, possibly containing data sent to the Reactor.  The sequence
   of the queries may be chosen arbitrarily, as well as whether to wait
   for each reply before sending the next query or not.  Also, as
   described in Section 3.7, some need not be queried in all cases.  The
   individual queries are:


   1.   Reactor type

   2.   Reactor status

   3.   vendor specific information




Ertl                    Expires November 24, 2010              [Page 63]

Internet-Draft       Protocol for Stage Illumination            May 2010


   4.   user specific information

   5.   channel counts

   6.   channel types

   7.   data formats

   8.   data boundaries

   9.   maximum message length

   10.  Safe Values

   11.  channel status


   Especially with Reactors having many channels, replies to one or more
   queries may need to be split into multiple messages.  It is within
   the Reactor's discretion to decide in which way to do this, so parts
   of different replies may be conglomerated into a single message.  The
   PSI Master must thus be prepared to re-request any part of the
   required information that may have been lost in transit.

   Reactors MUST reply to all of these requests, but may decide wether
   to combine multiple replies or not.

   When all information is known to the PSI Master, the Initialization
   Phase has completed.

   Note that Reactors that appear during normal operation MUST also be
   queried in this way.  The PSI Master MAY flag them in any way
   convenient.

3.8.3.  Normal Operation

   Periodic status inquiries  In order to always be informed about the
      status of the Reactors in the Nexus, the PSI Master must query
      their status periodically.  The interval SHOULD NOT be made
      smaller than about 1 to 2 Hz, because the information is evaluated
      by the user, resulting in much larger latency, but SHOULD be
      configurable.  This way, the network is not overly burdened by
      these inquiries.  Since these queries can easily be added to
      messages that need to be sent regardless, the overhead can be
      further reduced.  Since nearly all Reactors are expected to
      receive data or queries at a much smaller interval, almost no
      extra messages will need to be sent to accommodate this.  On the
      other hand, a Reactor MUST NOT delay replies to status inquiries



Ertl                    Expires November 24, 2010              [Page 64]

Internet-Draft       Protocol for Stage Illumination            May 2010


      in order to combine them with another message, but MAY do so,
      within length limits, if there is a message pending for sending
      already.  This may be convenient if pre-arbitration (not discussed
      in this memo) is employed to schedule messages sent to the PSI
      Master.  If no message is pending for sending, a dedicated message
      must be sent.


   Data messages  This is the most common form of communication, as data
      messages are the core intention of this protocol.  The goal is to
      reach the highest refresh rate possible, so data must be sent as
      soon as possible.  Especially, a node must not wait for data to be
      generated before sending what has already been generated.  This
      does however not mean that a message must be sent for each channel
      of a Reactor.  Actually, a node must strive to minimize the number
      of messages sent by packing data for as many channels as possible
      into every message, for example by arranging data generation or
      consumption in a way that ensures data can be sent and received at
      any time.
      However, the maximum message length may be dynamically adjusted to
      reach the lowest net data loss if the network proves unreliable.
      In that case, the node may distribute data for any Reactor's
      channels across multiple messages, but keeping identical data
      logically ordered is still sensible.  This is because using a
      single Word type message saves the overhead of requiring multiple
      Sentence Headers, reducing message size and therefore probability
      for errors, as well as bandwidth needed.  In such a case,
      multicast and broadcast messages also should contain data for
      fewer nodes than theoretically possible, in favor of smaller size.
      Loss feedback methods are not discussed as part of this memo,
      however.  An implementation MAY allow the user to set a maximum
      message length that best suits their network.
      A data message itself does not require a reply, but may be
      combined with requests.


   Data requests  If no pre-arbitration is performed, data generated by
      Input and InOut Reactors must be explicitly requested by the PSI
      Master (polling).  As before, the objective is a refresh rate that
      is as high as possible.  Therefore it is imperative to request
      data from all channels of any specific Reactor at once.  This way
      ensures that network latency is experienced only once per
      direction and Reactor.  As with data messages, an unreliable
      network may make splitting requests, and subsequently, replies,
      into multiple messages in favor of smaller size preferable.
      Data requests MUST always be replied to immediately, but MAY be
      combined with other messages if such messages are about to be sent
      already.  Waiting for additional requests is not allowed.  An



Ertl                    Expires November 24, 2010              [Page 65]

Internet-Draft       Protocol for Stage Illumination            May 2010


      implementation MAY allow the user to set a maximum message length
      that best suits their network.


   Information messages  An information message includes anything that
      are not channel data, like data types or GID assignments.  They
      are therefore not merely "informational", as the name might
      suggest.  Information messages usually appear during
      initialization of the Nexus, and therefore their impact on network
      performance is small during normal operation.  They do not require
      acknowledgement, but may be combined with requests.  They must be
      sent immediately, waiting for more information to be requested is
      not allowed.


   Information requests  This includes anything that is neither a data
      request nor a periodic status inquiry, like requests for data
      types, Safe Values or Reactor type.  Being the main cause of
      information messages, they also appear mostly during Nexus
      initialization, rendering their influence on network performance
      small.  They may be combined with other information or data
      messages, but replies still MUST be sent immediately.  Therefore,
      it is advisable to send all information requests for any specific
      Reactor within a single message to reduce the number of messages
      that have to be sent.  However, if the network is very unreliable,
      a higher number of smaller messages may be preferable even for
      this kind of messages.


   Lost nodes  Whenever a node does not receive replies (like periodic
      status inquiries) after 40 attempts, then the node must be
      considered as "lost".  This will happen if the node has failed, is
      turned off or disconnected from the network.  This applies to both
      Reactors and PSI Masters.


   Timeouts  Whenever a Reactor does not receive data messages from the
      PSI Master, it MUST switch all channels to Safe Values.  The time
      used for the timeout MUST be chosen according to the potential
      harm caused by the most dangerous channel of the Reactor, but
      SHOULD NOT be more than one second in any case.  For dimmers, for
      example, this timeout is not critical, as they might cause fire
      only after some minutes, if at all.  A LASER unit, especially if
      it does audience scanning, is much more critical, so the timeout
      time must follow local safety regulations unless other measures
      are put into place.

      If a single channel doesn't receive values anymore, then it, too,



Ertl                    Expires November 24, 2010              [Page 66]

Internet-Draft       Protocol for Stage Illumination            May 2010


      must switch to it's Safe Value just like an entire Reactor.  This
      also applies to channels using the Safety Sequence, that MUST be
      cancelled upon timeout.

      Like any other channel, a channel using Safety Sequence times out
      if it does not receive new values.  However, contrary to any other
      channel, this status is normal for an inactive channel using
      Safety Sequence: data for such channels needs to only be sent when
      the channel's value is supposed to change to or remain as anything
      possibly non-safe.  Upon timeout, such a channel MUST therefore
      immediately cease operation and assure safety if at all possible.
      Only correctly received and matching parts of the Safety Sequence
      keep it from timing out.

      If a PSI Master doesn't receive values from an Input or InOut
      channel or Reactor anymore, then it SHOULD set all channels that
      are controlled partially or in full by those channels to use Safe
      Values, especially if they use the Safety Sequence.  In any case,
      use of Input or InOut channels to control safety-critical channels
      is not recommended, as values may be kept longer than they are
      valid.


4.  Discussion

   As described in Section 3.1, a device independent data representation
   had to be chosen.  The following options have been considered:

   o  ASN.1 (Abstract Syntax Notation, version 1) uses explicit typing.
      Each element is prepended with an unique identifier and length
      information, enabling the receiver to correctly receive and decode
      any message without knowledge of it's structure.  The disadvantage
      is the additional overhead for transferring these metadata, which
      in case of the length may be up to 127 bytes (though usually one
      byte suffices for the length).  The flexibility gained through
      explicitly encoding the type and length of each datum sent is not
      useful for PSI, because PSI defines all messages and their
      structure, meaning that if both sender and receiver conform to the
      PSI specification, an implicitly typed representation is perfectly
      sufficient.  In fact, ASN.1 is mostly used for formal
      specifications instead of actual communication due to reasons like
      these.  While ASN.1 offers data types of any size, down to a mere
      8 bit, through the explicit typing and length bytes, this becomes
      at least three bytes when encoded as single data.


   o  CDR (Common Data Representation, [CORBA-CDR]) is used in CORBA and
      defines a single format for every primitive type, but two endian



Ertl                    Expires November 24, 2010              [Page 67]

Internet-Draft       Protocol for Stage Illumination            May 2010


      representations that can be chosen by the sender.  Therefore,
      every receiver must be prepared to byte-swap if needed.  CDR
      offers data types down to 8 bit like ASN.1, without the overhead
      of explicit typing and length fields wherever possible, but
      requires data types to start at an aligned position matching their
      own size, with a few exceptions.  This means overhead of a couple
      of bytes if a large data type follows smaller types that sum up to
      less than the alignment restriction of the larger type.

      However, some implementations, like the one of The Ace Orb
      ([TAO]), already offer the option to turn off alignment
      restrictions.  This unaligned CDR therefore is like XDR but with
      data types down to 8 bit in all cases.


   o  NDR (Network Data Representation) does not specify a single format
      definition.  Instead it allows the sender to choose one and uses a
      Format Label to convey the type selected.  Every receiver
      therefore has to provide all possible conversions, placing a
      significant burden on the implementor.  Because in PSI every node
      is both sender and receiver, this burden would be placed on every
      single implementation.  While this offers a speed advantage when
      similar hardware is communicating, PSI will encounter a highly
      heterogeneous environment, negating that advantage for the most
      part.  NDR offers data types down to 8 bit like ASN.1, without the
      overhead of explicit typing and length fields wherever possible,
      but requires alignment of data types to their own size.
      Especially for the 8 bit Word types, this means overhead of a
      couple of bytes each.


   o  XDR (eXternal Data Representation, [RFC4506]) is used in a number
      of over-the-wire protocols.  Like in ASN.1, the data are
      transferred as big endian.  Contrary to ASN.1, XDR uses implicit
      typing and length like NDR, meaning that the receiver has to know
      beforehand which data type to expect next, but also resulting in
      less message and processing overhead.  Contrary to NDR, it
      specifies a single format for all data types, so only one set of
      converters needs to be created.  However, XDR requires 32 bit as
      smallest block size, so an 8 bit datum occupies 32 bit when
      encoded.  This clearly wastes space, but can speed up encoding and
      decoding and ease implementation.

   Since PSI uses a well-defined message format, lack of explicit typing
   and length information poses no problem, so the overhead created by
   ASN.1 would not be justified.  While 8 bit data are the most common
   size at this time, ASN.1's advantage in this respect would be nearly
   negated because PSI uses explicit channel numbers.  Because they are



Ertl                    Expires November 24, 2010              [Page 68]

Internet-Draft       Protocol for Stage Illumination            May 2010


   interspaced with the data values, every 8 bit datum would have to be
   encoded as three bytes, so PSI would not actually benefit much from
   the smaller data types.  While PSI could have been designed to create
   contiguous ranges by, for example, specifying the channel numbers in
   one array and the data values in another, the added complexity would
   make PSI less easy to use, and a part of the flexibility aimed for
   would be lost.  Additionally, this would only be feasible when the
   Nexus consists of Reactors that actually have a significant number of
   similar channels each, since otherwise separate messages or at least
   separate sentences would be required, with each containing the entire
   ASN.1 overhead.

   CDR would, minus the alignment restrictions, clearly be the optimum
   choice regarding transfer efficiency, which is comparatively
   important, while the option of selecting endianness may or may not be
   viewed as a benefit.  NDR is very similar, but it's cumbersome
   requirement of providing converters for a number of different
   representations per data type hinders easy development and creates
   larger probability for errors.  ASN.1 may use Packed Encoding Rules
   (PER), but still would be less efficient than CDR, requires use of a
   special toolchain and PER is rather complex, creating even more
   possibility for error.  XDR has the advantage of easy usability,
   topped up with availability: the runtime libraries required for
   ASN.1, CDR and NDR may be a portability issue, while XDR's
   comparatively simple implementations are present and readily
   available on platforms using libc and even [micro]Clibc.  However,
   the presence of BSD-style open-source CDR implementations, along with
   the proliferation of CORBA implementations furthering CDR
   implementations on all major platforms means that adaptation issues
   are comparatively low.

   In the end, unaligned CDR was chosen above the other options: it is
   available and significantly more bandwidth efficient than XDR.  The
   bandwidth available from a typical, switched 100 Mbit network will
   suffice for a Nexus larger than two DMX universes even without use of
   any optimizations like Groups and Clusters, while maintaining a
   higher refresh rate even under the worst-case assumption that every
   single channel has an associated Reactor and thus requires an entire
   message for a single value.  Similarly, 10 Gbit Ethernet will support
   a Nexus larger than 200 DMX universes, still at a higher refresh
   rate, over a single cable.

   Of course, even without explicit typing done by the transfer syntax,
   a minimum of meta data still needs to be sent to identify the
   messages and their contents for flexibility.  This results in a
   hybrid approach, which is somewhat similar to what is discussed in
   section 5 (6) of [RFC4506].  It still allows for (comparatively)
   efficient utilization of the media while not sacrificing flexibility



Ertl                    Expires November 24, 2010              [Page 69]

Internet-Draft       Protocol for Stage Illumination            May 2010


   to any significant degree.



5.  Refresh rate

   When running across a fully switched, 100 base T Ethernet, the PSI
   can achieve a worst-case refresh rate of over 110 Hz for 1000
   channels.  Compared to DMX this is about doubling both refresh rate
   and channel count at the same time.  By using higher-level protocol
   functions like Groups, this can be increased to over 450 Hz with
   Groups of 20 Reactors each.

   The assumption for these values is that every Reactor only contains
   exactly one channel, so that the entire overhead, including that of
   lower levels, is required for every single channel.  If, under the
   same conditions as above, every Reactor hosts merely two channels,
   the refresh rate increases to over 850 Hz.  Even though Input
   Reactors require two messages per refresh, assuming 100 Input
   Reactors of ten channels each, in Groups of five Reactors, refresh
   rates of over 700 Hz can be reached.  Of course, instead of
   increasing the refresh rate, more channels can be added to the Nexus.
   With Gigabit Ethernet or faster being the norm, these figures
   increase appropriately.

   Also, this comparison equates a DMX channel to a PSI channel, so the
   data and channel number size is 8 bits.  If larger data sizes are
   used, then the comparative performance rises accordingly, but in
   reality most channels will use 8 bit resolution.  Likewise, if larger
   channel numbers are used, then performance drops accordingly.
   A large part of the loss of raw data efficiency compared to DMX is of
   course due to the protocol overhead that provides PSI with it's
   vastly increased flexibility, and to the lower layers (UDP, IP and
   Ethernet), that account for 66 bytes of overhead by themselves.  Even
   so, a single 100 Mbit link suffices for most installations.



6.  Routing Considerations

   The reliance on broadcasts for specific functions of this protocol
   implies that care must be taken when routers are employed.  In normal
   environments, the presence of routers is neither required nor
   recommended, but appropriate addressing schemes may allow broadcasts
   to cross the routers.  See [RFC1812] and [RFC2644] for details.
   Reactors MUST be configurable to use unicast only, necessitating the
   entering of a fixed PSI Master address.  The PSI Master should be
   designated the highest IP address in the given subnet by default,



Ertl                    Expires November 24, 2010              [Page 70]

Internet-Draft       Protocol for Stage Illumination            May 2010


   allowing Reactors to meaningfully default the unicast discovery
   target to this address without reconfiguration.
   Additionally, nodes MAY implement the use of directed broadcasts for
   discovery, specifying a set of subnets that discovery messages are to
   be broadcast to.


7.  Security Considerations

   This protocol is intended for use in a tightly controlled environment
   without publicly accessible connection points only.  If a connection
   to external networks like the Internet exists, it is expected to be
   protected by appropriate measures like firewalling, that block all
   PSI related traffic in both directions.  This assumption is
   reasonable given that the control wiring (rigging) is done outside of
   the audience's reach, and it may be assumed that the personnel with
   access to the rigging is reasonably trusted.  Likewise, operations
   using this type of installation have no need for external
   connectivity on the production devices.
   Similarly, the environment described is a low-risk target that would
   neither yield sensitive information when penetrated nor allow
   significant damage to be dealt when taken over or sabotaged.
   Additionally, implementing security measures, even as simple as plain
   text passwords, would impair quick installation, exchanging of
   devices and automatic discovery, that are central features of the
   PSI.  The cost of adding such security measures would therefore be
   unacceptably high compared to the rather low risk of attacks.
   Therefore, no provisions are made for confidentiality, authentication
   or other security measures.  Blind Denial of Service attacks are
   possible by sending Discovery messages of the FM type.  If the
   attacker can send these messages as broadcast, one such message
   causes every Reactor to keep sending Discovery messages, and this
   will both multiply and keep going because the attacker will not
   acknowledge any such message.  Additionally, an attacker might
   overflow the Reactor's list of PSI Masters by posing as more PSI
   Masters than it can hold.  This requires reception of the Discovery
   messages however, so due to the routing restrictions listed in
   Section 6 the attacker would need to be situated on the same network.
   Should this protocol be required to span an unsafe network, existing
   security technologies like IPSec MUST be used.  Depending on the
   actual security technology employed, the routing considerations in
   Section 6 may or may not apply in this case.

   While the Safety Sequence capability of the PSI requires an attacker
   to be able to receive messages in order to maliciously activate the
   devices, is not intended to safeguard against attacks; it is meant to
   protect against transmission errors, hardware or software failure,
   and misconfiguration.  It is further noted that current controllers



Ertl                    Expires November 24, 2010              [Page 71]

Internet-Draft       Protocol for Stage Illumination            May 2010


   for this application may, in theory, be compromised as well, though
   the general availability of compatible networking devices, that is
   one of the strengths of this protocol, and the expected proliferation
   of unobserved connection points creates a much easier target than the
   comparatively direct wiring of a conventional controller.


8.  IANA Considerations

   This protocol requires the assignment of two port numbers: one for
   the default PSI Master discovery reception port and one for the
   Reactor discovery reception port.  Two distinct ports are necessary
   so that both PSI Master and Reactor may run as separate applications
   on the same IP address.

   The ports assigned must be above 1023 so that the PSI does not
   require special privileges to be used.  While only UDP is used for
   this protocol, the corresponding TCP ports might be assigned as well
   so that the management / control protocol that may be created at a
   later date will not require a new assignment.  Currently, ports 7911
   (short name: PSI/Reactor) and 4919 (short name: PSI/Master) are used.


9.  References

9.1.  Normative References

   [CORBA-CDR]
              Object Management Group, OMG., "Common Object Request
              Broker Architecture (CORBA) Specification, Version 3.1 -
              Part 2: CORBA Interoperability, section 9.3: CDR Transfer
              Syntax", January 2008.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", RFC 2119, BCP 14, March 1997.

   [RFC3629]  Yergeau, F., "UTF-8, a transformation format of ISO
              10646", RFC 3629, STD 63, November 2003.

9.2.  Informative References

   [DMX512-A]
              ESTA, ESTA., "Entertainment Technology - USITT DMX512-A -
              Asynchronous Serial Digital Data Transmission Standard for
              Controlling Lighting Equipment and Accessories", 2004.

   [RFC1812]  Baker, F., "Requirements for IP Version 4 Routers",
              RFC 1812, STD 1, June 1995.



Ertl                    Expires November 24, 2010              [Page 72]

Internet-Draft       Protocol for Stage Illumination            May 2010


   [RFC2644]  Senie, D., "Changing the Default for Directed Broadcasts
              in Routers", RFC 2644, BCP 34, August 1999.

   [RFC4506]  Eisler, M., "XDR: External Data Representation Standard",
              RFC 4506, STD 67, May 2006.

   [TAO]      Schmidt, D., "The Ace Orb Home Page", June 2007,
              <http://www.cs.wustl.edu/~schmidt/TAO.html>.


Author's Address

   Marcus Ertl
   Ertl Software Productions
   An Peschbenden 13
   47906 Kempen, NRW
   DE

   Email: marcus.ertl@gmx.net
   URI:   http://ertl-industries.de/































Ertl                    Expires November 24, 2010              [Page 73]


