import time
from adafruit_matrixportal.matrix import Matrix
from messageboard import MessageBoard
from messageboard.fontpool import FontPool
from messageboard.message import Message
matrix = Matrix(width=128, height=16, bit_depth=5)
messageboard = MessageBoard(matrix)
fontpool = FontPool()
message = Message(fontpool.find_font("terminal"))
message.add_text("Hello World")
messageboard.animate(message, "Static", "show")
time.sleep(5)
You will need to import Matrix, MessageBoard, FontPool, and Message. Matrix uses the MatrixPortal library. See the Creating MatrixPortal Projects with CircuitPython guide for more details on that library. The matrix object is the only thing needed to pass in to create a MessageBoard object.
When FontPool is initialized, the terminal font is automatically added in, so that's available without doing anything further.
Finally, a message is created using the terminal font. The text "Hello World" is added, and the show animation is called. The message displays for 5 seconds before finishing the code.
Animations
There are quite a few animations available. To call an animation function, the animate function of the messageboard object is called, along with the Class name and function name of the animation. For instance, looking at the basic usage, the show function of the Static class is called. Here is a list of animations included:
Static Animations
Static animations keep a message in its last position, which is why this group is called static. These are used to show or hide text in various ways. If you would like to set the position manually, you can call messageboard.set_message_position(x, y) before animating the text.
Call messageboard.animate(message, "Static", "show") to show a message at its current position instantly.
Call messageboard.animate(message, "Static", "blink", count=3, duration=1) to blink a message on and off a certain number of times expressed by count (default of 3) over the duration time (default of 1 second).
Call messageboard.animate(message, "Static", "fade_in", duration=1) to fade a message in over the duration time (default of 1 second).
Call messageboard.animate(message, "Static", "fade_out", duration=1) to fade a message in over the duration time (default of 1 second).
Call messageboard.animate(message, "Static", "flash", count=3, duration=1) to fade a message in and out a certain number of times expressed by count (default of 3) over the duration time (default of 1 second).
Call messageboard.animate(message, "Scroll", "in_from_left", duration=1) to scroll a message into frame from the left over the duration time (default of 1 second).
Call messageboard.animate(message, "Scroll", "in_from_right", duration=1) to scroll a message into frame from the right over the duration time (default of 1 second).
Call messageboard.animate(message, "Scroll", "in_from_top", duration=1) to scroll a message into frame from the top over the duration time (default of 1 second).
Call messageboard.animate(message, "Scroll", "in_from_bottom", duration=1) to scroll a message into frame from the bottom over the duration time (default of 1 second).
Call messageboard.animate(message, "Scroll", "out_to_left", duration=1) to scroll a message out of frame to the left over the duration time (default of 1 second).
Call messageboard.animate(message, "Scroll", "out_to_right", duration=1) to scroll a message out of frame to the right over the duration time (default of 1 second).
Call messageboard.animate(message, "Scroll", "out_to_top", duration=1) to scroll a message out of frame towards the top over the duration time (default of 1 second).
Call messageboard.animate(message, "Scroll", "out_to_from", duration=1) to scroll a message out of frame towards the bottom over the duration time (default of 1 second).
Loop Animations
Similar to the scroll animations, but the message wraps around to the other side of the message board.
Call messageboard.animate(message, "Loop", "left", duration=1, count=1) to loop a message out of frame to the left and back in from the right a certain number of times expressed by count (default of 1) over the duration time (default of 1 second).
Call messageboard.animate(message, "Loop", "right", duration=1, count=1) to loop a message out of frame to the right and back in from the left a certain number of times expressed by count (default of 1) over the duration time (default of 1 second).
Call messageboard.animate(message, "Loop", "up", duration=1, count=1) to loop a message out of frame to the top and back in from the bottom a certain number of times expressed by count (default of 1) over the duration time (default of 1 second).
Call messageboard.animate(message, "Loop", "down", duration=1, count=1) to loop a message out of frame to the bottom and back in from the top a certain number of times expressed by count (default of 1) over the duration time (default of 1 second).
Split Animations
These animations are for splitting up or joining together the message either horizontally or vertically.
Call messageboard.animate(message, "Split", "out_horizontally", duration=0.5) to split a message out of frame horizontally over the duration time (default of 0.5 seconds).
Call messageboard.animate(message, "Split", "in_horizontally", duration=0.5) to join a message into frame horizontally over the duration time (default of 0.5 seconds).
Call messageboard.animate(message, "Split", "out_vertically", duration=0.5) to split a message out of frame vertically over the duration time (default of 0.5 seconds).
Call messageboard.animate(message, "Split", "in_vertically", duration=0.5) to join a message into frame vertically over the duration time (default of 0.5 seconds).
Examples
There are a couple of examples that demonstrate how to use the included messageboard library.
code.py
The one included in code.py is only slightly more complicated than the basic usage code. It also loads the Arial font, a background, and an image.
import time
from adafruit_matrixportal.matrix import Matrix
from messageboard import MessageBoard
from messageboard.fontpool import FontPool
from messageboard.message import Message
matrix = Matrix(width=128, height=16, bit_depth=5)
messageboard = MessageBoard(matrix)
messageboard.set_background("images/background.bmp")
fontpool = FontPool()
fontpool.add_font("arial", "fonts/Arial-10.pcf")
# Create the message ahead of time
message = Message(fontpool.find_font("arial"), mask_color=0xFF00FF, opacity=0.8)
message.add_image("images/maskedstar.bmp")
message.add_text("Hello World!", color=0xFFFF00, x_offset=2, y_offset=2)
For the animation, it resides in the main program loop and scrolls the message both into and out of the frame.
while True:
# Animate the message
messageboard.animate(message, "Scroll", "in_from_right")
time.sleep(1)
messageboard.animate(message, "Scroll", "out_to_left")
Here is that example code in its entirety:
# SPDX-FileCopyrightText: 2023 Melissa LeBlanc-Williams for Adafruit Industries
#
# SPDX-License-Identifier: MIT
import time
from adafruit_matrixportal.matrix import Matrix
from messageboard import MessageBoard
from messageboard.fontpool import FontPool
from messageboard.message import Message
matrix = Matrix(width=128, height=16, bit_depth=5)
messageboard = MessageBoard(matrix)
messageboard.set_background("images/background.bmp")
fontpool = FontPool()
fontpool.add_font("arial", "fonts/Arial-10.pcf")
# Create the message ahead of time
message = Message(fontpool.find_font("arial"), mask_color=0xFF00FF, opacity=0.8)
message.add_image("images/maskedstar.bmp")
message.add_text("Hello World!", color=0xFFFF00, x_offset=2, y_offset=2)
while True:
# Animate the message
messageboard.animate(message, "Scroll", "in_from_right")
time.sleep(1)
messageboard.animate(message, "Scroll", "out_to_left")
demo.py
The demo.py example is a little more complex and shows some of the capabilities using four different messages. Like the previous example, it starts off with the same imports and sets up the messageboard with a background image.
import time
from adafruit_matrixportal.matrix import Matrix
from messageboard import MessageBoard
from messageboard.fontpool import FontPool
from messageboard.message import Message
matrix = Matrix(width=128, height=16, bit_depth=5)
messageboard = MessageBoard(matrix)
messageboard.set_background("images/background.bmp")
After that, a FontPool object is created and two fonts are added to it, which will be reused.
fontpool = FontPool()
fontpool.add_font("comic", "fonts/Comic-10.pcf")
fontpool.add_font("dejavu", "fonts/DejaVuSans-10.pcf")
Next, the messages are set up. Note that the first message doesn't have any content added to it at this time because the intent is to change it inside the main loop.
message1 = Message(fontpool.find_font("dejavu"))
message2 = Message(fontpool.find_font("comic"), mask_color=0x00FF00)
print("add blinka")
message2.add_image("images/maskedblinka.bmp")
print("add text")
message2.add_text("CircuitPython", color=0xFFFF00, y_offset=-2)
message3 = Message(fontpool.find_font("dejavu"))
message3.add_text("circuitpython.com", color=0xFF0000)
message4 = Message(fontpool.find_font("arial"))
message4.add_text("Buy Electronics", color=0xFFFFFF)
In the main loop, message1 has content added and is animated. To demonstrate how the messages can be dynamically changed, this is show three more times. This would be useful for updating the message with the current time or from data on the internet.
message1.clear()
message1.add_text("Scroll Text In", color=0xFF0000)
messageboard.animate(message1, "Scroll", "in_from_left")
time.sleep(1)
message1.clear()
message1.add_text("Change Messages")
messageboard.animate(message1, "Static", "show")
time.sleep(1)
message1.clear()
message1.add_text("And Scroll Out")
messageboard.animate(message1, "Static", "show")
messageboard.animate(message1, "Scroll", "out_to_right")
time.sleep(1)
message1.clear()
message1.add_text("Or more effects like looping ", color=0xFFFF00)
messageboard.animate(message1, "Split", "in_vertically")
messageboard.animate(message1, "Loop", "left")
messageboard.animate(message1, "Static", "flash", count=3)
messageboard.animate(message1, "Split", "out_vertically")
time.sleep(1)
Here is the animation of the remaining messages. For message2, use of an alternate mask color is demonstrated and for message3, the background is changed to green prior to displaying the message and changed back to the image after.
messageboard.animate(message2, "Static", "fade_in")
time.sleep(1)
messageboard.animate(message2, "Static", "fade_out")
messageboard.set_background(0x00FF00)
messageboard.animate(message3, "Scroll", "in_from_top")
time.sleep(1)
messageboard.animate(message3, "Scroll", "out_to_bottom")
messageboard.set_background("images/background.bmp")
messageboard.animate(message4, "Scroll", "in_from_right")
time.sleep(1)
Here is that example code in its entirety:
# SPDX-FileCopyrightText: 2023 Melissa LeBlanc-Williams for Adafruit Industries
#
# SPDX-License-Identifier: MIT
import time
from adafruit_matrixportal.matrix import Matrix
from messageboard import MessageBoard
from messageboard.fontpool import FontPool
from messageboard.message import Message
matrix = Matrix(width=128, height=16, bit_depth=5)
messageboard = MessageBoard(matrix)
messageboard.set_background("images/background.bmp")
fontpool = FontPool()
fontpool.add_font("comic", "fonts/Comic-10.pcf")
fontpool.add_font("dejavu", "fonts/DejaVuSans-10.pcf")
message1 = Message(fontpool.find_font("dejavu"))
message2 = Message(fontpool.find_font("comic"), mask_color=0x00FF00)
print("add blinka")
message2.add_image("images/maskedblinka.bmp")
print("add text")
message2.add_text("CircuitPython", color=0xFFFF00, y_offset=-2)
message3 = Message(fontpool.find_font("dejavu"))
message3.add_text("circuitpython.com", color=0xFF0000)
message4 = Message(fontpool.find_font("arial"))
message4.add_text("Buy Electronics", color=0xFFFFFF)
while True:
# Set message 1 content and animate
message1.clear()
message1.add_text("Scroll Text In", color=0xFF0000)
messageboard.animate(message1, "Scroll", "in_from_left")
time.sleep(1)
# Change message 1 content and animate
message1.clear()
message1.add_text("Change Messages")
messageboard.animate(message1, "Static", "show")
time.sleep(1)
# Change message 1 content again and animate
message1.clear()
message1.add_text("And Scroll Out")
messageboard.animate(message1, "Static", "show")
messageboard.animate(message1, "Scroll", "out_to_right")
time.sleep(1)
# Change message 1 content a final time and animate
message1.clear()
message1.add_text("Or more effects like looping ", color=0xFFFF00)
messageboard.animate(message1, "Split", "in_vertically")
messageboard.animate(message1, "Loop", "left")
messageboard.animate(message1, "Static", "flash", count=3)
messageboard.animate(message1, "Split", "out_vertically")
time.sleep(1)
messageboard.animate(message2, "Static", "fade_in")
time.sleep(1)
messageboard.animate(message2, "Static", "fade_out")
messageboard.set_background(0x00FF00)
messageboard.animate(message3, "Scroll", "in_from_top")
time.sleep(1)
messageboard.animate(message3, "Scroll", "out_to_bottom")
messageboard.set_background("images/background.bmp")
messageboard.animate(message4, "Scroll", "in_from_right")
time.sleep(1)
Page last edited February 24, 2025
Text editor powered by tinymce.
