Pixly API & User Manual

Version: 1.0Date: 2025-06-11

User Manual_Pixly.pdf

Download PDF • 13.52MB

Very important notice: Pixly — Battery & Power Guidelines

To keep Pixly performing at its best:

1. OK to stay on USB-CIt’s safe to leave Pixly plugged in. The device manages charging and deep-sleep to avoid unnecessary battery wear.

2. Long-term storageIf you won’t use Pixly for an extended period, remove both 14430 batteries and store them separately at roughly 40–60% charge. Avoid leaving cells installed and fully drained.

3. Correct battery orientation (very important)

   • Left bay: “+” faces up toward the EC11 knob.

   • Right bay: “+” faces down, away from the EC11 knob.Incorrect installation can cause permanent damage.

4. Cell health & replacementUse matched 14430 Li-ion cells (same brand/capacity/age). If Pixly becomes unresponsive after a long idle period with batteries left inside, remove the cells. Any cell below about 2.5 V may be irrecoverable and should be replaced/recycled—do not attempt to revive deeply discharged cells in-device.

5. 
   

OPEN BOX

If you've opened and disassembled Pixly MDF, here's how you can reassemble it.

Pixly_MDF_Install.pdf

Download PDF • 2.10MB

Introduction

The Pixly API provides a comprehensive, ASCII‑based command set for seamless communication between an ATmega328P and an ESP32‑S3 over a serial interface (Serial1). It enables network access, sensor readings, advanced text and graphics primitives, encoder events, and internet radio streaming.

Every command is sent from the ATmega328P to the ESP32‑S3 on Serial1 and consists of a single ASCII line terminated with \n. Responses, if any, are returned as single lines or structured blocks.

Audience

This documentation is intended for embedded firmware developers familiar with Arduino or similar development boards to customize the Pixly program using its integrated networking, display, and control features.

README

getFromAPI

SHOWNUMBER

SCROLL_NUMBER

SHOW_TEXT

SCROLL_TEXT

SCROLL_STR

The links below will lead you to examples using an Arduino helper class. While this approach offers less control over the communication between the ATMEGA328p and ESP32, it simplifies the programming process.

getFromAPI

GET_SOUND

SHOWNUMBER SCROLL_NUMBER

SHOW_TEXT SCROLL_TEXT SCROLL_STR EC11_EVENT

SETPIXEL

README

In the following README.txt, we keep track of currently tested APIs marked with 👌 and yet-to-be-fixed buggy APIs with ⚠️ or ‼️.

README.txt

Pixly ESP32 ↔ ATmega Serial API

================================

Every command is sent **from the ATmega328P** to the ESP32‑S3 on `Serial1`.

Each command is a single ASCII line terminated with `\n`.

Responses (when any) are single lines as noted below.

Legend

------

`[...]`   optional argument(s)  

`|`      separates alternative choices  

UPPERCASE arguments should be substituted by you  

`true/false` are the literal ASCII words

--------------------------------------------------------------------

🌐  Network / Sensor utilities

--------------------------------------------------------------------

👌getFromAPI <url>

    Fetch JSON at <url>.  ESP32 replies:

        BEGIN_JSON

        <payload split into <=64‑byte lines>

        END_JSON

👌GET_SOUND

    Returns raw ADC reading (0‑4095) from the LM393 sound sensor.

--------------------------------------------------------------------

💾  Numbers & Text primitives

--------------------------------------------------------------------

👌SHOWNUMBER <x> <y> <value>

👌SHOWNUMBER <x> <y> <value>  <r> <g> <b>

👌SHOWNUMBER <x> <y> <value>  <r> <g> <b>  true <dotR> <dotG> <dotB>

        Draw a 3×5 integer / float at (x,y).

        · Default colour = dim white.

        · If RGB supplied → digits use that colour (auto‑dimmed).

        · If *true* flag present → dot uses separate RGB.

👌SCROLL_NUMBER <value> <y>

👌SCROLL_NUMBER <value> <y> <speed>

👌SCROLL_NUMBER <value> <y> <speed> L|R

👌SCROLL_NUMBER <value> <y> <speed> L|R  <r> <g> <b>

👌SCROLL_NUMBER <value> <y> <speed> L|R  <r> <g> <b>  true <dotR> <dotG> <dotB>

        Continuous marquee of a number.  

        speed = ms per pixel (default 100).  

        Direction L (left) or R (right), default L.

