# MicroPython Wiegand Driver

A lightweight, event-driven Wiegand protocol driver for MicroPython.  
Supports 26-bit Wiegand, 34-bit Wiegand, and 8-bit keypad input.  
No polling, no debouncing – just pure interrupt-driven collection with a one-shot timeout.

## Features

- **Fully interrupt-driven** – Records bits on both DATA0/DATA1 falling edges.
- **One‑shot timer** – 80 ms timeout started only on the first bit; zero CPU overhead when idle.
- **No software debouncing** – Relies on frame length and parity checks to reject noise.
- **Multi‑format support** – Automatically detects 26‑bit, 34‑bit, and 8‑bit keypad frames.
- **Raw payload output** – Returns the data bits without parity bits (24 bits for WG26, 32 bits for WG34), giving the application full control over facility code / card number extraction.
- **Automatic parity validation** – Standard Wiegand even/odd parity check.
- **Keypad verification** – For 8‑bit keypad frames, validates that the upper nibble is the bitwise complement of the lower nibble, then returns the key number (0–15).
- **Safe for MicroPython** – Uses a pre‑allocated `bytearray` buffer; no memory allocation inside interrupts.

## Installation

Copy the file `wiegand.py` to your MicroPython device (e.g., into `/lib/` or the root directory).

## Usage

```python
from machine import Pin
from wiegand import Wiegand

def on_wiegand(data_type, value):
    if data_type == 'wg26':
        facility = (value >> 16) & 0xFF
        card = value & 0xFFFF
        print("WG26 - Facility: {}, Card: {}".format(facility, card))
    elif data_type == 'wg34':
        print("WG34 raw payload: 0x{:08X}".format(value))
    elif data_type == 'keypad':
        print("Key pressed:", value)

# DATA0 on GPIO16, DATA1 on GPIO17
reader = Wiegand(pin0=16, pin1=17, callback=on_wiegand)
```

## API

### `Wiegand(pin0, pin1, callback, buf_len=34)`

- **`pin0`** – GPIO number for the DATA0 (zero‑bit) line.  
- **`pin1`** – GPIO number for the DATA1 (one‑bit) line.  
- **`callback`** – Function called when a valid frame is received.  
  Signature: `callback(data_type, value)`  
  - `data_type` (str): one of `'wg26'`, `'wg34'`, `'keypad'`.  
  - `value` (int):  
    - `'wg26'`: 24‑bit payload (bits 1–24 of the 26‑bit frame, parity bits removed).  
    - `'wg34'`: 32‑bit payload (bits 1–32 of the 34‑bit frame).  
    - `'keypad'`: integer 0–15, the key number.  
- **`buf_len`** – (optional) maximum buffer size, default `34`. Must be at least as large as the longest expected frame.

## Supported Formats

| Format  | Total bits | Payload bits returned | Parity check                          |
|---------|------------|------------------------|----------------------------------------|
| WG26    | 26         | 24                     | Even (first half) / Odd (second half)  |
| WG34    | 34         | 32                     | Even (first half) / Odd (second half)  |
| Keypad  | 8          | lower nibble (0–15)    | Upper nibble must be ~lower nibble     |

*For WG26 and WG34 the leading and trailing parity bits are stripped. The user is responsible for extracting facility code and card number from the raw payload.*

## How It Works

1. **Pin setup** – Both DATA0 and DATA1 pins are configured as inputs with internal pull‑ups and falling‑edge interrupts.
2. **Interrupt handler** – On each falling edge, the handler reads the state of **both** pins and encodes it as `0b01` (bit 0) or `0b10` (bit 1). Any other combination (e.g., both low) is ignored.
3. **One‑shot timer** – When the **first** valid bit is recorded, a hardware timer is started in `ONE_SHOT` mode with an 80 ms period.
4. **Timeout** – When the timer fires, the collected bit array is copied, parsed, and the buffer is reset.  
   - If the frame length is 26 or 34 and parity checks pass, the callback is called with the raw payload.  
   - If the frame length is 8 and the keypad nibble inversion check passes, the key number is reported.  
   - Otherwise the frame is silently discarded.
5. **Ready for next read** – The buffer index is set to zero immediately after the timeout, so a new card can be processed right away.

## Notes

- The 80 ms timeout works for virtually all standard Wiegand readers. If you have an exceptionally slow reader, adjust the `period` value in `self.timer.init(period=...)` inside the source.
- No debouncing is applied. If your hardware produces spurious edges, the parity or length checks will reject the frame, and no callback will fire. This keeps the interrupt handler extremely short.
- The driver uses a pre‑allocated `bytearray` – it never allocates memory in the IRQ, making it safe for all MicroPython ports.
- If your platform does not support `Timer.ONE_SHOT`, you can replace it with a periodic timer that calls `self.timer.deinit()` on the first callback.
- This library is **not thread‑safe** – it is designed for the single‑threaded MicroPython environment.

## License

MIT License.