> ## Documentation Index
> Fetch the complete documentation index at: https://motorbridge.seeedstudio.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Python Getting Started Overview

This folder is a fresh, beginner-first quickstart for users who install from pip.

Goal: install package -> run scan -> run a motor example in minutes.

## 1) Install

```bash theme={null}
python3 -m pip install motorbridge
```

If you want to test pre-release package from TestPyPI:

```bash theme={null}
python3 -m pip install -i https://test.pypi.org/simple/ motorbridge==<version>
```

## 2) Hardware and Channel

* Linux SocketCAN channel examples: `can0`, `can1`, `slcan0`
* Windows PCAN channel examples: `can0@1000000`, `can1@1000000`
* Ensure only one sender is writing to the bus while testing.

### Which transport should I use?

* `TRANSPORT = "auto"` or `"socketcan"`:
  use normal CAN path (`CHANNEL` is used).
* `TRANSPORT = "dm-serial"`:
  use Damiao serial bridge (`SERIAL_PORT` / `SERIAL_BAUD` are used), Damiao only.

## 3) Quick Commands (no source checkout required)

```bash theme={null}
# Unified scan from installed CLI
motorbridge-cli scan --vendor all --channel can0 --start-id 1 --end-id 255

# Single Damiao control (example IDs)
motorbridge-cli run --vendor damiao --channel can0 --model 4340P --motor-id 0x01 --feedback-id 0x11 \
  --mode pos-vel --pos 1.0 --vlim 1.0 --loop 60 --dt-ms 20
```

## 4) Course scripts in this folder

All runnable scripts in `get_started` now live under `courses/`.
For beginners, this is easier to follow and avoids duplicate entry points.

### Config constants (simple meaning)

* `TRANSPORT`: `auto/socketcan/dm-serial`
* `CHANNEL`: CAN interface name (`can0`, `slcan0`, `can0@1000000`, ...)
* `VENDOR`: scan target vendor (`all` is most common)
* `MOTOR_ID` / `FEEDBACK_ID`: motor command/feedback IDs
* `MODEL`: motor model string
* `TARGET_POS` / `POS`: target position in radians
* `V_LIMIT`: velocity limit for position mode
* `LOOP`: send loop count
* `DT_MS`: control period in ms
* `SERIAL_PORT` / `SERIAL_BAUD`: used only for `dm-serial`

## 5) Course Series (workflow-first)

If you want a strict real-world workflow course, use `courses/`:

* `courses/00-enable-and-status.py`
* `courses/01-scan.py`
* `courses/02-register-rw.py`
* `courses/03-mode-switch-method.py`
* `courses/04-mode-mit.py`
* `courses/05-mode-pos-vel.py`
* `courses/06-mode-vel.py`
* `courses/07-mode-force-pos.py`
* `courses/08-mode-mixed-switch.py`
* `courses/09-multi-motor.py`

Example:

```bash theme={null}
python3 bindings/python/get_started/courses/00-enable-and-status.py
python3 bindings/python/get_started/courses/01-scan.py
python3 bindings/python/get_started/courses/03-mode-switch-method.py
```

## 6) Run now (courses only)

```bash theme={null}
python3 bindings/python/get_started/courses/00-enable-and-status.py
python3 bindings/python/get_started/courses/01-scan.py
python3 bindings/python/get_started/courses/09-multi-motor.py
```

## 7) Common Issues

* `os error 105`: bus TX is too fast or another process is sending; increase `--dt-ms` to 30/50.
* no motor response: verify CAN wiring, bitrate, motor/feedback IDs.
* `slcan` users: bring up `slcan0` before running examples.

## 8) `poll_feedback_once()` version note

* `<= v0.1.6`: keep manual `poll_feedback_once()` in status-query scripts.
* `v0.1.7+`: background polling is enabled by default, so manual poll is usually optional.
* Course scripts keep `poll_feedback_once()` for backward-compatible teaching style.

## 9) What to read next

* Python API overview: `bindings/python/README.md`
* Full examples catalog: `bindings/python/examples/README.md`
* CLI full docs: `motor_cli/README.md`