👌STOP_SCROLL

        Halts the current number marquee and clears the buffer.

👌SHOW_TEXT "<text>" <x> <y> [r g b]

        One‑off draw of lowercase 5×5 text.

👌SCROLL_TEXT "<text>" <y> [speed] [L|R] [r g b]

        Scroll lowercase text string.

👌STOP_TEXT_SCROLL

        Stop active text marquee.

👌SCROLL_STR "<mixed>" <y> [speed] [L|R] [r g b] [true <dotR> <dotG> <dotB>]

        Marquee that can mix letters, digits and decimal points.

👌STOP_STR_SCROLL

        Stop the mixed‑string marquee.

--------------------------------------------------------------------

🎮  EC‑11 rotary encoder

--------------------------------------------------------------------

👌ENABLE_EC11

        ESP32 begins **pushing** events, one per line:

            >   clockwise step

            <   counter‑clockwise step

            P   button pressed

            R   button released

👌DISABLE_EC11

        Stops event stream.

--------------------------------------------------------------------

🖼  Icons & Graphics

--------------------------------------------------------------------

⚠️SHOWCUSTOMICON <w> <h> <x> <y>  <r0> <g0> <b0>  <r1> <g1> <b1> ... 	(Display a custom icon of given size at (x, y) using RGB pixel data)

        Blit W×H image at (x,y).  Provide W·H RGB triplets.

--------------------------------------------------------------------

🧱  Low‑level pixel control

--------------------------------------------------------------------

👌DRAWPIXEL <x> <y> <r> <g> <b> 	( Set single pixel at (x, y) to the given color)

👌CLEARSCREEN 			(Clear the entire display)

👌RENDER                   	(Push buffered display data to screen (if using deferred draw))

--------------------------------------------------------------------

📻  Internet radio  (MAX98357A DAC)

--------------------------------------------------------------------

‼️PLAY <url>               Start MP3/AAC stream.

‼️STOP                     Halt playback.

--------------------------------------------------------------------

Examples

--------------------------------------------------------------------

SHOWNUMBER 1 11 28.9 255 130 39             # orange digits, red dot

NUMBERSCROLL 123.456 4 80 L 0 255 180       # aqua‑green ticker

SHOWTXT "hello" 0 0 0 255 0                 # green static text

SCROLLTXT "weather" 10 120 R 255 100 0      # orange marquee

ENABLE_EC11                                  # start receiving encoder tokens

PLAY http://icecast.omradio.com/stream       # start radio

---

getFromAPI

Overview

• Command Name: getFromAPI

• Category: Network

• Purpose: Retrieves JSON data from a specified URL using the ESP32-S3 Wi-Fi connection and returns it to the ATmega328P.

Syntax

getFromAPI <url>

<url>: A full HTTP or HTTPS URL pointing to a resource that returns JSON data.

Function Description

The getFromAPI command is initiated by the ATmega328P via Serial communication. Upon receiving the command, the ESP32-S3 makes an HTTP GET request to the provided URL. It then returns the JSON response back to the ATmega328P in segmented lines for easy handling.

Response Format

ESP32-S3 will respond with data structured as follows:

BEGIN_JSON

<JSON payload split into lines up to 64 bytes each>

END_JSON

• BEGIN_JSON: Marks the start of the JSON data.

• END_JSON: Marks the end of the JSON data.

In case of an error (e.g., Wi-Fi disconnected), ESP32-S3 returns a JSON-formatted error starting with {"error":...}.

Example Usage

Arduino Sketch Example:

getFromAPI.zip

Download ZIP • 3KB

Before you test this example please sign up and obtain your own API key from http://weatherapi.com

Error Handling and Retry Logic

To ensure robust data retrieval, implement the following logic:

• If no response is received from the ESP32 within 20 seconds after sending a request:

  • Retry the request.

  • Limit retries to a recommended 2-3 attempts.

• If maximum retries are reached without receiving data:

  • Alert the user via serial monitor and prompt to check Wi-Fi connectivity or ESP32 status.

Notes and Best Practices

• The ESP32-S3 returns data lines with a maximum of 64 bytes per line.

