API Reference

`adafruit_pybadger.pybadger_base`

Base class for badge-focused CircuitPython helper library.

Author(s): Kattni Rembor

Implementation Notes

Hardware:

Software and Dependencies:

Adafruit CircuitPython firmware for the supported boards: https://circuitpython.org/downloads

class adafruit_pybadger.pybadger_base.KeyStates(scanner: Keys | ShiftRegisterKeys)

Convert keypad.Event information from the given keypad scanner into key-pressed state.

Parameters:: scanner – a keypad scanner, such as keypad.Keys

pressed(key_number: int) → bool: True if key is currently pressed, as of the last update().

update() → None: Update key information based on pending scanner events.

was_pressed(key_number: int) → bool: True if key was down at any time since the last update(), even if it was later released.

class adafruit_pybadger.pybadger_base.PyBadgerBase

PyBadger base class.

property acceleration: tuple[int, int, int]: Accelerometer data, +/- 2G sensitivity.

activity(current_time=None): Turn postpone dimming of the screen

auto_dim_display(delay: float = 5.0, movement_threshold: int = 10)

Auto-dim the display when board is not moving.

Parameters:

delay (float) – Time in seconds before display auto-dims after movement has ceased.
movement_threshold (int) – Threshold required for movement to be considered stopped. Change to increase or decrease sensitivity.

from adafruit_pybadger import pybadger

while True:
    pybadger.auto_dim_display(delay=10)

badge_background(background_color: tuple[int, int, int] = (255, 0, 0), rectangle_color: tuple[int, int, int] = (255, 255, 255), rectangle_drop: float = 0.4, rectangle_height: float = 0.5) → displayio.Group

Create a customisable badge background made up of a background color with a rectangle color block over it. Defaults are for show_badge.

Parameters:

background_color (tuple) – The color to fill the entire screen as a background, as RGB values.
rectangle_color (tuple) – The color of a rectangle that displays over the background, as RGB values.
rectangle_drop (float) – The distance from the top of the display to begin displaying the rectangle. Float represents a percentage of the display, e.g. 0.4 = 40% of the display. Defaults to 0.4.
rectangle_height (float) – The height of the rectangle. Float represents a percentage of the display, e.g. 0.5 = 50% of the display. Defaults to 0.5.

from adafruit_pybadger import pybadger

pybadger.badge_background(background_color=pybadger.WHITE,
                          rectangle_color=pybadger.PURPLE,
                          rectangle_drop=0.2, rectangle_height=0.6)

while True:
    pybadger.show_custom_badge()

badge_line(text: str = ' ', color: tuple[int, int, int] = (0, 0, 0), scale: int = 1, font: BuiltinFont | BDF | PCF = terminalio.FONT, left_justify: bool = False, padding_above: float = 0) → None

Add a line of text to the display. Designed to work with badge_background for a color-block style badge, or with image_background for a badge with a background image.

Parameters:

text (str) – The text to display. Defaults to displaying a blank line if no text is provided.
color (tuple) – The color of the line of text. Defaults to (0, 0, 0).
scale (int) – The scale of the text. Must be an integer 1 or higher. Defaults to 1.
font – The font used for displaying the text. Defaults to terminalio.FONT.
left_justify (bool) – Left-justify the line of text. Defaults to False which centers the font on the display.
padding_above (int) – Add padding above the displayed line of text. A padding_above of 1 is equivalent to the height of one line of text, 2 is equivalent to the height of two lines of text, etc. Defaults to 0.

The following example is designed to work on CLUE. To adapt for PyBadge or PyGamer, change the scale and padding_above values to fit the text to the display. Examples for CLUE, and PyBadge and PyGamer are included in the examples folder in the library repo.

from adafruit_pybadger import pybadger

pybadger.badge_background(background_color=pybadger.WHITE,
                          rectangle_color=pybadger.PURPLE,
                          rectangle_drop=0.2, rectangle_height=0.6)

pybadger.badge_line(text="@circuitpython", color=pybadger.BLINKA_PURPLE, scale=2,
                    padding_above=2)
pybadger.badge_line(text="Blinka", color=pybadger.WHITE, scale=5,
                    padding_above=3)
pybadger.badge_line(text="CircuitPython", color=pybadger.WHITE, scale=3,
                    padding_above=1)
