Metadata-Version: 2.4
Name: pololu
Version: 0.1.1
Summary: Sterowanie silnikiem krokowym bipolarnym przez Pololu Tic T249 z obsługą wyłączników krańcowych i procedury homing
Project-URL: Homepage, https://github.com/maskservice/rpi-motor-tic249
Project-URL: Repository, https://github.com/maskservice/rpi-motor-tic249
Project-URL: Issues, https://github.com/maskservice/rpi-motor-tic249/issues
Author: MaskService
Author-email: Tom Sapletta <tom@sapletta.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: controller,motor,pololu,raspberry-pi,stepper,t249,tic
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Hardware
Requires-Python: >=3.9
Requires-Dist: pyusb>=1.2.0
Requires-Dist: ticlib>=0.3.0
Provides-Extra: gpio
Requires-Dist: gpiozero>=2.0; extra == 'gpio'
Requires-Dist: rpi-gpio>=0.7.0; extra == 'gpio'
Description-Content-Type: text/markdown

# Tic T249 Stepper Motor Controller

Sterowanie silnikiem krokowym bipolarnym przez **Pololu Tic T249** (TB67S249FTG) z pełną obsługą **wyłączników krańcowych** (limit switches) i procedury **homing**.

## Tryby obsługi krańcówek

### 1. Tryb `tic` — sprzętowy (zalecany)

Wyłączniki podłączone bezpośrednio do pinów Tic T249 (SCL, SDA, TX, RX lub RC). Konfiguracja pinów w **Tic Control Center** → Advanced → Pin configuration. Wymaga firmware ≥1.06.

Tic automatycznie blokuje ruch w kierunku aktywnego wyłącznika i obsługuje sprzętową procedurę homing (go_home → jedzie do krańcówki → cofa → pozycja = 0).

```
Tic T249 Pin TX ─── Limit Switch Forward ─── GND
Tic T249 Pin RX ─── Limit Switch Reverse ─── GND
```

### 2. Tryb `gpio` — programowy (Raspberry Pi)

Wyłączniki podłączone do dowolnych pinów GPIO, monitorowane z przerwaniami. Natychmiastowe zatrzymanie silnika (emergency stop) przy aktywacji krańcówki w kierunku ruchu.

```
RPi GPIO 17 ─── Limit Switch Forward ─── GND  (pull-up wewnętrzny)
RPi GPIO 27 ─── Limit Switch Reverse ─── GND  (pull-up wewnętrzny)
```

Wymaga `gpiozero` lub `RPi.GPIO`:
```bash
pip install gpiozero
```

## Instalacja

```bash
sudo apt-get install libusb-1.0-0-dev
pip install -r requirements.txt

# Reguła udev
echo 'SUBSYSTEM=="usb", ATTR{idVendor}=="1ffb", MODE="0666"' | \
    sudo tee /etc/udev/rules.d/99-pololu-tic.rules
sudo udevadm control --reload-rules
```

## Użycie — CLI

### Homing (zerowanie na krańcówce)

```bash
# Homing sprzętowy Tic — jedź reverse aż limit switch, cofnij, pozycja=0
python tic_t249_controller.py home-reverse --limit-mode tic

# Homing forward
python tic_t249_controller.py home-forward --limit-mode tic

# Homing GPIO — piny BCM 17 (forward) i 27 (reverse)
python tic_t249_controller.py home-reverse --limit-mode gpio --gpio-fwd 17 --gpio-rev 27

# Z pliku konfiguracji
python tic_t249_controller.py home-reverse --config config.json
python tic_t249_controller.py home-reverse --config config-gpio.json
```

### Wyznaczanie zakresu ruchu

```bash
# Jedź do reverse limit (pozycja=0), potem do forward limit → odczytaj zakres
python tic_t249_controller.py demo-range --limit-mode tic
```

### Ruch z ochroną krańcówek

```bash
# Ruch do pozycji (Tic blokuje sprzętowo przy limit switch)
python tic_t249_controller.py move -p 5000 --limit-mode tic

# Ruch z soft limitami (przycina do zakresu - margin)
python tic_t249_controller.py move-safe -p 3000

# GPIO — emergency stop jeśli krańcówka aktywna w kierunku ruchu
python tic_t249_controller.py move -p 5000 --limit-mode gpio --gpio-fwd 17 --gpio-rev 27
```

### Status krańcówek

```bash
python tic_t249_controller.py limit-status --limit-mode tic
python tic_t249_controller.py status --limit-mode tic
```

