VTM Pro Maker Workbench™ (aka the Desk Bot ;-) The AI-Driven Prototyping Ecosystem for Arduino Uno Q

1git clone https://github.com/VideotronicMaker/VideotronicMaker-OS.git
2cd VideotronicMaker-OS

1sudo apt update && sudo apt install -y python3-pip python3-venv
2python3 -m venv venv
3source venv/bin/activate
4pip install flask pyserial "google-generativeai>=0.8.3" psutil

1source venv/bin/activate
2python3 app.py

1/*
2  =============================================================================
3    PROJECT:        VideotronicMaker OS (VTM-OS) - The Body
4    FILE:           vtm_mouth_controller.ino
5    AUTHOR:         Tishin Padilla (VideotronicMaker)
6    DATE:           2025-12-09
7    VERSION:        1.0.0
8    DESCRIPTION:    This sketch runs on the dedicated STM32 Microcontroller (MCU)
9                    of the Arduino Uno Q. Its primary role is to execute 
10                    control commands for the LED Matrix mouth animation. It 
11                    functions as the 'Body' in the Dual-Brain architecture, 
12                    taking commands from the Linux MPU via the Arduino Router 
13                    Bridge (RPC).
14    ASSISTANT:      Code logic and structure assisted by Google Gemini.
15    LICENSE:        FREE and Unrestricted for all use (Public Domain).
16  =============================================================================
17*/
18
19// =======================
20// 1. LIBRARY INCLUDES
21// =======================
22
23#include <ArduinoGraphics.h>      // Necessary for drawing shapes on the display.
24#include <Arduino_LED_Matrix.h>   // Required for accessing the built-in 12x8 LED matrix hardware.
25#include <Arduino_RouterBridge.h> // **CRITICAL:** Enables Remote Procedure Calls (RPC) 
26                                  // between the Linux MPU (Python) and the STM32 MCU (C++).
27
28ArduinoLEDMatrix matrix;
29
30// =======================
31// 2. CONSTANTS & STATE
32// =======================
33
34// Define the ON and OFF colors for the LED matrix (White and Black).
35const uint32_t ON_COLOR = 0xFFFFFFFF;
36const uint32_t OFF_COLOR = 0x00000000;
37
38// Global State Variable: Controls the animation loop in loop().
39// 'volatile' ensures the variable is read correctly when updated by the Bridge interrupt.
40volatile int talkState = 0; // 0 = Mouth Closed (Idle), 1 = Talking (Animating)
41
42// =======================
43// 3. DRAWING FUNCTIONS
44// =======================
45
46// FUNCTION: drawMouthClosed
47// Purpose: Draws the idle, horizontal line on the LED matrix.
48void drawMouthClosed() {
49  matrix.beginDraw();
50  matrix.clear();
51  
52  matrix.stroke(ON_COLOR);
53  matrix.fill(ON_COLOR);
54  
55  // SHAPE 1: Waiting/Closed (A simple horizontal rectangle)
56  matrix.rect(1, 3, 10, 2); 
57  
58  matrix.endDraw();
59}
60
61// FUNCTION: drawRandomMouth
62// Purpose: Selects a random mouth shape (from 3 options) and renders it.
63// This gives the impression of speaking without high-level TTS analysis.
64void drawRandomMouth() {
65  matrix.beginDraw();
66  matrix.clear();
67  
68  matrix.stroke(ON_COLOR);
69  matrix.fill(ON_COLOR);
70  
71  // Randomly select one of the 3 open shapes (0, 1, or 2)
72  int shapeIndex = random(0, 3);
73
74  if (shapeIndex == 0) {
75    // SHAPE 2: Fully Open (Smiley/Wide Vowel Sound)
76    matrix.rect(0, 0, 12, 2);
77    matrix.rect(0, 2, 2, 1);
78    matrix.rect(11, 2, 1, 1);
79    matrix.rect(1, 3, 2, 1);
80    matrix.rect(10, 3, 2, 1);
81    matrix.rect(1, 4, 2, 1);
82    matrix.rect(9, 4, 2, 1);
83    matrix.rect(2, 5, 2, 1);
84    matrix.rect(8, 5, 2, 1);
85    matrix.rect(3, 6, 2, 1);
86    matrix.rect(7, 6, 2, 1);
87    matrix.rect(3, 7, 6, 1);
88  } 
89  else if (shapeIndex == 1) {
90    // SHAPE 3: Half Open (Resting Position)
91    matrix.rect(1, 1, 10, 2);
92    matrix.rect(1, 3, 2, 2);
93    matrix.rect(10, 3, 1, 2);
94    matrix.rect(9, 4, 1, 1);
95    matrix.rect(2, 5, 8, 1);
96  } 
97  else {
98    // SHAPE 4: Narrow Open (O-shape/Tense Vowel)
99    matrix.rect(2, 1, 8, 1);
100    matrix.rect(3, 2, 6, 1);
101    matrix.rect(3, 3, 1, 3);
102    matrix.rect(8, 3, 1, 3);
103    matrix.rect(4, 6, 4, 1);
104  }
105  
106  matrix.endDraw();
107}
108
109// =======================
110// 4. BRIDGE FUNCTIONS (RPC)
111// =======================
112
113// RPC FUNCTION: set_mouth
114// **CRITICAL BRIDGE LINK:** This function is called directly by the Python/Flask 
115// server running on the Linux MPU. It receives the 'state' integer via the 
116// internal serial bridge.
117int set_mouth(int state) {
118  // Update the global state based on the MPU's command.
119  talkState = state;
120  // Return the state for confirmation to the MPU (standard RPC practice).
121  return state;
122}
123
124// =======================
125// 5. ARDUINO SETUP
126// =======================
127
128void setup() {
129  // Initialize the LED Matrix hardware.
130  matrix.begin();
131  
132  // Initialize the Router Bridge (The communication link to the Linux MPU).
133  // This starts the internal serial communication that prevents restart hangs 
134  // and allows for robust communication.
135  Bridge.begin(); 
136  
137  // Provide the function 'set_mouth' to the Linux MPU.
138  // The MPU can now call this C++ function remotely using its Python script.
139  Bridge.provide("set_mouth", set_mouth);
140  
141  // Set the initial, idle state.
142  drawMouthClosed();
143}
144
145// =======================
146// 6. MAIN LOOP
147// =======================
148
149void loop() {
150  // 1. Handle Animation (Real-Time Control)
151  if (talkState == 1) {
152    // If the MPU command is 'Talking', rapidly draw a new frame.
153    drawRandomMouth();
154    Bridge.update(); // CRITICAL: Continuously service the Bridge communication during animation.
155    delay(80);       // Frame rate control (12.5 FPS) for smooth animation.
156  } else {
157    // 2. Handle Idle State (Optimization)
158    // Use a static check to only redraw the 'Closed' mouth once.
159    static int lastState = -1;
160    if (lastState != 0) {
161      drawMouthClosed();
162      lastState = 0;
163    }
164    // CRITICAL: Always service the Bridge even when idle to listen for MPU commands.
165    Bridge.update();
166  }
167}