pybadger.badge_line(text="she/her", color=pybadger.BLINKA_PINK, scale=4,
                    padding_above=4)

while True:
    pybadger.show_custom_badge()

static bitmap_qr(matrix: QRBitMatrix) → displayio.Bitmap: The QR code bitmap.

property brightness: float: Display brightness. Must be a value between 0 and 1.

image_background(image_name: str | None = None) → None

Create a bitmap image background.

Parameters:: image_name (str) – The name of the bitmap image as a string including .bmp, e.g. "Blinka.bmp". Image file name is required.

from adafruit_pybadger import pybadger

pybadger.image_background("Blinka.bmp")

while True:
    pybadger.show_custom_badge()

property light: bool: Light sensor data.

property pixels: NeoPixel: Sequence like object representing the NeoPixels on the board.

play_file(file_name: str) → None

Play a .wav file using the onboard speaker.

Parameters:: file_name (str) – The name of your .wav file in quotation marks including .wav

play_tone(frequency: int, duration: float) → None

Produce a tone using the speaker. Try changing frequency to change the pitch of the tone.

Parameters:

frequency (int) – The frequency of the tone in Hz
duration (float) – The duration of the tone in seconds

property root_group: The currently showing Group

show_badge(*, background_color: tuple[int, int, int] = (255, 0, 0), foreground_color: tuple[int, int, int] = (255, 255, 255), background_text_color: tuple[int, int, int] = (255, 255, 255), foreground_text_color: tuple[int, int, int] = (0, 0, 0), hello_font: BuiltinFont | BDF | PCF = terminalio.FONT, hello_scale: int = 1, hello_string: str = 'HELLO', my_name_is_font: BuiltinFont | BDF | PCF = terminalio.FONT, my_name_is_scale: int = 1, my_name_is_string: str = 'MY NAME IS', name_font: BuiltinFont | BDF | PCF = terminalio.FONT, name_scale: int = 1, name_string: str = 'Blinka') → None

Create a “Hello My Name is”-style badge.

Parameters:

background_color (tuple) – The color of the background. Defaults to (255, 0, 0).
foreground_color (tuple) – The color of the foreground rectangle. Defaults to (255, 255, 255).
background_text_color (tuple) – The color of the “HELLO MY NAME IS” text. Defaults to (255, 255, 255).
foreground_text_color (tuple) – The color of the name text. Defaults to (0, 0, 0).
hello_font (~BuiltinFont|~BDF|~PCF) – The font for the “HELLO” string. Defaults to terminalio.FONT.
hello_scale (int) – The size scale of the “HELLO” string. Defaults to 1.
hello_string (str) – The first string of the badge. Defaults to “HELLO”.
my_name_is_font (~BuiltinFont|~BDF|~PCF) – The font for the “MY NAME IS” string. Defaults to terminalio.FONT.
my_name_is_scale (int) – The size scale of the “MY NAME IS” string. Defaults to 1.
my_name_is_string (str) – The second string of the badge. Defaults to “MY NAME IS”.
name_font (~BuiltinFont|~BDF|~PCF) – The font for the name string. Defaults to terminalio.FONT.
name_scale (int) – The size scale of the name string. Defaults to 1.
name_string (str) – The third string of the badge - change to be your name. Defaults to “Blinka”.

from adafruit_pybadger import pybadger

while True:
    pybadger.show_badge(name_string="Blinka", hello_scale=2, my_name_is_scale=2,
                        name_scale=3)

Display a bitmap image and a text string, such as a personal image and email address.

Parameters:

image_name (str) – REQUIRED. The name of the bitmap image including .bmp, e.g. "Blinka.bmp".
name_string (str) – A name string to display along the bottom of the display, e.g. "Blinka".
name_scale (int) – The scale of name_string. Defaults to 1.
name_font (~BuiltinFont|~BDF|~PCF) – The font for the name string. Defaults to terminalio.FONT.
font_background_color (int) – The color of the font background, default is None (transparent)
font_color (int) – The font color, default is white
email_string_one (str) – A string to display along the bottom of the display, e.g. "blinka@adafruit.com".
email_scale_one (int) – The scale of email_string_one. Defaults to 1.
email_font_one (~BuiltinFont|~BDF|~PCF) – The font for the first email string. Defaults to terminalio.FONT.
email_string_two (str) – A second string to display along the bottom of the display. Use if your email address is longer than one line or to add more space between the name and email address, e.g. (blinka@) "adafruit.com".
email_scale_two (int) – The scale of email_string_two. Defaults to 1.
email_font_two (~BuiltinFont|~BDF|~PCF) – The font for the second email string. Defaults to terminalio.FONT.

