Metadata-Version: 2.1
Name: sprig-essentials
Version: 0.2.0
Summary: Useful functions for creating games and apps with Sprig
Author-email: Sooraj Sannabhadti <developer.soorajs@gmail.com>
Project-URL: Homepage, https://github.com/WhenLifeHandsYouLemons/sprig-essentials
Project-URL: Bug Tracker, https://github.com/WhenLifeHandsYouLemons/sprig-essentials/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE

# sprig-essentials 0.2.0

Useful functions to simplify the process of creating games and apps with Sprig.

[![Upload Python Package](https://github.com/WhenLifeHandsYouLemons/sprig-essentials/actions/workflows/python-publish.yml/badge.svg)](https://github.com/WhenLifeHandsYouLemons/sprig-essentials/actions/workflows/python-publish.yml)

_**This package is not affiliated with Sprig or HackClub in any form.**_

## Installation

To install `sprig-essentials`, use:

```txt
pip install sprig-essentials
```

# Documentation

This package is intended to run on any type of `Raspberry Pi`.
Most focused on the `Raspberry Pi Pico H`.

This package assumes you've installed `CircuitPython` and are using the `ST7735` display.

## Wiring Diagram

The wiring diagram that this package assumes is intended for anyone using a Sprig, however, you can also wire this manually and achieve the same effect.

![Image showing the pin connections from the Raspberry Pi Pico H to the various peripherals on the Sprig's board](https://camo.githubusercontent.com/d9b4afd8b99cc6befd3e04bdb8231c9fd134333ebd6a17166ca391429221ff05/68747470733a2f2f70617065722d6174746163686d656e74732e64726f70626f782e636f6d2f735f303531314241344231393135393837353345434243343935363743303632334234453646313535314241453338333243443842384232454441463236464142365f313636323537323037313339375f53637265656e2b53686f742b323032322d30392d30372b61742b312e33342e32312b504d2e706e67 "Taken from 'https://github.com/hackclub/sprig/blob/main/docs/GROWING_A_SPRIG.md'")

Here's a clearer electrical wiring diagram:

![Image showing the electric wiring diagram for the Raspberry Pi Pico H and the Sprig](https://camo.githubusercontent.com/f0ff037c476cfa07603e9c8ec77394ee53f18701c89f509a2852b623583d1807/68747470733a2f2f70617065722d6174746163686d656e74732e64726f70626f782e636f6d2f735f303531314241344231393135393837353345434243343935363743303632334234453646313535314241453338333243443842384232454441463236464142365f313636323537313738303737365f53637265656e2b53686f742b323032322d30392d30372b61742b312e31322e35372b504d2e706e67 "Taken from 'https://github.com/hackclub/sprig/blob/main/docs/GROWING_A_SPRIG.md'")

## Display

### Imports

You will need to import the following to connect to the pins and use the package.

```python
import board
import sprig_essentials as se
```

If you're using a Sprig, chances are the wiring is going to be the exact same through the board, so you can skip to [`quickStartDisplay()`](#quickstartdisplay).

### `startBacklight()`

```python
def startBacklight(backlight_pin):
    # Create the digital output
    backlight = digitalio.DigitalInOut(backlight_pin)
    # Set it as output
    backlight.direction = digitalio.Direction.OUTPUT
    # Turn it on
    backlight.value = True
    return backlight
```

This function takes in the pin number where the `LITE` pin on the display is connected to (formatted like so: `board.GP0`), and turns the backlight on.

It returns an object of type `digitalio.DigitalInOut` which will be used in other functions.

Example:

```python
import board
backlight = startBacklight(board.GP17)
```

### `createSPI()`

```python
def createSPI(clock_pin, MOSI_pin, MISO_pin):
    spi = busio.SPI(clock=clock_pin, MOSI=MOSI_pin, MISO=MISO_pin)
    return spi
```

This function takes in 3 pin numbers (formatted like so: `board.GP0`) and creates an SPI which will be used when creating a display bus.

It returns an object of type `busio.SPI`.

Example:

```python
import board
spi = createSPI(board.GP18, board.GP19, board.GP16)
```

### `createDisplayBus()`

```python
def createDisplayBus(spi, cs_pin, dc_pin, reset_pin):
    display_bus = displayio.FourWire(spi, command=dc_pin, chip_select=cs_pin, reset=reset_pin)
    return display_bus
```

This function takes in 3 pin numbers (formatted like so: `board.GP0`) along with an SPI (_See [`createSPI()`](#createspi)_) and creates a display bus.

It returns an object of type `displayio.FourWire`.

Example:

```python
import board
spi = createSPI(board.GP18, board.GP19, board.GP16)
display_bus = createDisplayBus(spi, board.GP20, board.GP22, board.GP26)
```

### `initDisplay()`

```python
def initDisplay(display_bus, width, height, rotation=0, bgr=True, auto_refresh=True):
    display = ST7735R(display_bus, width=width, height=height, rotation=rotation, bgr=bgr)
    display.auto_refresh = auto_refresh
    return display
```

This function requires a display bus (_See [`createDisplayBus()`](#createdisplaybus)_), and the screen's width and height as an integer.

There are 3 optional parameters: the rotation which should be a multiple of 90 degrees, the colour format (depends on the type of screen), and whether the display should auto-refresh or not.

Example:

```python
import board
spi = createSPI(board.GP18, board.GP19, board.GP16)
display_bus = createDisplayBus(spi, board.GP20, board.GP22, board.GP26)
display = initDisplay(display_bus, 160, 128, rotation=270)
```

### `quickStartDisplay()`

```python
def quickStartDisplay():
    backlight = startBacklight(board.GP17)
    spi = createSPI(board.GP18, board.GP19, board.GP16)
    display_bus = createDisplayBus(spi, board.GP20, board.GP22, board.GP26)
    display = initDisplay(display_bus, 160, 128, rotation=270)
    return backlight, spi, display_bus, display
```

This function assumes you're using a Sprig, meaning the pin wiring will be the same across all of them. The display and Raspberry Pi Pico should be the same model and therefore these users can simply use this function rather than set the parameters manually using the previous functions.

Example:

```python
backlight, spi, display_bus, display = quickStartDisplay()
```

Using this also doesn't require importing `board`.

_**Documentation unfinished**_

## Audio

### `createI2S()`

```python
def createI2S(bit_clock_pin, word_select_pin, data_pin):
    i2s = audiobusio.I2SOut(bit_clock_pin, word_select_pin, data_pin)
    return i2s
```

This function takes in 3 numbers (formatted like so: `board.GP0`) and creates an I2S. The return is an `audiobusio.I2SOut` that can be used to play a sound.

Example:

```python
import board
i2s = createI2S(board.GP10, board.GP11, board.GP9)
```
