Altair GUI

• Altair GUI
  • Overview
  • Why This Project Exists
    • The Problem
    • The Solution
    • Who Benefits
  • Features
    • Core Capabilities
    • Technical Highlights
  • Installation
    • Prerequisites
    • Using Nix (Recommended)
    • Manual Setup
  • Usage
    • Basic Workflow
    • Running Tests
    • Building for Production
    • Preview Production Build
  • Configuration
    • ROS2 Connection
    • Supported Message Types
    • Theming
  • Development
    • Project Structure
    • Code Style
    • Adding New Features
  • Contributing
    • Development Roadmap
      • ✅ Completed
      • 🚧 In Progress
      • 📋 Planned Features
  • License
  • Acknowledgments

⚠️ Project Status: Active Development

Altair GUI is currently under active development. Core features like telemetry indicators, entity browsing, and ROS2 connectivity are functional, but some features are incomplete or experimental. Expect breaking changes as the project evolves. Contributions and feedback are welcome!

A modern, reactive web-based graphical user interface for ROS2 (Robot Operating System 2) built with SolidJS and TypeScript. Altair provides real-time visualization and control of robotic systems through an intuitive, responsive interface.

Overview

Altair GUI is a browser-based control panel that connects to ROS2 systems via WebSocket (rosbridge), offering a comprehensive view of your robot's state and enabling interactive control. Built with modern web technologies, it delivers a fast, reactive experience for monitoring telemetry, inspecting topics and services, and sending commands to robotic platforms.

The interface features live indicators for battery status, GPS position, compass heading, altitude, and safety systems, alongside dynamic entity browsers for nodes, topics, services, and actions. A sophisticated configuration panel allows users to compose and send messages, adjust parameters, and invoke service requests—all through a clean, theme-aware UI.

Why This Project Exists

The Problem

Working with ROS2 typically requires juggling multiple terminal windows, command-line tools, and various monitoring utilities. While powerful, this workflow can be:

• Fragmented: Information is scattered across different terminals and tools
• Difficult to Monitor: Real-time telemetry requires separate visualization tools
• Not User-Friendly: Non-technical operators struggle with command-line interfaces
• Hard to Integrate: Setting up monitoring dashboards often requires custom development

The Solution

Altair GUI addresses these challenges by providing:

• Unified Interface: All ROS2 entities (nodes, topics, services, actions) in one place
• Real-Time Visualization: Live indicators for critical telemetry (battery, GPS, orientation)
• Interactive Controls: Point-and-click interaction with topics and services
• Accessibility: Browser-based access from any device on the network
• Modern UX: Clean, responsive design with light/dark theme support

Who Benefits

• Robotics Developers: Quickly inspect and debug ROS2 systems during development
• UAV/Drone Operators: Monitor vehicle status and control modes in real-time
• Research Teams: Provide non-technical team members with accessible robot interfaces
• Field Engineers: Access robot diagnostics from tablets or laptops without CLI tools
• Educators: Teach ROS2 concepts with visual, interactive demonstrations

The project is particularly well-suited for PX4 autopilot systems and MAVROS-enabled vehicles, with built-in support for common UAV telemetry messages.

Features

Core Capabilities

• Real-Time ROS2 Connection: WebSocket-based communication via rosbridge-server
• Entity Discovery: Automatic detection and listing of nodes, topics, services, and actions
• Live Telemetry Indicators:
  • Battery voltage and percentage with visual charge indicators
  • GPS fix type and satellite count
  • Compass heading with directional visualization
  • Altitude (relative and absolute)
  • Safety switch status
• Interactive Configuration Panel:
  • Message composition and publishing to topics
  • Service request builder with type introspection
  • Dynamic form generation from ROS message definitions
• Theme Support: Catppuccin Latte (light) and Mocha (dark) themes
• Type-Safe Development: Full TypeScript support with strict type checking

Technical Highlights

• SolidJS Reactivity: Fine-grained reactive updates for optimal performance
• Modular Architecture: Context-based state management with custom hooks
• Message Type Parsing: Automatic field generation from ROS typedef specifications
• Comprehensive Testing: Vitest test suite with SolidJS Testing Library
• Modern Build System: Vite-powered development and production builds

Installation

Prerequisites

• Node.js 18+ or Bun runtime
• ROS2 Humble (or compatible distribution)
• rosbridge-server package
• Optional: Nix package manager (for reproducible development environment)

Using Nix (Recommended)

The project includes a Nix flake that sets up ROS2 Humble, rosbridge-server, and all dependencies:

# Enter the development shell (installs ROS2 + rosbridge + Node.js)
nix develop

# Dependencies are auto-installed via the shell hook
# Start the development server
bun run dev

Manual Setup

1. Install Dependencies:

   npm install
   # or
   pnpm install
   # or
   yarn install
   # or
   bun install

2. Start rosbridge-server:

   Ensure your ROS2 environment is sourced, then:

   ros2 launch rosbridge_server rosbridge_websocket_launch.xml

   By default, rosbridge runs on ws://localhost:9090.

3. Configure Connection (if needed):

   Edit src/contexts/ros/provider.tsx to change the WebSocket URL:

   ros.connect("ws://your-robot-ip:9090");

4. Start Development Server:

   bun run dev

   Open http://localhost:3000 in your browser.

Usage

Basic Workflow