from adafruit_pybadger import pybadger

while True:
    pybadger.show_business_card(image_name="Blinka.bmp", name_string="Blinka",
                                name_scale=2, email_string_one="blinka@",
                                email_string_two="adafruit.com")

show_custom_badge() → None: Call pybadger.show_custom_badge() to display the custom badge elements. If show_custom_badge() is not called, the custom badge elements will not be displayed.

show_qr_code(data: str = 'https://circuitpython.org') → None

Generate a QR code.

Parameters:: data (str) – A string of data for the QR code

from adafruit_pybadger import pybadger

while True:
    pybadger.show_qr_code("https://adafruit.com")

show_terminal() → None: Revert to terminalio screen.

start_tone(frequency: int) → None

Produce a tone using the speaker. Try changing frequency to change the pitch of the tone. Use stop_tone to stop the tone.

Parameters:: frequency (int) – The frequency of the tone in Hz

stop_tone() → None: Use with start_tone to stop the tone produced.

adafruit_pybadger.pybadger_base.load_font(fontname: str, text: str) → BDF | PCF

Load a font and glyphs in the text string

Parameters:

fontname (str) – The full path to the font file.
text (str) – The text containing the glyphs we want to load.

`adafruit_pybadger.clue`

Badge-focused CircuitPython helper library for CLUE.

Author(s): Kattni Rembor

Implementation Notes

Hardware:

Adafruit CLUE

Software and Dependencies:

Adafruit CircuitPython firmware for the supported boards: https://github.com/adafruit/circuitpython/releases

class adafruit_pybadger.clue.Buttons(a, b)

a: Alias for field number 0

b: Alias for field number 1

class adafruit_pybadger.clue.Clue

Class that represents a single CLUE.

property button: Buttons

The buttons on the board.

Example use:

from adafruit_pybadger import pybadger

while True:
    if pybadger.button.a:
        print("Button A")
    elif pybadger.button.b:
        print("Button B")

property light: This feature is not supported on CLUE.

property play_file: This feature is not supported on CLUE.

adafruit_pybadger.clue.clue = <adafruit_pybadger.clue.Clue object>: Object that is automatically created on import.

`adafruit_pybadger.magtag`

Badge-focused CircuitPython helper library for Mag Tag.

Author(s): Kattni Rembor, Tim C

Implementation Notes

Hardware:

Adafruit Mag Tag

Software and Dependencies:

Adafruit CircuitPython firmware for the supported boards: https://github.com/adafruit/circuitpython/releases

class adafruit_pybadger.magtag.Buttons(a, b, c, d)

a: Alias for field number 0

b: Alias for field number 1

c: Alias for field number 2

d: Alias for field number 3

class adafruit_pybadger.magtag.MagTag

Class that represents a single Mag Tag.

property acceleration: This feature is not supported on Mag Tag.

property button: This feature is not supported on Mag Tag.

property light: This feature is not supported on Mag Tag.

property play_file: This feature is not supported on Mag Tag.

adafruit_pybadger.magtag.magtag = <adafruit_pybadger.magtag.MagTag object>: Object that is automatically created on import.

`adafruit_pybadger.pewpewm4`

Badge-focused CircuitPython helper library for Pew Pew M4.

Author(s): Kattni Rembor

Implementation Notes

Hardware:

Pew Pew M4

Software and Dependencies:

Adafruit CircuitPython firmware for the supported boards: https://github.com/adafruit/circuitpython/releases

class adafruit_pybadger.pewpewm4.Buttons(o, x, z, right, down, up, left)

down: Alias for field number 4

left: Alias for field number 6

o: Alias for field number 0

right: Alias for field number 3

up: Alias for field number 5

x: Alias for field number 1

z: Alias for field number 2

class adafruit_pybadger.pewpewm4.PewPewM4

Class that represents a single Pew Pew M4.

property acceleration: This feature is not supported on PewPew M4.

property button: Buttons

The buttons on the board.

Example use:

from adafruit_pybadger import pybadger

while True:
    if pybadger.button.x:
        print("Button X")
    elif pybadger.button.o:
        print("Button O")

