Store:  https://intellar.square.site/

Source: https://github.com/intellar/Intellar-Engine

Youtube:

Français

# Intellar Engine

L'Intellar Engine est une carte de développement basée sur l'ESP32-S3. Elle a été conçue pour les projets où l'électronique doit entrer dans un objet réel : une tête de robot, une interface interactive, un module d'affichage compact ou un prototype qui doit être manipulé sans que les fils se débranchent.

Le point de départ est simple. Beaucoup de projets fonctionnent très bien sur la table avec un ESP32, des écrans SPI, des capteurs et des fils Dupont. Le problème arrive quand le prototype doit être déplacé, fermé dans un boîtier, montré à quelqu'un ou utilisé pendant plusieurs heures. Les fils deviennent une source de panne, les masses sont longues, les connecteurs bougent et le montage devient difficile à reproduire.

L'Intellar Engine cherche à garder la flexibilité du prototypage, mais avec une base matérielle plus propre.

## Matériel

Le coeur du système est un ESP32-S3 avec PSRAM. Ce choix permet de rester dans l'écosystème Arduino/PlatformIO tout en ayant assez de mémoire pour gérer des écrans couleur, des buffers d'images, des animations et des communications Bluetooth LE.

La carte mère regroupe les fonctions qui reviennent dans presque tous les prototypes :

- microcontrôleur ESP32-S3 avec Wi-Fi, Bluetooth LE et PSRAM ;

- connecteurs FPC 0.5 mm pour sortir les bus SPI, I2C et GPIO vers des cartes satellites ;

- alimentation USB-C et chemin de charge pour batterie Li-ion/LiPo ;

- régulation locale pour alimenter les périphériques ;

- routage prévu pour des écrans SPI et des modules d'entrée/sortie compacts.

Les cartes satellites évitent de tout mettre directement sur la carte principale. Un écran, un touchpad, un capteur ou une interface spécifique peut être placé là où il est utile dans l'objet, relié par une nappe FPC courte et stable. Cette approche est plus proche d'un produit embarqué que d'un montage de breadboard, mais elle reste assez simple pour être utilisée dans un projet de maker.

## Affichage et interaction

Le firmware actuel supporte plusieurs chemins d'affichage. Le cas principal est une paire d'écrans ronds GC9A01 de 240 x 240 pixels, utilisés pour des visages, des yeux animés ou des séquences vidéo courtes. Une cible ILI9341 est aussi présente pour les montages avec écran rectangulaire et tactile XPT2046.

Un petit écran OLED SSD1306 peut servir d'interface de diagnostic. Il peut afficher des animations, l'état du touchpad ou des informations de performance comme le nombre d'images par seconde et la mémoire disponible.

Le projet inclut aussi des entrées tactiles capacitives, ainsi que du code pour des capteurs comme l'IMU et le ToF. Ces modules ne sont pas tous au même niveau de maturité, mais l'architecture est déjà en place pour les intégrer dans le même état système.

## Logiciel

Le dépôt GitHub contient le firmware de référence de l'Intellar Engine. Il est organisé pour être ouvert dans PlatformIO et adapté selon le type d'écran utilisé.

Les principaux blocs logiciels sont :

- initialisation système, I2C, PSRAM et LittleFS ;

- driver LCD basé sur LovyanGFX ;

- animations RGB565 stockées dans LittleFS ;

- lecture vidéo MJPEG pour afficher une suite d'images JPEG sur les TFT ;

- service Bluetooth LE pour contrôler le firmware depuis un téléphone ou un dashboard ;

- état système partagé pour les écrans, capteurs, fichiers et diagnostics.

Les ressources visuelles sont placées dans le système de fichiers LittleFS. Cela permet de changer des animations ou des vidéos sans modifier le code C++ principal. Le firmware liste les fichiers disponibles au démarrage, les trie, puis les expose au dashboard Bluetooth.

## Fonctionnement du code

Le firmware est organisé autour d'une boucle principale Arduino, mais plusieurs responsabilités sont séparées en blocs assez distincts. `main.cpp` joue le rôle de chef d'orchestre : il initialise la carte, monte LittleFS, détecte les assets disponibles, démarre les drivers, puis appelle régulièrement les services nécessaires.