### Pozostałe komendy

```bash
python tic_t249_controller.py demo-positions
python tic_t249_controller.py demo-velocity
python tic_t249_controller.py demo-homing --limit-mode tic
python tic_t249_controller.py velocity --speed 1000000 --duration 5
python tic_t249_controller.py home  # ręczne zerowanie, bez krańcówek
```

## Użycie — Python API

```python
from tic_t249_controller import (
    TicT249Controller, MotorConfig, LimitSwitchConfig,
    StepMode, HomingDirection,
)

# --- Tryb Tic (sprzętowy) ---
config = MotorConfig(
    current_limit_ma=1200,
    step_mode=StepMode.SIXTEENTH,
    limit_switches=LimitSwitchConfig(mode="tic"),
)

with TicT249Controller(config) as ctrl:
    # Homing na reverse limit switch → pozycja = 0
    ctrl.go_home(HomingDirection.REVERSE)

    # Ruch — Tic automatycznie blokuje przy limit switch
    ctrl.move_to(5000)
    ctrl.wait_for_position()

    # Status krańcówek
    status = ctrl.get_limit_switch_status()
    print(f"Forward: {status['forward_active']}")
    print(f"Reverse: {status['reverse_active']}")

    # Wyznacz zakres ruchu
    travel = ctrl.find_travel_range()
    print(f"Zakres: {travel} kroków")

    # Ruch bezpieczny (z soft limitami)
    ctrl.move_to_safe(travel // 2)
    ctrl.wait_for_position()


# --- Tryb GPIO (Raspberry Pi) ---
config_gpio = MotorConfig(
    limit_switches=LimitSwitchConfig(
        mode="gpio",
        gpio_forward_pin=17,
        gpio_reverse_pin=27,
        gpio_active_low=True,  # NO switch z pull-up
        homing_speed_towards=300_000,
        homing_speed_away=100_000,
    ),
)

with TicT249Controller(config_gpio) as ctrl:
    ctrl.go_home(HomingDirection.REVERSE)
    ctrl.move_to(3000)
    ctrl.wait_for_position()  # przerywa jeśli krańcówka aktywna
```

## Konfiguracja JSON

### `config.json` (tryb Tic)

```json
{
  "limit_switches": {
    "mode": "tic",
    "homing_speed_towards": 500000,
    "homing_speed_away": 200000,
    "soft_limit_margin": 50
  }
}
```

### `config-gpio.json` (tryb GPIO)

```json
{
  "limit_switches": {
    "mode": "gpio",
    "gpio_forward_pin": 17,
    "gpio_reverse_pin": 27,
    "gpio_active_low": true,
    "gpio_bounce_time_ms": 5,
    "homing_speed_towards": 500000,
    "homing_speed_away": 200000,
    "soft_limit_margin": 50
  }
}
```

## Procedura homing — jak działa

### Tryb Tic (sprzętowy)

1. Komenda `go_home(direction)` → Tic jedzie w zadanym kierunku
2. Tic napotyka limit switch → natychmiastowe zatrzymanie (sprzętowe)
3. Tic czeka 20 ms
4. Tic cofa wolno aż limit switch się dezaktywuje
5. Pozycja = 0, flaga "position uncertain" skasowana

### Tryb GPIO (programowy)

1. Jeśli już na krańcówce → najpierw odjazd
2. Ruch wolny w kierunku krańcówki (`homing_speed_towards`)
3. GPIO przerwanie → `halt_and_hold()` (natychmiastowy stop)
4. Cofanie wolne (`homing_speed_away`) aż GPIO zwolni
5. `halt_and_set_position(0)`

## Bezpieczeństwo

- **Ctrl+C** → bezpieczne deenergize (cewki wyłączone)
- **GPIO emergency stop** → natychmiastowe `halt_and_hold()` przy krańcówce
- **Soft limity** → `move_to_safe()` przycina pozycję do zakresu ± margines
- **Nigdy nie odłączaj silnika przy zasilonym sterowniku**
- Bez radiatora max ~1800 mA na cewkę

## Licencja

Program: **MIT** (Softreck, softreck.dev)
Zależność ticlib: **BSD-2-Clause** (Julien Phalip) — dozwolona komercyjnie

## License

Apache License 2.0 - see [LICENSE](LICENSE) for details.

## Author

Created by **Tom Sapletta** - [tom@sapletta.com](mailto:tom@sapletta.com)