property light: This feature is not supported on PewPew M4.

property pixels: This feature is not supported on PewPew M4.

adafruit_pybadger.pewpewm4.pewpewm4 = <adafruit_pybadger.pewpewm4.PewPewM4 object>: Object that is automatically created on import.

`adafruit_pybadger.pybadge`

Badge-focused CircuitPython helper library for PyBadge, PyBadge LC and EdgeBadge. All three boards are included in this module as there is no difference in the CircuitPython builds at this time, and therefore no way to differentiate the boards from within CircuitPython.

Author(s): Kattni Rembor

Implementation Notes

Hardware:

Software and Dependencies:

Adafruit CircuitPython firmware for the supported boards: https://github.com/adafruit/circuitpython/releases

class adafruit_pybadger.pybadge.Buttons(b, a, start, select, right, down, up, left)

a: Alias for field number 1

b: Alias for field number 0

down: Alias for field number 5

left: Alias for field number 7

right: Alias for field number 4

select: Alias for field number 3

start: Alias for field number 2

up: Alias for field number 6

class adafruit_pybadger.pybadge.PyBadge

Class that represents a single PyBadge, PyBadge LC, or EdgeBadge.

property button: Buttons

The buttons on the board.

Example use:

from adafruit_pybadger import pybadger

while True:
    if pybadger.button.a:
        print("Button A")
    elif pybadger.button.b:
        print("Button B")
    elif pybadger.button.start:
        print("Button start")
    elif pybadger.button.select:
        print("Button select")

adafruit_pybadger.pybadge.pybadge = <adafruit_pybadger.pybadge.PyBadge object>: Object that is automatically created on import.

`adafruit_pybadger.pygamer`

Badge-focused CircuitPython helper library for PyGamer.

Author(s): Kattni Rembor

Implementation Notes

Hardware:

Adafruit PyGamer

Software and Dependencies:

Adafruit CircuitPython firmware for the supported boards: https://github.com/adafruit/circuitpython/releases

class adafruit_pybadger.pygamer.Buttons(b, a, start, select, right, down, up, left)

a: Alias for field number 1

b: Alias for field number 0

down: Alias for field number 5

left: Alias for field number 7

right: Alias for field number 4

select: Alias for field number 3

start: Alias for field number 2

up: Alias for field number 6

class adafruit_pybadger.pygamer.PyGamer

Class that represents a single PyGamer.

property button: Buttons

The buttons on the board.

Example use:

from adafruit_pybadger import pybadger

while True:
    if pybadger.button.a:
        print("Button A")
    elif pybadger.button.b:
        print("Button B")
    elif pybadger.button.start:
        print("Button start")
    elif pybadger.button.select:
        print("Button select")

property joystick: Tuple[int, int]: The joystick on the PyGamer.

adafruit_pybadger.pygamer.pygamer = <adafruit_pybadger.pygamer.PyGamer object>: Object that is automatically created on import.

`adafruit_pybadger.pyportal`

Badge-focused CircuitPython helper library for PyPortal.

Author(s): Kattni Rembor

Implementation Notes

Hardware:

Adafruit PyPortal

Software and Dependencies:

Adafruit CircuitPython firmware for the supported boards: https://github.com/adafruit/circuitpython/releases

class adafruit_pybadger.pyportal.PyPortal

Class that represents a single PyPortal.

property acceleration: This feature is not supported on PyPortal.

property auto_dim_display: This feature is not supported on PyPortal.

property button: This feature is not supported on PyPortal.

adafruit_pybadger.pyportal.pyportal = <adafruit_pybadger.pyportal.PyPortal object>: Object that is automatically created on import.

API Reference

adafruit_pybadger.pybadger_base

Implementation Notes

adafruit_pybadger.clue

Implementation Notes

adafruit_pybadger.magtag

Implementation Notes

adafruit_pybadger.pewpewm4

Implementation Notes

adafruit_pybadger.pybadge

Implementation Notes

adafruit_pybadger.pygamer

Implementation Notes

adafruit_pybadger.pyportal

Implementation Notes

`adafruit_pybadger.pybadger_base`

`adafruit_pybadger.clue`

`adafruit_pybadger.magtag`

`adafruit_pybadger.pewpewm4`

`adafruit_pybadger.pybadge`

`adafruit_pybadger.pygamer`

`adafruit_pybadger.pyportal`