Please add documentation for the private fields present for all topics in the HTML generated from ts_xml. Please also document the ackcmd topic. None of these are defined in the XML, so this documentation will have to be manually created and maintained.
The following descriptions are my own understanding and are how ts_salobj uses them (though users can set the public fields of the ackcmd topic as they like). Anyone should feel free to correct me if I am mistaken. I have added Dave Mills, Tiago Ribeiro, and Rob Bovill as watchers for this reason.
I suggest that the private fields be documented in one place (even though they are present for all topics) to avoid needless repetition. But do as you think best. The private fields, which are present on all topics are:
- private_sndStamp: time at which the sample was sent (TAI, unix seconds).
- private_rcvStamp: time at which the sample was received (TAI, unix seconds).
- private_identity: For a CSC this has the form <SAL component name>[:index] e.g. "Script:5" or "ATDome". For a user this has the form username@host. This field is used for authorization. New in ts_sal 4.2.
- private_origin: the process ID of the writer.
- private_host: the host address of the writer. This is deprecated, and due to be removed in ts_sal 5.
- private_seqNum: for commands this uniquely identifies the command (within a reasonable timespan, since the value must eventually wrap around). For other kinds of topics this may be incremented for each sample, though that is optional.
- <SAL component name>ID e.g. ScriptID (only present for indexed SAL components): the SAL index of the writer.
The ackcmd topic is how commands are acknowledged. Note that there is just one ackcmd topic that is used to acknowledge all commands. The public fields and one private field of the ackcmd topic are as follows:
- private_seqNum: the private_seqNum of the command being acknowledged.
- ack: the acknowledgement code, one of the CMD_ constants, such as CMD_COMPLETE = 303 or CMD_FAILED = -302.
- error: the error code. Set to a nonzero value if ack=CMD_FAILED.
- result: salobj sets this to an error message if ack=CMD_FAILED. I am not sure if it is used for anything else.
- identity: the private_identity of the command being acknowledged (see below).
- host: the private_host of the command being acknowledged. private_host is deprecated, so this field is also deprecated, and both should be gone in ts_sal 5.
- origin: the private_origin of the command being acknowledged, which is a process ID.
- cmdtype: command identifier: I believe this is supposed to be the 0-based index of the command in an alphabetical list of all topics for that SAL component. That is surprising to me as the list includes all topics, not just command topics. I hope I am wrong, but if so, I need to fix it in ts_salobj.
- timeout: the approximate expected duration of the command. Only set if ack=CMD_INPROGRESS.
I am not sure if you want to also explain the acknowledgement sequence here. It should certainly be documented somewhere, and this might be a nice place for it. As a quick reminder:
- The initial ack code is CMD_ACK when the command is read.
- If the command will take a long time to run then the CSC should respond with a CMD_INPROGRESS ack that includes an estimate of the command duration. This should only happen after the command has been approved.
- Usually the next ack is the final one for this command and is typically one of:
- CMD_COMPLETE if the command finishes successfully.
- CMD_FAILED if the command fails.
- CMD_NOPERM if the command issuer is not authorized to send the command.
- CMD_ABORTED if the command is superseded.
- CMD_TIMEOUT is returned if the command issuer times out waiting for command completion. Note that it is the issuer, not the CSC, that returns this. If the command times out inside the CSC then the ack code is CMD_FAILED. In particular note that if the issuer gives up waiting for command completion and then the command finishes, the user will only see the CMD_TIMEOUT ack, but the DDS system will see the final ack from the CSC.
- There are at least two other CMD_ codes as well:
- CMD_NOACK: ts_salobj sets the ackcmd field of AckTimeoutError to this value if no CMD_ACK was seen for the command before the command timed out. I am not sure how non-salobj systems use this code.
- CMD_STALLED: I think the intent is to indicate "this is going more slowly than I expected, but I am still working on it." I am not sure which systems use this code.
Here is how the ackcmd topic shows up in an IDL file. This also shows the data types of the private fields: