Neobotics Foundation Inc.
OS & imageNEORACER DOCS
NEORACER DOCS
These docs are public and open source.Edit on GitHub
SOFTWARE / OS & IMAGE

THE PRE-FLASHED IMAGE.

Every NeoRacer ships with a card that boots straight to JetPack 6.2, Ubuntu 22.04.5 LTS, Python 3.10.12, ROS 2 Humble, and JupyterLab running as a . So you can power on, SSH in, install the neoracer_ros2_driver, and start writing code on the same day it arrives.

Pre-flashed at the factoryJetPack 6.2Ubuntu 22.04.5 LTSROS 2 HumblePython 3.10.12Jetson Orin Nano
FIG. A / WHAT'S ON THE IMAGE
YOUR CODE
/home/racecar/*.py
YOU LIVE HERE
neoracer_ros2_driver
teleop launch · run manually
racecar-neo-library
Python · rc.* namespace
ROS 2 Humble
topics · services · params · TF
Ubuntu 22.04 LTS
rootfs · apt · users · network
Jetson Linux BSP
kernel · CUDA · TensorRT · drivers
Bottom to top. Everything below your code is read-only by default. Your scripts live in /home/racecar/scripts.
01 / WHAT'S RUNNING AT BOOT

WHAT RUNS AT BOOT.

The only thing that auto-starts at boot is JupyterLab. The robot stack is not a systemd service: once you have installed the neoracer_ros2_driver, you bring every on the ROS 2 driver page up by running teleop yourself.

// systemctl is-active neoracer-jupyter
neoracer-jupyter.service  # headless JupyterLab on :8888, auto-start

// then bring up the robot yourself
racecar teleop  # wraps: ros2 launch neoracer_ros2_driver teleop.launch.py
  # brings up controller, gamepad_node, mux_node,
  # throttle_node, camera, led_matrix, lakibeam1
  • racecar teleop brings up the full driver stack: the controller node owns the ESP32 serial link (publishes /imu, /odom, /joy and subscribes to /motor), plus gamepad_node, mux_node, throttle_node, camera, led_matrix, and the Lakibeam .
  • The watchdog supervises every node and restarts a dead one. The web dashboard at http://neoracer.local:8080 shows per-node liveness, topic rates, and Jetson temperature.
  • JupyterLab logs route through journalctl -u neoracer-jupyter -f, no separate log directory to track.
FIG. B / RE-FLASH FROM SCRATCH
1
Download
neoracer-os.img
2
balenaEtcher
Flash to SD
3
Insert SD
Into Jetson
4
Power on
Boot to login
5
192.168.1.101
static IP · SSH
A spare SD card and balenaEtcher. Five steps. The whole thing takes about 12 minutes on a fresh laptop.
02 / FLASH A FRESH CARD

FLASH A FRESH CARD.

You only need this if you broke something unrecoverable, or you want a clean classroom set. The car ships flashed.

bash
# 1. Download the latest image (verify the SHA-256 against the release page).
curl -LO https://images.neobotics.org/neoracer/neoracer-os-latest.img.xz
sha256sum neoracer-os-latest.img.xz

# 2. Open balenaEtcher.
#    Flash from file → pick the .img.xz (Etcher will decompress on the fly).
#    Insert the microSD. Pick it as the target. Flash.

# 3. Eject the card, slide it into the Jetson SD slot under the chassis.
# 4. Plug the battery in, flip the master switch.
# 5. Wait ~30 s for first boot. The status LED ladder will turn solid red→green.
03 / FIRST BOOT, THE DEFAULTS

FIRST-BOOT DEFAULTS.

01

Hostname

neoracer
The car has a static IP of 192.168.1.[100 + Car ID] on its own network (Car 1 is 192.168.1.101). Reach it by hostname or by that address.
ssh racecar@neoracer
02

Default user

racecar
Password is neobotics. If the car will share a classroom space, it's worth setting a new one on day one.
passwd # change me
03

Time + locale

UTC, NTP synced
NTP locks within the first 5 s of Wi-Fi association. ROS 2 timestamps line up with your laptop without any extra config.
timedatectl status
04

Wi-Fi access point

neoracer-[Car ID]
The car is its own access point. Join its network from your laptop (Car 1 broadcasts neoracer-1), then SSH in or open JupyterLab. See Networking.
ssid: neoracer-1 · pw: neobotics
FIG. C / FINDING THE CAR ON THE NETWORK
ssh racecar@neoracerYOUR LAPTOPCAR Wi-Fi AP(neoracer_1 · neobotics)NEORACER192.168.1.101static ip · sshd · ros 2THE CARSTATIC IP · NO DNS SERVER
The car is its own Wi-Fi access point. Join neoracer-[Car ID] (password neobotics), then reach it at its static IP 192.168.1.[100 + Car ID], hostname neoracer. Car 1 is 192.168.1.101.
04 / SSH IN, VERIFY EVERYTHING

SSH IN AND VERIFY.

bash
# 1. Confirm you're in (after joining the car's neoracer-[Car ID] network).
ssh racecar@neoracer                     # or: ssh racecar@192.168.1.101
# racecar@neoracer:~$

# 2. JupyterLab service is healthy?
systemctl is-active jupyterlab           # active

# 3. ROS 2 graph is up? (run "teleop" first)
ros2 topic list                          # /camera /scan /imu /odom /joy /drive

# 4. Try a single LiDAR scan.
ros2 topic echo /scan --once | head -20
05 / WHEN IT WON'T BOOT

RECOVERY AND RE-FLASH.

Recovery here is just three steps: pull the SD card, re-flash it with balenaEtcher, and slide it back. There's no Recovery Mode UI to learn. Your calibration files live on the MCU (microcontroller unit)'s flash, not on the SD card, so the car is ready to drive the moment it boots.

  • Boot loops usually point at a corrupt SD card, so a re-flash is the first thing to try, and it clears them up far more often than a Jetson fault does.
  • AP not coming up after re-flash? Connect an ethernet cable, SSH via racecar@neoracer, run sudo nmtui to rebuild the access point.
  • Lost the password? A re-flash is the way back in. The password lives in shadow on the SD card, so a fresh image gives you the default again.
  • Calibration gone? It's not. The motor trim and servo center live on the MCU. Re-flashing the SD does not touch them. See Motor trim.