CircuitPython driver for Adafruit PyPortal.

  • Author(s): Limor Fried, Kevin J. Walters

Implementation Notes


Software and Dependencies:

class adafruit_pyportal.Fake_Requests(filename)

For faking ‘requests’ using a local file instead of the network.


json parsed version for local requests.

class adafruit_pyportal.PyPortal(*, url=None, headers=None, json_path=None, regexp_path=None, default_bg=0, status_neopixel=None, text_font=None, text_position=None, text_color=8421504, text_wrap=False, text_maxlen=0, text_transform=None, json_transform=None, image_json_path=None, image_resize=None, image_position=None, image_dim_json_path=None, caption_text=None, caption_font=None, caption_position=None, caption_color=8421504, image_url_path=None, success_callback=None, esp=None, external_spi=None, debug=False)

Class representing the Adafruit PyPortal.

  • url – The URL of your data source. Defaults to None.
  • headers – The headers for authentication, typically used by Azure API’s.
  • json_path – The list of json traversal to get data out of. Can be list of lists for multiple data points. Defaults to None to not use json.
  • regexp_path – The list of regexp strings to get data out (use a single regexp group). Can be list of regexps for multiple data points. Defaults to None to not use regexp.
  • default_bg – The path to your default background image file or a hex color. Defaults to 0x000000.
  • status_neopixel – The pin for the status NeoPixel. Use board.NEOPIXEL for the on-board NeoPixel. Defaults to None, no status LED
  • text_font (str) – The path to your font file for your data text display.
  • text_position – The position of your extracted text on the display in an (x, y) tuple. Can be a list of tuples for when there’s a list of json_paths, for example
  • text_color – The color of the text, in 0xRRGGBB format. Can be a list of colors for when there’s multiple texts. Defaults to None.
  • text_wrap – Whether or not to wrap text (for long text data chunks). Defaults to False, no wrapping.
  • text_maxlen – The max length of the text for text wrapping. Defaults to 0.
  • text_transform – A function that will be called on the text before display
  • json_transform – A function or a list of functions to call with the parsed JSON. Changes and additions are permitted for the dict object.
  • image_json_path – The JSON traversal path for a background image to display. Defaults to None.
  • image_resize – What size to resize the image we got from the json_path, make this a tuple of the width and height you want. Defaults to None.
  • image_position – The position of the image on the display as an (x, y) tuple. Defaults to None.
  • image_dim_json_path – The JSON traversal path for the original dimensions of image tuple. Used with fetch(). Defaults to None.
  • success_callback – A function we’ll call if you like, when we fetch data successfully. Defaults to None.
  • caption_text (str) – The text of your caption, a fixed text not changed by the data we get. Defaults to None.
  • caption_font (str) – The path to the font file for your caption. Defaults to None.
  • caption_position – The position of your caption on the display as an (x, y) tuple. Defaults to None.
  • caption_color – The color of your caption. Must be a hex value, e.g. 0x808000.
  • image_url_path – The HTTP traversal path for a background image to display. Defaults to None.
  • esp – A passed ESP32 object, Can be used in cases where the ESP32 chip needs to be used before calling the pyportal class. Defaults to None.
  • external_spi (busio.SPI) – A previously declared spi object. Defaults to None.
  • debug – Turn on debug print outs. Defaults to False.

Fetch data from the url we initialized with, perfom any parsing, and display text or graphics. This function does pretty much everything Optionally update the URL


Fetch and “set” the local time of this microcontroller to the local time at the location, using an internet time API.

Parameters:location (str) – Your city and country, e.g. "New York, US".

Clear any QR codes that are currently on the screen

static image_converter_url(image_url, width, height, color_depth=16)

Generate a converted image url from the url passed in, with the given width and height. aio_username and aio_key must be set in secrets.


The status NeoPixel.

Parameters:value – The color to change the NeoPixel.
play_file(file_name, wait_to_finish=True)

Play a wav file.

Parameters:file_name (str) – The name of the wav file to play on the speaker.

Preload font.

Parameters:glyphs – The font glyphs to load. Defaults to None, uses alphanumeric glyphs if None.
push_to_io(feed_key, data)

Push data to an feed

  • feed_key (str) – Name of feed key to push data to.
  • data – data to send to feed

Returns True if there is an SD card preset and False if there is no SD card. The _sdcard value is set in _init

set_background(file_or_color, position=None)

The background image to a bitmap file.

Parameters:file_or_color – The filename of the chosen background image, or a hex color.

Adjust the TFT backlight.

Parameters:val – The backlight brightness. Use a value between 0 and 1, where 0 is off, and 1 is 100% brightness.
set_caption(caption_text, caption_position, caption_color)

A caption. Requires setting caption_font in init!

  • caption_text – The text of the caption.
  • caption_position – The position of the caption text.
  • caption_color – The color of your caption text. Must be a hex value, e.g. 0x808000.

Set the headers used by fetch().

Parameters:headers – The new header dictionary
set_text(val, index=0)

Display text, with indexing into our list of text boxes.

  • val (str) – The text to be displayed
  • index – Defaults to 0.
show_QR(qr_data, *, qr_size=1, x=0, y=0, hide_background=False)

Display a QR code on the TFT

  • qr_data – The data for the QR code.
  • qr_size (int) – The scale of the QR code.
  • x – The x position of upper left corner of the QR code on the display.
  • y – The y position of upper left corner of the QR code on the display.
  • hide_background – Show the QR code on a black background if True.
wget(url, filename, *, chunk_size=12000)

Download a url and save to filename location, like the command wget.

  • url – The URL from which to obtain the data.
  • filename – The name of the file to save the data to.
  • chunk_size – how much data to read/write at a time.
static wrap_nicely(string, max_chars)

A helper that will return a list of lines with word-break wrapping.

  • string (str) – The text to be wrapped.
  • max_chars (int) – The maximum number of characters on a line before wrapping.