1. Connect to ROS2: Launch rosbridge-server on your robot or development machine
2. Open Altair: Navigate to http://localhost:3000 (or the server's IP if running remotely)
3. Monitor Telemetry: View real-time indicators in the top navigation bar
4. Explore Entities: Browse nodes, topics, services, and actions in the left sidebar
5. Interact with Topics: Click a topic to view its message structure and send data
6. Call Services: Select a service to compose and send requests

Running Tests

# Run all tests
bun run test

# Run tests in watch mode
bun run watch

# Run specific test file
vitest tests/components/button/dark-light.spec.tsx

Building for Production

bun run build

The optimized bundle will be output to the dist/ folder, ready for deployment to any static hosting service.

Preview Production Build

bun run serve

Configuration

ROS2 Connection

The WebSocket URL is configured in src/contexts/ros/provider.tsx. Modify the connection string to point to your rosbridge instance:

ros.connect("ws://192.168.1.100:9090");

Supported Message Types

Altair includes TypeScript interfaces for:

• MAVROS: mavros_msgs/State, sensor_msgs/BatteryState
• PX4 Messages: Battery status, GPS, vehicle position, vehicle status
• ROS API: Type introspection services (rosapi/topics, rosapi/services, etc.)
• Standard Messages: std_msgs/Header and common types

Additional message types can be added by creating interfaces in src/interfaces/.

Theming

Toggle between light and dark themes using the theme switcher button (if implemented). Themes use the Catppuccin color palette:

• Latte: Light theme with soft pastels
• Mocha: Dark theme with rich, muted tones

CSS variables are defined in src/styles/catppuccin-latte.css and catppuccin-mocha.css.

Development

Project Structure

src/
├── components/       # Reusable UI components
│   ├── buttons/      # Button components (theme toggle, etc.)
│   ├── configs/      # Configuration panel components
│   ├── elements/     # Base elements (Header, IconButton, Indicator)
│   ├── entities/     # Entity browsers (Nodes, Topics, Services, Actions)
│   └── indicators/   # Telemetry displays (Battery, GPS, Compass, etc.)
├── contexts/         # React-style context providers
│   ├── config/       # Configuration panel state
│   ├── entity/       # Entity list state
│   ├── form/         # Form field management
│   └── ros/          # ROS connection and state
├── hooks/            # Custom SolidJS hooks
├── interfaces/       # TypeScript message type definitions
├── layouts/          # Page layout components
├── pages/            # Top-level page components
├── styles/           # Global styles and themes
└── utils/            # Utility functions

Code Style

• Framework: SolidJS with TypeScript
• Styling: TailwindCSS with custom theme variables
• State Management: SolidJS signals, stores, and context
• Testing: Vitest + SolidJS Testing Library
• Build Tool: Vite

Refer to AGENTS.md for detailed coding guidelines.

Adding New Features

1. Create Components: Add components in the appropriate src/components/ subdirectory
2. Define Types: Add message interfaces in src/interfaces/ matching ROS message structure
3. Use Hooks: Leverage existing hooks (useRos, useListener, useTopic, etc.)
4. Write Tests: Add test files in tests/ mirroring the src/ structure
5. Follow Conventions: Match existing patterns for imports, naming, and styling

Contributing

Contributions are welcome! To contribute:

1. Fork the Repository: Create your own fork on GitHub
2. Create a Branch: Use a descriptive branch name (feature/add-param-editor, fix/gps-indicator)
3. Follow Code Style: Adhere to the guidelines in AGENTS.md
4. Write Tests: Add or update tests for your changes
5. Test Locally: Run bun run test and bun run build before submitting
6. Submit a Pull Request: Describe your changes and their motivation

Development Roadmap

Altair is actively evolving. Current priorities and planned features include:

✅ Completed

• ROS2 base connection setup
• Real-time telemetry indicators (Battery, GPS, Compass, Altitude, Safety Switch)
• Entity browsers (Nodes, Topics, Services, Actions)
• Message type introspection and dynamic form generation
• Basic configuration panel for messages and requests

🚧 In Progress

• Message composition and publishing interface
• Service request builder with full type support
• Parameter editing functionality

📋 Planned Features

• Navigation Section:
  • Vehicle context switching for multi-robot systems
  • Flight mode selector and arming controls
• Right Sidebar Extensions:
  • Template system for common message/service patterns
  • Advanced parameter editor
• Footer Enhancements:
  • Real-time clock display
  • Flash message notifications
  • Backend log collection viewer
  • Integrated console
  • Web-based shell access
• UI/UX Improvements:
  • Responsive design for mobile and tablet devices
  • Color scheme refinements
  • Integration with Ark.UI and crow.UI component libraries
• Additional Features:
  • Launch file management
  • Package browser
  • Connection status indicator and reconnection handling

License

This project is licensed under the MIT License. See the LICENSE file for details.

You are free to use, modify, and distribute this software for any purpose, commercial or non-commercial, as long as the original copyright notice is retained.

Acknowledgments

Altair GUI is developed and maintained by:

• VKWHM (@VKWHM) - Original author and primary developer

Special thanks to the open-source community and the following projects that make Altair possible:

• SolidJS: The reactive JavaScript library powering the UI
• ROS2: Robot Operating System 2 and the robotics ecosystem
• rosbridge-suite: WebSocket bridge for ROS
• PX4 Autopilot: Open-source flight control software
• Catppuccin: The soothing pastel theme palette
• Vite: Next-generation frontend build tool
• TailwindCSS: Utility-first CSS framework

---

Built with ❤️ for the robotics community