bag_recorder_frontend
6.7 KB•MD
README.md
6.7 KB • 212 lines • markdown
1# ROS2 Bag Recorder Frontend
2
3A modern web-based interface for recording ROS2 bag files. This tool provides an intuitive UI for managing ROS2 bag recordings, selecting topics, and downloading recorded data.
4
5> **Note**: This project was developed with the assistance of AI tools to accelerate development and implement best practices.
6
7## Features
8
9- **Real-time Topic Discovery**: Automatically discovers and displays available ROS2 topics
10- **Status Polling**: Automatic status updates via HTTP polling (WebSocket support prepared but currently disabled)
11- **Topic Selection**: Multi-select interface for choosing which topics to record
12- **Recording Management**:
13 - Start/stop recordings with custom names and configurations
14 - View all recorded bag files with size and path information
15 - Download individual recordings or batch download multiple files
16 - Delete recordings with confirmation
17- **Batch Operations**: Select multiple recordings for bulk download or deletion
18- **Connection Status**: Visual indicators for backend connectivity
19- **Responsive Design**: Clean, modern UI built with Tailwind CSS
20
21## Prerequisites
22
23- Node.js 18+ (managed via NVM recommended)
24- A running ROS2 Bag Recorder backend service (default: `http://localhost:8080`)
25- ROS2 environment with active topics (for recording functionality)
26
27## Installation
28
29```bash
30# Install dependencies
31source ~/.nvm/nvm.sh && npm install
32
33# Start development server
34source ~/.nvm/nvm.sh && npm run dev
35```
36
37The application will be available at `http://localhost:3000`
38
39## Development
40
41### Available Scripts
42
43```bash
44# Development server with hot reload
45npm run dev
46
47# Type checking
48npm run type-check
49
50# Linting
51npm run lint
52
53# Production build
54npm run build
55
56# Preview production build
57npm run preview
58```
59
60### Project Structure
61
62```
63src/
64âââ api/
65â âââ client.ts # API client for backend communication
66â âââ types.ts # TypeScript type definitions
67âââ components/
68â âââ BatchActions.tsx # Bulk operations UI
69â âââ RecordingControls.tsx # Start/stop recording controls
70â âââ StatusDisplay.tsx # Connection and recording status
71â âââ TopicSelector.tsx # Multi-select topic interface
72âââ hooks/
73â âââ useRecording.ts # Recording state management (HTTP polling)
74â âââ useWebSocket.ts # WebSocket connection logic (prepared, not active)
75âââ App.tsx # Main application component
76âââ main.tsx # Application entry point
77```
78
79## Backend Integration
80
81The frontend connects to a backend service that handles actual ROS2 bag recording operations.
82
83### API Endpoints
84
85- `GET /api/topics` - Retrieve available ROS2 topics
86- `GET /api/status` - Get current recording status
87- `POST /api/start` - Start a new recording
88- `POST /api/stop` - Stop current recording
89- `GET /api/recordings` - List all recorded bag files
90- `GET /api/download/:filename` - Download a specific recording
91- `POST /api/batch/download` - Batch download multiple recordings (returns ZIP)
92- `DELETE /api/recordings/:filename` - Delete a recording
93- `POST /api/batch/delete` - Batch delete multiple recordings
94
95### WebSocket (Currently Disabled)
96
97- `WS /ws` - Real-time status updates *(prepared but not currently used)*
98
99**Note**: The frontend currently uses HTTP polling (every 3 seconds) for status updates. WebSocket support is implemented in the code but disabled, as the backend may not yet support it. To enable WebSocket, uncomment the WebSocket code in `src/hooks/useRecording.ts` (lines 61-118).
100
101The frontend expects the backend at `http://localhost:8080` by default. This can be configured in `vite.config.ts` under the proxy settings.
102
103## Docker Deployment
104
105A Dockerfile is provided for containerized deployment:
106
107```bash
108# Build the image
109docker build -t bag-recorder-frontend .
110
111# Run the container
112docker run -p 80:80 bag-recorder-frontend
113```
114
115The Docker setup includes:
116- Multi-stage build for optimized image size
117- Nginx server for production serving (HTTP only, no SSL)
118- Proxy configuration for backend API and WebSocket endpoint (via nginx.conf)
119- SPA routing support
120- Health check endpoint
121
122**Note**: WebSocket proxy is configured but the frontend currently uses HTTP polling.
123
124## Configuration
125
126### Backend URL
127
128Edit `vite.config.ts` to change the backend server location:
129
130```typescript
131server: {
132 proxy: {
133 '/api': {
134 target: 'http://localhost:8080', // Change this
135 changeOrigin: true,
136 secure: false
137 },
138 '/ws': {
139 target: 'ws://localhost:8080', // Change this
140 ws: true,
141 changeOrigin: true
142 }
143 }
144}
145```
146
147### Port Configuration
148
149Change the development server port in `vite.config.ts`:
150
151```typescript
152server: {
153 port: 3000, // Change this
154 host: true
155}
156```
157
158## Technology Stack
159
160- **React 18** - UI framework
161- **TypeScript** - Type safety and developer experience
162- **Vite** - Fast build tool and dev server
163- **Tailwind CSS** - Utility-first CSS framework
164- **Lucide React** - Icon library
165- **clsx** - Utility for constructing className strings
166
167## Development Notes
168
169This is a development tool designed for robotics engineers working with ROS2. It prioritizes functionality and ease of use over complex deployment scenarios. The application is intended to run locally alongside ROS2 development environments.
170
171### Design Decisions
172
173- **No authentication**: Designed for local development use
174- **Simple deployment**: Single container, minimal configuration
175- **Direct API calls**: No complex state management library needed
176- **Batch operations**: Essential for managing multiple test recordings
177- **Polling-based updates**: HTTP polling (3s interval) keeps UI synchronized with recording state
178- **WebSocket ready**: Code includes WebSocket implementation for when backend supports it
179
180## Troubleshooting
181
182### Cannot connect to backend
183
184- Ensure the backend service is running on `http://localhost:8080`
185- Check that CORS is properly configured on the backend
186- Verify the proxy settings in `vite.config.ts`
187
188### No topics appearing
189
190- Confirm ROS2 nodes are running and publishing topics
191- Verify the backend can access the ROS2 environment
192- Check the backend logs for ROS2 discovery errors
193
194### Status not updating
195
196- The frontend polls status every 3 seconds via HTTP
197- Ensure the backend `/api/status` endpoint is working
198- Check browser console for API errors
199- **Note**: WebSocket support is prepared but currently disabled in the code
200
201## Contributing
202
203This is a development tool for personal/team use. Contributions are welcome for bug fixes and feature enhancements that maintain the project's focus on simplicity and usability.
204
205## License
206
207MIT
208
209## Acknowledgments
210
211This project was developed with AI assistance to implement modern web development best practices and accelerate the development process.
212