# Debug probe

A Binho debug probe (the Atira) is a different instrument from a host adapter,
so it has its own classes: {py:obj}`~pycosmicsdk.DebugProbe` and its asyncio
twin {py:obj}`~pycosmicsdk.AsyncDebugProbe`. A probe and a Supernova or Pulsar
can be open in the same process. The probe needs firmware fw-atira v1.0 or newer
(16-bit status); older images are refused at `open()`.

The surface is the control plane, target power, SWD debug, target flash (1.9.0),
the SPI controller and SPI NOR flash. RTT, SWO and UPDI are not in this release.
`examples/blocking_api/debugprobe/` has the runnable starting points: `get_probe_info.py`,
`debug_halt_and_read.py` and `flash_program_and_verify.py`.

## Discovery

```{eval-rst}
.. autofunction:: pycosmicsdk.list_debug_probes

.. autoclass:: pycosmicsdk.DiscoveredDebugProbe
```

## DebugProbe

Probe-wide calls live on the probe. Each function of the probe is a sub-object
returned by a call, as on {py:obj}`~pycosmicsdk.Device` (`dev.spi()`):
`probe.power()`, `probe.uart()`, `probe.debug()`, `probe.spi()` and
`probe.flash()`. Firmware older than fw-atira v1.0 raises
{py:obj}`~pycosmicsdk.UnsupportedFirmwareError` at `open()`.

```{eval-rst}
.. autoclass:: pycosmicsdk.DebugProbe
   :members:
   :special-members: __enter__, __exit__
.. autoclass:: pycosmicsdk.debugprobe.TargetPower
   :members:
.. autoclass:: pycosmicsdk.debugprobe.UartBridge
   :members:
.. autoclass:: pycosmicsdk.debugprobe.DebugTarget
   :members:
.. autoclass:: pycosmicsdk.debugprobe.DebugProbeSpi
   :members:
.. autoclass:: pycosmicsdk.debugprobe.SpiFlash
   :members:
.. autoclass:: pycosmicsdk.debugprobe.TargetFlash
   :members:
```

## AsyncDebugProbe

Every call runs the blocking method in the default executor, one at a time per
probe: the SDK's debug and flash calls have no non-blocking form. The
sub-objects mirror the blocking ones (`AsyncTargetPower`, `AsyncDebugTarget`, ...).

```{eval-rst}
.. autoclass:: pycosmicsdk.AsyncDebugProbe
   :members:
.. autoclass:: pycosmicsdk.debugprobe_async.AsyncTargetPower
   :members:
.. autoclass:: pycosmicsdk.debugprobe_async.AsyncUartBridge
   :members:
.. autoclass:: pycosmicsdk.debugprobe_async.AsyncDebugTarget
   :members:
.. autoclass:: pycosmicsdk.debugprobe_async.AsyncDebugProbeSpi
   :members:
.. autoclass:: pycosmicsdk.debugprobe_async.AsyncSpiFlash
   :members:
.. autoclass:: pycosmicsdk.debugprobe_async.AsyncTargetFlash
   :members:
```

## Enums and results

```{eval-rst}
.. autoclass:: pycosmicsdk.ProgMode
   :no-members:
.. autoclass:: pycosmicsdk.FlashVerifyMethod
   :no-members:
.. autoclass:: pycosmicsdk.FlashCheck
.. autoclass:: pycosmicsdk.debugprobe.SpiHashAlgorithm
   :no-members:
.. autoclass:: pycosmicsdk.debugprobe.SpiListFlag
   :no-members:
.. autoclass:: pycosmicsdk.debugprobe.SpiParameters
.. autoclass:: pycosmicsdk.debugprobe.SpiSessionStatus
```

## Data types

Records the probe methods return or take, bound from the SDK. `PowerReading` is
in mV, µA and mW.

```{eval-rst}
.. autoclass:: pycosmicsdk.debugprobe.DebugProbeInfo
   :members:
   :undoc-members:
.. autoclass:: pycosmicsdk.debugprobe.DeviceSettings
   :members:
   :undoc-members:
.. autoclass:: pycosmicsdk.debugprobe.UartConfig
   :members:
   :undoc-members:
.. autoclass:: pycosmicsdk.debugprobe.Cdc1Config
   :members:
   :undoc-members:
.. autoclass:: pycosmicsdk.debugprobe.PinStatus
   :members:
   :undoc-members:
.. autoclass:: pycosmicsdk.debugprobe.SwdCoexistStatus
   :members:
   :undoc-members:
.. autoclass:: pycosmicsdk.debugprobe.PowerReading
   :members:
   :undoc-members:
.. autoclass:: pycosmicsdk.debugprobe.SignalVoltageCheck
   :members:
   :undoc-members:
.. autoclass:: pycosmicsdk.debugprobe.TargetFlashInfo
   :members:
   :undoc-members:
.. autoclass:: pycosmicsdk.debugprobe.TargetFlashReport
   :members:
   :undoc-members:
.. autoclass:: pycosmicsdk.debugprobe.TargetFlashPackDevice
   :members:
   :undoc-members:
.. autoclass:: pycosmicsdk.debugprobe.SignalVoltageState
   :no-members:
.. autoclass:: pycosmicsdk.debugprobe.TargetFlashRoutine
   :no-members:
.. autoclass:: pycosmicsdk.debugprobe.TargetFlashPackSupport
   :no-members:
.. autoclass:: pycosmicsdk.debugprobe.DebugState
   :members:
   :undoc-members:
.. autoclass:: pycosmicsdk.debugprobe.DebugStopReason
   :no-members:
.. autoclass:: pycosmicsdk.debugprobe.DebugResetKind
   :no-members:
.. autoclass:: pycosmicsdk.debugprobe.DebugBreakpoint
   :members:
   :undoc-members:
.. autoclass:: pycosmicsdk.debugprobe.DebugCall
   :members:
   :undoc-members:
.. autoclass:: pycosmicsdk.debugprobe.SpiPoll
   :members:
   :undoc-members:
.. autoclass:: pycosmicsdk.debugprobe.SpiListEntry
   :members:
   :undoc-members:
.. autoclass:: pycosmicsdk.debugprobe.SpiListResult
   :members:
   :undoc-members:
.. autoclass:: pycosmicsdk.debugprobe.FlashParams
   :members:
   :undoc-members:
.. autoclass:: pycosmicsdk.debugprobe.FlashEraseType
   :members:
   :undoc-members:
.. autoclass:: pycosmicsdk.debugprobe.SpiFlashBulkStats
   :members:
   :undoc-members:
```