spore-ui/docs/FIRMWARE_REGISTRY_INTEGRATION.md

Firmware Registry Integration

This document describes the integration of the SPORE Registry into the SPORE UI, replacing the previous firmware upload functionality with a comprehensive CRUD interface for managing firmware in the registry.

Overview

The firmware view has been completely redesigned to provide:

• Registry Management: Full CRUD operations for firmware in the SPORE Registry
• Search & Filter: Search firmware by name, version, or labels
• Drawer Forms: Add/edit forms displayed in the existing drawer component
• Real-time Status: Registry connection status indicator
• Download Support: Direct download of firmware binaries

Architecture

Components

1. FirmwareComponent (FirmwareComponent.js)

   • Main component for the firmware registry interface
   • Handles CRUD operations and UI interactions
   • Manages registry connection status

2. FirmwareFormComponent (FirmwareFormComponent.js)

   • Form component for add/edit operations
   • Used within the drawer component
   • Handles metadata and file uploads

3. API Client Extensions (api-client.js)

   • New registry API methods added to existing ApiClient
   • Auto-detection of registry server URL
   • Support for multipart form data uploads

API Integration

The integration uses the SPORE Registry API endpoints:

• GET /health - Health check
• GET /firmware - List firmware with optional filtering
• POST /firmware - Upload firmware with metadata
• GET /firmware/{name}/{version} - Download firmware binary

Registry Server Configuration

The registry server is expected to run on:

• Localhost: http://localhost:8080
• Remote: http://{hostname}:8080

The UI automatically detects the appropriate URL based on the current hostname.

Features

Firmware Management

• Add Firmware: Upload new firmware with metadata and labels
• Edit Firmware: Modify existing firmware (requires new file upload)
• Download Firmware: Direct download of firmware binaries
• Delete Firmware: Remove firmware from registry (not yet implemented in API)

Search & Filtering

• Text Search: Search by firmware name, version, or label values
• Real-time Filtering: Results update as you type
• Label Display: Visual display of firmware labels with color coding

User Interface

• Card Layout: Clean card-based layout for firmware entries
• Action Buttons: Edit, download, and delete actions for each firmware
• Status Indicators: Registry connection status with visual feedback
• Loading States: Proper loading indicators during operations
• Error Handling: User-friendly error messages and notifications

Form Interface

• Drawer Integration: Forms open in the existing drawer component
• Metadata Fields: Name, version, and custom labels
• File Upload: Drag-and-drop or click-to-upload file selection
• Label Management: Add/remove key-value label pairs
• Validation: Client-side validation with helpful error messages

Usage

Adding Firmware

1. Click the "Add Firmware" button in the header
2. Fill in the firmware name and version
3. Select a firmware file (.bin or .hex)
4. Add optional labels (key-value pairs)
5. Click "Upload Firmware"

Editing Firmware

1. Click the edit button on any firmware card
2. Modify the metadata (name and version are read-only)
3. Upload a new firmware file
4. Update labels as needed
5. Click "Update Firmware"

Downloading Firmware

1. Click the download button on any firmware card
2. The firmware binary will be downloaded automatically

Searching Firmware

1. Use the search box to filter firmware
2. Search by name, version, or label values
3. Results update in real-time

Testing

A test suite is provided to verify the registry integration:

cd spore-ui/test
node registry-integration-test.js

The test suite verifies:

• Registry health check
• List firmware functionality
• Upload firmware functionality
• Download firmware functionality

Configuration

Registry Server

Ensure the SPORE Registry server is running on port 8080:

cd spore-registry
go run main.go

UI Configuration

The UI automatically detects the registry server URL. No additional configuration is required.

Error Handling

The integration includes comprehensive error handling:

• Connection Errors: Clear indication when registry is unavailable
• Upload Errors: Detailed error messages for upload failures
• Validation Errors: Client-side validation with helpful messages
• Network Errors: Graceful handling of network timeouts and failures

Future Enhancements

Planned improvements include:

• Delete Functionality: Complete delete operation when API supports it
• Bulk Operations: Select multiple firmware for bulk operations
• Version History: View and manage firmware version history
• Deployment Integration: Deploy firmware directly to nodes from registry
• Advanced Filtering: Filter by date, size, or other metadata

Migration Notes

The previous firmware upload functionality has been completely replaced. The new interface provides:

• Better organization with the registry
• Improved user experience with search and filtering
• Consistent UI patterns with the rest of the application
• Better error handling and user feedback

All existing firmware functionality is now handled through the registry interface.