Skip to content

README.md

Latest commit

 

History

History
382 lines (286 loc) · 9.02 KB

README.md

File metadata and controls

382 lines (286 loc) · 9.02 KB
Raw

Innate-OS Update System

Table of Contents

Quick Start

# Check for updates
innate update check

# Apply updates (asks confirmation)
innate update apply

# Show current version and service status
innate update status

# Manage ROS services
innate service start    # Start ROS services
innate service stop     # Stop ROS services
innate restart          # Restart ROS services
innate view             # Attach to tmux session

# List and trigger robot skills
innate skill list
innate skill run innate-os/wave

Commands

Update Commands

innate update check           # Check for updates (latest tagged release)
innate update check --dev     # Check for updates (latest commit on main)
innate update apply           # Apply latest release
innate update apply --dev     # Update to latest commit (git-based)
innate update status          # Show version info and service status

Service Commands

innate service start          # Start ROS services in tmux
innate service stop           # Stop ROS services
innate restart                # Restart ROS services
innate view                   # Attach to tmux session (Ctrl+b d to detach)

Skill Commands

innate skill list                                      # List available robot skills
innate skill type innate-os/wave                      # Print inputs and guidelines
innate skill type innate-os/wave --json               # Print the raw contract as JSON
innate skill run innate-os/wave                       # Trigger a skill by ID
innate skill run innate-os/arm_utils @command=torque_on
innate skill run local/my-skill @x=1 @name=alice      # Pass typed params

innate skill run calls the high-level /execute_skill action and defaults inputs to {}. Pass the skill ID exactly as published by the robot, such as innate-os/wave. Use innate skill type SKILL to inspect a readable input contract with the input type schema and guidelines advertised on /brain/available_skills before calling run. Skill parameters use @name=value; booleans and numbers are sent with those types, while other values are sent as strings. --inputs is only a completion marker for discovering the selected skill's params, not a JSON input flag. The zsh completion script suggests published skill IDs for innate skill type and innate skill run, then suggests the selected skill's @param= entries. For low-latency shell usage, the skills server mirrors the latest advertised contracts to /tmp/innate_skill_contracts.json (override with INNATE_SKILL_CACHE). innate skill type reads that cache before falling back to ROS; completion uses the cache directly so tab suggestions stay fast. innate skill run first tries the local /tmp/innate_skill_cli.sock bridge (override with INNATE_SKILL_SOCKET) hosted by skills_action_server, then falls back to direct ROS if the bridge is unavailable.

Daemon Mode (internal)

The update daemon runs via systemd and is not invoked directly by users:

innate-update daemon          # Called by innate-update.service

Running GitHub Actions with a Local Runner

The build workflows use runs-on: selfhosted and require a local GitHub Actions runner.

Setting Up a Self-Hosted Runner

  1. Go to your repository settings:

    https://github.com/YOUR_ORG/innate-os/settings/actions/runners

  2. Click "New self-hosted runner"

  3. Follow the setup instructions for your OS (Linux recommended):

    # Create a directory for the runner
mkdir actions-runner && cd actions-runner

# Download the runner (get latest URL from GitHub)
curl -o actions-runner-linux-x64-2.311.0.tar.gz -L \
  https://github.com/actions/runner/releases/download/v2.311.0/actions-runner-linux-x64-2.311.0.tar.gz

# Extract
tar xzf ./actions-runner-linux-x64-2.311.0.tar.gz

# Configure (get token from GitHub UI)
./config.sh --url https://github.com/YOUR_ORG/innate-os --token YOUR_TOKEN

# Install as service (optional, recommended)
sudo ./svc.sh install
sudo ./svc.sh start

  4. Verify runner is connected:

    • Go to Settings → Actions → Runners
    • Runner should show as "Idle" with green status

Requirements for the Runner Machine

The runner needs:

  • Docker with buildx support
  • Git
  • Sufficient disk space (builds can be 10GB+)
  • Network access to GitHub and Docker registries
# Install Docker
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER

# Verify Docker buildx
docker buildx version