Le bloc `Core` contient l'initialisation de base et l'état partagé. `EngineState` sert de mémoire commune entre les drivers : face active, fichiers disponibles, état Bluetooth, valeurs du touchpad, diagnostics de performance et informations sur les capteurs. Cette approche évite que chaque module garde sa propre version de l'état du système.

Les drivers sont séparés par fonction. `LCD` s'occupe des écrans TFT et de l'envoi des images RGB565. `OLED` gère l'affichage de diagnostic. `Bluetooth` expose l'état de la carte et reçoit les commandes. `MjpegPlayer` lit les fichiers vidéo, décode les images JPEG et les envoie vers le driver LCD.

Les modules d'interface et de capteurs ajoutent le comportement autour de ces drivers : animations d'yeux, logique RobotEye, touchpad capacitif, IMU et ToF. Certains éléments sont déjà utilisés dans les démonstrations actuelles, d'autres servent de base pour les prochaines extensions.

Ce diagramme montre l'idée générale. La boucle principale garde le système vivant : elle lit les commandes, met à jour l'état, choisit quoi afficher et publie les diagnostics. La tâche I2C séparée permet de garder les modules plus lents, comme l'OLED ou certains capteurs, hors du chemin critique de l'affichage TFT.

## Pourquoi une carte dédiée

Il est possible de reproduire une partie du projet avec un ESP32-S3 de développement, deux écrans SPI, quelques capteurs et beaucoup de câblage. C'est même une bonne façon de comprendre le fonctionnement de base : bus SPI, formats RGB565, fichiers LittleFS, contrôle Bluetooth et contraintes de mémoire.

L'intérêt de l'Intellar Engine apparaît quand le prototype doit devenir plus robuste. Les nappes FPC remplacent les fils volants, les cartes satellites réduisent la mécanique improvisée, l'alimentation est déjà prévue et le firmware correspond au routage de la carte. On passe moins de temps à chercher un faux contact et plus de temps à travailler sur le comportement, l'interface et l'intégration dans l'objet.

Cette carte n'enlève pas la partie expérimentale du projet. Elle enlève surtout une partie du bricolage fragile autour du projet.

## État actuel

Le matériel de base est validé et sert maintenant de plateforme commune pour les prochains développements Intellar. Le firmware évolue autour de trois axes :

- stabiliser les drivers d'affichage et les assets dans LittleFS ;

- améliorer le contrôle Bluetooth et le dashboard ;

- ajouter des démonstrations plus complètes avec capteurs, touchpad, OLED et vidéo.

Le kit est disponible sur la boutique Intellar :

https://intellar.square.site/

# Mode vidéo MJPEG sur Intellar Engine

L'ajout du mode vidéo part d'un besoin assez simple : afficher une animation plus riche qu'une suite de poses fixes sur les écrans de l'Intellar Engine. Les visages RGB565 en fichiers `.bin` sont efficaces pour des expressions ou des atlas d'images, mais ils ne sont pas pratiques quand on veut jouer une vraie séquence image par image.

Le mode MJPEG ajoute donc un second type d'asset dans le firmware. En plus des strips RGB565, la carte peut maintenant lire des fichiers `.mjpeg` ou `.mjpg` placés dans LittleFS, décoder chaque image JPEG et l'envoyer directement vers un écran TFT.

Ce n'est pas un lecteur vidéo général comme sur un ordinateur. C'est une solution adaptée à l'ESP32-S3 : simple, locale, sans réseau, et assez légère pour fonctionner avec les écrans SPI 240 x 240 utilisés sur l'Intellar Engine.

## Pourquoi MJPEG

Une vidéo classique comme un fichier MP4 utilise une compression temporelle. Les images dépendent souvent des images précédentes ou suivantes. C'est efficace pour la taille du fichier, mais beaucoup plus lourd à décoder sur un microcontrôleur.

Le MJPEG est plus simple : le fichier contient une suite d'images JPEG complètes. Le firmware lit un JPEG, le décode, l'affiche, puis passe au suivant. Il n'y a pas de prédiction temporelle ni de pipeline vidéo complexe.

Ce choix a quelques avantages pour ce projet :

- le décodage reste compréhensible et débogable ;

- chaque frame peut être traitée indépendamment ;

- le format convient bien à de courtes animations ;

- le fichier peut être stocké localement dans LittleFS ;

- le firmware peut sauter des images pour accélérer la lecture.

La contrepartie est que le MJPEG prend plus d'espace qu'un vrai codec vidéo. Pour une carte comme l'Intellar Engine, ce compromis est acceptable pour des boucles courtes, des effets de visage, des transitions ou des animations de personnage.

## Matériel utilisé

Le mode vidéo s'appuie sur les mêmes éléments que le reste du firmware :

- ESP32-S3 avec PSRAM ;

- système de fichiers LittleFS dans la mémoire flash ;

- écrans TFT SPI, principalement les GC9A01 ronds en 240 x 240 ;

- driver LCD basé sur LovyanGFX ;

- Bluetooth LE pour choisir la vidéo et contrôler la lecture.

Il serait possible de refaire ce principe sur un ESP32-S3 générique avec un écran SPI bien câblé. Le point délicat est surtout la stabilité matérielle : fréquence SPI élevée, alimentation correcte, masse propre, rétroéclairage, connecteurs qui ne bougent pas et assez de mémoire disponible pour les buffers.

C'est justement le rôle de l'Intellar Engine. La carte fournit une base plus propre pour ce type de montage : connecteurs FPC, cartes satellites, alimentation intégrée et firmware déjà adapté au routage. Le résultat est moins fragile qu'un prototype avec des fils Dupont entre deux écrans, surtout quand le montage doit entrer dans une tête de robot ou un boîtier compact.

## Format des fichiers

Les vidéos doivent être placées à la racine de `data/` avant de générer et téléverser le système de fichiers LittleFS. Au démarrage, le firmware liste les fichiers qui se terminent par :

- `.mjpeg`

- `.mjpg`

Le contenu attendu est une suite d'images JPEG baseline. Chaque frame doit commencer par le marqueur JPEG `FF D8` et se terminer par `FF D9`. Le lecteur cherche ces marqueurs dans le fichier pour extraire une image à la fois.

Le format recommandé est :

- 240 x 240 pixels pour les écrans ronds ;

- environ 20 images par seconde ;

- JPEG baseline ;

- une image complète par frame ;

- fichier à la racine de LittleFS.

Un fichier plus grand peut être décodé dans certaines limites, puis redimensionné vers 240 x 240. Le firmware limite cependant la taille du raster JPEG afin de protéger la mémoire. Pour un résultat prévisible, il vaut mieux préparer directement les animations en 240 x 240.

## Fonctionnement dans le firmware

Au démarrage, `main.cpp` monte LittleFS et parcourt les fichiers disponibles. Les fichiers `.bin` sont classés comme animations RGB565, tandis que les fichiers `.mjpeg` et `.mjpg` sont ajoutés à la liste des vidéos.

Quand une vidéo est lancée, le lecteur MJPEG :

1. ouvre le fichier dans LittleFS ;

2. lit la prochaine image JPEG dans un buffer en PSRAM ;

3. décode l'image avec la librairie `JPEGDEC` ;

4. convertit le résultat en framebuffer RGB565 ;

5. ajuste l'image dans un canevas 240 x 240 si nécessaire ;

6. pousse le framebuffer vers l'écran choisi avec `pushVideo565()`.

Le firmware utilise un buffer RGB565 de 240 x 240 pixels pour l'affichage final. Cela correspond à 115 200 octets par image, sans compter le buffer JPEG temporaire et le raster de décodage. La PSRAM de l'ESP32-S3 est donc importante pour garder assez de marge.

Le lecteur est appelé régulièrement dans la boucle principale avec `Drivers::Mjpeg::service(millis())`. Il ne bloque pas toute la logique du firmware en permanence. Il avance image par image selon la cadence demandée, puis laisse le reste du système continuer : touchpad, Bluetooth, OLED, diagnostics et mise à jour d'état.

Le flux interne ressemble à ceci :

Le lecteur ne dépend pas d'un nom de fichier précis. Il travaille avec l'index de la vidéo dans la liste construite au démarrage. C'est ce qui permet au dashboard Bluetooth de présenter les fichiers disponibles sans recompiler le firmware.

## Contrôle par Bluetooth

Le dashboard Bluetooth reçoit la liste des vidéos disponibles dans LittleFS. Chaque vidéo reçoit un identifiant de commande.

Les commandes actuellement utilisées sont :

- `500` à `519` : jouer une vidéo sur l'écran gauche ;

- `520` à `539` : jouer une vidéo sur l'écran droit ;

- `540` : vitesse 0.5x ;

- `541` : vitesse 1x ;

- `542` : vitesse 1.5x ;

- `598` : arrêter la lecture ;

- `599` : activer ou désactiver la boucle.

L'état vidéo est aussi renvoyé dans les notifications Bluetooth : lecture active, boucle activée et multiplicateur de vitesse. Cela permet au dashboard d'afficher l'état réel de la carte au lieu de supposer que la commande a fonctionné.

## Gestion de la vitesse

La cadence nominale utilisée dans le lecteur est de 20 images par seconde.

Pour la vitesse 0.5x, le firmware garde chaque image plus longtemps à l'écran. Pour la vitesse 1.5x, il saute périodiquement des images JPEG après décodage. Cette approche est simple et évite d'avoir à recalculer une vraie interpolation temporelle.

Le résultat est suffisant pour des animations de visage ou des boucles courtes. Pour une vidéo très détaillée, le rendu dépendra de la taille des JPEG, du taux de compression et du temps nécessaire au décodage.

## Limites actuelles

Le mode vidéo est volontairement simple. Il ne gère pas le son, les codecs modernes, les fichiers MP4, ni la synchronisation audio/vidéo. Il ne cherche pas non plus à faire du streaming depuis le réseau. Tout est lu localement depuis LittleFS.

Les principales limites à garder en tête sont :

- la taille disponible dans la partition LittleFS ;

- la mémoire PSRAM nécessaire aux buffers ;

- le temps de décodage JPEG ;

- la bande passante SPI vers l'écran ;

- la taille des fichiers si les JPEG sont trop peu compressés.

En pratique, le meilleur usage est une animation courte, optimisée pour l'écran cible, avec une résolution déjà proche de 240 x 240.

## Préparation d'une animation

Un workflow typique consiste à préparer une petite animation carrée, puis à l'exporter comme suite d'images JPEG concaténées dans un fichier MJPEG. Le fichier obtenu est placé dans `data/`, puis envoyé sur la carte avec LittleFS.

Exemple de commande PlatformIO pour téléverser le système de fichiers :

```bash

pio run -e gc9a01 -t buildfs

pio run -e gc9a01 -t uploadfs

```

Après redémarrage, le firmware affiche dans le moniteur série le nombre de fichiers vidéo trouvés. Si un dashboard Bluetooth est connecté, la vidéo apparaît aussi dans la liste des vidéos disponibles.

## Ce que cela apporte au projet

Le mode MJPEG ajoute une nouvelle façon de donner de la personnalité à l'Intellar Engine. Les expressions fixes restent utiles, car elles sont rapides et peu coûteuses en mémoire. La vidéo ajoute une couche plus expressive pour les transitions, les animations de démarrage, les réactions ou les démonstrations visuelles.

Le plus important est que tout reste local et modifiable. On peut changer une animation en remplaçant un fichier dans LittleFS, sans réécrire le driver d'affichage. On peut aussi continuer à utiliser les autres fonctions du firmware : Bluetooth, OLED, touchpad et diagnostics.

Pour quelqu'un qui veut comprendre ou reproduire le projet, le mode vidéo montre bien le type de compromis nécessaire sur microcontrôleur : format simple, buffers maîtrisés, décodage image par image et affichage direct en RGB565. Pour quelqu'un qui veut construire un objet plus robuste, l'Intellar Engine fournit une base matérielle qui évite de refaire toute la partie fragile du montage.

