Initial documentation work

README.md

@@ -1,5 +1,58 @@
-# PicoFX
+# PicoFX - A RGB and Mono LED effects system for MicroPython <!-- omit in toc -->
 
-## A tiny RGB and Mono LED effects sequencer for MicroPython
+This repository is home to the PicoFX library, as well as MicroPython builds for supported boards like the Pimoroni TinyFX.
 
+[![Build Status](https://img.shields.io/github/actions/workflow/status/pimoroni/picofx/micropython.yml?branch=main&label=MicroPython)](https://github.com/pimoroni/picofx/actions/workflows/micropython.yml)
+[![GitHub release (latest by date)](https://img.shields.io/github/v/release/pimoroni/picofx)](https://github.com/pimoroni/picofx/releases/latest/)
 
+- [Introduction](#introduction)
+- [Download MicroPython for TinyFX](#download-micropython-for-tinyfx)
+  - [Firmware Only](#firmware-only)
+  - [With Libraries and Examples](#with-libraries-and-examples)
+- [Flashing the Firmware](#flashing-the-firmware)
+- [TinyFX Examples](#tinyfx-examples)
+
+
+## Introduction
+
+PicoFX is a MicroPython library for easily playing effects on mono and RGB leds.
+
+## Download MicroPython for TinyFX
+
+All TinyFX boards come pre-flashed with MicroPython and the libraries and examples needed to get you started. The instructions below are for if you wish to update your board to the latest firmware or restore it back to a factory state.
+
+Grab the latest release from [https://github.com/pimoroni/picofx/releases/latest](https://github.com/pimoroni/picofx/releases/latest)
+
+There are two .uf2 files to pick from:
+
+### Firmware Only
+
+* `tinyfx-vX.X.X-pimoroni-micropython.uf2`
+
+This build includes only the firmware needed for TinyFX to function. You will need to manually update the `lib/picofx` library afterwards to get the latest features and bug fixes.
+
+
+### With Libraries and Examples
+
+:warning: **This option will overwrite the entire contents of your TinyFX! Be sure to back up files to your PC before installing!**
+
+* `tinyfx-vX.X.X-pimoroni-micropython-with-libs-and-examples.uf2 `
+
+This build contains both the firmware for TinyFX, library files to easily create effects, and examples to get you going.
+
+## Flashing the Firmware
+
+1. Connect TinyFX to your computer using a USB A to C cable.
+
+2. Put your board into bootloader mode by holding the BOOT button whilst tapping the RST button.
+
+3. Drag and drop one of the `tinyfx-vX.X.X...` .uf2 files to the "RPI-RP2" drive that appears.
+
+5. After the copy completes your board should reset and, if you used the `with-libs-and-examples` variant, should start playing a wave sequence on the mono outputs, and a rainbow on the RGB output.
+
+
+## TinyFX Examples
+
+There are many examples to get you started with TinyFX, located in the examples folder of this repository:
+
+* [Examples](/examples/tiny_fx/README.md)

examples/tiny_fx/README.md

@@ -0,0 +1,56 @@
+# TinyFX Micropython Examples <!-- omit in toc -->
+
+These are micropython examples for the Pimoroni [TinyFX](https://shop.pimoroni.com/products/tiny_fx), a stamp-sized light and sound effects controller board for model making, construction kits, and dioramas.
+
+- [Function Examples](#function-examples)
+- [Effect Examples](#effect-examples)
+  - [Traffic Light](#traffic-light)
+  - [Wave Sequence](#wave-sequence)
+- [Audio Examples](#audio-examples)
+- [Showcase Examples](#showcase-examples)
+  - [Ship Thrusters](#ship-thrusters)
+  - [Space Tales](#space-tales)
+  - [Space Tales with PIR Sensor](#space-tales-with-pir-sensor)
+
+
+## Function Examples
+
+
+
+## Effect Examples
+
+### Traffic Light
+[effects/traffic_light.py](effects/traffic_light.py)
+
+Play a traffic light sequence on TinyFX's outputs.
+
+
+### Wave Sequence
+[effects/wave.py](effects/wave.py)
+
+Read Yukon's onboard Buttons.
+
+
+## Audio Examples
+
+
+
+## Showcase Examples
+
+### Ship Thrusters
+[showcase/ship_thrusters.py](showcase/ship_thrusters.py)
+
+Play a set of flickering thruster effects on a model spaceship, with an RGB light used for planetshine underglow.
+
+
+### Space Tales
+[showcase/space_tales.py](showcase/space_tales.py)
+
+Play effects for each space themed "postcard".
+
+
+### Space Tales with PIR Sensor
+[showcase/space_tales_pir.py](showcase/space_tales_with_pir.py)
+
+Play effects for each space themed "postcard" when someone walks past.
+A PIR sensor is used to activate the effect, which will turn off after a certain time.

picofx/README.md

@@ -0,0 +1,119 @@
+# PicoFX - Library Reference <!-- omit in toc -->
+
+This is the library reference for the PicoFX library.
+
+- [LEDs](#leds)
+  - [PWMLED](#pwmled)
+  - [RGBLED](#rgbled)
+- [Players](#players)
+  - [MonoPlayer](#monoplayer)
+  - [ColourPlayer](#colourplayer)
+  - [StripPlayer](#stripplayer)
+  - [Common](#common)
+- [Effects System](#effects-system)
+
+
+## LEDs
+
+Two classes are offered for controlling LEDs:
+* `PWMLED` - This is for controlling a single LED using a PWM output
+* `RGBLED` - This is for controlling a three LEDs, as red, green, and blue, using PWM outputs
+
+### PWMLED
+
+```python
+# Initialisation
+PWMLED(pin: int, invert: bool=False, gamma: float=1)
+
+# Brightness Control
+brightness(brightness: float) -> None
+on() -> None
+off() -> None
+toggle() -> None
+```
+
+### RGBLED
+
+```python
+# Initialisation
+RGBLED(r: Pin | PWMLED, g: Pin | PWMLED, b: Pin | PWMLED, invert: bool=True, gamma: float=1)
+
+# Variables
+led_r: PWMLED
+led_g: PWMLED
+led_b: PWMLED
+
+# Colour Control
+set_rgb(r: int | float, g: int | float, b: int | float) -> None
+set_hsv(h: float, s: float, v: float) -> None
+```
+
+
+## Players
+
+Players are classes that deal with taking brightnesses and colours from effects and applying them to a set of LEDs.
+There is a common `EffectPlayer` class, and three subclasses to support specific LED types:
+* `MonoPlayer` - controls a set of `PWMLED` objects
+* `ColourPlayer` - controls a set of `RGBLED` objects
+* `StripPlayer` - controls a strip of `WS2812` or `APA102` LEDs. These classes come from the Pimoroni [Plasma library](https://github.com/pimoroni/pimoroni-pico/tree/main/micropython/modules/plasma).
+
+
+### MonoPlayer
+
+```python
+# Initialisation
+MonoPlayer(mono_leds: PWMLED | list[PWMLED])
+```
+
+
+### ColourPlayer
+
+```python
+# Initialisation
+ColourPlayer(rgb_leds: RGBLED | list[RGBLED])
+```
+
+
+### StripPlayer
+
+```python
+# Initialisation
+StripPlayer(rgb_leds : WS2812 | APA102, num_leds: int=60)
+```
+
+
+### Common
+```python
+# Constants
+DEFAULT_FPS = 100
+
+# Player Control
+start(fps: int=DEFAULT_FPS, force: bool=False) -> None
+stop(reset_fx: bool=False) -> None
+is_running() -> bool
+
+# Synchronisation
+pair(player: EffectPlayer) -> None
+
+# Properties
+effects: tuple[Any]
+effects(effect_list: Any | list[Any]) -> None
+```
+
+## Effects System
+
+The effect system is quite flexible, accepting any `callable` object, be it a function or a class. Using classes is preferred, by implementing their `__call__` method as this lets their state be changed over time. For example:
+
+```python
+class StaticFX:
+    def __init__(self, brightness=1.0):
+        self.brightness = brightness
+
+    def __call__(self):
+        return self.brightness
+```
+
+For creating dynamic effects, classes can inherit from two types, `Updateable` and `Cycling`:
+
+* `Updateable` gives an effect the `ticks_ms(delta_ms)` function, letting the effect change over time.
+* `Cycling` is an extension of `Updateable` that pre-implements a cycling counter within `ticks_ms` giving the `__call__` method access to a `__offset` variable that counts up from 0.0 to 1.0 and repeats.