Pixly API Documentation

Version: 1.0Date: 2025-06-11

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

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_SENSOR

    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.

---