diff --git a/examples/mascot-jump-game/python/main.py b/examples/mascot-jump-game/python/main.py index 0c26439..ea94914 100644 --- a/examples/mascot-jump-game/python/main.py +++ b/examples/mascot-jump-game/python/main.py @@ -1,4 +1,4 @@ -# SPDX-FileCopyrightText: Copyright (C) 2025 ARDUINO SA +# SPDX-FileCopyrightText: Copyright (C) ARDUINO SRL (http://www.arduino.cc) # # SPDX-License-Identifier: MPL-2.0 diff --git a/examples/mascot-jump-game/sketch/game_frames.h b/examples/mascot-jump-game/sketch/game_frames.h index f155c76..e5f0027 100644 --- a/examples/mascot-jump-game/sketch/game_frames.h +++ b/examples/mascot-jump-game/sketch/game_frames.h @@ -1,5 +1,5 @@ /* - * SPDX-FileCopyrightText: Copyright (C) 2025 ARDUINO SA + * SPDX-FileCopyrightText: Copyright (C) ARDUINO SRL (http://www.arduino.cc) * * SPDX-License-Identifier: MPL-2.0 */ diff --git a/examples/mascot-jump-game/sketch/sketch.ino b/examples/mascot-jump-game/sketch/sketch.ino index 80a729e..7f42f8e 100644 --- a/examples/mascot-jump-game/sketch/sketch.ino +++ b/examples/mascot-jump-game/sketch/sketch.ino @@ -1,4 +1,4 @@ -// SPDX-FileCopyrightText: Copyright (C) 2025 ARDUINO SA +// SPDX-FileCopyrightText: Copyright (C) ARDUINO SRL (http://www.arduino.cc) // // SPDX-License-Identifier: MPL-2.0 diff --git a/examples/object-hunting/python/main.py b/examples/object-hunting/python/main.py index 84e5996..e6624ea 100644 --- a/examples/object-hunting/python/main.py +++ b/examples/object-hunting/python/main.py @@ -1,4 +1,4 @@ -# SPDX-FileCopyrightText: Copyright (C) 2025 ARDUINO SA +# SPDX-FileCopyrightText: Copyright (C) ARDUINO SRL (http://www.arduino.cc) # # SPDX-License-Identifier: MPL-2.0 diff --git a/examples/theremin/README.md b/examples/theremin/README.md index 7175288..ed79aeb 100644 --- a/examples/theremin/README.md +++ b/examples/theremin/README.md @@ -1,146 +1,166 @@ # 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 minimal 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 low latency. -> **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**. +**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**. ![Theremin Simulator](assets/docs_assets/theremin-simulator.png) -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. +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. +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 -- `web_ui`: Brick that provides the web interface and a WebSocket channel for real-time control of the theremin. -- `wave_generator`: Brick that generates continuous audio waveforms and streams them to the USB speaker with smooth frequency and amplitude transitions. +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](https://store.arduino.cc/products/uno-q) (x1) +- Arduino UNO Q (x1) - **USB-C® hub with external power (x1)** -- A power supply (5 V, 3 A) for the USB hub adapter with external power (x1) +- A power supply (5 V, 3 A) for the USB hub (x1) - A **USB audio device** (choose one): - - **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) + - **USB speaker** (cabled) + - **USB wireless speaker receiver/dongle** (2.4 GHz, non-Bluetooth) - 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 -**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)**. +**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:** **HDMI audio** and **Bluetooth® Speakers** are not supported by this App. ## How to Use the Example -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) +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 `: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.* -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 `: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). +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. +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 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 uses the `wave_generator` brick to continuously generate and stream audio to the connected **USB** audio device with smooth transitions. +The application relies on a continuous data pipeline between the web interface and the audio synthesis engine. -- **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**, then updates the `wave_generator` brick's state. The brick handles smooth transitions using configurable envelope parameters (attack, release, glide). -- **Audio Output**: The `wave_generator` brick runs continuously in a background thread, generating audio blocks and streaming them to the **USB** audio device with minimal latency. +**High-level data flow:** -High-level data flow: ``` -Web Browser Interaction → WebSocket → Python Backend → WaveGenerator Brick → USB Audio Device Output +Web Browser Interaction ──► WebSocket ──► Python Backend + ▲ │ + │ ▼ + (Visual Updates) (Glide & Synthesis) + │ │ + └─ WebSocket ◄── State ◄── Sine Wave Generation + │ + ▼ + USB Audio 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 code manages the web server, handles real-time user input, and controls the audio generation brick. +The Python script simplifies audio logic by utilizing the `WaveGenerator` Brick. -- `ui = WebUI()` – Initializes the web server that serves the HTML interface and handles WebSocket communication. -- `wave_gen = WaveGenerator(...)` – Creates the wave generator brick with configured envelope parameters (attack=0.01s, release=0.03s, glide=0.02s). The brick automatically manages the USB speaker connection and audio streaming in a background thread. -- `ui.on_message('theremin:move', on_move)` – Registers a handler that fires whenever the frontend sends new coordinates. This function updates the wave generator's frequency and amplitude using `wave_gen.set_frequency()` and `wave_gen.set_amplitude()`. -- The `wave_generator` brick handles all audio generation and streaming automatically, including smooth transitions between frequency and amplitude changes, continuous audio output with ~**30 ms** blocks, and non-blocking playback without cracks or pops. +- **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. -### 💻 Frontend (`main.js`) +```python +wave_gen = WaveGenerator(sample_rate=16000, ...) -The web interface provides the interactive play area and controls for the user. +def _freq_from_x(x): + # Exponential mapping from 20Hz up to Nyquist frequency + return 20.0 * ((SAMPLE_RATE / 2.0 / 20.0) ** x) -- **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-100** hardware volume value to control the USB speaker's output level. -- `socket.emit('theremin:power', { on })` – Toggles synth power (**On/Off**). After turning **On**, move/tap in the play area to resume sound. +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`) +The web interface handles user input and visualization. -## Troubleshooting +- **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. -### "No USB speaker found" error +```javascript +// Send normalized coordinates (0.0 - 1.0) to backend +socket.emit('theremin:move', { x, y }); -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. +// Receive state for visualization +socket.on('theremin:state', (data) => { + updateStateDisplay(data.freq, data.amp); +}); ``` -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**. + +## 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. 3. Restart the application. ### No Sound Output - -- **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. +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. ### Choppy or Crackling Audio - -- **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. - - +- **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. ## Technical Details -- **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 \ No newline at end of file +- **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) \ No newline at end of file diff --git a/examples/theremin/assets/docs_assets/theremin-simulator.png b/examples/theremin/assets/docs_assets/theremin-simulator.png index fce4662..84aa2e2 100644 Binary files a/examples/theremin/assets/docs_assets/theremin-simulator.png and b/examples/theremin/assets/docs_assets/theremin-simulator.png differ diff --git a/examples/theremin/python/main.py b/examples/theremin/python/main.py index f499d9a..5c2acab 100644 --- a/examples/theremin/python/main.py +++ b/examples/theremin/python/main.py @@ -1,4 +1,4 @@ -# SPDX-FileCopyrightText: Copyright (C) 2025 ARDUINO SA +# SPDX-FileCopyrightText: Copyright (C) ARDUINO SRL (http://www.arduino.cc) # # SPDX-License-Identifier: MPL-2.0 diff --git a/examples/vibration-anomaly-detection/python/main.py b/examples/vibration-anomaly-detection/python/main.py index d3fa19f..f79b877 100644 --- a/examples/vibration-anomaly-detection/python/main.py +++ b/examples/vibration-anomaly-detection/python/main.py @@ -1,4 +1,4 @@ -# SPDX-FileCopyrightText: Copyright (C) 2025 ARDUINO SA +# SPDX-FileCopyrightText: Copyright (C) ARDUINO SRL (http://www.arduino.cc) # # SPDX-License-Identifier: MPL-2.0 diff --git a/examples/vibration-anomaly-detection/sketch/sketch.ino b/examples/vibration-anomaly-detection/sketch/sketch.ino index f413983..47d24b5 100644 --- a/examples/vibration-anomaly-detection/sketch/sketch.ino +++ b/examples/vibration-anomaly-detection/sketch/sketch.ino @@ -1,4 +1,4 @@ -// SPDX-FileCopyrightText: Copyright (C) 2025 ARDUINO SA +// SPDX-FileCopyrightText: Copyright (C) ARDUINO SRL (http://www.arduino.cc) // // SPDX-License-Identifier: MPL-2.0