qwstpad-micropython 0.0.1
Micropython library for the Pimoroni QwSTPad

# QwSTPad MicroPython

The [Pimoroni QwSTPad](https://shop.pimoroni.com/products/qwstpad) is an I2C mini gamepad with 10 buttons and 4 status LEDs. The buttons are arranged as two four-way directional pads with two independent buttons in the middle.


## Getting Started

To start using QwSTPad in your project, you will first need to import the `QwSTPad` class and one of its four addresses:

```python
from machine import I2C
from qwstpad import QwSTPad
from qwstpad import DEFAULT_ADDRESS as ADDRESS
```

:information_source: Up to four QwSTPads can be used at once for multiplayer fun. Change the address of a QwSTPad on its rear using the two cuttable traces.

Next, create an I2C object on the correct bus and pins for your QwST port:

```python
i2c = I2C(id=0, scl=4, sda=3)   # Typical pins used by our products
```

This is what we will use to communicate to the QwSTPad.

Finally, create a `QwSTPad` object and pass it the `I2C` instance and the `ADDRESS`. It can be helpful to wrap this in a `try except` block in case communication with the QwSTPad fails due to an incorrect address or bad connection.

```python
try:
    pad = QwSTPad(i2c, ADDRESS)
except OSError:
    print("QwSTPad: Not Connected ... Exiting")
    raise SystemExit

print("QwSTPad: Connected ... Starting")
```

By default, any connected QwSTPad will turn on an LED that corresponds with its I2C address, making it easy to identify controllers if multiple are connected at once (for a 4 player mini-game perhaps). This function can be disabled by adding `, show_address=False` when creating the `QwSTPad` object.


## Reading the Buttons

To read the buttons on QwSTPad, simply call `.read_buttons()` on the `QwSTPad` object:

```python
buttons = pad.read_buttons()
```

This will return an ordered dictionary of all the button states at a single moment in time. To then get a button's state, address the dictionary with the character of the button:

```python
if buttons['U']:
    # Up pressed
else:
    # Up unpressed
```

Supported characters are `A`, `B`, `X`, `Y`, `U`, `D`, `L`, `R`, `+`, and `-`.

It is also possible to print out all the button states, using the following for loop:

```python
for key, value in buttons.items():
    print(f"{key} = {value:n}", end=", ")
print()
```

## Setting the LEDs

The four status LEDs on QwSTPad can be set in one of two ways. The first is by calling `.set_led()` on the `QwSTPad` object, passing it the number of the LED (from `1` to `4`) along with either `True` to turn the LED on or `False` to turn the LED off. E.g.

```python
pad.set_led(1, True)
pad.set_led(2, False)
pad.set_led(3, False)
pad.set_led(4, True)
```

The second way is to set all four LEDs at once using the `.set_leds()` function. This takes in an integer from `0` to `15`. These correspond to the binary representations `0b0000` and `0b1111`. Here is how a wave effect could be played on the LEDs using this function:

```python
while True:
    pad.set_leds(0b1000)
    time.sleep(0.2)
    pad.set_leds(0b0100)
    time.sleep(0.2)
    pad.set_leds(0b0010)
    time.sleep(0.2)
    pad.set_leds(0b0001)
    time.sleep(0.2)
```

Related to this, there is the `.address_code()` function. This returns an integer representing the I2C address of the connected QwSTPad, that can be passed directly into `.set_leds()`.

```python
pad.set_leds(pad.address_code())
```

This happens by default when first creating the `QwSTPad` object, but can be useful to call again, in case you have changed the LEDs at any point. For example to flash when a player takes damage.

The final LED function is `.clear_leds()`, which turns all the LEDs off. This is a shorthand for `.set_leds(0)` and can be handy for calling at the end of your program.


## `qwstpad` Module Reference

### Constants

```python
NUM_LED = 4
NUM_BUTTONS = 10

DEFAULT_ADDRESS = 0x21
ALT_ADDRESS_1 = 0x23
ALT_ADDRESS_2 = 0x25
ALT_ADDRESS_3 = 0x27
ADDRESSES = (DEFAULT_ADDRESS, ALT_ADDRESS_1, ALT_ADDRESS_2, ALT_ADDRESS_3)
```

## `QwSTPad` Class Reference

### Constants

```python
# Registers
INPUT_PORT0 = 0x00
INPUT_PORT1 = 0x01
OUTPUT_PORT0 = 0x02
OUTPUT_PORT1 = 0x03
POLARITY_PORT0 = 0x04
POLARITY_PORT1 = 0x05
CONFIGURATION_PORT0 = 0x06
CONFIGURATION_PORT1 = 0x07

# Mappings
BUTTON_MAPPING = OrderedDict({'A': 0xE, 'B': 0xC, 'X': 0xF, 'Y': 0xD,
                              'U': 0x1, 'D': 0x4, 'L': 0x2, 'R': 0x3,
                              '+': 0xB, '-': 0x5
                             })
LED_MAPPING = (0x6, 0x7, 0x9, 0xA)
```

### Functions

```python
# Initialisation
QwSTPad(i2c: I2C | PimoroniI2C,
        address: int=DEFAULT_ADDRESS,
        show_address: bool=True)

# Special
address_code() -> int

# Buttons
read_buttons() -> OrderedDict()

# LEDs
set_leds(states: int) -> None
set_led(led: int, state: bool | int) -> None
clear_leds() -> None
```
# Changelog

0.0.1
-----

* Initial Release