------
Update for ts_sal v4. This version cannot communicate with ts_sal v3 or ts_salobj v4 because of changes at the DDS level:
* The ``ackcmd`` topic has new fields that distinguish acknowledgements for commands sent by one `Remote` from those sent by another.
* Command topics and the ``ackcmd`` topic now have ``volatile`` durability instead of ``transient``.
This means they cannot read late-joiner data, which eliminates a source of potential problems from stale commands or command acknowledgements.
* The DDS queues now hold 100 samples instead of 1000.
Another backward incompatible change is that the setSimulationMode command can no only be issued in the STANDBY state.
This makes it much easier to implement simulation mode in CSCs that connect to external controllers,
because one can make the connection in the appropriate mode when in DISABLED or ENABLED state, without having to worry about changing it.
This change may break some existing unit tests for CSCs that support simulation mode.
Deprecated APIs:
* Specifying ``code=None`` for `BaseCsc.fault` is deprecated. Please always specify an error code so the ``errorCode`` event can be output.
* `BaseCsc.main` and `BaseScript.main` are deprecated. Please replace ``cls.main(...)`` with ``asyncio.run(cls.amain(...))``.
This makes it much clearer that the call may not return quickly, avoids explicitly creating event loops, and takes advantage of the (new to Python 3.7) preferred way to run asynchronous code.
* Setting ``BaseCsc.summary_state`` is deprecated.
In unit tests use the standard state transition commands or call the `set_summary_state` function.
In CSCs you should not be setting summary state directly; of the existing CSC code I've seen,
most of it sends the CSC to a FAULT state, for which you should call `BaseCsc.fault`,
and the rest doesn't need to set the summary state at all.
* Script commands ``setCheckpoints`` and ``setLogLevel`` are deprecated.
Specify checkpoints and log level using the new ``pauseCheckpoint``, ``stopCheckpoint`` and ``logLevel`` fields in the ``configure`` command.
* Code that constructs a `Remote` or `Controller` without a running event loop should be rewritten because it will break when we replace the remaining usage of `asyncio.ensure_future` with the preferred `asyncio.create_task`. For example:
.. code-block:: python
csc = MyCscClass(...)
asyncio.get_event_loop().run_until_complete(csc.done_task)
can be replaced with (see `BaseCsc.make_from_cmd_line` to add command-line arguments):
.. code-block:: python
asyncio.run(MyCscClass.amain(...))
New capabilities:
* Add function `current_tai` to return the current time in TAI unix seconds (LSST's standard for SAL timestamps).
* Enhance function `tai_from_utc` to support alternate formats for UTC using new argument ``format="unix"``.
* Add `topics.ReadTopic.aget` to return the current sample, if any, else wait for the next sample (DM-20975).
* Add coroutine ``BaseCsc.handle_summary_state``.
This is the preferred way to handle changes to summary state instead of overriding synchronous method `BaseCsc.report_summary_state`.
* Add property ``BaseCsc.disabled_or_enabled`` which returns true if the current summary state is `State.DISABLED` or `State.ENABLED`.
This is useful in ``BaseCsc.handle_summary_state`` to determine if you should start or stop a telemetry loop.
* Add ``result_contains`` argument to `assertRaisesAckError`.
* Enhance `topics.ControllerCommand` automatic acknowledgement for callback functions so that the ``ack`` value is `SalRetCode`.CMD_ABORTED if the callback raises `asyncio.CancelledError` and `SalRetCode`.CMD_TIMEOUT if the callback raises `asyncio.TimeoutError`.
* `Controller.start` now waits for all remotes to start (except those constructed with ``start=False``, which is rare).
* Added ``start_called`` attribute to `SalInfo`, `Controller` and `Remote`.
Other improvements:
* Fix support for environment variable ``LSST_DDS_IP``.
The value is now a dotted IP address; formerly it was an integer.
* Improve error handling when specifying a non-zero index for a non-indexed SAL component (DM-20976).
The `SalInfo` constructor will now raise an exception.
* Improve error handling in `BaseCsc.fault`. Report the problem and continue if the error code is not an integer, or if `BaseCsc.report_summary_state` fails.
* The unit tests use the ``asynctest`` package, which is pip installable.
* The documentation for `BaseCsc.main` now recommends specifying ``index=None or 0`` for non-indexed components, instead of ``None or False``, in order to match standard usage in ts_salobj.
All three values worked, and continue to work, but no existing code used `False`.
* Minor improvements to version handling:
* Set ``lsst.ts.salobj.__version__`` to "?" if running directly from source and there is no ``version.py`` file generated by ``setup.py`` or ``scons``.
* Update ``doc/conf.py`` to get ``__version__`` from ``lsst.ts.salobj`` instead of ``lsst.ts.salobj.version``.
* Stop reading dead topics because ts_sal 4 no longer disposes of any samples immediately after writing.
This removes a workaround added in v4.3.0.
* Add this revision history.
Existing code is unlikely to require any changes to transition from salobj v4 to v5.
Communicates with ts_sal v4.
Requirements:
* ts_idl
* IDL files for Test and Script
* SALPY_Test generated by ts_sal v4 (for unit tests)