From d82471b64f19b6cf3cf7e35fc0be4f8c44a57941 Mon Sep 17 00:00:00 2001 From: Peter Buterbaugh Date: Mon, 26 Jun 2023 12:52:20 -0400 Subject: [PATCH 1/8] Draft of #2267 fix. --- .../docs/hardware/hardware-safety/index.rst | 9 ++++ .../hardware/hardware-safety/placeholder.rst | 44 +++++++++++++++++++ source/docs/software/frc-glossary.rst | 9 ++++ source/index.rst | 1 + 4 files changed, 63 insertions(+) create mode 100644 source/docs/hardware/hardware-safety/index.rst create mode 100644 source/docs/hardware/hardware-safety/placeholder.rst diff --git a/source/docs/hardware/hardware-safety/index.rst b/source/docs/hardware/hardware-safety/index.rst new file mode 100644 index 0000000000..c1cc657950 --- /dev/null +++ b/source/docs/hardware/hardware-safety/index.rst @@ -0,0 +1,9 @@ +Hardware Safety +=============== + +This section describes some of the safety features built into the NI roboRIO Control System. + +.. toctree:: + :maxdepth: 1 + + placeholder \ No newline at end of file diff --git a/source/docs/hardware/hardware-safety/placeholder.rst b/source/docs/hardware/hardware-safety/placeholder.rst new file mode 100644 index 0000000000..431e7ef228 --- /dev/null +++ b/source/docs/hardware/hardware-safety/placeholder.rst @@ -0,0 +1,44 @@ +Placeholder for Safety Writeup +============================== + +.. Note:: From a Chief Delphi `thread reply `_ by WPILib Developer Peter Johnson. + +I/O Safety +----------- + +roboRIO Control System +^^^^^^^^^^^^^^^^^^^^^^ + +There are multiple safety mechanisms on the robot that handle input / output operations while it is powered on. + +Robot side: there are multiple hardware and software components involved. Outputs of the RoboRIO (e.g. :term:`PWM` s) are controlled by the :term:`FPGA` hardware. :term:`NetComm` is a software daemon that talks to the DS, the FPGA, and the user program. Inside of the user process \(the team\’s robot program\), there\’s a NetComm :term:`DLL` component that talks to the FPGA, CAN, and the NetComm daemon. And of course there are CAN motor controllers on the CAN bus. + +- The FPGA has a system :term:`watchdog`. This watchdog will time out and force a “disable” of PWM motor outputs if NetComm hasn\’t told it it\’s received an enable packet in the last 125 `ms`. +- The NetComm DLL in the user process will send a disable broadcast message on the CAN network and then stop sending keep-alive CAN messages after the disabled system watchdog signal is read back from the FPGA \(this is checked on a 20 `ms` loop\). REV pneumatics and motor controllers will stop immediately upon receipt of the disable broadcast. They also stop if no keep-alive is received for 100 `ms` \(pneumatics\) or 220 `ms` \(motor controllers\). +- The PWM disable works by sending a single idle pulse to the motor controller at the start of the next 20 `ms` PWM cycle after the disable condition is set, and following that, stopping output on the PWM signal line. +- When NetComm receives a control packet from the DS with enable set to true, it will immediately enable motors \(and restart the FPGA watchdog timer\). +- A count of watchdog expiration events is sent by NetComm to the DS, so this data is in the DS log. + +Software Side: + +- The DS sends a control packet to the robot every 20 `ms`. This is on a high-priority timed loop. Other loops in the DS, including the joystick and GUI loops, run at lower priority. What this means is that under poor CPU conditions or rendering delays \(e.g. large amounts of console output\), it\’s possible for the DS to have internal delay between disable being clicked, a key being hit, or joystick inputs being read to those changes being reflected in the control packets being sent to the robot. +- Control \(DS->Robot\) and status \(Robot->DS\) packets have an embedded sequence number. The DS uses these to compute round-trip-time and packet loss. A status packet that\’s returned is marked as “lost” if the RTT is greater than ~250 ms. This does not mean it was actually missing \(no response received\). The DS does keep a separate count of truly missing \(e.g. no response\) packets and disables \(starts sending control packets with enable=false\) after ~10 drops occur \(so I think this works out to ~450 ms, assuming it\’s 250+10*20\). +- High CPU / GUI delays result in the DS continuing to send packets with enable=true for a period of time until that loop is notified a disable occurs. + +Vendor Components: +^^^^^^^^^^^^^^^^^^ + +- CTRE uses a custom approach that reads the disable indicator on NetComm and stops motors within 100 `ms` of a disable. + +Potential Improvements: +^^^^^^^^^^^^^^^^^^^^^^^ + +- NetComm \(and the control protocol\) does not currently have a mechanism to detect delayed control packets. \(If it gets a control packet with enable set to true, it will enable the robot and feed the watchdog, even if that packet was sent seconds ago and delayed that much by the network\). +- DS: keyboard events should be processed at the same (or higher) thread priority as the control packet transmit loop. Or there should be an internal watchdog that tracks when the last keyboard/joystick/gui event check happened, and force disables when that expires. +- NetComm: Figure out a way to detect delayed control packets and reduce the probability of “stuttering” on sporadic enable packets. This is a hard problem in the general case, will almost certainly require a protocol change, and has some really tricky corner cases. To take one example: a radio reboot on the field will result in the first thing the robot sees being an enable packet after a period of watchdog. There probably needs to be some kind of predict time for receiving a control packet (to discard overly late ones), as well as timestamps and measured RTT provided by the DS to NetComm in control packets to provide a time sync. + +Known Issues / Potential Fault Conditions: +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- There is no upper limit to control lag. As long as packets keep arriving, they may be several seconds delayed from the DS, so a disable command from the DS would take the same amount of time to be reflected in robot operation. Once it\’s delayed, all controls, including disable/estop, will be delayed. We\’ve all seen delays increase either slowly or quickly\–the robot was controllable until it\’s suddenly much more laggy, or even been laggy from the start. +- Packet buffering / wifi retransmits of control packets result in sporadic enable packets making it to the robot after some delay. The watchdog would disable after 125 ms, but a single enable packet would re-enable motors for another 125 `ms` at a time. diff --git a/source/docs/software/frc-glossary.rst b/source/docs/software/frc-glossary.rst index b5b016fd2c..b09aac727f 100644 --- a/source/docs/software/frc-glossary.rst +++ b/source/docs/software/frc-glossary.rst @@ -131,6 +131,9 @@ FRC Glossary pose The collection of position and rotation information that describes how a rigid body is oriented in space, relative to some fixed reference point. + PWM + An acronym which stands for "Pulse Width Modulation", a method for motor controllers, sensors, and other components to transmit or receive their operational status. For motor controllers, PWM is often used to affect the power output to the motor or connected actuator. See `PWM ` on Wikipedia for more information. + RAII Resource Acquisition Is Initialization; a language behavior (in C++, but not in Java) where holding a resource is tied to object lifetime. @@ -178,3 +181,9 @@ FRC Glossary transitory In :term:`NetworkTables`, a :term:`topic` that will disappear after the last :term:`publisher` stops publishing. + + user program + In the context of the roboRIO control system, the primary FRC runtime program that handles all communication and robot operations. + + watchdog + A timer mechanism often built into embedded devices or software to monitor the runtime status of a program and reset it if crashes or errors occur. The watchdog will reset the main program if the timer itself is not reset, an activity which occurs during normal operations of the program. diff --git a/source/index.rst b/source/index.rst index 4dff0f9525..d537371a21 100644 --- a/source/index.rst +++ b/source/index.rst @@ -385,6 +385,7 @@ Community translations can be found in a variety of languages in the bottom-left docs/hardware/hardware-basics/index docs/hardware/hardware-tutorials/index + docs/hardware/hardware-safety/index docs/hardware/sensors/index .. toctree:: From 61ce242278957657c55dccac537fdada08cb35e7 Mon Sep 17 00:00:00 2001 From: Peter Buterbaugh Date: Mon, 26 Jun 2023 13:26:22 -0400 Subject: [PATCH 2/8] Should be all the changes I made to the previous fork. --- source/docs/software/frc-glossary.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/source/docs/software/frc-glossary.rst b/source/docs/software/frc-glossary.rst index b09aac727f..38a2d74eb5 100644 --- a/source/docs/software/frc-glossary.rst +++ b/source/docs/software/frc-glossary.rst @@ -53,6 +53,9 @@ FRC Glossary DHCP Dynamic Host Configuration Protocol, the protocol that allows a central device to assign unique IP addresses to all other devices. + DLL + An acronym which stands for "Dynamic-Link Library", a shared library or resource used for programs or files within the Microsoft Windows operating system. See `Dynamic-link library ` for more information. + encapsulation A software design pattern which uses a class to hide the implementation details of other classes. See `encapsulation `__ on Wikipedia for more info. @@ -116,6 +119,9 @@ FRC Glossary mutable An object that can be modified after it is created. + NetComm + A software daemon running on the NI roboRIO controller to maintain communications with the Driver Station, :term:`FPGA`, and user program. + permanent-magnet DC motor The classification of all legal motors for the FIRST robotics competition. This type of motor takes direct current as input, and uses it to create a magnetic field. In turn, this magnetic field interacts with a physical magnet to create a force that turns the output shaft. Electrical ("brushless") or mechanical ("brushed") means are used to ensure the electrically-generated magnetic field always points in a direction that creates forces when it interacts with the physical magnet, even as the motor's shaft rotates. See `permanent-magnet motor `__ on Wikipedia for more info. From e8f34aac4c9d201d37eeeb0c60451aaa9e4214ae Mon Sep 17 00:00:00 2001 From: Peter Buterbaugh Date: Mon, 26 Jun 2023 12:52:20 -0400 Subject: [PATCH 3/8] Draft of #2267 fix. --- .../docs/hardware/hardware-safety/index.rst | 9 ++++ .../hardware/hardware-safety/placeholder.rst | 44 +++++++++++++++++++ source/docs/software/frc-glossary.rst | 9 ++++ source/index.rst | 1 + 4 files changed, 63 insertions(+) create mode 100644 source/docs/hardware/hardware-safety/index.rst create mode 100644 source/docs/hardware/hardware-safety/placeholder.rst diff --git a/source/docs/hardware/hardware-safety/index.rst b/source/docs/hardware/hardware-safety/index.rst new file mode 100644 index 0000000000..c1cc657950 --- /dev/null +++ b/source/docs/hardware/hardware-safety/index.rst @@ -0,0 +1,9 @@ +Hardware Safety +=============== + +This section describes some of the safety features built into the NI roboRIO Control System. + +.. toctree:: + :maxdepth: 1 + + placeholder \ No newline at end of file diff --git a/source/docs/hardware/hardware-safety/placeholder.rst b/source/docs/hardware/hardware-safety/placeholder.rst new file mode 100644 index 0000000000..431e7ef228 --- /dev/null +++ b/source/docs/hardware/hardware-safety/placeholder.rst @@ -0,0 +1,44 @@ +Placeholder for Safety Writeup +============================== + +.. Note:: From a Chief Delphi `thread reply `_ by WPILib Developer Peter Johnson. + +I/O Safety +----------- + +roboRIO Control System +^^^^^^^^^^^^^^^^^^^^^^ + +There are multiple safety mechanisms on the robot that handle input / output operations while it is powered on. + +Robot side: there are multiple hardware and software components involved. Outputs of the RoboRIO (e.g. :term:`PWM` s) are controlled by the :term:`FPGA` hardware. :term:`NetComm` is a software daemon that talks to the DS, the FPGA, and the user program. Inside of the user process \(the team\’s robot program\), there\’s a NetComm :term:`DLL` component that talks to the FPGA, CAN, and the NetComm daemon. And of course there are CAN motor controllers on the CAN bus. + +- The FPGA has a system :term:`watchdog`. This watchdog will time out and force a “disable” of PWM motor outputs if NetComm hasn\’t told it it\’s received an enable packet in the last 125 `ms`. +- The NetComm DLL in the user process will send a disable broadcast message on the CAN network and then stop sending keep-alive CAN messages after the disabled system watchdog signal is read back from the FPGA \(this is checked on a 20 `ms` loop\). REV pneumatics and motor controllers will stop immediately upon receipt of the disable broadcast. They also stop if no keep-alive is received for 100 `ms` \(pneumatics\) or 220 `ms` \(motor controllers\). +- The PWM disable works by sending a single idle pulse to the motor controller at the start of the next 20 `ms` PWM cycle after the disable condition is set, and following that, stopping output on the PWM signal line. +- When NetComm receives a control packet from the DS with enable set to true, it will immediately enable motors \(and restart the FPGA watchdog timer\). +- A count of watchdog expiration events is sent by NetComm to the DS, so this data is in the DS log. + +Software Side: + +- The DS sends a control packet to the robot every 20 `ms`. This is on a high-priority timed loop. Other loops in the DS, including the joystick and GUI loops, run at lower priority. What this means is that under poor CPU conditions or rendering delays \(e.g. large amounts of console output\), it\’s possible for the DS to have internal delay between disable being clicked, a key being hit, or joystick inputs being read to those changes being reflected in the control packets being sent to the robot. +- Control \(DS->Robot\) and status \(Robot->DS\) packets have an embedded sequence number. The DS uses these to compute round-trip-time and packet loss. A status packet that\’s returned is marked as “lost” if the RTT is greater than ~250 ms. This does not mean it was actually missing \(no response received\). The DS does keep a separate count of truly missing \(e.g. no response\) packets and disables \(starts sending control packets with enable=false\) after ~10 drops occur \(so I think this works out to ~450 ms, assuming it\’s 250+10*20\). +- High CPU / GUI delays result in the DS continuing to send packets with enable=true for a period of time until that loop is notified a disable occurs. + +Vendor Components: +^^^^^^^^^^^^^^^^^^ + +- CTRE uses a custom approach that reads the disable indicator on NetComm and stops motors within 100 `ms` of a disable. + +Potential Improvements: +^^^^^^^^^^^^^^^^^^^^^^^ + +- NetComm \(and the control protocol\) does not currently have a mechanism to detect delayed control packets. \(If it gets a control packet with enable set to true, it will enable the robot and feed the watchdog, even if that packet was sent seconds ago and delayed that much by the network\). +- DS: keyboard events should be processed at the same (or higher) thread priority as the control packet transmit loop. Or there should be an internal watchdog that tracks when the last keyboard/joystick/gui event check happened, and force disables when that expires. +- NetComm: Figure out a way to detect delayed control packets and reduce the probability of “stuttering” on sporadic enable packets. This is a hard problem in the general case, will almost certainly require a protocol change, and has some really tricky corner cases. To take one example: a radio reboot on the field will result in the first thing the robot sees being an enable packet after a period of watchdog. There probably needs to be some kind of predict time for receiving a control packet (to discard overly late ones), as well as timestamps and measured RTT provided by the DS to NetComm in control packets to provide a time sync. + +Known Issues / Potential Fault Conditions: +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- There is no upper limit to control lag. As long as packets keep arriving, they may be several seconds delayed from the DS, so a disable command from the DS would take the same amount of time to be reflected in robot operation. Once it\’s delayed, all controls, including disable/estop, will be delayed. We\’ve all seen delays increase either slowly or quickly\–the robot was controllable until it\’s suddenly much more laggy, or even been laggy from the start. +- Packet buffering / wifi retransmits of control packets result in sporadic enable packets making it to the robot after some delay. The watchdog would disable after 125 ms, but a single enable packet would re-enable motors for another 125 `ms` at a time. diff --git a/source/docs/software/frc-glossary.rst b/source/docs/software/frc-glossary.rst index b5b016fd2c..b09aac727f 100644 --- a/source/docs/software/frc-glossary.rst +++ b/source/docs/software/frc-glossary.rst @@ -131,6 +131,9 @@ FRC Glossary pose The collection of position and rotation information that describes how a rigid body is oriented in space, relative to some fixed reference point. + PWM + An acronym which stands for "Pulse Width Modulation", a method for motor controllers, sensors, and other components to transmit or receive their operational status. For motor controllers, PWM is often used to affect the power output to the motor or connected actuator. See `PWM ` on Wikipedia for more information. + RAII Resource Acquisition Is Initialization; a language behavior (in C++, but not in Java) where holding a resource is tied to object lifetime. @@ -178,3 +181,9 @@ FRC Glossary transitory In :term:`NetworkTables`, a :term:`topic` that will disappear after the last :term:`publisher` stops publishing. + + user program + In the context of the roboRIO control system, the primary FRC runtime program that handles all communication and robot operations. + + watchdog + A timer mechanism often built into embedded devices or software to monitor the runtime status of a program and reset it if crashes or errors occur. The watchdog will reset the main program if the timer itself is not reset, an activity which occurs during normal operations of the program. diff --git a/source/index.rst b/source/index.rst index 4dff0f9525..d537371a21 100644 --- a/source/index.rst +++ b/source/index.rst @@ -385,6 +385,7 @@ Community translations can be found in a variety of languages in the bottom-left docs/hardware/hardware-basics/index docs/hardware/hardware-tutorials/index + docs/hardware/hardware-safety/index docs/hardware/sensors/index .. toctree:: From 9ddae6be4581269736f60ad9b917fac7cd2a2c0d Mon Sep 17 00:00:00 2001 From: Peter Buterbaugh Date: Mon, 26 Jun 2023 13:26:22 -0400 Subject: [PATCH 4/8] Should be all the changes I made to the previous fork. --- source/docs/software/frc-glossary.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/source/docs/software/frc-glossary.rst b/source/docs/software/frc-glossary.rst index b09aac727f..38a2d74eb5 100644 --- a/source/docs/software/frc-glossary.rst +++ b/source/docs/software/frc-glossary.rst @@ -53,6 +53,9 @@ FRC Glossary DHCP Dynamic Host Configuration Protocol, the protocol that allows a central device to assign unique IP addresses to all other devices. + DLL + An acronym which stands for "Dynamic-Link Library", a shared library or resource used for programs or files within the Microsoft Windows operating system. See `Dynamic-link library ` for more information. + encapsulation A software design pattern which uses a class to hide the implementation details of other classes. See `encapsulation `__ on Wikipedia for more info. @@ -116,6 +119,9 @@ FRC Glossary mutable An object that can be modified after it is created. + NetComm + A software daemon running on the NI roboRIO controller to maintain communications with the Driver Station, :term:`FPGA`, and user program. + permanent-magnet DC motor The classification of all legal motors for the FIRST robotics competition. This type of motor takes direct current as input, and uses it to create a magnetic field. In turn, this magnetic field interacts with a physical magnet to create a force that turns the output shaft. Electrical ("brushless") or mechanical ("brushed") means are used to ensure the electrically-generated magnetic field always points in a direction that creates forces when it interacts with the physical magnet, even as the motor's shaft rotates. See `permanent-magnet motor `__ on Wikipedia for more info. From 0ffab9c2fd71f3df56e428c01cfa0318e23b1614 Mon Sep 17 00:00:00 2001 From: Peter Buterbaugh Date: Tue, 8 Aug 2023 14:28:52 -0400 Subject: [PATCH 5/8] Few tiny changes. --- .gitignore | 3 +++ source/docs/hardware/hardware-safety/placeholder.rst | 5 ----- 2 files changed, 3 insertions(+), 5 deletions(-) diff --git a/.gitignore b/.gitignore index 6a2b230273..7992ec4f8c 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,9 @@ # Created by https://www.gitignore.io/api/linux,macos,windows,visualstudiocode # Edit at https://www.gitignore.io/?templates=linux,macos,windows,visualstudiocode +### Miscellaneous ### +.wpilib/ + ### Sphinx ### # Build directories build/ diff --git a/source/docs/hardware/hardware-safety/placeholder.rst b/source/docs/hardware/hardware-safety/placeholder.rst index 431e7ef228..e71892084c 100644 --- a/source/docs/hardware/hardware-safety/placeholder.rst +++ b/source/docs/hardware/hardware-safety/placeholder.rst @@ -1,11 +1,6 @@ Placeholder for Safety Writeup ============================== -.. Note:: From a Chief Delphi `thread reply `_ by WPILib Developer Peter Johnson. - -I/O Safety ------------ - roboRIO Control System ^^^^^^^^^^^^^^^^^^^^^^ From 6a32ba165699ee2b4d524ad41ef60963025e1348 Mon Sep 17 00:00:00 2001 From: Peter Buterbaugh Date: Tue, 8 Aug 2023 14:42:34 -0400 Subject: [PATCH 6/8] Added label for PWM doc, corrected external reference for PWM in glossary. --- source/docs/hardware/hardware-safety/placeholder.rst | 5 ----- source/docs/software/frc-glossary.rst | 2 +- .../docs/software/hardware-apis/motors/pwm-controllers.rst | 2 ++ 3 files changed, 3 insertions(+), 6 deletions(-) diff --git a/source/docs/hardware/hardware-safety/placeholder.rst b/source/docs/hardware/hardware-safety/placeholder.rst index e71892084c..1a58a61ae0 100644 --- a/source/docs/hardware/hardware-safety/placeholder.rst +++ b/source/docs/hardware/hardware-safety/placeholder.rst @@ -20,11 +20,6 @@ Software Side: - Control \(DS->Robot\) and status \(Robot->DS\) packets have an embedded sequence number. The DS uses these to compute round-trip-time and packet loss. A status packet that\’s returned is marked as “lost” if the RTT is greater than ~250 ms. This does not mean it was actually missing \(no response received\). The DS does keep a separate count of truly missing \(e.g. no response\) packets and disables \(starts sending control packets with enable=false\) after ~10 drops occur \(so I think this works out to ~450 ms, assuming it\’s 250+10*20\). - High CPU / GUI delays result in the DS continuing to send packets with enable=true for a period of time until that loop is notified a disable occurs. -Vendor Components: -^^^^^^^^^^^^^^^^^^ - -- CTRE uses a custom approach that reads the disable indicator on NetComm and stops motors within 100 `ms` of a disable. - Potential Improvements: ^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/source/docs/software/frc-glossary.rst b/source/docs/software/frc-glossary.rst index 38a2d74eb5..0ba1907812 100644 --- a/source/docs/software/frc-glossary.rst +++ b/source/docs/software/frc-glossary.rst @@ -138,7 +138,7 @@ FRC Glossary The collection of position and rotation information that describes how a rigid body is oriented in space, relative to some fixed reference point. PWM - An acronym which stands for "Pulse Width Modulation", a method for motor controllers, sensors, and other components to transmit or receive their operational status. For motor controllers, PWM is often used to affect the power output to the motor or connected actuator. See `PWM ` on Wikipedia for more information. + An acronym which stands for "Pulse Width Modulation", a method for motor controllers, sensors, and other components to transmit or receive their operational status. For motor controllers, PWM is often used to affect the power output to the motor or connected actuator. See :ref:`PWM` for more information. RAII Resource Acquisition Is Initialization; a language behavior (in C++, but not in Java) where holding a resource is tied to object lifetime. diff --git a/source/docs/software/hardware-apis/motors/pwm-controllers.rst b/source/docs/software/hardware-apis/motors/pwm-controllers.rst index e156f23dba..3549242895 100644 --- a/source/docs/software/hardware-apis/motors/pwm-controllers.rst +++ b/source/docs/software/hardware-apis/motors/pwm-controllers.rst @@ -1,5 +1,7 @@ .. include:: +.. _PWM: + PWM Motor Controllers in Depth ============================== From 58fa2871d9d94226a9435480433d3e13587edb1c Mon Sep 17 00:00:00 2001 From: Peter Buterbaugh Date: Tue, 8 Aug 2023 16:30:13 -0400 Subject: [PATCH 7/8] Removed improvements, made some small improvements as suggested in draft PR corresponding to #2227. --- source/docs/hardware/hardware-safety/index.rst | 2 +- .../{placeholder.rst => io_safety.rst} | 13 +++---------- 2 files changed, 4 insertions(+), 11 deletions(-) rename source/docs/hardware/hardware-safety/{placeholder.rst => io_safety.rst} (71%) diff --git a/source/docs/hardware/hardware-safety/index.rst b/source/docs/hardware/hardware-safety/index.rst index c1cc657950..feeff52e12 100644 --- a/source/docs/hardware/hardware-safety/index.rst +++ b/source/docs/hardware/hardware-safety/index.rst @@ -6,4 +6,4 @@ This section describes some of the safety features built into the NI roboRIO Con .. toctree:: :maxdepth: 1 - placeholder \ No newline at end of file + io_safety \ No newline at end of file diff --git a/source/docs/hardware/hardware-safety/placeholder.rst b/source/docs/hardware/hardware-safety/io_safety.rst similarity index 71% rename from source/docs/hardware/hardware-safety/placeholder.rst rename to source/docs/hardware/hardware-safety/io_safety.rst index 1a58a61ae0..3d07c1ddbf 100644 --- a/source/docs/hardware/hardware-safety/placeholder.rst +++ b/source/docs/hardware/hardware-safety/io_safety.rst @@ -1,5 +1,5 @@ -Placeholder for Safety Writeup -============================== +Input/Output Safety Mechanisms Built into the 2015-2026 `FRC` Control System +============================================================================ roboRIO Control System ^^^^^^^^^^^^^^^^^^^^^^ @@ -20,15 +20,8 @@ Software Side: - Control \(DS->Robot\) and status \(Robot->DS\) packets have an embedded sequence number. The DS uses these to compute round-trip-time and packet loss. A status packet that\’s returned is marked as “lost” if the RTT is greater than ~250 ms. This does not mean it was actually missing \(no response received\). The DS does keep a separate count of truly missing \(e.g. no response\) packets and disables \(starts sending control packets with enable=false\) after ~10 drops occur \(so I think this works out to ~450 ms, assuming it\’s 250+10*20\). - High CPU / GUI delays result in the DS continuing to send packets with enable=true for a period of time until that loop is notified a disable occurs. -Potential Improvements: -^^^^^^^^^^^^^^^^^^^^^^^ - -- NetComm \(and the control protocol\) does not currently have a mechanism to detect delayed control packets. \(If it gets a control packet with enable set to true, it will enable the robot and feed the watchdog, even if that packet was sent seconds ago and delayed that much by the network\). -- DS: keyboard events should be processed at the same (or higher) thread priority as the control packet transmit loop. Or there should be an internal watchdog that tracks when the last keyboard/joystick/gui event check happened, and force disables when that expires. -- NetComm: Figure out a way to detect delayed control packets and reduce the probability of “stuttering” on sporadic enable packets. This is a hard problem in the general case, will almost certainly require a protocol change, and has some really tricky corner cases. To take one example: a radio reboot on the field will result in the first thing the robot sees being an enable packet after a period of watchdog. There probably needs to be some kind of predict time for receiving a control packet (to discard overly late ones), as well as timestamps and measured RTT provided by the DS to NetComm in control packets to provide a time sync. - Known Issues / Potential Fault Conditions: ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - There is no upper limit to control lag. As long as packets keep arriving, they may be several seconds delayed from the DS, so a disable command from the DS would take the same amount of time to be reflected in robot operation. Once it\’s delayed, all controls, including disable/estop, will be delayed. We\’ve all seen delays increase either slowly or quickly\–the robot was controllable until it\’s suddenly much more laggy, or even been laggy from the start. -- Packet buffering / wifi retransmits of control packets result in sporadic enable packets making it to the robot after some delay. The watchdog would disable after 125 ms, but a single enable packet would re-enable motors for another 125 `ms` at a time. +- Packet buffering / wifi retransmits of control packets result in sporadic enable packets making it to the robot after some delay. The watchdog would disable after 125 `ms`, but a single enable packet would re-enable motors for another 125 `ms` at a time. From fd506617e60b68bcff3507b20b99241a8ce72a24 Mon Sep 17 00:00:00 2001 From: Peter Buterbaugh Date: Thu, 10 Aug 2023 09:59:45 -0400 Subject: [PATCH 8/8] Fixed minor mistakes leading to linting CICD fail, removed years from io_safety page. --- source/docs/hardware/hardware-safety/index.rst | 2 +- source/docs/hardware/hardware-safety/io_safety.rst | 4 ++-- source/docs/software/frc-glossary.rst | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/source/docs/hardware/hardware-safety/index.rst b/source/docs/hardware/hardware-safety/index.rst index feeff52e12..b005ab26aa 100644 --- a/source/docs/hardware/hardware-safety/index.rst +++ b/source/docs/hardware/hardware-safety/index.rst @@ -6,4 +6,4 @@ This section describes some of the safety features built into the NI roboRIO Con .. toctree:: :maxdepth: 1 - io_safety \ No newline at end of file + io_safety diff --git a/source/docs/hardware/hardware-safety/io_safety.rst b/source/docs/hardware/hardware-safety/io_safety.rst index 3d07c1ddbf..fca92c6bb9 100644 --- a/source/docs/hardware/hardware-safety/io_safety.rst +++ b/source/docs/hardware/hardware-safety/io_safety.rst @@ -1,7 +1,7 @@ -Input/Output Safety Mechanisms Built into the 2015-2026 `FRC` Control System +Input/Output Safety Mechanisms Built into the `FRC` Control System ============================================================================ -roboRIO Control System +roboRIO Control System ^^^^^^^^^^^^^^^^^^^^^^ There are multiple safety mechanisms on the robot that handle input / output operations while it is powered on. diff --git a/source/docs/software/frc-glossary.rst b/source/docs/software/frc-glossary.rst index 0ba1907812..e810e3af60 100644 --- a/source/docs/software/frc-glossary.rst +++ b/source/docs/software/frc-glossary.rst @@ -120,7 +120,7 @@ FRC Glossary An object that can be modified after it is created. NetComm - A software daemon running on the NI roboRIO controller to maintain communications with the Driver Station, :term:`FPGA`, and user program. + A software daemon running on the NI roboRIO controller to maintain communications with the Driver Station, :term:`FPGA`, and user program. permanent-magnet DC motor The classification of all legal motors for the FIRST robotics competition. This type of motor takes direct current as input, and uses it to create a magnetic field. In turn, this magnetic field interacts with a physical magnet to create a force that turns the output shaft. Electrical ("brushless") or mechanical ("brushed") means are used to ensure the electrically-generated magnetic field always points in a direction that creates forces when it interacts with the physical magnet, even as the motor's shaft rotates. See `permanent-magnet motor `__ on Wikipedia for more info.