ENGLISH

English

# Intellar Engine

The Intellar Engine is an ESP32-S3 development board designed for projects where the electronics need to live inside a real object: a robot head, an interactive interface, a compact display module, or a prototype that can be handled without wires coming loose.

The starting point is simple. Many projects work very well on a desk with an ESP32, SPI displays, sensors, and Dupont wires. The problems start when the prototype has to be moved, enclosed, shown to someone, or used for several hours. Wires become failure points, ground paths get long, connectors move, and the build becomes hard to reproduce.

The Intellar Engine keeps the flexibility of prototyping, but gives it a cleaner hardware base.

## Hardware

At the center of the system is an ESP32-S3 with PSRAM. This keeps the project in the Arduino/PlatformIO ecosystem while providing enough memory for color displays, image buffers, animations, and Bluetooth LE communication.

The mainboard groups the functions that come back in almost every prototype:

- ESP32-S3 microcontroller with Wi-Fi, Bluetooth LE, and PSRAM;

- 0.5 mm FPC connectors carrying SPI, I2C, and GPIO to satellite boards;

- USB-C power and a Li-ion/LiPo battery charge path;

- local regulation for peripherals;

- routing designed for SPI displays and compact input/output modules.

The satellite boards avoid putting every connector directly on the mainboard. A display, touchpad, sensor, or dedicated interface can be placed where it makes sense in the object, connected by a short and stable FPC cable. This is closer to an embedded product than to a breadboard build, but still simple enough for maker projects.

## Display and Interaction

The current firmware supports several display paths. The main configuration uses two round GC9A01 displays at 240 x 240 pixels, used for faces, animated eyes, or short video sequences. An ILI9341 target is also available for builds using a rectangular display and an XPT2046 touch controller.

A small SSD1306 OLED can be used as a diagnostic interface. It can show animations, touchpad state, or performance information such as frame rate and available memory.

The project also includes capacitive touch inputs, along with code for sensors such as the IMU and ToF module. These modules are not all at the same maturity level, but the architecture is already in place to integrate them into the same system state.

## Software

The GitHub repository contains the reference firmware for the Intellar Engine. It is organized for PlatformIO and can be adapted depending on the display target.

The main software blocks are:

- system initialization, I2C, PSRAM, and LittleFS;

- LCD driver based on LovyanGFX;

- RGB565 animations stored in LittleFS;

- MJPEG video playback for displaying JPEG frame sequences on the TFTs;

- Bluetooth LE service for controlling the firmware from a phone or dashboard;

- shared system state for displays, sensors, files, and diagnostics.

Visual assets are stored in the LittleFS filesystem. This makes it possible to change animations or videos without modifying the main C++ code. On startup, the firmware lists the available files, sorts them, and exposes them to the Bluetooth dashboard.

## How the Code Works

The firmware is built around the Arduino main loop, but the responsibilities are separated into clear blocks. `main.cpp` acts as the orchestrator: it initializes the board, mounts LittleFS, detects the available assets, starts the drivers, and then regularly calls the services needed to keep the system running.

The `Core` block contains the base initialization and the shared state. `EngineState` is the common memory used by the drivers: active face, available files, Bluetooth state, touchpad values, performance diagnostics, and sensor information. This avoids each module keeping its own disconnected version of the system state.

The drivers are separated by function. `LCD` handles the TFT displays and RGB565 image output. `OLED` manages the diagnostic display. `Bluetooth` exposes the board status and receives commands. `MjpegPlayer` reads video files, decodes JPEG frames, and sends them to the LCD driver.

The interface and sensor modules add behavior around these drivers: eye animations, RobotEye logic, capacitive touchpad, IMU, and ToF. Some of these are already used in the current demos, while others are the base for upcoming extensions.

This diagram shows the general idea. The main loop keeps the system alive: it reads commands, updates the state, decides what should be displayed, and publishes diagnostics. The separate I2C task keeps slower modules, such as the OLED or some sensors, away from the critical TFT display path.

