OmniSocketGo/scripts/dev/README.md

Dev Startup Scripts

This directory lives inside the OmniSocketGo repo and acts as the main launch entry for the whole local setup.

Default layout:

~/Documents/
  OmniSocketGo/
    scripts/dev/
  robot-command-center/

The scripts assume:

• OmniSocketGo is the current repo
• robot-command-center is a sibling directory next to it

If your robot-command-center is elsewhere, set ROBOT_COMMAND_CENTER_ROOT in robot-remote.env.local. start-backend.sh and start-frontend.sh need that repo; start-ros-receiver.sh and start-b-side-omnid.sh do not.

Files

• robot-remote.env: shared defaults for backend, frontend, ROS, and b_side_omnid
• robot-remote.env.local: optional local override file loaded after robot-remote.env
• load-env.sh: loads the shared environment into the current shell
• apply-camera-controls.sh: applies the camera preset before b_side_omnid starts
• start-backend.sh: starts Django ASGI with uvicorn
• start-frontend.sh: starts the Vite dev server
• start-ros-receiver.sh: starts the ROS2 udp_teleop_bridge receiver
• start-b-side-omnid.sh: applies camera controls, then starts ./bin/b_side_omnid and uses sudo -E by default
• start-dev-tmux.sh: optional one-command tmux launcher for all four processes

Usage

Run these from the OmniSocketGo repo root:

bash scripts/dev/start-backend.sh
bash scripts/dev/start-frontend.sh
bash scripts/dev/start-ros-receiver.sh
bash scripts/dev/start-b-side-omnid.sh

If you prefer one command and use tmux:

bash scripts/dev/start-dev-tmux.sh

If you only want the shared environment for manual commands:

source scripts/dev/load-env.sh

When you launch via start-*.sh, you do not need to manually export the variables from robot-remote.env or robot-remote.env.local. load-env.sh loads those files with set -a, so the variables are exported automatically for the child process. Manual export is only needed if you bypass these scripts and start binaries directly from a clean shell.

Customizing

Edit scripts/dev/robot-remote.env for shared changes such as:

• ROBOT_COMMAND_CENTER_ROOT
• CONTROL_SIDE_OMNISOCKET_SERVER_ADDR
• CONTROL_SIDE_OMNISOCKET_RELAY_VIA
• ROBOT_SIDE_OMNISOCKET_SERVER_ADDR
• ROBOT_SIDE_OMNISOCKET_RELAY_VIA
• VITE_API_BASE_URL
• OMNI_CAMERA_DEVICE
• OMNI_CAMERA_PROFILE
• OMNI_CAMERA_BRIGHTNESS
• OMNI_CAMERA_CUSTOM_CTRL
• OMNI_CAMERA_VERIFY
• OMNI_VIDEO_PEER_ID
• OMNI_CONTROL_PEER_ID
• OMNI_VIDEO_SOFT_BACKPRESSURE_SEGMENTS
• OMNI_VIDEO_HARD_BACKPRESSURE_SEGMENTS
• OMNI_VIDEO_HARD_BACKPRESSURE_HOLD_MS
• OMNI_CONTROL_SERVER_IDLE_RECONNECT_MS
• OMNI_VIDEO_MAX_FRAME_AGE_MS

Camera presets use v4l2-ctl from v4l-utils on the robot side.

Role mapping:

• start-backend.sh uses the CONTROL_SIDE_* address pair
• start-b-side-omnid.sh uses the ROBOT_SIDE_* address pair
• start-b-side-omnid.sh also applies the OMNI_CAMERA_* preset before the daemon opens the camera
• start-ros-receiver.sh defaults to the robot-side address pair, but with transport=unix_dgram it usually does not need the server address

New repair knobs:

• OMNI_VIDEO_SOFT_BACKPRESSURE_SEGMENTS, OMNI_VIDEO_HARD_BACKPRESSURE_SEGMENTS, and OMNI_VIDEO_HARD_BACKPRESSURE_HOLD_MS are used by b_side_omnid
• OMNI_CONTROL_SERVER_IDLE_RECONNECT_MS is used by b_side_omnid
• OMNI_VIDEO_MAX_FRAME_AGE_MS is used by start-backend.sh on the A-side backend, not by b_side_omnid

Put machine-specific overrides into scripts/dev/robot-remote.env.local. Example:

ROBOT_COMMAND_CENTER_ROOT="$HOME/Documents/robot-command-center"
OMNI_CAMERA_DEVICE="/dev/video30"
B_SIDE_OMNID_USE_SUDO="0"

Default camera behavior is the night preset:

OMNI_CAMERA_PROFILE="night"
# Optional per-machine tweak:
OMNI_CAMERA_BRIGHTNESS="8"

To switch to a daytime preset with brightness only:

OMNI_CAMERA_PROFILE="day"
OMNI_CAMERA_BRIGHTNESS="8"

To send the raw v4l2-ctl --set-ctrl=... payload yourself:

OMNI_CAMERA_PROFILE="custom"
OMNI_CAMERA_CUSTOM_CTRL="brightness=8,auto_exposure=1,exposure_time_absolute=800,gain=64"
OMNI_CAMERA_VERIFY="1"