Merge pull request #592 from pimoroni/hel-festive-plasma-stick

Add festive Plasma Stick examples

micropython/examples/plasma_stick/README.md

@@ -7,8 +7,12 @@
   - [Alternating Blinkies](#alternating-blinkies)
   - [Fire](#fire)
   - [Moon](#moon)
+  - [Pulse](#pulse)
   - [Rainbows](#rainbows)
+  - [Snow](#snow)
+  - [Sparkles](#sparkles)
   - [Thermometer](#thermometer)
+  - [Tree](#tree)
 - [Advanced Examples](#advanced-examples)
   - [CO2](#co2)
   - [Encoder](#encoder)
@@ -86,18 +90,42 @@ A simple 🔥 fire effect example 🤘 (warning, flashy).
 Spooky moon simulator - the LEDs will get brighter as midnight approaches!
 Needs to be run from Thonny to get the correct time.
 
+### Pulse
+
+[pulse.py](pulse.py)
+
+Adjust the brightness or saturation of the LEDs using a sine wave.
+
 ### Rainbows
 
 [rainbows.py](rainbows.py)
 
 Some good old fashioned rainbows!
 
+### Snow
+
+[snow.py](snow.py)
+
+Snow in a bottle!
+
+### Sparkles
+
+[sparkles.py](sparkles.py)
+
+A festive, customisable sparkly effect.
+
 ### Thermometer
 
 [thermometer_pico.py](thermometer_pico.py)
 
 Reads the temperature from the Pico W's internal temperature sensor and changes the LED strip an appropriate colour.
 
+### Tree
+
+[tree.py](tree.py)
+
+A Christmas tree simulator.
+
 ## Advanced Examples
 
 These examples require additional hardware.

micropython/examples/plasma_stick/pulse.py

@@ -0,0 +1,39 @@
+import plasma
+from plasma import plasma_stick
+from math import sin
+
+"""
+Simple pulsing effect generated using a sine wave.
+"""
+
+# Set how many LEDs you have
+NUM_LEDS = 50
+
+# we're using HSV colours in this example - find more at https://colorpicker.me/
+# to convert a hue that's in degrees, divide it by 360
+COLOUR = 0.5
+
+# set up the WS2812 / NeoPixel™ LEDs
+led_strip = plasma.WS2812(NUM_LEDS, 0, 0, plasma_stick.DAT, color_order=plasma.COLOR_ORDER_RGB)
+
+# start updating the LED strip
+led_strip.start()
+
+offset = 0
+
+while True:
+    # use a sine wave to set the brightness
+    for i in range(NUM_LEDS):
+        led_strip.set_hsv(i, COLOUR, 1.0, sin(offset))
+    offset += 0.002
+
+#     # our sine wave goes between -1.0 and 1.0 - this means the LEDs will be off half the time
+#     # this formula forces the brightness to be between 0.0 and 1.0
+#     for i in range(NUM_LEDS):
+#         led_strip.set_hsv(i, COLOUR, 1.0, (1 + sin(offset)) / 2)
+#     offset += 0.002
+
+#     # adjust the saturation instead of the brightness/value
+#     for i in range(NUM_LEDS):
+#         led_strip.set_hsv(i, COLOUR, (1 + sin(offset)) / 2, 0.8)
+#     offset += 0.002

micropython/examples/plasma_stick/snow.py

@@ -0,0 +1,62 @@
+import plasma
+from plasma import plasma_stick
+from random import uniform
+
+"""
+Snow in a bottle! Always winter, never Christmas!
+Adjust SNOW_INTENSITY for more snow.
+"""
+
+# Set how many LEDs you have
+NUM_LEDS = 50
+
+# How much snow? [bigger number = more snowflakes]
+SNOW_INTENSITY = 0.0002
+
+# Change RGB colours here (RGB colour picker: https://g.co/kgs/k2Egjk )
+BACKGROUND_COLOUR = [30, 50, 50]  # dim blue
+SNOW_COLOUR = [240, 255, 255]  # bluish white
+
+# how quickly current colour changes to target colour [1 - 255]
+FADE_UP_SPEED = 255  # abrupt change for a snowflake
+FADE_DOWN_SPEED = 1
+
+
+def display_current():
+    # paint our current LED colours to the strip
+    for i in range(NUM_LEDS):
+        led_strip.set_rgb(i, current_leds[i][0], current_leds[i][1], current_leds[i][2])
+
+
+def move_to_target():
+    # nudge our current colours closer to the target colours
+    for i in range(NUM_LEDS):
+        for c in range(3):  # 3 times, for R, G & B channels
+            if current_leds[i][c] < target_leds[i][c]:
+                current_leds[i][c] = min(current_leds[i][c] + FADE_UP_SPEED, target_leds[i][c])  # increase current, up to a maximum of target
+            elif current_leds[i][c] > target_leds[i][c]:
+                current_leds[i][c] = max(current_leds[i][c] - FADE_DOWN_SPEED, target_leds[i][c])  # reduce current, down to a minimum of target
+
+
+# Create a list of [r, g, b] values that will hold current LED colours, for display
+current_leds = [[0] * 3 for i in range(NUM_LEDS)]
+# Create a list of [r, g, b] values that will hold target LED colours, to move towards
+target_leds = [[0] * 3 for i in range(NUM_LEDS)]
+
+# set up the WS2812 / NeoPixel™ LEDs
+led_strip = plasma.WS2812(NUM_LEDS, 0, 0, plasma_stick.DAT, color_order=plasma.COLOR_ORDER_RGB)
+
+# start updating the LED strip
+led_strip.start()
+
+while True:
+    for i in range(NUM_LEDS):
+        # randomly add snow
+        if SNOW_INTENSITY > uniform(0, 1):
+            # set a target to start a snowflake
+            target_leds[i] = SNOW_COLOUR
+        # slowly reset snowflake to background
+        if current_leds[i] == target_leds[i]:
+            target_leds[i] = BACKGROUND_COLOUR
+    move_to_target()   # nudge our current colours closer to the target colours
+    display_current()  # display current colours to strip

micropython/examples/plasma_stick/sparkles.py

@@ -0,0 +1,61 @@
+import plasma
+from plasma import plasma_stick
+from random import uniform
+
+"""
+A festive sparkly effect. Play around with BACKGROUND_COLOUR and SPARKLE_COLOUR for different effects!
+"""
+
+# Set how many LEDs you have
+NUM_LEDS = 50
+
+# How many sparkles? [bigger number = more sparkles]
+SPARKLE_INTENSITY = 0.005
+
+# Change your colours here! RGB colour picker: https://g.co/kgs/k2Egjk
+BACKGROUND_COLOUR = [50, 50, 0]
+SPARKLE_COLOUR = [255, 255, 0]
+
+# how quickly current colour changes to target colour [1 - 255]
+FADE_UP_SPEED = 2
+FADE_DOWN_SPEED = 2
+
+
+def display_current():
+    # paint our current LED colours to the strip
+    for i in range(NUM_LEDS):
+        led_strip.set_rgb(i, current_leds[i][0], current_leds[i][1], current_leds[i][2])
+
+
+def move_to_target():
+    # nudge our current colours closer to the target colours
+    for i in range(NUM_LEDS):
+        for c in range(3):  # 3 times, for R, G & B channels
+            if current_leds[i][c] < target_leds[i][c]:
+                current_leds[i][c] = min(current_leds[i][c] + FADE_UP_SPEED, target_leds[i][c])  # increase current, up to a maximum of target
+            elif current_leds[i][c] > target_leds[i][c]:
+                current_leds[i][c] = max(current_leds[i][c] - FADE_DOWN_SPEED, target_leds[i][c])  # reduce current, down to a minimum of target
+
+
+# Create a list of [r, g, b] values that will hold current LED colours, for display
+current_leds = [[0] * 3 for i in range(NUM_LEDS)]
+# Create a list of [r, g, b] values that will hold target LED colours, to move towards
+target_leds = [[0] * 3 for i in range(NUM_LEDS)]
+
+# set up the WS2812 / NeoPixel™ LEDs
+led_strip = plasma.WS2812(NUM_LEDS, 0, 0, plasma_stick.DAT, color_order=plasma.COLOR_ORDER_RGB)
+
+# start updating the LED strip
+led_strip.start()
+
+while True:
+    for i in range(NUM_LEDS):
+        # randomly add sparkles
+        if SPARKLE_INTENSITY > uniform(0, 1):
+            # set a target to start a sparkle
+            target_leds[i] = SPARKLE_COLOUR
+        # for any sparkles that have achieved max sparkliness, reset them to background
+        if current_leds[i] == target_leds[i]:
+            target_leds[i] = BACKGROUND_COLOUR
+    move_to_target()   # nudge our current colours closer to the target colours
+    display_current()  # display current colours to strip

micropython/examples/plasma_stick/tree.py

@@ -0,0 +1,42 @@
+import time
+import plasma
+from plasma import plasma_stick
+from random import random, choice
+
+"""
+A Christmas tree, with fairy lights!
+This will probably work better if your LEDs are in a vaguely tree shaped bottle :)
+"""
+
+# Set how many LEDs you have
+NUM_LEDS = 50
+
+# we're using HSV colours in this example - find more at https://colorpicker.me/
+# to convert a hue that's in degrees, divide it by 360
+TREE_COLOUR = [0.34, 1.0, 0.6]
+LIGHT_RATIO = 8  # every nth pixel is a light, the rest are tree.
+LIGHT_COLOURS = ((0.0, 1.0, 1.0),   # red
+                 (0.1, 1.0, 1.0),   # orange
+                 (0.6, 1.0, 1.0),   # blue
+                 (0.85, 0.4, 1.0))  # pink
+LIGHT_CHANGE_CHANCE = 0.5  # change to 0.0 if you want static lights
+
+# set up the WS2812 / NeoPixel™ LEDs
+led_strip = plasma.WS2812(NUM_LEDS, 0, 0, plasma_stick.DAT, color_order=plasma.COLOR_ORDER_RGB)
+
+# start updating the LED strip
+led_strip.start()
+
+# initial setup
+for i in range(NUM_LEDS):
+    if i % LIGHT_RATIO == 0:  # add an appropriate number of lights
+        led_strip.set_hsv(i, *choice(LIGHT_COLOURS))  # choice randomly chooses from a list
+    else:  # GREEN
+        led_strip.set_hsv(i, *TREE_COLOUR)
+
+# animate
+while True:
+    for i in range(NUM_LEDS):
+        if (i % LIGHT_RATIO == 0) and (random() < LIGHT_CHANGE_CHANCE):
+            led_strip.set_hsv(i, *choice(LIGHT_COLOURS))
+    time.sleep(0.5)

micropython/modules/breakout_bme280/README.md

@@ -1,7 +1,7 @@
 # BME280 <!-- omit in toc -->
 
 - [Getting Started](#getting-started)
-- [Reading Temperature, Pressure & Humidity](#reading-temperature-pressure--humidity)
+- [Reading Temperature, Pressure and Humidity](#reading-temperature-pressure-and-humidity)
 - [Configuring The Sensor](#configuring-the-sensor)
   - [Filter Settings](#filter-settings)
   - [Oversampling Settings](#oversampling-settings)
@@ -24,7 +24,7 @@ i2c = PimoroniI2C(**PINS_BREAKOUT_GARDEN)
 bme = BreakoutBME280(i2c)
 ```
 
-## Reading Temperature, Pressure & Humidity
+## Reading Temperature, Pressure and Humidity
 
 The `read` method will return a tuple containing Temperature (degrees C), Pressure (Pa) and Humidity (RH %) values:
 
@@ -37,7 +37,7 @@ temperature, pressure, humidity = bme.read()
 The `configure` method allows you to set up the oversampling, filtering and operation mode.
 
 ```python
-bmp.configure(filter, standby_time, os_pressure, os_humidity, os_temp, mode)
+bme.configure(filter, standby_time, os_pressure, os_humidity, os_temp, mode)
 ```
 
 The `breakout_bme280` module includes constants for these:

micropython/modules/picographics/README.md

@@ -13,11 +13,11 @@ Pico Graphics replaces the individual drivers for displays- if you're been using
     - [I2C](#i2c)
 - [Function Reference](#function-reference)
   - [General](#general)
-    - [Creating & Setting Pens](#creating--setting-pens)
+    - [Creating and Setting Pens](#creating-and-setting-pens)
       - [RGB888, RGB565, RGB332, P8 and P4 modes](#rgb888-rgb565-rgb332-p8-and-p4-modes)
       - [Monochrome Modes](#monochrome-modes)
       - [Inky Frame](#inky-frame)
-    - [Controlling The Backlight](#controlling-the-backlight)
+    - [Controlling the Backlight](#controlling-the-backlight)
     - [Clipping](#clipping)
     - [Clear](#clear)
     - [Update](#update)
@@ -136,7 +136,7 @@ display = PicoGraphics(display=DISPLAY_I2C_OLED_128X128, bus=i2cbus)
 
 ### General
 
-#### Creating & Setting Pens
+#### Creating and Setting Pens
 
 ##### RGB888, RGB565, RGB332, P8 and P4 modes
 
@@ -198,7 +198,7 @@ These are:
 * `ORANGE` = 6
 * `TAUPE` = 7
 
-#### Controlling The Backlight
+#### Controlling the Backlight
 
 You can set the display backlight brightness between `0.0` and `1.0`:
 
@@ -228,7 +228,7 @@ Clear the display to the current pen colour:
 display.clear()
 ```
 
-This is equivilent to:
+This is equivalent to:
 
 ```python
 w, h = display.get_bounds()
@@ -302,7 +302,6 @@ For example:
 display.set_font("bitmap8")
 display.text("Hello World", 0, 0, scale=2)
 ```
-
 Draws "Hello World" in a 16px tall, 2x scaled version of the `bitmap8` font.
 
 Sometimes you might want to measure a text string for centering or alignment on screen, you can do this with:
@@ -319,6 +318,15 @@ Write a single character:
 display.character(char, x, y, scale)
 ```
 
+Specify `char` using a [decimal ASCII code](https://www.ascii-code.com/). Note not all characters are supported.
+
+For example:
+```python
+display.set_font("bitmap8")
+display.character(38, 0, 0, scale=2)
+```
+Draws an ampersand in a 16px tall, 2x scaled version of the 'bitmap8' font.
+
 ### Basic Shapes
 
 #### Line
@@ -329,7 +337,7 @@ To draw a line:
 display.line(x1, y1, x2, y2)
 ```
 
-The X1/Y1 and X2/Y2 coordinates describe the start and end of the line repsectively. 
+The X1/Y1 and X2/Y2 coordinates describe the start and end of the line respectively. 
 
 #### Circle