mirror of
https://gitlab.com/wirelos/sprocket-ui.git
synced 2025-12-14 22:02:24 +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