Add Theremin, Vibration detection and Object Hunting examples

Author: mirkokurt

examples/object-hunting/app.yaml

@@ -1,6 +1,7 @@
 name: Object Hunting
 icon: 🔍
 description: Detect a list of object to win the game
+
 bricks:
   - arduino:video_object_detection
   - arduino:web_ui

examples/object-hunting/assets/app.js

@@ -1,4 +1,4 @@
-// SPDX-FileCopyrightText: Copyright (C) ARDUINO SRL (http://www.arduino.cc)
+// SPDX-FileCopyrightText: Copyright (C) 2025 ARDUINO SA <http://www.arduino.cc>
 //
 // SPDX-License-Identifier: MPL-2.0
 

examples/object-hunting/assets/fonts/fonts.css

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: Copyright (C) ARDUINO SRL (http://www.arduino.cc)
+ * SPDX-FileCopyrightText: Copyright (C) 2025 ARDUINO SA <http://www.arduino.cc>
  *
  * SPDX-License-Identifier: MPL-2.0
  */

examples/object-hunting/assets/img/logo.svg.license

@@ -1,3 +1,3 @@
-SPDX-FileCopyrightText: Copyright (C) ARDUINO SRL (http://www.arduino.cc)
+SPDX-FileCopyrightText: Copyright (C) 2025 ARDUINO SA <http://www.arduino.cc>
 
 SPDX-License-Identifier: MPL-2.0

examples/object-hunting/assets/index.html

@@ -1,5 +1,5 @@
 <!--
-SPDX-FileCopyrightText: Copyright (C) ARDUINO SRL (http://www.arduino.cc)
+SPDX-FileCopyrightText: Copyright (C) 2025 ARDUINO SA <http://www.arduino.cc>
 
 SPDX-License-Identifier: MPL-2.0
 -->

examples/object-hunting/assets/style.css

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: Copyright (C) ARDUINO SRL (http://www.arduino.cc)
+ * SPDX-FileCopyrightText: Copyright (C) 2025 ARDUINO SA <http://www.arduino.cc>
  *
  * SPDX-License-Identifier: MPL-2.0
  */

examples/object-hunting/python/main.py

@@ -1,4 +1,4 @@
-# SPDX-FileCopyrightText: Copyright (C) ARDUINO SRL (http://www.arduino.cc)
+# SPDX-FileCopyrightText: Copyright (C) 2025 ARDUINO SA <http://www.arduino.cc>
 #
 # SPDX-License-Identifier: MPL-2.0
 

examples/theremin/README.md

@@ -1,166 +1,146 @@
 # Theremin Simulator
 
-The **Theremin Simulator** example lets you create and control a virtual theremin instrument using an interactive web interface, producing synthesized audio output through a connected **USB** audio device with low latency.
+The **Theremin Simulator** example lets you create and control a virtual theremin instrument using an interactive web interface, producing synthesized audio output through a connected **USB** audio device with minimal latency.
 
-**Note:** This example requires to be run using **Network Mode** or **Single-Board Computer (SBC)**, since it requires a **USB-C® hub** and a **USB speaker**.
+> **Note**: This example must be run in **[Network Mode](learn/network-mode)** or **[SBC Mode](learn/single-board-computer)**, since it requires a **USB-C® hub** and a **USB speaker**.
 
 ![Theremin Simulator](assets/docs_assets/theremin-simulator.png)
 
-This App creates a virtual instrument that generates real-time audio by creating sine waves at varying frequencies and amplitudes based on user input. The workflow involves receiving mouse or touch coordinates from the frontend and updating a **Wave Generator** Brick, which handles the audio synthesis, smoothing, and streaming to the **USB device** automatically.
+This example generates real-time audio by creating sine waves at varying frequencies and amplitudes based on user input from the web interface. The workflow involves receiving mouse/touch coordinates from the frontend, calculating the corresponding frequency and amplitude, generating audio blocks using a sine wave generator, and playing them through a **USB** audio device with minimal latency.
 
-**Key features include:**
-
-- Real-time audio synthesis with low latency
-- Interactive web interface for pitch and volume control
-- Visual waveform display showing frequency and amplitude
-- Automatic envelope smoothing (attack, release, glide) for natural sound
-- Support for USB speakers and wireless USB audio receivers
 
 ## Bricks Used
 
-The theremin simulator example uses the following Bricks:
-
 - `web_ui`: Brick that provides the web interface and a WebSocket channel for real-time control of the theremin.
-- `wave_generator`: Brick that handles audio synthesis, envelope control (smoothing), and streaming to the USB audio device.
+
 
 ## Hardware and Software Requirements
 
 ### Hardware
 
-- Arduino UNO Q (x1)
+- [Arduino UNO Q](https://store.arduino.cc/products/uno-q) (x1)
 - **USB-C® hub with external power (x1)**
-- A power supply (5 V, 3 A) for the USB hub (x1)
+- A power supply (5 V, 3 A) for the USB hub adapter with external power (x1)
 - A **USB audio device** (choose one):
-  - **USB speaker** (cabled)
-  - **USB wireless speaker receiver/dongle** (2.4 GHz, non-Bluetooth)
+  - **USB speaker** (cabled) (x1) ✅ *supported*
+  - **USB wireless speaker receiver/dongle** (2.4 GHz) (x1) ✅ *supported*
+  - **USB‑C → 3.5 mm audio connector** + headphones/speakers (x1) ⚠️ *not tested* (may work)
 - A **power supply** (5 V, 3 A) for the USB hub (e.g. a phone charger)
 
+> **Not supported:** **HDMI audio and Bluetooth® Speakers** output is not supported by this App.
+
 ### Software
 
 - Arduino App Lab
 
-**Important:** A **USB-C® hub is mandatory** for this example. The UNO Q's single port must be used for the hub, which provides the necessary connections for both the power supply and the USB audio device. Consequently, this example must be run in **[Network Mode](learn/network-mode)** or **[SBC Mode](learn/single-board-computer)**.
+**Note:** A **USB-C® hub is mandatory** for this example. The UNO Q's single port must be used for the hub, which provides the necessary connections for both the power supply and the USB audio device. Consequently, this example must be run in **[Network Mode](learn/network-mode)** or **[SBC Mode](learn/single-board-computer)**.
 
-**Note:** **HDMI audio** and **Bluetooth® Speakers** are not supported by this App.
 
 ## How to Use the Example
 
-1. **Hardware Setup**
-   Connect your **USB audio device** (e.g., USB speaker, wireless USB receiver) to a powered **USB-C® hub** attached to the UNO Q. Ensure the hub is powered.
-
-2. **Run the App**
-   Launch the App from Arduino App Lab. Wait until the App has launched completely.
-
-3. **Access the Web Interface**
-   Open the App in your browser at `<UNO-Q-IP-ADDRESS>:7000` (typically `192.168.x.x`).
-
-4. **Turn on Power**
-   Locate the orange control panel at the bottom of the interface. Click the **POWER** switch to toggle it **ON** (the small LED indicator will light up).
-   *Note: No sound will be produced if this switch is OFF.*
+1. Connect your **USB audio device** (e.g., USB speaker, wireless USB receiver, or USB‑C→3.5 mm dongle) to a powered **USB-C® hub** attached to the UNO Q.
+   ![hardware-setup](assets/docs_assets/hardware-setup.png)
 
-5. **Set Master Volume**
-   Use the **+** and **-** buttons near the **VOL** indicator to adjust the master volume. This sets the maximum output limit for the application.
+2. Launch the App by clicking the **Play** button in the top-right corner. Wait until the App has launched. 
+   ![Launching an App](assets/docs_assets/launch-app-theremin.png)
+3. Open the App in your browser at `<UNO-Q-IP-ADDRESS>:7000` *(typically 192.168.x.x, e.g., http://192.168.1.11:7000)*.
+4. Click and drag your mouse (or use touch) on the interactive area to play:
+   - **Horizontal movement (X-axis)** controls the **pitch** (frequency).
+   - **Vertical movement (Y-axis)** controls the **volume** (amplitude).
 
-6. **Play the Instrument**
-   Drag your mouse (or use your finger on a touchscreen) inside the large gray background area:
-   - **Horizontal (Left ↔ Right):** Controls **Pitch**. Moving right increases the frequency (higher notes).
-   - **Vertical (Bottom ↕ Top):** Controls **Note Volume**. Moving up increases the amplitude (louder). Moving to the very bottom silences the note.
-
-7. **Visualize Audio**
-   Observe the screen in the center of the panel, which visualizes the real-time sine wave, frequency (Hz), and amplitude data. You can also toggle the **GRID** switch to visually reference specific pitch intervals.
 
 ## How it Works
 
-The application relies on a continuous data pipeline between the web interface and the audio synthesis engine.
+The application creates a real-time audio synthesizer controlled by a web interface. User interactions on the webpage are sent to the Python backend via a WebSocket. The backend then calculates the audio parameters, generates a sine wave, and streams the audio data directly to the connected **USB** audio device.
 
-**High-level data flow:**
+- **User Interaction**: The frontend captures mouse or touch coordinates within a designated "play area".
+- **Real-time Communication**: These coordinates are sent to the Python backend in real-time using the `web_ui` Brick's WebSocket channel.
+- **Audio Synthesis**: The backend maps the X-coordinate to **frequency** and the Y-coordinate to **amplitude**. It uses a sine wave generator to create small blocks of audio data based on these parameters.
+- **Audio Output**: The generated audio blocks are continuously streamed to the **USB** audio device, creating a smooth and responsive sound.
 
+High-level data flow:
 ```
-Web Browser Interaction  ──►  WebSocket  ──►  Python Backend
-         ▲                                          │
-         │                                          ▼
-  (Visual Updates)                         (Glide & Synthesis)
-         │                                          │
-         └─  WebSocket   ◄──   State    ◄──  Sine Wave Generation
-                                                    │
-                                                    ▼
-                                             USB Audio Output
+Web Browser Interaction → WebSocket → Python Backend → Sine Wave Generation → USB Audio Device Output
 ```
 
-- **User Interaction**: The frontend captures mouse/touch coordinates and sends them to the backend via the `web_ui` Brick's WebSocket channel.
-- **Audio Synthesis**: The `wave_generator` Brick runs in the background. It takes the target frequency and amplitude and applies a **glide algorithm** to transition smoothly between notes.
-- **Envelope Smoothing**: The Brick automatically handles attack, release, and glide to ensure the audio changes sound natural and analog-like, rather than robotic.
-- **Audio Output**: The Brick streams the generated sine wave directly to the **USB** audio device.
 
 ## Understanding the Code
 
 ### 🔧 Backend (`main.py`)
 
-The Python script simplifies audio logic by utilizing the `WaveGenerator` Brick.
-
-- **Initialization**: Configures the audio engine with specific parameters (sine wave, 16kHz sample rate) and envelope settings (attack, release, glide).
-- **Frequency Calculation**: Maps the X-axis input (0.0 to 1.0) exponentially to a frequency range of 20 Hz to ~8000 Hz.
-- **Event Handling**: Listens for `theremin:move` events from the frontend to update frequency and amplitude.
+The Python code manages the web server, handles real-time user input, and performs all audio generation and playback.
 
-```python
-wave_gen = WaveGenerator(sample_rate=16000, ...) 
+- `ui = WebUI()` – Initializes the web server that serves the HTML interface and handles WebSocket communication.
+- `speaker = Speaker(...)` – Initializes the connection to the USB audio device. This will raise an error if no compatible device is found.
+- `sine_gen = SineGenerator(...)` – Creates an instance of the audio synthesis engine.
+- `ui.on_message('theremin:move', on_move)` – Registers a handler that fires whenever the frontend sends new coordinates. This function updates the target frequency and amplitude.
+- `theremin_producer_loop()` – Core audio engine. Runs continuously, generating ~**30 ms** blocks of audio based on the current frequency and amplitude, and streams them to the audio device for playback. This non-blocking, continuous stream ensures smooth audio without cracks or pops.
 
-def _freq_from_x(x):
-    # Exponential mapping from 20Hz up to Nyquist frequency
-    return 20.0 * ((SAMPLE_RATE / 2.0 / 20.0) ** x)
-
-def on_move(sid, data):
-    # Calculate target frequency and amplitude based on coordinates
-    freq = _freq_from_x(data.get("x"))
-    amp = max(0.0, min(1.0, 1.0 - float(data.get("y"))))
-    
-    wave_gen.set_frequency(freq)
-    wave_gen.set_amplitude(amp)
-```
+### 💻 Frontend (`main.js`)
 
-### 🔧 Frontend (`main.js`)
+The web interface provides the interactive play area and controls for the user.
 
-The web interface handles user input and visualization.
+- **Socket.IO connection** to the backend to send and receive data in real time.
+- **Event listeners** capture `mousedown`, `mousemove`, `mouseup` (and touch equivalents) to track user interaction in the play area.
+- `socket.emit('theremin:move', { x, y })` – Sends normalized (0.0–1.0) X and Y coordinates to the backend; emissions are **throttled to ~80 Hz (≈12 ms)** to avoid overload.
+- `socket.on('theremin:state', ...)` – Receives state updates from the backend (like the calculated frequency and amplitude) and updates the values displayed on the webpage.
+- `socket.emit('theremin:set_volume', { volume })` – Sends a **0.0–1.0** master volume value and updates a progress bar in the UI.
+- `socket.emit('theremin:power', { on })` – Toggles synth power (**On/Off**). After turning **On**, move/tap in the play area to resume sound.
 
-- **Input Capture**: Event listeners track `mousemove`, `touchmove`, and `touchstart` to capture user interaction.
-- **Throttling**: Emissions to the backend are throttled to approximately 80 Hz (~12 ms) to prevent network overload while maintaining responsiveness.
-- **Visual Feedback**: The canvas draws a real-time sine wave animation based on the amplitude and frequency data received back from the server.
 
-```javascript
-// Send normalized coordinates (0.0 - 1.0) to backend
-socket.emit('theremin:move', { x, y });
-
-// Receive state for visualization
-socket.on('theremin:state', (data) => {
-    updateStateDisplay(data.freq, data.amp);
-});
-```
 
 ## Troubleshooting
 
 ### "No USB speaker found" error
-If the application fails to start and you see an error regarding the speaker:
-**Fix:**
-1. Ensure a **powered USB-C® hub** is connected to the UNO Q.
-2. Verify the **USB audio device** is connected to the hub and turned on.
+
+If the application fails to start and you see the following error in the logs, it means the required audio hardware is missing or not detected.
+```
+arduino.app_peripherals.speaker.SpeakerException: No USB speaker found.
+```
+**Fix:**  
+1. Make sure a **powered USB-C® hub** is connected to the UNO Q and its **5 V / 3 A** power supply is plugged in.  
+2. Verify the **USB audio device** (USB speaker, wireless USB receiver, or USB-C→3.5 mm dongle) is **connected to the hub** and, if it has a switch, **turned on**.  
 3. Restart the application.
 
 ### No Sound Output
-If the interface works but there is no sound:
-- **Power Button:** Ensure the **POWER** switch in the web UI is **ON**.
-- **Pointer Position:** Ensure you are interacting with the upper part of the play area (bottom is zero volume).
-- **Volume Controls:** Increase the volume using the **+** button in the UI.
-- **Hardware Volume:** Check the physical volume control on your speaker.
-- **Audio Device:** Remember that **HDMI audio** and **Bluetooth® speakers** are not supported.
+
+- **Power Button:** Make sure the button in the web UI shows **On**.  
+- **Volume Slider:** Increase the volume slider in the web UI.  
+- **Pointer Position:** Move your mouse/finger toward the top of the play area (the bottom corresponds to zero volume).  
+- **Speaker/Headphone Volume:** Check the physical volume control and mute status on your speaker or headphones.  
+- **Output Path:** Remember that **HDMI audio** and **Bluetooth® speakers** are not supported; use a **USB** audio device.
 
 ### Choppy or Crackling Audio
-- **CPU Load:** Close other applications running on the Arduino UNO Q.
-- **Power Supply:** Ensure you are using a stable 5 V, 3 A power supply for the USB-C® hub. Insufficient power often degrades USB audio performance.
+
+- **CPU Load:** Close any other applications running on the Arduino UNO Q that may be consuming significant resources.  
+- **Power Supply:** Ensure you are using a stable, adequate power supply (5 V, 3 A) for the USB-C® hub, as insufficient power can affect USB peripheral performance.
+
+
 
 ## Technical Details
 
-- **Sample rate:** 16,000 Hz
-- **Audio format:** 32-bit float, little-endian
-- **Latency:** ~30 ms block duration
-- **Frequency range:** ~20 Hz to ~8,000 Hz
-- **Envelope:** Attack (0.01s), Release (0.03s), Glide (0.02s)
+- **Sample rate:** 16,000 Hz  
+- **Audio format:** 32-bit float, little-endian  
+- **Block duration:** ~30 ms (≈480 samples per block)  
+- **Frequency range:** ~20 Hz to ~8,000 Hz  
+- **Update rate:** Frontend throttled to ~80 Hz (≈12 ms minimum between updates)
+
+
+
+## Compatibility Notes
+
+- **Works with:**  
+  - **USB speakers** (cabled)  
+  - **USB wireless speaker receivers** (2.4 GHz dongles)
+- **Untested (may work):**  
+  - **USB‑C → 3.5 mm audio dongles** feeding analog speakers/headphones
+- **Not supported:**  
+  - **HDMI audio** output  
+  - **Bluetooth® speakers**
+
+
+## License
+
+This example is licensed under the Mozilla Public License 2.0 (MPL-2.0).
+
+Copyright (C) 2025 ARDUINO SA <http://www.arduino.cc>

examples/theremin/app.yaml

@@ -3,4 +3,3 @@ icon: 🎼
 description: A simple theremin simulator that generates audio based on user input.
 bricks:
   - arduino:web_ui
-  - arduino:wave_generator