> Complete documentation index: [llms.txt](/llms.txt). Markdown versions of all pages are available by appending `.md` to page URLs.

# Binho Atira: Setup

> Take the Atira from the box to a halted Cortex-M target: connect the probe, install PyCosmicSDK 1.7.0 or later, set the Linux udev rule, wire the target.

This page goes from the box to a halted Cortex-M target. For the full pinout, specifications and more examples, see the [Binho Atira overview](/hardware/atira/) and its [hardware reference](/hardware/atira/reference/).

## 1. Connect the probe

Plug the Atira into the computer with a USB-C cable. Leave the target unconnected for now.

The probe needs **Atira firmware 1.0** or newer. Step 4 shows how to read the version.

## 2. Install PyCosmicSDK

PyCosmicSDK 1.7.0 is the first version with Atira support. It needs Python 3.10 or newer.

```bash
pip install "pycosmicsdk>=1.7.0"
```

## 3. Linux: udev rule

On Linux, a udev rule gives the current user access to the probe (USB ID `1fc9:8347`). Without it, `DebugProbe.open()` fails with `DeviceNotFoundError` and names the permission problem. Windows and macOS need nothing.

Create `/etc/udev/rules.d/65-binho-atira.rules`:

```bash
sudo nano /etc/udev/rules.d/65-binho-atira.rules
```

with these lines:

```text
# Binho Atira (HID control)
SUBSYSTEM=="hidraw", ATTRS{idVendor}=="1fc9", ATTRS{idProduct}=="8347", MODE="0660", GROUP="plugdev", TAG+="uaccess"
# Binho Atira (USB: CMSIS-DAP and SPI bulk)
SUBSYSTEM=="usb", ATTRS{idVendor}=="1fc9", ATTRS{idProduct}=="8347", MODE="0660", GROUP="plugdev", TAG+="uaccess"
# Binho Atira bootloader
SUBSYSTEM=="hidraw", ATTRS{idVendor}=="1fc9", ATTRS{idProduct}=="82fe", MODE="0660", GROUP="plugdev", TAG+="uaccess"
SUBSYSTEM=="usb", ATTRS{idVendor}=="1fc9", ATTRS{idProduct}=="82fe", MODE="0660", GROUP="plugdev", TAG+="uaccess"
# Binho Atira UART bridge
SUBSYSTEM=="tty", ATTRS{idVendor}=="1fc9", ATTRS{idProduct}=="8347", TAG+="uaccess"
```

Reload the rules, then unplug and replug the probe:

```bash
sudo udevadm control --reload-rules && sudo udevadm trigger
```

:::note
The rule grants access to the logged-in user (`uaccess`) and to the `plugdev` group where it exists. The `usb` line matters too: pyOCD and SPI flash programming use the probe's USB bulk interface, not HID.

:::

## 4. Identify the probe

```python
from pycosmicsdk import DebugProbe, list_debug_probes

print(list_debug_probes())

with DebugProbe.open() as probe:
    info = probe.info
    print(f"Serial:      {probe.serial_number}")
    print(f"Firmware:    {info.fw_major}.{info.fw_minor}.{info.fw_patch}")
    print(f"UART bridge: {probe.uart().bridge_port or '(not found)'}")
```

| Observed | Meaning |
| ------- | ------- |
| An empty list | The probe is not on USB. Try another cable or port. |
| `DeviceNotFoundError` | Another program holds the probe, or (Linux) the udev rule is missing. |
| `UnsupportedFirmwareError` | The probe runs firmware older than 1.0. Update it, then retry. |

## 5. Wire the target

Connect the target's 10-pin Cortex debug header to the Atira's **J4** with a straight (not mirrored) 1.27 mm ribbon: the red stripe goes to pin 1 at both ends.

| J4 pin | Signal |
| ------ | ------ |
| 1 | VDD (target rail, 3.3 V) |
| 2 | SWDIO |
| 3, 5 | GND |
| 4 | SWCLK |
| 10 | nRESET |

Choose how the target is powered:



**Powered by the Atira**

Leave the target's own supply (USB, bench supply) disconnected. The Atira powers it through J4 pin 1.



**Self-powered target**

Self-powered targets are not supported in 9.0. Power the target from Atira. A self-powered board works only if it is a 3.3 V board with J4 pin 1 unwired. Power it before turning Atira supply on, and turn Atira supply off before unplugging or swapping it. The rail must still be switched on in step 6: the probe's level shifters need it.



:::danger
Never switch the rail on while the target's own supply is wired to J4 pin 1. That puts two supplies in parallel.

:::

## 6. First power-on

The rail is off when the probe powers up. Switch it on and check the reading:

```python
import time
from pycosmicsdk import DebugProbe

with DebugProbe.open() as probe:
    power = probe.power()
    power.set_output(True)
    time.sleep(0.5)                       # the reading lags the switch by ~0.5 s
    r = power.reading()
    print(f"{r.voltage_mv} mV, {r.current_ua / 1000:.2f} mA")
```

Expect about 3300 mV. The current is what the target draws; a NUCLEO-H503RB powered this way draws about 20 mA. If the current is far above what the board should draw, switch the rail off (`power.set_output(False)`) and check the wiring.

## 7. First SWD halt

```python
import time
from pycosmicsdk import DebugProbe

with DebugProbe.open() as probe:
    probe.power().set_output(True)
    time.sleep(0.5)

    debug = probe.debug()
    debug.attach()
    state = debug.halt()
    print(f"halted at PC 0x{state.pc:08X}")
    print(f"SP = 0x{debug.read_register(13):08X}")

    debug.run()
    debug.detach()
```

A PC address inside the target's flash (for example `0x08xxxxxx` on STM32) means SWD works.

If `attach()` fails:

* Check that the rail is on and reads about 3.3 V. With the rail off, SWD cannot connect.
* Check the cable is straight, not mirrored.
* If the target board has its own on-board debugger (ST-LINK, MCU-Link), hold it in reset or unpower it so it does not drive SWDIO/SWCLK. On a NUCLEO-H503RB, fit JP1.

## Next steps

* [Protocols](/hardware/atira/protocols/): breakpoints, SPI flash programming, the UART bridge and flashing with pyOCD.
* [Hardware reference](/hardware/atira/reference/): connectors, pinout, target power and specifications.
* [PyCosmicSDK debug probe guide](https://binhollc.github.io/pycosmicsdk/guides/debugprobe.html)
* [CosmicSDK debug probe guide](https://binhollc.github.io/CosmicSDK/getting_started/debug_probe.html) (C/C++)