From 9dba6b4a8f765ce3cda53622f2d3273696ea6e28 Mon Sep 17 00:00:00 2001 From: Adrian Del Grosso <10929341+ad3154@users.noreply.github.com> Date: Thu, 29 Feb 2024 17:59:25 -0700 Subject: [PATCH] [Docs]: Add basic sphinx API docs for ISO11783-7 interfaces --- .../api/implement messages/guidance.rst | 25 +++++++++++++++++++ .../api/implement messages/heartbeat.rst | 14 +++++++++++ .../source/api/implement messages/index.rst | 17 +++++++++++++ .../api/implement messages/maintain power.rst | 15 +++++++++++ .../api/implement messages/shortcut.rst | 21 ++++++++++++++++ .../api/implement messages/speed distance.rst | 9 +++++++ sphinx/source/api/index.rst | 1 + 7 files changed, 102 insertions(+) create mode 100644 sphinx/source/api/implement messages/guidance.rst create mode 100644 sphinx/source/api/implement messages/heartbeat.rst create mode 100644 sphinx/source/api/implement messages/index.rst create mode 100644 sphinx/source/api/implement messages/maintain power.rst create mode 100644 sphinx/source/api/implement messages/shortcut.rst create mode 100644 sphinx/source/api/implement messages/speed distance.rst diff --git a/sphinx/source/api/implement messages/guidance.rst b/sphinx/source/api/implement messages/guidance.rst new file mode 100644 index 000000000..447b0c925 --- /dev/null +++ b/sphinx/source/api/implement messages/guidance.rst @@ -0,0 +1,25 @@ +.. _API Guidance: + +ISOBUS Guidance API +=================== + +The guidance API is an interface for sending and receiving ISOBUS guidance messages. +These messages are used to steer ISOBUS compliant machines, steering valves, and implements in general. + + +.. warning:: + + Please use extreme care if you try to steer a machine with this interface! + Remember that this library is licensed under The MIT License, and that by obtaining a + copy of this library and of course by attempting to steer a machine with it, you are agreeing + to our license. + +.. note:: + These messages are expected to be deprecated or at least made redundant in favor + of Tractor Implement Management (TIM) at some point by the AEF, though the timeline on that + is not known at the time of writing this, and it's likely that many machines will + continue to support this interface going forward due to its simplicity over TIM. + This project is not affiliated with the AEF, and the AEF has not endorsed this project. + +.. doxygenclass:: isobus::AgriculturalGuidanceInterface + :members: diff --git a/sphinx/source/api/implement messages/heartbeat.rst b/sphinx/source/api/implement messages/heartbeat.rst new file mode 100644 index 000000000..fb14d6133 --- /dev/null +++ b/sphinx/source/api/implement messages/heartbeat.rst @@ -0,0 +1,14 @@ +.. _API Heartbeat: + +ISOBUS Heartbeat API +==================== + +The heartbeat message (PGN 61668/0xF0E4) is used to determine the integrity of the communication of messages and parameters being transmitted by a control function. +There may be multiple instances of the heartbeat message on the network, and CFs are required transmit the message on request. +As long as the heartbeat message is transmitted at the regular time interval and the sequence number increases through the valid range, then the heartbeat message indicates that the data source CF is operational and provides correct data in all its messages. + +.. note:: + This interface is enabled by default, but can be disabled if you want to stop your heartbeat(s) or don't care about the safety-critical path of the machine. + +.. doxygenclass:: isobus::HeartbeatInterface + :members: diff --git a/sphinx/source/api/implement messages/index.rst b/sphinx/source/api/implement messages/index.rst new file mode 100644 index 000000000..0e2a14e50 --- /dev/null +++ b/sphinx/source/api/implement messages/index.rst @@ -0,0 +1,17 @@ +.. _API ImplementMessages: + +Implement Messages Application Layer +==================================== + +AgIsoStack++ contains a number of interfaces that are meant to simplify the messages defined in ISO11783-7 for communication between a tractor and implement. +These include the following: + +.. toctree:: + :maxdepth: 1 + :titlesonly: + + heartbeat + guidance + maintain power + shortcut + speed distance diff --git a/sphinx/source/api/implement messages/maintain power.rst b/sphinx/source/api/implement messages/maintain power.rst new file mode 100644 index 000000000..5fae93d1d --- /dev/null +++ b/sphinx/source/api/implement messages/maintain power.rst @@ -0,0 +1,15 @@ +.. _API MaintainPower: + +Maintain Power API +================== + +This interface provides a way to manage sending and receiving the "maintain power" message. +This message is sent by any control function connected to the implement bus and requests that the Tractor ECU (TECU) not switch off the power for 2 s after it has received the wheel-based speed and distance message indicating that the ignition has been switched off. +The message also includes the connected implement(s) operating state. +You can choose if the TECU maintains actuator power independently of ECU power as well, as an option. + +.. note:: + If you are using the library for implement section control, you might want to maintain actuator power using this interface to ensure your section valves close when keyed off. + +.. doxygenclass:: isobus::MaintainPowerInterface + :members: diff --git a/sphinx/source/api/implement messages/shortcut.rst b/sphinx/source/api/implement messages/shortcut.rst new file mode 100644 index 000000000..82903e647 --- /dev/null +++ b/sphinx/source/api/implement messages/shortcut.rst @@ -0,0 +1,21 @@ +.. _API ISB: + +ISOBUS Shortcut Button (ISB) API +================================ + +This is an interface for communicating as or from an ISOBUS shortcut button (ISB). +This functionality is defined in AEF Guideline 004 - ISB and at https://www.isobus.net (ISO 11783-7). + +You can choose to either receive this message, send it, or both. An ISB is essentially +a command to all implements to enter a safe state. See the descriptions located at +https://www.isobus.net/isobus/pGNAndSPN/?type=PGN by searching "All implements stop operations switch state", ISO 11783-7, or +https://www.aef-online.org/fileadmin/user_upload/Content/pdfs/AEF_One_Pager.pdf +for more details. + +.. warning:: + If you consume this message, you **MUST** implement an associated alarm in your + VT object pool, along with an icon or other indication on your home screen that your + working set master supports ISB, as required for AEF conformance. + +.. doxygenclass:: isobus::ShortcutButtonInterface + :members: diff --git a/sphinx/source/api/implement messages/speed distance.rst b/sphinx/source/api/implement messages/speed distance.rst new file mode 100644 index 000000000..07b641098 --- /dev/null +++ b/sphinx/source/api/implement messages/speed distance.rst @@ -0,0 +1,9 @@ +.. _API SpeedDistance: + +Speed and Distance API +====================== + +This is a collection of classes for processing and sending ISOBUS speed messages. + +.. doxygenclass:: isobus::SpeedMessagesInterface + :members: diff --git a/sphinx/source/api/index.rst b/sphinx/source/api/index.rst index 4447bb91b..ec7ad10c3 100644 --- a/sphinx/source/api/index.rst +++ b/sphinx/source/api/index.rst @@ -12,6 +12,7 @@ AgIsoStack++ project. network/index virtual terminal/index task controller/index + implement messages/index .. note::