Available Workflows

Workflow File Trigger Description
Build Release build-release.yml Push to main, tags, PRs, manual Builds ROS2 workspace, creates release archives
Test Pose Image test-pose-image.yml Changes to brain_client Runs Python tests

Manually Triggering a Workflow

  1. Go to Actions tab in your repository
  2. Select the workflow
  3. Click "Run workflow"
  4. Select branch and click "Run workflow"

Or via CLI:

gh workflow run build-release.yml --ref main

Viewing Workflow Logs

# List recent runs
gh run list

# View specific run
gh run view <run-id>

# Watch live
gh run watch

Configuration

Environment Variables

Variable Default Description
INNATE_OS_DIR ~/innate-os Installation directory
INNATE_STATE_DIR /var/lib/innate-update State/cache directory
INNATE_UPDATE_BRANCH main Git branch to track
INNATE_UPDATE_INTERVAL 3600 Daemon check interval (seconds)

Update Cache

/var/lib/innate-update/update-cache

Update Process

Release Updates (Default)

innate update apply
       |
       v
1. Git fetch with tags
       |
       v
2. Find latest tag
       |
       v
3. Git checkout to tag
       |
       v
4. Run post_update.sh:
   - Install apt dependencies
   - Install pip dependencies
   - Update systemd services
   - Update udev rules
   - Restart services
       |
       v
5. Start ROS services

Development Updates (--dev)

innate update apply --dev
       |
       v
1. Git fetch origin
       |
       v
2. Stash local changes
       |
       v
3. Git checkout origin/main
       |
       v
4. Run post_update.sh
       |
       v
5. Start ROS services

Service Management

Systemd Services

# Update daemon (checks for updates periodically)
sudo systemctl status innate-update.service
sudo systemctl start innate-update.service
sudo systemctl enable innate-update.service

# Discovery server
sudo systemctl status discovery-server.service

# ROS app
sudo systemctl status ros-app.service

# BLE provisioner
sudo systemctl status ble-provisioner.service

Tmux Sessions

# List sessions
tmux ls

# Attach to ROS nodes
tmux attach -t ros_nodes

# Navigation in tmux
# Ctrl+b then arrow keys - switch panes
# Ctrl+b then d - detach

Troubleshooting

View Logs

# Update logs
tail -f ~/innate-os/logs/update.log

# Post-update logs
tail -f ~/innate-os/logs/post_update.log

# Systemd service logs
journalctl -u innate-update.service -f
journalctl -u ros-app.service -f

Common Issues

"Permission denied (publickey)"

# Check if deploy key is installed
ls -la ~/.ssh/innate_deploy_key

# Test GitHub connection
ssh -T git@github.com

"No tags found"

  • Ensure the release repository has tagged releases
  • Check git remote: git remote -v

Update fails at post_update.sh

# Run manually to see errors
sudo ~/innate-os/scripts/update/post_update.sh

Rollback

cd ~/innate-os
git log --oneline --tags        # Find version to rollback to
git checkout 0.1.97             # Checkout specific version
sudo ./scripts/update/post_update.sh  # Rebuild and restart

Shell Integration

Add update notifications to your shell prompt:

echo 'source ~/innate-os/scripts/ssh_welcome.zsh' >> ~/.zshrc

This shows a notification on login if updates are available, and drops interactive SSH logins into ~/innate-os. To opt out of the cd:

echo 'INNATE_SSH_CD=0' >> ~/.zshenv

For Developers

Release Workflow

When you push a tag to innate-os, GitHub Actions automatically pushes to innate-os-release:

# Create and push a new release
git tag 0.1.99
git push origin 0.1.99

The workflow (.github/workflows/release-to-deploy-repo.yml):

  1. Checks out the tagged commit
  2. Removes .github/workflows (deploy keys can't push workflows)
  3. Commits as "Release X.Y.Z"
  4. Pushes to innate-os-release with the tag

Repository Structure

Repository Purpose Access
innate-os Development repo Developers only
innate-os-release Customer-facing releases Deploy keys (read-only)