napco-ibridge 1.0.0
Python library for Napco iBridge security panel communication
Requires Python: >=3.9
Keywords: napco, ibridge, security, alarm, home-automation, home-assistant

# Napco iBridge Python Library

A Python library for communicating with Napco security panels via the iBridge protocol.

## Features

- **Async/await support** - Built on Python's asyncio
- **Auto-reconnection** - Automatic reconnection with exponential backoff
- **Connection state management** - Track connection status
- **Full protocol support** - All Napco iBridge keypad buttons and status updates
- **Type hints** - Full type annotation support
- **Robust error handling** - Comprehensive exception handling

## Installation

```bash
pip install napco-ibridge
```

## Quick Start

```python
import asyncio
from napco_ibridge import IBridgeClient, BUTTONS

async def main():
    # Create client
    client = IBridgeClient(
        panel_address="192.168.1.100",
        status_interval=1.0,
        auto_reconnect=True
    )

    # Define status callback
    def on_status_update(status):
        print(f"Arm Status: {status['arm_status']}")
        print(f"Text: {status['raw_data'].get('text_line1', '')}")

    # Connect to panel
    await client.connect(on_update=on_status_update)

    # Send buttons (e.g., arm in STAY mode)
    await client.send_buttons([BUTTONS.BUTTON_INTERIOR_STAY_LONG])

    # Keep running
    await asyncio.sleep(3600)

    # Disconnect
    await client.disconnect()

if __name__ == "__main__":
    asyncio.run(main())
```

## Panel Discovery

```python
from napco_ibridge import discover_panel

# Discover panel on local network
panel_ip = await discover_panel(timeout=5.0)
print(f"Found panel at: {panel_ip}")
```

## Arm/Disarm Examples

### Arm STAY Mode

```python
await client.send_buttons([BUTTONS.BUTTON_INTERIOR_STAY_LONG])
```

### Arm AWAY Mode

```python
# Enter code + ENTER
await client.send_buttons([
    BUTTONS.BUTTON_1,
    BUTTONS.BUTTON_2,
    BUTTONS.BUTTON_3,
    BUTTONS.BUTTON_4,
    BUTTONS.BUTTON_ON_OFF_ENTER
])
```

### Disarm

```python
# Enter code + ENTER
await client.send_buttons([
    BUTTONS.BUTTON_1,
    BUTTONS.BUTTON_2,
    BUTTONS.BUTTON_3,
    BUTTONS.BUTTON_4,
    BUTTONS.BUTTON_ON_OFF_ENTER
])
```

## Connection State Management

```python
from napco_ibridge import ConnectionState

def on_connection_state(new_state, old_state):
    print(f"Connection: {old_state.name} -> {new_state.name}")

    if new_state == ConnectionState.CONNECTED:
        print("Connected to panel!")
    elif new_state == ConnectionState.FAILED:
        print("Connection failed!")

await client.connect(
    on_update=on_status_update,
    on_connection_state=on_connection_state
)
```

## Available Button Codes

All button codes are available in the `BUTTONS` enum:

```python
from napco_ibridge import BUTTONS

# Number buttons
BUTTONS.BUTTON_0 through BUTTONS.BUTTON_9

# Special buttons
BUTTONS.BUTTON_STAR
BUTTONS.BUTTON_ON_OFF_ENTER
BUTTONS.BUTTON_INTERIOR_STAY
BUTTONS.BUTTON_INTERIOR_STAY_LONG
BUTTONS.BUTTON_INSTANT_AWAY
BUTTONS.BUTTON_INSTANT_AWAY_LONG
BUTTONS.BUTTON_BYPASS
BUTTONS.BUTTON_RESET
BUTTONS.BUTTON_NEXT
BUTTONS.BUTTON_PREV
BUTTONS.BUTTON_F
BUTTONS.BUTTON_A
BUTTONS.BUTTON_P

# And many more...
```

## Status Updates

Status updates include:

```python
{
    'arm_status': 'DISARMED',  # or ARMED_AWAY, ARMED_STAY, ARMED_NIGHT, etc.
    'raw_data': {
        'text_line1': 'SYSTEM READY    ',
        'text_line2': 'ENTER CODE      ',
        'armed_led': 'Off',
        'status_led': 'On',
        'trouble_led': 'Off',
        'fire_led': 'Off',
        'bypass_led': 'Off',
        # ... and more
    }
}
```

## Advanced Configuration

```python
client = IBridgeClient(
    panel_address="192.168.1.100",
    status_interval=1.0,           # Status polling interval (seconds)
    auto_reconnect=True,            # Enable auto-reconnection
    max_reconnect_attempts=0,       # 0 = unlimited retries
    reconnect_interval=1.0,         # Initial reconnect delay (seconds)
    max_reconnect_interval=60.0     # Max reconnect delay (seconds)
)
```

## Requirements

- Python 3.9 or higher
- No external dependencies (uses standard library only)

## Supported Panels

This library works with Napco security panels that support the iBridge protocol, including:

- GEM-K1 keypads
- Other Napco panels with iBridge support

## License

MIT License - see LICENSE file for details

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Support

For issues, questions, or contributions, please visit:
https://github.com/tikotzky/node-napco-ibridge/issues

## Related Projects

- [Home Assistant Integration](https://github.com/tikotzky/node-napco-ibridge) - Use this library with Home Assistant

## Protocol Documentation

For detailed protocol documentation, see:
- [Protocol Specification](../NAPCO_IBRIDGE_PROTOCOL_SPECIFICATION.md)
- [Verification Notes](../VERIFICATION_NOTES.md)