## Why a Dedicated Board

Part of this project can be reproduced with a generic ESP32-S3 development board, two SPI displays, a few sensors, and a lot of wiring. That is even a good way to understand the basics: SPI buses, RGB565 formats, LittleFS files, Bluetooth control, and memory constraints.

The value of the Intellar Engine becomes clear when the prototype needs to be more robust. FPC cables replace loose wires, satellite boards reduce improvised mechanics, the power path is already planned, and the firmware matches the board routing. Less time is spent chasing intermittent connections, and more time can go into behavior, interface design, and integration into the object.

The board does not remove the experimental part of the project. It mainly removes a fragile layer of hardware improvisation around it.

## Current Status

The base hardware has been validated and is now the common platform for upcoming Intellar developments. The firmware is evolving around three areas:

- stabilizing display drivers and LittleFS assets;

- improving Bluetooth control and the dashboard;

- adding more complete demos with sensors, touchpad, OLED, and video.

The kit is available on the Intellar store:

https://intellar.square.site/

MJPEG

# MJPEG Video Mode on Intellar Engine

The video mode was added for a simple reason: to display animations that are richer than a fixed set of facial poses. RGB565 face strips stored as `.bin` files work well for expressions or image atlases, but they are not very convenient when the goal is to play a real frame-by-frame sequence.

The MJPEG mode adds a second type of asset to the firmware. In addition to RGB565 strips, the board can now read `.mjpeg` or `.mjpg` files stored in LittleFS, decode each JPEG frame, and send it directly to a TFT display.

This is not a general-purpose video player like on a computer. It is a solution adapted to the ESP32-S3: simple, local, network-free, and light enough to run with the 240 x 240 SPI displays used on the Intellar Engine.

## Why MJPEG

A typical video file such as MP4 uses temporal compression. Many frames depend on previous or future frames. This is efficient for file size, but much heavier to decode on a microcontroller.

MJPEG is simpler: the file contains a sequence of complete JPEG images. The firmware reads one JPEG, decodes it, displays it, and then moves to the next one. There is no temporal prediction and no complex video pipeline.

This choice has several advantages for this project:

- decoding remains easy to understand and debug;

- each frame can be processed independently;

- the format works well for short animations;

- the file can be stored locally in LittleFS;

- the firmware can skip frames to speed up playback.

The tradeoff is that MJPEG uses more storage than a modern video codec. For a board like the Intellar Engine, this is acceptable for short loops, face effects, transitions, or character animations.

## Hardware Used

The video mode uses the same hardware blocks as the rest of the firmware:

- ESP32-S3 with PSRAM;

- LittleFS filesystem in flash memory;

- SPI TFT displays, mainly round 240 x 240 GC9A01 panels;

- LCD driver based on LovyanGFX;

- Bluetooth LE for selecting the video and controlling playback.

This principle could be reproduced on a generic ESP32-S3 with a correctly wired SPI display. The delicate part is hardware stability: high SPI frequency, clean power, good ground paths, backlight control, connectors that do not move, and enough available memory for the buffers.

That is where the Intellar Engine is useful. The board provides a cleaner base for this kind of build: FPC connectors, satellite boards, integrated power, and firmware that already matches the routing. The result is less fragile than a prototype wired with Dupont cables between two displays, especially when the build has to fit inside a robot head or compact enclosure.

## File Format

Videos must be placed at the root of `data/` before building and uploading the LittleFS filesystem. On startup, the firmware lists files ending with:

- `.mjpeg`

- `.mjpg`

The expected content is a sequence of baseline JPEG images. Each frame must start with the JPEG marker `FF D8` and end with `FF D9`. The player scans for these markers in the file to extract one frame at a time.

The recommended format is:

- 240 x 240 pixels for the round displays;

- around 20 frames per second;

- baseline JPEG;

- one complete image per frame;

- file stored at the root of LittleFS.

A larger file can be decoded within limits and then resized to 240 x 240. The firmware still limits the decoded JPEG raster size to protect memory. For predictable results, it is better to prepare animations directly at 240 x 240.

