PRT files / PRT file format
This page has been automatically translated and has not been reviewed in detail yet. Therefore, the translation might not be completely accurate.
Introduction
The communication protocols of most hardware devices, whether serial or network connected, are proprietary and not standardized.
A PRT protocol is a text file that makes it possible to establish a connection to the device connected to the PC or a network switch via the RS232 or TCP/IP or UDP interface.
The PRT file format was specifically developed to specify in NRN what types of technical commands can be exchanged with devices over the network. These commands (actions and events) are sent back and forth as ASCII strings.
Use of PRTs in NRN
Creating PRTs
PRT files can be defined in the Setup module in the Device Protocols tab:
Except for the "header" with control instructions (previously only for serial devices), the COMMANDS and EVENTS are of course the decisive factor. This “header” is only briefly mentioned here at the moment.
In principle, there are "Key: Value" lines, whereby they are arbitrary and only a few are used permanently, for example to be able to generate a "protocol name".
In the header, semicolons at the end of the line are optional - but otherwise necessary (for historical reasons).
Comments can be added by "//" for the rest of the line.
The blocks "COMMANDS:" and "EVENTS:" are introduced exactly by this respective heading. In the following lines the iSy+ syntax (iSMaster):
COMMAND/[PARAMETER TYPE]/.../[PARAMETER TYPE]
or.
EVENT/[PARAMETER TYPE]/.../[PARAMETER TYPE]
linked to ascii or hex data (the bytes that are sent or received). With COMMAND it is defined how the parameters are inserted into the data, with EVENT how they are extracted from it. In the implementation for NeuroomNet, of course, not iSMaster commands/events are used, but NeuroomNet actions and events (there is no difference in the format of the file, only in the internal processing).
Data can only be defined as hex data if it is constant (i.e. no parameters are used), e.g. E.g.:
PowerOn = 0x506f7765724f6e;
PowerOff = 0x506f7765724f6666;
Upper/lower case should not matter.
At that time, this status was the starting point for further development.
Asciidates, on the other hand, must be used when there are parameters. They should be enclosed in quotation marks. Strictly speaking, the first and last characters simply have to be the same. This was originally intended so that "quotes" could also appear in the string without an escape. Maybe it will read better then. In fact, quotes do not need to be treated particularly within quotation marks (the beginning and end are simply removed if they are equal).
You can also enter arbitrary characters in asciid data, which are then introduced with "\x" and must be encoded in hexadecimal. This then only has to be exactly one character. The result of the above example is identical to this one:
PowerOn = "\x50\x6f\x77\x65\x72\x4f\x6e";
PowerOff = "\x50\x6f\x77\x65\x72\x4f\x66\x66";
Therefore, "\x" cannot be sent like this. Instead, you would have to use at least the Ascii code (0x5c) for "\" and thus specify it as "\x5c". But this has never been necessary before.
Parameters are determined from the master command by distribution to the "/". NeuroomNet also uses parameters in an analogous manner.
[STRING] and [INTEGER] are supported. There were rudimentary implementations for [FLOAT] and [BOOL] in iSCom, which were also incorporated into the Javascript implementation and improved. However, in both cases they have never been used productively and have therefore only been tested little. There has never been a need for it over the years. Therefore, the two cases are currently left out below.
The parameters are counted from left to right starting from 1. In NeuroomNet they are also called “p1”, etc.
Each parameter may only be used once in the asciid data. This is certainly sufficient in the vast majority of cases. If not, you would simply give the command definition an additional parameter and ensure that the master or NeuroomNet uses the same value twice.
The parameters are then referred to as "\<no>" - the same applies to the literal use of "\1" etc. as to "\x" above. Since according to the scheme the parameter number must be single-digit, currently no more than 10 parameters are possible, where "\0" corresponds to the 10th. More than 4-5 parameters have never been needed so far.
The "\<no>" is followed by a format specification. This can be:
- a for ascii
- b for binary, little endian
- B for binary, big endian
- h for hexascii, little endian
- H for hexascii, big endian
There was also an "x" for "hexascii hexascii" (double) - that would have been helpful for a single exotic protocol, but was developed later and therefore never used and not tested productively (- This is only a comment for the part in Source code).
In iSCom it was more or less enforced that the parameters in the master and in the translation are used in the same order (ultimately numbered in ascending order). In the new implementation you can also swap them. This may only be necessary for special applications, for example if you want to fix a bug in a firmware only in the protocol without making any changes to the master script/NeuroomNet.
For [STRING] only the format "a" is permitted, for [INTEGER] all are supported.
After the format specification comes a length in bytes (theoretically up to 255, since the length not only indicates bytes, but is also only one byte).
This may be a bit confusing and perhaps there are better solutions. You learn something new in 14 years...
The point is that in binary, for example, a 128 would be encoded with \1b01, while for hexascii \1h01 would also be correct, but would be output as "80" (2 bytes). \1h02 would result in "8000" (and \1H02 would result in "0080").
The following applies when sending
If the format specification is 'a', the length specification 0 is possible, otherwise not. 0 then means "automatic": 1:1 and as much as necessary.
If the length specification for strings is greater than 0, the left is padded with spaces. Numbers are preceded by '0's depending on their length.
Of course, 'b' and 'B' or 'h' and 'H' only differ if the length is greater than 1. In these cases, binary 0s or "00" are padded to the right or left.
If the specified length is not possible (e.g. because 256 does not fit in \1b01), there should be a runtime error when sending. What to do with it still needs to be clarified. If you send it directly, it will certainly be displayed in the “Toast”, but what happens within the media control?!
Applies to receiving
An Ascii string should be viewed similarly to a regex (regular expression) (it is actually implemented that way) - here as a simple pattern that is implemented internally.
This means that the length specification 00 must always be filled with meaning using delimiters (possibly also the beginning and/or end). Lengths greater than 0 are used in the corresponding size. If the lengths of the parameters in the protocol are set to finite values, you can work with length and/or limiters (e.g. with "*" for Extron).
In many cases, if asciid data is "incorrectly" defined (e.g. if lengths and delimiters do not allow recognition), no event is simply triggered. The data is discarded. But if e.g. For example, if a piece of data cannot be converted into a number after recognition (because text was read according to the pattern), a TypeError exception is triggered internally. What happens to it at some point (easily ignored or lied to) may still need to be clarified.
Other protocol components are
TOX: <number>
Delay in milliseconds when sending to avoid flooding end devices with too many commands - not yet implemented!
ETX: <hex or ascii string>
End-of-text for separating data packets - not necessary with UDP
STX: <hex or ascii string>
Start-of-Text for separating data packets - not necessary with UDP
STX and ETX can also occur together depending on the protocol. You can even use a string like 0x0d0a or "\x0d\x0a" here. It should be noted that, particularly for historical reasons, but also for reasons of flexibility, this information will not be sent before or after the data to be sent. This must be stated explicitly in the COMMANDS.
There is currently an intended incompatibility with iSCom: STX/ETX is not allowed to be included in the EVENTS translation. It has to be here. This is intended to ensure better consistency (with COMMANDS) and readability/comparison (with protocol definitions)!
The STX/ETX information is therefore only used to configure the separation of data packets.
GOAL: <number>
Timeout when receiving - especially without STX and ETX or only with STX, after the time specified in milliseconds without received data(!), the data packet collected up to that point is passed on to the parser.
With UDP this is not necessary (because complete data packets are always transmitted individually).
The definition of COMMANDS and EVENTS can be followed by the ";" an explanatory text (help) must be added, which can also be started with ";" must be completed, but may not contain any. Otherwise bad things can happen ;-)
Preferences header
- MANUFACTURER: BrightSign - Manufacturer of the device
- PROTOCOL: NeuroomNetUDP - protocol name
- DEVICE: BrightSignPlayer - device name
- UNIQUEID: NrN-BS-47526 - Ideally an abbreviation with a random component,
- VERSION: v0.1 - Version of the PRT file
- COM_PARAM: 115200;8;No;1;No; - must be present, even with UDP
- DATE: 03/08/2022 12:00:00 - year, month, day and time of creation
- EDITOR: inSynergie - Creator (company) of the PRT file
- DESCRIPTION: Standard BrightSign UDP protocol for NeuroomNet
- INTREVISION: 1.0 - Always 1.0
Notes on Unique ID
If this is NOT present, ANY change to the file will be considered incompatible and ALL existing references (actions/events) will be INVALID.
To ensure that there are no duplications and confusions in the actions, the unique IDs should contain a random component (e.g. a hash value of the file or an excerpt from the creation time in milliseconds).
The Unique ID should not be longer than 10-15 characters so that it can be displayed correctly in other places (actions of the components).
The unique ID and thus the PRT protocol used for a component can also be viewed in the description of the actions:
