Add info on how DS/NetComm safety controls work (the sequel) #2308
Conversation
…aft PR corresponding to wpilibsuite#2227.
| @@ -0,0 +1,27 @@ | |||
| Input/Output Safety Mechanisms Built into the 2015-2026 `FRC` Control System | |||
There was a problem hiding this comment.
| Input/Output Safety Mechanisms Built into the 2015-2026 `FRC` Control System | |
| Input/Output Safety Mechanisms Built into the `FRC` Control System |
calling out the years is overly specfici and not really helpful. If the next control system has different safety mechanisms, the document would be updated.
| @@ -0,0 +1,27 @@ | |||
| Input/Output Safety Mechanisms Built into the `FRC` Control System | |||
| ============================================================================ | |||
There was a problem hiding this comment.
Couple of issues here
- Underline is too long (legal in rST spec, but against our styleguide)
- You probably want ``FRC`` instead of FRC
- The title is too long, I think "Control System" and "FRC" is redundant
|
|
||
| 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`. |
There was a problem hiding this comment.
| - 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 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`. |
Don't use non-UTF8 quotations. Replace “ with ". This helps our translators. Additionally, replace the non-UTF8 apostrophe with '
| 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\). |
There was a problem hiding this comment.
Our specific timeout values are really just implementation details. It's one thing to share them for a Chief Delphi post that isn't expected to be evergreen, and another thing to put them somewhere that's expected to be an up-to-date resource. Here's my suggestion for a more generic replacement.
| - 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 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 after a very brief timeout period. |
There was a problem hiding this comment.
Additionally, there is incorrect information about how the roboRIO's software behaves in this paragraph. While the roboRIO is booted, it never stops sending Universal Heartbeat messages. When the robot is stopped, the roboRIO merely changes the WatchdogEnabled field from a 1 to a 0, but it keeps sending out the heartbeat.
This paragraph should also probably use the official "heartbeat" term consistently, rather than "keep-alive", which I think more strongly implies that receipt of the frame itself indicates an enabled status, rather than the truth, which is that it merely indicates the presence of a roboRIO, and you have to look at a specific byte to check the enabled status.
There was a problem hiding this comment.
Not to block the PR, but I think it would be nice to have the timeout value(s) documented. Even if implementations will vary and even change, would it be fair to document minimum and maximum timeouts that all implementations fall inside of?
There was a problem hiding this comment.
I think its important to have those timeouts (or at least an upper bound) documented. @Kevin-OConnor maybe you can comment on what FIRST's expectation of motor controllers' timeout period is?
There was a problem hiding this comment.
It seems odd that this specifically calls out what REVs devices do while not saying anything about other vendors. This should probably be genericized and use language similar to the "brief timeout period" Noah has suggested.
| - 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: |
There was a problem hiding this comment.
This should be "Driver Station side" or similar
Closes #2227.
Created a new PR after a bit of a mix-up on my end with branches.