## How It Works in the Firmware

On startup, `main.cpp` mounts LittleFS and scans the available files. `.bin` files are classified as RGB565 animations, while `.mjpeg` and `.mjpg` files are added to the video list.

When a video is started, the MJPEG player:

1. opens the file from LittleFS;

2. reads the next JPEG frame into a PSRAM buffer;

3. decodes the image with the `JPEGDEC` library;

4. converts the result into an RGB565 framebuffer;

5. scales or contains the image into a 240 x 240 canvas if needed;

6. pushes the framebuffer to the selected display with `pushVideo565()`.

The firmware uses a 240 x 240 RGB565 buffer for final display output. That is 115,200 bytes per frame, not counting the temporary JPEG buffer and the decoded raster. The ESP32-S3 PSRAM is therefore important to keep enough headroom.

The player is called regularly from the main loop with `Drivers::Mjpeg::service(millis())`. It does not permanently block the rest of the firmware. It advances frame by frame according to the selected timing, then lets the rest of the system continue: touchpad, Bluetooth, OLED, diagnostics, and state updates.

The internal flow looks like this:

The player does not depend on a specific filename. It works with the video index from the list built at startup. This is what allows the Bluetooth dashboard to show available files without recompiling the firmware.

## Bluetooth Control

The Bluetooth dashboard receives the list of videos available in LittleFS. Each video gets a command identifier.

The current commands are:

- `500` to `519`: play a video on the left display;

- `520` to `539`: play a video on the right display;

- `540`: 0.5x speed;

- `541`: 1x speed;

- `542`: 1.5x speed;

- `598`: stop playback;

- `599`: enable or disable looping.

The video state is also included in Bluetooth notifications: whether playback is active, whether looping is enabled, and the current speed multiplier. This lets the dashboard display the real board state instead of assuming that a command worked.

## Speed Handling

The nominal playback cadence used by the player is 20 frames per second.

At 0.5x speed, the firmware keeps each image on screen longer. At 1.5x speed, it periodically skips JPEG frames after decoding. This approach is simple and avoids implementing real temporal interpolation.

The result is good enough for face animations and short loops. For very detailed video, the result will depend on JPEG size, compression level, and decoding time.

## Current Limits

The video mode is intentionally simple. It does not handle audio, modern codecs, MP4 files, or audio/video synchronization. It also does not stream from the network. Everything is read locally from LittleFS.

The main limits to keep in mind are:

- available space in the LittleFS partition;

- PSRAM needed by the buffers;

- JPEG decoding time;

- SPI bandwidth to the display;

- file size if the JPEG frames are not compressed enough.

In practice, the best use case is a short animation, optimized for the target display, with a resolution already close to 240 x 240.

## Preparing an Animation

A typical workflow is to prepare a small square animation, then export it as a sequence of JPEG frames concatenated into one MJPEG file. The resulting file is placed in `data/`, then uploaded to the board with LittleFS.

Example PlatformIO commands for uploading the filesystem:

```bash

pio run -e gc9a01 -t buildfs

pio run -e gc9a01 -t uploadfs

```

After reboot, the firmware prints the number of video files found in the serial monitor. If a Bluetooth dashboard is connected, the video also appears in the list of available videos.

## What This Adds to the Project

The MJPEG mode adds a new way to give personality to the Intellar Engine. Fixed expressions remain useful because they are fast and inexpensive in memory. Video adds a more expressive layer for transitions, startup animations, reactions, or visual demos.

The important point is that everything stays local and replaceable. An animation can be changed by replacing a file in LittleFS, without rewriting the display driver. The other firmware features can continue to run at the same time: Bluetooth, OLED, touchpad, and diagnostics.

For someone who wants to understand or reproduce the project, the video mode shows the kind of tradeoff needed on a microcontroller: simple format, controlled buffers, frame-by-frame decoding, and direct RGB565 display output. For someone who wants to build a more robust object, the Intellar Engine provides the hardware base that avoids rebuilding the fragile part of the setup.