Choose a complete beginner workshop
New: Vibe Coding playground. Each model workshop now includes copyable AI prompts, a no-flash personality experiment, a personalized startup greeting and expandable game ideas. Start with the personality exercise for a quick first experience, then follow the build workshop when you want firmware changes. The guidance and exercises stay on the same model page.
Each workshop includes installation, commands, expected results, a first edit, an optional MCP exercise and recovery on the same page. Open the workshop for your actual robot and follow it in order.
- RIG-Puppy: my first firmware change
- RIG-Hover: my first firmware change
- RIG-Arm: my first firmware change
- RIG-TARS: my first firmware change
TARS public source is available. Select RIG-Tars in the public board configuration. The TARS beginner workshop now covers its complete build, first edit, MCP tools and recovery. Use ESP-IDF 5.5.3 for that workshop; the repository documents TARS builds with this version.
1. Understand what you are about to do
You do not need to understand the whole program. Your first goal is to add a message to the robot's startup log, then read that message on your computer. This proves that your own source was compiled, transferred and started. The new line does not request movement; the robot's existing startup behavior still runs.
| Word | What it means here |
|---|---|
| Source code | Editable text files describing how the robot works. |
| Firmware | The compiled program stored on the robot. |
| ESP-IDF | Espressif's tools and libraries for building ESP32 firmware. |
| Terminal | A window where you type commands and read their results. |
| Build / compile | Turn source files into firmware on your computer. This does not write to the robot. |
| Flash | Write firmware from your computer to the robot. |
| Serial port | The computer's connection to the controller, such as COM5. |
| Monitor / log | Live text printed by the running firmware. |
| Board target | The robot model whose hardware and behavior will be built. |
Before continuing: finish assembly, calibration and normal first use. Have a USB data cable, a computer with Internet access and a charged robot. A charge-only cable can power a board without connecting it to your computer. Identify the correct controller connector from your kit instructions.
Record the robot model, controller revision, working firmware version and how to obtain its matching official firmware again. Flashing writes firmware; changes to partitions or a full erase can also remove settings. Keep account details and calibration notes available. Do not begin with an unknown model or an unidentified recovery image.
2. Install the tools and open the right terminal
Use ESP-IDF 5.5.2 as the initial tutorial environment. The project's README specifies 5.5.2 or newer, but that is not a promise that every future major version works. Avoid changing both your program and the toolchain during your first exercise.
Windows: start here
- Install Git from Git for Windows. Git downloads and tracks the source files. The standard installation is sufficient for this exercise.
- Open Espressif's ESP-IDF installation instructions. Use its Windows installer or Installation Manager. In the version selection, choose 5.5.2 and install the tools for ESP32-S3. Let it finish downloading its Python environment, compiler and build tools.
- Open the ESP-IDF terminal / PowerShell environment supplied by the installation. If the manager offers an environment launch action, launch the installed 5.5.2 environment there. An ordinary PowerShell window may not know where these tools are.
- Install a text editor such as Visual Studio Code. Use it to open and edit files. You can keep the ESP-IDF terminal in a separate window; an editor extension is optional for this walkthrough.
- In the ESP-IDF terminal, run these checks, one line at a time:
git --version
python --version
idf.py --version
Expected result: each command prints a version. The last command identifies ESP-IDF 5.5.2. If a command is not found, fix this before downloading or compiling the project. Reopen the ESP-IDF environment after installation; reinstalling the robot firmware cannot fix a missing computer tool.
Using macOS or Linux instead?
Use the macOS or Linux instructions in the same official ESP-IDF guide and select the same IDF version. Activate the installed environment in every new terminal. For a traditional ESP-IDF checkout, activation is usually performed from its installation folder with:
. ./export.sh
That command belongs in the ESP-IDF installation directory, not in the robot project. If you used an installation manager, use its environment launcher instead. Run the three version checks above before continuing. The Git and IDF commands below are otherwise the same; use your own project directory and serial port.
3. Download the public code and find the project folder
Create a simple working folder such as C:\rig-work using File Explorer. Avoid a synchronized cloud folder for the first build. In your ESP-IDF terminal, move into it and download the project:
cd C:\rig-work
git clone --branch main https://github.com/LuwuDynamics/rig_omni.git
cd rig_omni
On macOS/Linux, create a working directory in your home folder and run the same clone command there. The last command enters the newly downloaded project. Do not copy the Windows path on those systems.
Open the rig_omni folder in your editor using File → Open Folder. You should see CMakeLists.txt, main and sdkconfig.defaults at the project root. If you only see a single folder named rig_omni, open that inner folder. Keep the terminal at the same project root for all remaining IDF commands.
If Git says the destination already exists: use the existing checkout if it is yours, or choose a new empty working directory. Do not delete another project to make the command work. A GitHub ZIP also contains source, but Git history commands in this tutorial will not work in a ZIP download.
Make a branch for your work and record which source you downloaded:
git switch -c my-first-rig-change
git rev-parse --short HEAD
git status --short
The first command creates a local workspace branch; it does not publish anything. Save the short identifier in your own notes. An empty status output means no tracked file changes. If the branch name already exists, use a new name or switch to your own existing branch without the -c option.
Something isn't working? A download failure is a computer/network issue. Confirm the public repository opens in your browser and read the Git error. Do not substitute an unrelated robot repository.
What to do next
Choose your model's workshop above for the exact board selection and editing path. You do not need to study every shared reference before your first build. The public source is the source used by these workshops.
Connect RIG through MCP
Connect an AI client to RIG or add external tools. For home control, follow the official RIG Home Assistant integration. Existing-tool connections do not require firmware edits.