• Recommended maximum length for the URL string is 128 characters to avoid overflow issues on the ESP32 serial buffer.

• If Wi-Fi is disconnected on the ESP32-S3, it sends a JSON error message starting with "{"error":"WiFi not connected"}". Ensure your code properly handles such situations by stopping requests and waiting until connectivity is restored.

You can use this API to obtain any data you want and display it on the Pixly screen, whether it's stock, movie times, train schedules, or even moon phases from NASA. The following APIs will show you how to use the display APIs.

---

SHOWNUMBER

Overview

• Command Name: SHOWNUMBER

• Category: Numeric and Text Primitives

• Purpose: Displays a specified number at a given position on the Pixly LED matrix, using defined colors for foreground and background.

Syntax Variations

Basic Usage: (uses default white color)

SHOWNUMBER <x> <y> <value>

Colored Number: (specify RGB text color)

SHOWNUMBER <x> <y> <value> <r> <g> <b>

Colored Number with Dot Indicator: (includes dot indicator below number with custom color)

SHOWNUMBER <x> <y> <value> <r> <g> <b> <dotR> <dotG> <dotB>

Parameters

Parameter	Description	Range / Format	Required?
<x>	X-coordinate of number's position (left)	Integer (0–15 for 16x16 matrix)	✅ Yes
<y>	Y-coordinate of number's position (top)	Integer (0–15 for 16x16 matrix)	✅ Yes
<value>	Number to display	Integer or Float	✅ Yes
<r>	Number color (red component)	Integer (0–255)	Optional
<g>	Number color (green component)	Integer (0–255)	Optional
<b>	Number color (blue component)	Integer (0–255)	Optional
<dotR>	Dot indicator color (red component)	Integer (0–255)	Optional
<dotG>	Dot indicator color (green component)	Integer (0–255)	Optional
<dotB>	Dot indicator color (blue component)	Integer (0–255)	Optional

Function Description

• Basic Usage:Displays a numeric value at specified (x,y) coordinates using default white color without any additional indicators.

• Colored Number:Allows customization of the displayed number’s color by specifying RGB values.

• Colored Number with Dot Indicator:Displays the number with specified RGB color and includes a colored dot indicator directly below the number, useful for highlighting or visual alerts.

Each command must be followed by the separate command RENDER to apply and display changes.

  espSerial.println("SHOWNUMBER 1 11 12.3 255 255 255 0 255 0");

  waitForHash();              // ← returns as soon as ESP32 replies

  // send render

  espSerial.println("RENDER");

  waitForHash();

Response Format

ESP32 responds with acknowledgment upon successful command processing:

#

Ensure to wait for this response before sending subsequent commands. The waitForHash() function does exactly that.

Example Usage

Arduino Sketch Example:

showNumber.zip

Download ZIP • 2KB

Error Handling and Notes

• Implement a timeout (recommended: 500ms) after each command sent.

• If a timeout occurs, consider retrying or notifying via serial monitor.

• Remember that changes are buffered until explicitly rendered using RENDER.

Best Practices

• Keep RGB values consistent and visually clear for readability.

• Reserve bright or distinct colors for alerts or important notifications using the dot indicator.

• Check coordinate ranges to avoid displaying numbers off-screen.

---

SCROLL_NUMBER

Overview

• Command Name: SCROLL_NUMBER

• Category: Numeric and Text Primitives

• Purpose: Scroll a numeric value horizontally across the Pixly LED matrix display with customizable speed, direction, and color.

Syntax

Basic Usage:

SCROLL_NUMBER <y> <speedMs> <direction> <value> <r> <g> <b>

With Dot Indicator:

SCROLL_NUMBER <y> <speedMs> <direction> <value> <r> <g> <b> <dotR> <dotG> <dotB>

Parameters

Parameter	Description	Range / Format	Required
<y>	Y-coordinate (row) for scrolling	Integer (0–15 on 16x16 matrix)	✅ Yes
<speedMs>	Scrolling speed in milliseconds per shift step	Integer (recommended: 50–200)	✅ Yes
<direction>	Direction of scrolling	L (left) or R (right)	✅ Yes
<value>	Number to scroll across the matrix	Float or Integer	✅ Yes
<r> <g> <b>	RGB color values for the number	Integers (0–255)	✅ Yes
<dotR> <dotG> <dotB>	RGB color for the dot indicator (optional)	Integers (0–255)	❌ No

