mirror of
https://gitlab.com/wirelos/sprocket-ui.git
synced 2025-12-14 05:56:50 +01:00
docs: add comprehensive README with UI framework documentation
This commit is contained in:
220
README.md
Normal file
220
README.md
Normal file
@@ -0,0 +1,220 @@
|
||||
# Sprocket UI Framework
|
||||
|
||||
A modern web-based user interface framework for Sprocket devices, providing real-time control, visualization, and management capabilities through a responsive web interface.
|
||||
|
||||
## Overview
|
||||
|
||||
The Sprocket UI Framework is a comprehensive web application that enables users to interact with Sprocket devices through an intuitive browser-based interface. It features real-time communication, component-based architecture, and modern web technologies.
|
||||
|
||||
## Features
|
||||
|
||||
- **Real-Time Communication**: WebSocket-based live updates and control
|
||||
- **Component-Based Architecture**: Modular, reusable UI components
|
||||
- **Responsive Design**: Works on desktop and mobile devices
|
||||
- **Live Data Binding**: Real-time synchronization with device state
|
||||
- **Plugin Integration**: Support for various Sprocket plugins
|
||||
- **Modern Web Stack**: Built with ES6+, Webpack, and Less
|
||||
|
||||
## Architecture
|
||||
|
||||
### Core Components
|
||||
- **App**: Main application controller
|
||||
- **Mediator**: Event-driven communication system
|
||||
- **Component System**: Modular UI component framework
|
||||
- **Data Store**: State management and persistence
|
||||
- **WebSocket Client**: Real-time device communication
|
||||
|
||||
### UI Components
|
||||
- **Form Controls**: Input fields, sliders, switches, and selectors
|
||||
- **Color Picker**: Advanced color selection with gradients
|
||||
- **Chat Interface**: Real-time messaging and logging
|
||||
- **Parameter Controls**: Dynamic parameter adjustment
|
||||
- **Preset Management**: Save and load device configurations
|
||||
|
||||
## Technology Stack
|
||||
|
||||
### Frontend
|
||||
- **JavaScript**: ES6+ with Babel transpilation
|
||||
- **CSS**: Less preprocessor for styling
|
||||
- **Build Tools**: Webpack for bundling and optimization
|
||||
- **Dependencies**: jQuery, Mustache, WebSocket
|
||||
|
||||
### Development
|
||||
- **Build System**: Webpack with hot reloading
|
||||
- **CSS Processing**: Less compilation
|
||||
- **Development Server**: Live-server with auto-reload
|
||||
- **Docker Support**: Containerized development and deployment
|
||||
|
||||
## Getting Started
|
||||
|
||||
### Prerequisites
|
||||
- Node.js (v12 or higher)
|
||||
- Yarn package manager
|
||||
- Modern web browser
|
||||
|
||||
### Installation
|
||||
|
||||
```bash
|
||||
# Install dependencies
|
||||
yarn install
|
||||
|
||||
# Setup development environment
|
||||
yarn setup
|
||||
|
||||
# Start development server
|
||||
yarn dev
|
||||
```
|
||||
|
||||
### Build Commands
|
||||
|
||||
```bash
|
||||
# Build frontend assets
|
||||
yarn build:frontend
|
||||
|
||||
# Build specific components
|
||||
yarn build:js # JavaScript bundle
|
||||
yarn build:css # CSS compilation
|
||||
yarn build:html # HTML templates
|
||||
```
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### File Structure
|
||||
```
|
||||
src/
|
||||
├── app/ # Application logic
|
||||
│ ├── core/ # Core framework
|
||||
│ ├── components/ # UI components
|
||||
│ └── main.js # Entry point
|
||||
├── pages/ # HTML templates
|
||||
├── styles/ # Less stylesheets
|
||||
└── data/ # Generated assets
|
||||
```
|
||||
|
||||
### Component Development
|
||||
Components are modular and follow a consistent pattern:
|
||||
- **HTML Template**: Structure and markup
|
||||
- **JavaScript Logic**: Behavior and event handling
|
||||
- **CSS Styling**: Component-specific styles
|
||||
- **Data Binding**: Integration with data store
|
||||
|
||||
### Real-Time Features
|
||||
- **WebSocket Communication**: Live device updates
|
||||
- **Event System**: Component-to-component messaging
|
||||
- **State Synchronization**: Automatic UI updates
|
||||
- **Live Controls**: Real-time device control
|
||||
|
||||
## Configuration
|
||||
|
||||
### WebSocket Endpoint
|
||||
Configure the WebSocket connection endpoint:
|
||||
```javascript
|
||||
let endpoint = '/ws'; // Default WebSocket path
|
||||
```
|
||||
|
||||
### Component Registration
|
||||
Register components with the main application:
|
||||
```javascript
|
||||
let app = new App($('body'))
|
||||
.components(components)
|
||||
.websocket(wsConnection);
|
||||
```
|
||||
|
||||
## Deployment
|
||||
|
||||
### Docker
|
||||
```bash
|
||||
# Build container
|
||||
yarn docker:build
|
||||
|
||||
# Run locally
|
||||
yarn docker:run
|
||||
|
||||
# Release to registry
|
||||
yarn docker:release
|
||||
```
|
||||
|
||||
### Production Build
|
||||
```bash
|
||||
# Build optimized assets
|
||||
yarn build:frontend
|
||||
|
||||
# Deploy to web server
|
||||
# Copy data/ directory to web root
|
||||
```
|
||||
|
||||
## API Integration
|
||||
|
||||
### WebSocket Events
|
||||
- **Device Status**: Real-time device state updates
|
||||
- **Control Commands**: Send commands to devices
|
||||
- **Configuration**: Update device settings
|
||||
- **Monitoring**: Live sensor data and metrics
|
||||
|
||||
### REST Endpoints
|
||||
- **Device Control**: POST commands to devices
|
||||
- **Status Information**: GET device status
|
||||
- **Configuration**: GET/SET device settings
|
||||
- **System Management**: Restart, update, etc.
|
||||
|
||||
## Customization
|
||||
|
||||
### Themes
|
||||
- **Color Schemes**: Customizable color palettes
|
||||
- **Layout Options**: Flexible component arrangement
|
||||
- **Responsive Breakpoints**: Mobile-first design
|
||||
- **Component Styling**: Individual component customization
|
||||
|
||||
### Plugins
|
||||
- **Component Extensions**: Add new UI components
|
||||
- **Data Sources**: Integrate with external systems
|
||||
- **Communication Protocols**: Support for various protocols
|
||||
- **Storage Backends**: Different data persistence options
|
||||
|
||||
## Browser Support
|
||||
|
||||
- **Modern Browsers**: Chrome, Firefox, Safari, Edge
|
||||
- **Mobile Support**: iOS Safari, Chrome Mobile
|
||||
- **ES6 Features**: Arrow functions, classes, modules
|
||||
- **WebSocket**: Real-time communication support
|
||||
|
||||
## Performance
|
||||
|
||||
- **Code Splitting**: Lazy loading of components
|
||||
- **Asset Optimization**: Minified and compressed assets
|
||||
- **Caching**: Browser caching strategies
|
||||
- **Lazy Loading**: On-demand component loading
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
- **WebSocket Connection**: Check device connectivity
|
||||
- **Build Errors**: Verify Node.js and Yarn versions
|
||||
- **Component Loading**: Check component registration
|
||||
- **Styling Issues**: Verify Less compilation
|
||||
|
||||
### Debug Mode
|
||||
Enable debug output for troubleshooting:
|
||||
```javascript
|
||||
// Enable debug logging
|
||||
app.debug = true;
|
||||
```
|
||||
|
||||
## Contributing
|
||||
|
||||
1. Fork the repository
|
||||
2. Create feature branch
|
||||
3. Implement changes
|
||||
4. Add tests if applicable
|
||||
5. Submit pull request
|
||||
|
||||
## License
|
||||
|
||||
See LICENSE file for details.
|
||||
|
||||
## Support
|
||||
|
||||
- **Documentation**: Check the docs/ directory
|
||||
- **Issues**: Report bugs via GitHub issues
|
||||
- **Community**: Join the Sprocket community
|
||||
- **Examples**: See examples/ directory for usage patterns
|
||||
Reference in New Issue
Block a user