# Return values, communication failures, and alarm detection

This page is a static source audit of `source_reference/dobot_core/dobot_ctrl.py`, `dobot_tcp.py`, and `dobot_error.py`; it is not hardware validation.

## Return-value contracts

| API | Normal result | Failure or limitation |
| --- | --- | --- |
| `get_digital_input(index)` | `True` for HIGH, `False` for LOW | Non-success Dashboard replies, parse errors, missing values, and exceptions also return `False`; LOW cannot be distinguished from failure by return value alone. |
| `get_IO(id_num)` | `1` or `0` from the `digital_outputs` Feedback bitfield | `id_num < 1` raises `ValueError`. Missing initial Feedback raises `RuntimeError`. Feedback freshness is not verified after the initial frame. |
| `set_IO(id_num, value)` | `True` for Dashboard `DO` return code 0 | `False` otherwise; no physical-output readback verification. |
| `reset_error()` | `True` for successful `ClearError` response | `False` for unsuccessful response; does not establish that the underlying fault was resolved. |
| `get_motion_complete()` | `True` when `busy_status` is false | `busy_status` checks `RunningStatus` and `JogStatus`. Initial Feedback timeout can raise `RuntimeError`. `True` does not prove target reached or alarm-free completion. |
| `wait_for_complete()` | `True` after successful `Sync()` and no detected alarm | `False` for failed Sync or detected alarm. Not all communication/alarm-query failures are detectable. The public `DobotCtrl` method has no arguments. |
| `get_error()` | List of alarm IDs | Missing Dashboard, failed `GetErrorID`, or malformed/empty payload can produce `[]`. |
| `get_error_code()` / `get_error_count()` | First ID / count | The above failures can also produce `0`. |
| `check_error()` | `get_error_count() == 0` | Can return `True` if alarm retrieval fails; not a connection-health check. |

## Feedback and alarm-query boundary

`_state()` waits for the first valid Feedback frame and raises `RuntimeError` on timeout. It does not validate age of cached Feedback after the first frame. `motion_error_active()` catches `RuntimeError` from `_state_getter("ErrorStatus", timeout=0.1)` and treats the error status as false. When `GetErrorID()` also yields an empty alarm list because retrieval failed, the control flow can report no active alarm without having established that status.

**Operational implication:** Do not use an isolated `False`, `0`, `[]`, or `True` as proof of connection health or motion safety. This page documents existing behavior; it does not change the implementation.

## Scope

Only the provided Python source branches and return paths were inspected. Hardware alarms, network interruptions, I/O wiring, TCP timeouts, and Sphinx HTML output were not tested.