Function Description

SCROLL_NUMBER allows ATmega328P to instruct the ESP32-S3 to horizontally scroll a numeric value across the Pixly LED matrix.

• The scrolling begins immediately upon command issuance.

• Scrolling continues until explicitly stopped with STOP_SCROLL or until the number has fully scrolled out of view.

• Optionally includes a colored dot indicator below the number to enhance visual communication.

Stopping the Scroll

Use the following command to stop scrolling explicitly:

STOP_SCROLL

ESP32 responds with acknowledgment (#) upon successfully stopping.

Response Format

ESP32 returns acknowledgment for each command:

#

Wait for this response before sending additional commands.

Example Usage

Arduino Sketch Example:

scrollNumber.zip

Download ZIP • 2KB

Error Handling & Notes

• Commands such as scrolling (SCROLL_NUMBER) do not automatically terminate. Explicitly use STOP_SCROLL to end scrolling early.

• Implement appropriate delays (delay()) or a timed wait mechanism after starting scrolling to manage program flow and prevent indefinite scrolling.

• Ensure your program terminates scrolling before completion to allow proper exit from the Pixly Arduino submenu.

Best Practices

• Maintain clear contrast between number and background color for readability.

• Choose scrolling speeds (speedMs) carefully for optimal readability and visual appeal.

• Always handle acknowledgments (#) from the ESP32 to ensure synchronization between ATmega328P and Pixly.

• MAKE SURE YOUR SCROLL TEXT STOPS before try to exit the main menu.

---

SHOW_TEXT

Overview

• Command Name: SHOW_TEXT

• Category: Text Primitives

• Purpose: Display static text at specified coordinates on Pixly’s LED matrix with customizable color.

• Only A-Z supported. Please do not mix any other characters in your command.

Syntax

SHOW_TEXT <x> <y> <text> <r> <g> <b>

Parameters

Parameter	Description	Range / Format	Required
<x>	X-coordinate of text position (left)	Integer (0–15 for 16x16 matrix)	✅ Yes
<y>	Y-coordinate of text position (top)	Integer (0–15 for 16x16 matrix)	✅ Yes
<text>	The text string to display	ASCII String (up to available space)	✅ Yes
<r>	Text color red component	Integer (0–255)	✅ Yes
<g>	Text color green component	Integer (0–255)	✅ Yes
<b>	Text color blue component	Integer (0–255)	✅ Yes

Function Description

• SHOW_TEXT instructs the ESP32-S3 to display a provided static text string on the Pixly LED matrix at the specified coordinates.

• The text is rendered in the specified RGB color.

• To make the text visible, the SHOW_TEXT command must be followed by the separate command RENDER.

Function Description

• SHOW_TEXT instructs the ESP32-S3 to display a provided static text string on the Pixly LED matrix at the specified coordinates.

• The text is rendered in the specified RGB color.

• AGAIN! To make the text visible, the SHOW_TEXT command must be followed by the separate command RENDER.

Rendering the Text

After issuing SHOW_TEXT, you must explicitly call RENDER:

  espSerial.println("SHOW_TEXT 0 0 abc 255 255 0");

  waitForHash();                    // wait for #OK

  espSerial.println("RENDER");      // latch to LEDs

  waitForHash();

This command updates the display to show your changes.

Response Format

After each command (SHOW_TEXT and RENDER), ESP32-S3 returns acknowledgment:

#

Wait for this acknowledgment before continuing just like previous examples show.

Example Usage

Arduino Sketch Example:

showText_Static.zip

Download ZIP • 2KB

Error Handling and Notes

• Always wait for acknowledgment (#) from ESP32 after each command to ensure synchronization.

• Implement timeout handling to detect and resolve communication issues promptly.

Best Practices

• Ensure text strings are short enough to fit visibly within your Pixly LED matrix dimensions.

• Clearly differentiate foreground text colors from background for best readability.

---

SCROLL_TEXT

Overview

• Command Name: SCROLL_TEXT

• Category: Text Primitives

• Purpose: Scroll a line of text across the Pixly LED matrix with adjustable direction, speed, and color.

  
  

Syntax

SCROLL_TEXT <y> <speedMs> <direction> <text> <r> <g> <b>

<direction>: L (scroll left) or R (scroll right)

Parameters

Parameter	Description	Format / Range	Required
<y>	Vertical Y-coordinate (row index)	Integer (0–15 on 16×16 matrix)	✅ Yes
<speedMs>	Scrolling speed in milliseconds per shift	Integer (recommended: 50–200)	✅ Yes
<direction>	Scrolling direction	L = left, R = right	✅ Yes
<text>	Text to be scrolled	ASCII string	✅ Yes
<r> <g> <b>	Text color in RGB	Integers (0–255)	✅ Yes

Function Description

SCROLL_TEXT scrolls a string across the LED matrix along the horizontal axis, starting at the specified Y-coordinate.It supports customizable:

• Direction: leftward or rightward

• Speed: scrolling interval in milliseconds

• Color: RGB value for the text

The scroll runs until stopped explicitly with the STOP_TEXT_SCROLL command.

Stop Scrolling

To stop the text scroll:

STOP_TEXT_SCROLL

The ESP32 responds with:

#

Always wait for this to ensure proper command execution.

bool waitHash(uint16_t to=500)    // waits for “#OK”

{

  unsigned long t0 = millis();

  while (millis() - t0 < to) {

    if (esp.available() && esp.read() == '#') { flushLine(); return true; }

  }

  Serial.println("⚠ timeout #"); return false;

}

Example Usage

Arduino Sketch Example:

scrollText.zip

Download ZIP • 2KB

Notes & Recommendations

• Always issue STOP_TEXT_SCROLL to terminate scrolling before exiting the submenu.

• Use waitHash() to verify that the command was accepted.

• Keep scroll speed within 50–200ms for readable animation.

• Consider short text strings for smooth rendering on 16x16 displays.

---

SCROLL_STR

Overview

• Command Name: SCROLL_STR

• Category: Numeric and Text Primitives

• Purpose: Scroll text horizontally across the Pixly LED matrix, with customizable speed, direction, color, and optional dot indicator.

Syntax

Basic syntax (text only):

SCROLL_STR <y> <speedMs> <direction> <text> <r> <g> <b>

Syntax with dot indicator:

SCROLL_STR <y> <speedMs> <direction> <text> <r> <g> <b> <dotR> <dotG> <dotB>

Sample Code:

  /* scroll “today temp 23.9” orange text, cyan dot, 5 s */

  sendStr("today temp 23.9",3,100,true,150,120,79,true,0,255,255);

  delay(9000);

  /* pause 2 s */

  stopStr(); delay(2000);

  /* scroll “demo 2025” right→left green text, 5 s, no dot colour */

  sendStr("demo 2025",3,100,false,0,255,0,false);

  delay(5000);

Parameters

Parameter	Description	Range / Format	Required
<y>	Y-coordinate (row) for scrolling	Integer (0–15 for 16x16 matrix)	✅ Yes
<speedMs>	Speed in milliseconds per scroll step	Integer (recommended: 50–200)	✅ Yes
<direction>	Direction of scrolling (L or R)	Literal character	✅ Yes
<text>	Text string to scroll	ASCII String	✅ Yes
<r> <g> <b>	RGB color of scrolling text	Integers (0–255)	✅ Yes
<dotR> <dotG> <dotB>	RGB color of optional dot indicator	Integers (0–255)	❌ No

Function Description

The SCROLL_STR command instructs ESP32-S3 to display scrolling text horizontally on Pixly’s LED matrix. You can customize:

• The scroll direction (left or right)

• The scrolling speed

• The text and its color

• Optional colored dot indicator for emphasis or visual alerts.

Scrolling continues indefinitely until explicitly stopped with the STOP_STR_SCROLL command.

Stopping the Scroll

Use this command to stop scrolling explicitly:

STOP_STR_SCROLL

Again, please make sure your program will stop at some point to ensure exist to main menu is bug free.

ESP32 acknowledges receipt with:

#

Always wait for acknowledgment to maintain communication synchronization.

Example Usage

Arduino Sketch Example:

scrollString.zip

Download ZIP • 2KB

Error Handling & Notes

• Always implement acknowledgment waiting (#) after each command to ensure commands are processed correctly.

• Explicitly issue STOP_STR_SCROLL before ending the Arduino submenu to properly terminate scrolling behavior.

Best Practices

• Use clearly visible color combinations for readability.

• Choose scroll speeds carefully for comfortable readability.

• Limit text length to ensure smooth scrolling on the LED matrix.

---

getFromAPI With Helper Class

Using PixlyFetch (Helper Class)

If you prefer a simpler Arduino-style interface, you can use our built-in helper:

#include "PixlyFetch.h"

PixlyFetch fetch(Serial);  // or use SoftwareSerial

Example:

const char* keys[] = { "temp_c", "condition" };

if (fetch.request("http://api.weatherapi.com/v1/current.json?key=APIKEY&q=London", keys, 2)) {

  Serial.println("🌐 Sent request");

}

// Wait for result (non-blocking)

if (fetch.available()) {

  String temp = fetch.value("temp_c");

  String cond = fetch.value("condition");

  Serial.println("✅ Received:");

  Serial.println("Temp: " + temp);

  Serial.println("Condition: " + cond);

}

Key Features:

• request(url, keys[], count) sends the HTTP GET request with up to 5 fields to extract.

• available() returns true when response is ready.

• value("key") gives you the value as a string (number or text).

• Handles BEGIN, END, JSON parsing, and overflow detection internally.

This is the recommended way to use getFromAPI if you're writing Arduino code for Pixly's ATmega328P. It keeps your logic clean and avoids needing to manually parse the JSON stream.

Example Usage

Arduino Sketch Example:

getFromAPI_Helper.zip

Download ZIP • 4KB

---

Get_SOUND

Overview

• Command Name: GET_SOUND

• Category: Sensor Input

• Purpose: Requests a real-time reading from Pixly's onboard sound sensor (e.g. microphone or analog sound level).

Syntax

GET_SOUND

Response Format

The ESP32 responds with a JSON object containing the current sound level, surrounded by framing tokens:

BEGIN

{ "sound" : <value> }

END

<value> is an integer sound level, typically in millivolts (e.g. 435), proportional to the analog audio signal detected.

Typical Communication Flow

ATmega328P → ESP32

GET_SOUND\r\n

ESP32 → ATmega328P

BEGIN

{ "sound" : 435 }

END

Arduino Class Helper (C++ API)

You can use the PixlyFetchSound helper class for clean Arduino integration:

First Include

#include "PixlyFetchSound.h"

Create an instance

PixlyFetchSound fetch(Serial);  // or SoftwareSerial

Send Request

if (fetch.requestSound()) {

  Serial.println("Requested sound level");

}

Poll for Response

if (fetch.available()) {

  int level = fetch.soundValue();

  Serial.print("Sound level: ");

  Serial.println(level);

}

Example Usage

Arduino Sketch Example:

getSoundSensor.zip

Download ZIP • 5KB

Notes & Best Practices

• You must wait for the "BEGIN" and "END" wrapped response before calling soundValue().

• If deserializeJson fails or the reply format is invalid, soundValue() will return 0.

• PixlyFetchSound also provides state flags:

  • started() – true after "START" is received

  • stopped() – true after "STOP" is received

  • inFlight() – true if a request is pending

  • overflow() – true if response exceeds buffer size

---

SHOWNUMBER with helper class

If you’re programming the ATmega328P using Arduino, we recommend using the PixlyShowNumber class for easier number display without having to manually manage serial handshaking or render steps.

Include

#include "PixlyShowNumber.h"

Initialization

PixlyShowNumber display(Serial);  // or SoftwareSerial

Show a Number

display.showNumber(

  /* x */     1,

  /* y */     11,

  /* value */ 12.3,

  /* r_fg */  255,  /* g_fg */ 255,  /* b_fg */ 255,   // text color (white)

  /* r_bg */  0,    /* g_bg */ 255,  /* b_bg */ 0      // dot color (green)

);

This command:

• Sends SHOWNUMBER with the given coordinates and RGB values.

• Waits for confirmation (#) from the ESP32.

• Sends RENDER to update the display.

• Handles all timing and acknowledgments automatically.

Example Usage

Arduino Sketch Example:

showNumber_Helper.zip

Download ZIP • 3KB

Notes

• showNumber(...) uses one decimal place.

• You must wait for the "START" token before calling it, and optionally STOP after.

• Dot color is still included even if your number doesn’t have a decimal point.

• This helper automatically calls RENDER and waits for # OK from Pixly.

---

SCROLL_NUMBER with helper class

Using PixlyScrollNumber (Helper Class)

If you’re using Arduino to control Pixly through the onboard ATmega328P, the PixlyScrollNumber class wraps the low-level SCROLL_NUMBER command with clean function calls and automatic serial handshaking.

Include

#include "PixlyScrollNumber.h"

Initialization

PixlyScrollNumber scroll(Serial); 

Scroll a Number

scroll.scrollNumber(

  "123.4",      // value as string

  1,            // y position (row)

  80,           // scroll speed (ms)

  true,         // scroll left

  255, 255, 255,// RGB color for number

  true,         // show dot indicator

  0, 255, 0     // RGB color for dot

);

You can omit the last 4 arguments if you don’t want a dot indicator.

Stop Scrolling

scroll.stopScroll();

Example Usage

Arduino Sketch Example:

scrollNumber_Helper.zip

Download ZIP • 3KB

Notes

• scrollNumber(...) waits for Pixly’s # acknowledgment before proceeding.

• You must stop scrolling manually using stopScroll() before starting another one or exiting the Arduino submenu.

• The dot indicator is optional but great for making numbers like "3.0" visually distinct.

---

SHOW_TEXT With helper class

Using PixlyShowText (Helper Class)

The PixlyShowText class provides a simplified way to send static text to the Pixly LED matrix from the ATmega328P, handling command formatting, serial handshaking, and the RENDER step automatically.

Include

#include "PixlyShowText.h"

Initialization

PixlyShowText text(Serial); // or SoftwareSerial

Display Text

text.showText(

  /* x */    0,

  /* y */    0,

  /* text */ "abc",

  /* r */    255,

  /* g */    255,

  /* b */    0         // yellow text

);

This:

• Sends the SHOW_TEXT command with the given content and color.

• Waits for confirmation (#) from ESP32.

• Calls RENDER to update the screen.

Example Usage

Arduino Sketch Example:

showText_Static_Helper.zip

Download ZIP • 3KB

Notes

• showText(...) will only display static text; use SCROLL_TEXT or SCROLL_STR for animated text.

• You must call RENDER after issuing SHOW_TEXT — this helper does it for you.

• Avoid text longer than 5–6 characters per row depending on font size.

---

Scroll_Text With helper class

Using PixlyScrollText (Helper Class)

The PixlyScrollText helper provides a clean way to scroll text across the Pixly LED matrix using simple function calls, with automatic handling of #OK and other command handshaking.

Include

#include "PixlyScrollText.h"

Initialization

PixlyScrollText scroll(Serial);

Scroll Text

scroll.scrollText(

  "hello world", // text to scroll

  1,             // y-position (row)

  100,           // scroll speed in milliseconds

  true,          // scroll left

  255, 150, 0    // RGB color (orange)

);

Stop Scrolling

scroll.stopScroll();

Example Usage

Arduino Sketch Example:

scrollText_Helper.zip

Download ZIP • 3KB

Notes

• This helper sends SCROLL_TEXT followed by automatic #OK wait.

• Always use stopScroll() before sending a new scroll or exiting the Arduino submenu.

• Text longer than the screen width will scroll automatically.

• Scrolling speed is defined in milliseconds per frame — typical range: 50–150 ms.

---

SCROLL_STR with helper class

Using PixlyScrollString (Helper Class)

PixlyScrollString is a convenient Arduino helper class for scrolling strings across the Pixly LED matrix with full support for color and optional decimal-dot indicators.

Include

#include "PixlyScrollString.h"

Initialization

PixlyScrollString scroll(Serial); // or SoftwareSerial

Scroll a String

scroll.scrollString(

  "hello world", // text to scroll

  3,             // y-position

  100,           // scroll speed (ms)

  true,          // scroll left

  255, 100, 0,   // RGB text color (orange)

  true,          // use dot

  0, 255, 255    // RGB dot color (cyan)

);

Stop the Scroll

scroll.stopScroll();

Example Usage

Arduino Sketch Example:

scrollString_Helper.zip

Download ZIP • 3KB

Notes

• The scrollString(...) method automatically waits for ESP32's #OK after sending the command.

• Use stopScroll() to end the scroll before sending a new one or exiting the submenu.

• Dot color is optional but useful when displaying numeric-like strings (e.g. sensor values).

---

EC11 EVENT handling

Using PixlyEC11 (Helper Class)

The PixlyEC11 class simplifies interaction with the EC11 rotary encoder forwarding feature on Pixly. It lets you enable/disable passthrough mode from the ESP32, wait for startup tokens (START, EC11_ON, etc.), and cleanly synchronize behavior with the host app.

Initialization

#include "PixlyEC11.h" 
PixlyEC11 ec11(Serial); // or SoftwareSerial

Key Functions

flushInput()

Discards any unread serial input (optional pre-cleanup).

ec11.flushInput();

waitForStart()

Blocks until the ESP32 sends the "START" token (indicating entry into Arduino submenu).

ec11.waitForStart();

waitToken("TOKEN")

Waits for any specified token (e.g., "STOP", "EC11_ON", etc.), with serial output logging.

ec11.waitToken("STOP");

setPassthrough(true/false)

Enables or disables EC11 passthrough. Sends ENABLE_EC11 or DISABLE_EC11 and waits for confirmation.

ec11.setPassthrough(true); // Turns on EC11 passthrough ec11.setPassthrough(false); // Turns it off

Each call:

• Sends the corresponding command (ENABLE_EC11 or DISABLE_EC11)

• Waits for #OK

• Waits for final status token (ENABLE_EC11 or DISABLE_EC11)

sendAndWaitHash(cmd)

Sends any command string and waits for the ESP32 to respond with #OK.

bool ok = ec11.sendAndWaitHash("CLEARSCREEN");

Serial Protocol (Handled Automatically)

Command	Sent by Arduino	Expected Reply from ESP32
ENABLE_EC11	Enables EC11 passthrough	#OK, then ENABLE_EC11
DISABLE_EC11	Disables passthrough	#OK, then DISABLE_EC11
Other commands	e.g. CLEARSCREEN	#OK

Notes & Tips

• EC11 passthrough means ESP32 stops rendering menu and forwards raw EC11 events:

  • > → rotated clockwise

  • < → rotated counter-clockwise

  • P → button press

  • R → button release

• Your Arduino code is fully responsible for parsing and responding to these.

• You must explicitly call setPassthrough(false) to hand control back to the ESP32 main app.

Recommended Usage

Use PixlyEC11 when:

• You want to write your own control menus using EC11 input.

• You’re building an interactive loop with encoder input (e.g., a knob-controlled volume meter).

• You want tight real-time control from ATmega328P without interference from ESP32 menus.

Example Usage

Arduino Sketch Example:

EC11forwarding_Helper.zip

Download ZIP • 6KB

---

SETPIXEL

Using PixlySetPixel (Helper Class)

The PixlySetPixel class provides low-level access to individual LEDs on the Pixly 16×16 matrix. It sends SETPIXELcommands to the ESP32, waits for confirmation, and batches changes using RENDER.

Include and Initialization

#include "PixlySetPixel.h" PixlySetPixel matrix(Serial); // or SoftwareSerial

Key Methods

setPixel(x, y, r, g, b)

Sets a single pixel on the matrix to the specified RGB color. The pixel won’t light up until render() is called.

matrix.setPixel( 4, 8, // x = 4, y = 8 255, 0, 0   // red );

render()

Updates the display with all previously set pixels. This must be called after setPixel() if you want changes to appear.

matrix.render();

waitForToken("TOKEN")

Waits for a specific token like START or STOP — useful for synchronizing with Pixly's main menu state.

matrix.waitForToken("START");

Notes & Best Practices

• Each call to setPixel() sends a serial command and waits for #OK. Avoid calling it too rapidly in loops without batching.

• Always pair your pixel changes with a call to render() to make them visible.

• If setting many pixels at once (e.g. for full-frame animation), consider staggering or reducing color depth to avoid serial bottleneck.

• You can combine this with your own logic for drawing text, sprites, or even simple games.

Use Cases

• Visualize sensor data (e.g. sound level, joystick position)

• Build custom animations or progress bars

• Make your own pixel art editor

• Display audio spectrum frames pixel-by-pixel
  

Example Usage

Arduino Sketch Example:

setPixel_helperClass.zip

Download ZIP • 4KB

---