[Docs]: Add basic sphinx API docs for ISO11783-7 interfaces

Open-Agriculture · Mar 1, 2024 · 9dba6b4 · 9dba6b4
1 parent eb5b8c1
commit 9dba6b4
Show file tree

Hide file tree

Showing 7 changed files with 102 additions and 0 deletions.
diff --git a/sphinx/source/api/implement messages/guidance.rst 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -12,6 +12,7 @@ AgIsoStack++ project.
    network/index
    virtual terminal/index
    task controller/index
+   implement messages/index
 
 .. note::