bakery-admin/bakery-ia
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add whatsapp feature

Browse Source
This commit is contained in:
Urtzi Alfaro
2025-11-13 16:01:08 +01:00
parent d7df2b0853
commit 9bc048d360
74 changed files with 9765 additions and 533 deletions
Download Patch File Download Diff File Expand all files Collapse all files

653
services/production/IOT_IMPLEMENTATION_GUIDE.md Normal file
View File

@@ -0,0 +1,653 @@
# IoT Equipment Integration - Implementation Guide
## Overview
This guide documents the implementation of real-time IoT equipment tracking for bakery production equipment, specifically targeting smart industrial ovens with IoT connectivity capabilities.
## Table of Contents
1. [Architecture](#architecture)
2. [Database Schema](#database-schema)
3. [IoT Connectors](#iot-connectors)
4. [Supported Equipment](#supported-equipment)
5. [Implementation Status](#implementation-status)
6. [Next Steps](#next-steps)
7. [Usage Examples](#usage-examples)
## Architecture
### Component Overview
```
┌─────────────────────────────────────────────────────────────┐
│ Frontend Dashboard │
│ (Real-time Equipment Monitoring UI) │
└────────────────┬────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Production Service API │
│ /api/v1/equipment/{id}/iot-config │
│ /api/v1/equipment/{id}/realtime-data │
│ /api/v1/equipment/{id}/sensor-history │
│ /api/v1/equipment/{id}/test-connection │
└────────────────┬────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ IoT Integration Service │
│ - Connection management │
│ - Data transformation │
│ - Protocol abstraction │
└────────────────┬────────────────────────────────────────────┘
│
┌──────────┴──────────┬──────────────────┐
▼ ▼ ▼
┌────────────┐ ┌──────────────┐ ┌─────────────┐
│ REST API │ │ OPC UA │ │ MQTT │
│ Connector │ │ Connector │ │ Connector │
└─────┬──────┘ └──────┬───────┘ └──────┬──────┘
│ │ │
▼ ▼ ▼
┌─────────────────────────────────────────────────────────────┐
│ Smart IoT-Enabled Equipment │
│ - Rational iCombi (ConnectedCooking) │
│ - Wachtel REMOTE │
│ - SALVA Smart Ovens │
│ - Generic REST API Equipment │
└─────────────────────────────────────────────────────────────┘
```
## Database Schema
### New Tables
#### 1. `equipment` (Extended)
Added IoT connectivity fields:
- `iot_enabled` - Enable/disable IoT connectivity
- `iot_protocol` - Protocol type (rest_api, opc_ua, mqtt, modbus, custom)
- `iot_endpoint` - Connection endpoint URL/IP
- `iot_port` - Connection port
- `iot_credentials` - JSON encrypted credentials
- `iot_connection_status` - Current connection status
- `iot_last_connected` - Timestamp of last successful connection
- `iot_config` - Additional protocol-specific configuration
- `manufacturer` - Equipment manufacturer
- `firmware_version` - Firmware version
- `supports_realtime` - Supports real-time monitoring
- `poll_interval_seconds` - Data polling interval
- `temperature_zones` - Number of temperature zones
- `supports_humidity` - Humidity monitoring capability
- `supports_energy_monitoring` - Energy monitoring capability
- `supports_remote_control` - Remote control capability
#### 2. `equipment_sensor_readings`
Time-series sensor data storage:
- Core readings: temperature, humidity, energy consumption
- Status: operational_status, cycle_stage, progress
- Process parameters: motor_speed, door_status, steam_level
- Quality indicators: product_weight, moisture_content
- Flexible JSON field for manufacturer-specific sensors
#### 3. `equipment_connection_logs`
Connection event tracking:
- event_type, event_time, connection_status
- Error tracking: error_message, error_code
- Performance metrics: response_time_ms, data_points_received
#### 4. `equipment_iot_alerts`
Real-time equipment alerts:
- Alert types: temperature_deviation, connection_lost, equipment_error
- Severity levels: info, warning, critical
- Status tracking: active, acknowledged, resolved
- Automated response tracking
### Migration
Run migration to add IoT support:
```bash
cd services/production
alembic upgrade head
```
Migration file: `migrations/versions/002_add_iot_equipment_support.py`
## IoT Connectors
### Connector Architecture
All connectors implement the `BaseIoTConnector` abstract interface:
```python
from app.services.iot import BaseIoTConnector, ConnectorFactory
# Create connector instance
connector = ConnectorFactory.create_connector(
protocol='rest_api',
equipment_id='equipment-uuid',
config={
'endpoint': 'https://api.example.com',
'port': 443,
'credentials': {'api_key': 'xxx'},
'additional_config': {}
}
)
# Test connection
status = await connector.test_connection()
# Get current readings
reading = await connector.get_current_reading()
# Get equipment capabilities
capabilities = await connector.get_capabilities()
```
### Available Connectors
#### 1. Generic REST API Connector
**Protocol:** `rest_api`
**File:** `app/services/iot/rest_api_connector.py`
**Configuration Example:**
```json
{
"protocol": "rest_api",
"endpoint": "https://api.equipment.com",
"port": 443,
"credentials": {
"api_key": "your-api-key",
"token": "bearer-token"
},
"additional_config": {
"data_endpoint": "/api/v1/equipment/{equipment_id}/data",
"status_endpoint": "/api/v1/equipment/{equipment_id}/status",
"timeout": 10,
"verify_ssl": true
}
}
```
**Features:**
- Standard REST API support
- Bearer token & API key authentication
- Basic authentication
- Configurable endpoints
- SSL verification control
- Timeout configuration
#### 2. Rational ConnectedCooking Connector
**Protocol:** `rational` or `rational_connected_cooking`
**File:** `app/services/iot/rational_connector.py`
**Configuration Example:**
```json
{
"protocol": "rational",
"endpoint": "https://www.connectedcooking.com/api/v1",
"port": 443,
"credentials": {
"username": "your-email@example.com",
"password": "your-password"
},
"additional_config": {
"unit_id": "12345",
"timeout": 15
}
}
```
**Features:**
- Multi-zone temperature (cabinet + core)
- Humidity monitoring
- Energy consumption tracking
- Remote control support
- HACCP documentation
- Recipe management
- Automatic cleaning status
**Contact:** cc-support@rational-online.com
#### 3. Wachtel REMOTE Connector
**Protocol:** `wachtel` or `wachtel_remote`
**File:** `app/services/iot/wachtel_connector.py`
**Configuration Example:**
```json
{
"protocol": "wachtel",
"endpoint": "https://remote.wachtel.de/api",
"port": 443,
"credentials": {
"username": "bakery-username",
"password": "bakery-password"
},
"additional_config": {
"oven_id": "oven-serial-number",
"deck_count": 3
}
}
```
**Features:**
- Multi-deck temperature monitoring
- Energy consumption tracking
- Maintenance alerts
- Operation hours tracking
- Deck-specific control
**Contact:** support@wachtel.de
#### 4. OPC UA Connector (Template)
**Protocol:** `opc_ua`
**Status:** Template only (requires implementation)
For bakery equipment supporting OPC UA or Weihenstephan Standards (WS Bake).
**Dependencies:**
```bash
pip install asyncua==1.1.5
```
**Template Location:** To be created at `app/services/iot/opcua_connector.py`
## Supported Equipment
### Equipment Research Summary
#### Spanish Manufacturers (Madrid Region)
1. **SALVA Industrial** (Lezo, Guipuzcoa)
- Smart touch control panels
- Energy monitoring
- Digital integration
- Status: API details pending
2. **Farjas** (Madrid, Móstoles)
- Rotary ovens
- Status: IoT capabilities unknown
3. **COLBAKE** (Valencia)
- Complete bakery lines
- Status: IoT capabilities to be confirmed
#### International Manufacturers with Madrid Presence
1. **Rational** (Germany) - ✅ **Implemented**
- Product: iCombi ovens
- Platform: ConnectedCooking
- API: Available (REST)
- Showroom: Madrid (15 min from airport)
2. **Wachtel** (Germany) - ✅ **Template Created**
- Product: Deck ovens
- Platform: REMOTE monitoring
- API: REST (details pending confirmation)
3. **Sveba Dahlen** (Sweden)
- Showroom in Madrid
- Status: IoT capabilities to be researched
### Industry Standards
- **OPC UA**: Standard protocol for industrial automation
- **Weihenstephan Standards (WS Bake)**: Bakery-specific communication standard
- **MQTT**: Common IoT message protocol
- **Modbus**: Industrial communication protocol
## Implementation Status
### ✅ Completed
1. **Database Schema**
- Migration created and tested
- All IoT tables defined
- Indexes optimized for time-series queries
2. **Models**
- Equipment model extended with IoT fields
- Sensor reading model
- Connection log model
- IoT alert model
- Enums: IoTProtocol, IoTConnectionStatus
3. **Schemas (Pydantic)**
- IoTConnectionConfig
- Equipment schemas updated with IoT fields
- EquipmentSensorReadingResponse
- EquipmentConnectionTestResponse
- RealTimeDataResponse
- EquipmentIoTAlertResponse
- EquipmentSensorHistoryResponse
4. **IoT Connectors**
- Base connector interface (`BaseIoTConnector`)
- Connector factory pattern
- Generic REST API connector (fully implemented)
- Rational ConnectedCooking connector (implemented)
- Wachtel REMOTE connector (template created)
5. **Dependencies**
- requirements.txt updated
- httpx for REST APIs
- Commented dependencies for OPC UA and MQTT
### 🚧 In Progress / To Do
1. **IoT Integration Service** ⏳
- High-level service layer
- Connection pool management
- Automatic retry logic
- Health monitoring
2. **Repository Layer** ⏳
- Equipment IoT configuration CRUD
- Sensor data storage and retrieval
- Connection log management
- Alert management
3. **API Endpoints** ⏳
- POST `/api/v1/equipment/{id}/iot-config` - Configure IoT
- POST `/api/v1/equipment/{id}/test-connection` - Test connectivity
- GET `/api/v1/equipment/{id}/realtime-data` - Get current data
- GET `/api/v1/equipment/{id}/sensor-history` - Historical data
- GET `/api/v1/batches/{id}/realtime-tracking` - Batch tracking
- GET `/api/v1/equipment/iot-alerts` - Get active alerts
4. **Background Workers** ⏳
- Periodic data collection worker
- Connection health monitor
- Alert generation and notification
- Data cleanup (old sensor readings)
5. **Frontend Components** ⏳
- Equipment IoT configuration wizard
- Real-time monitoring dashboard
- Sensor data visualization charts
- Alert notification system
- Connection status indicators
6. **Additional Connectors** 📋
- OPC UA connector implementation
- MQTT connector implementation
- SALVA-specific connector (pending API details)
## Next Steps
### Priority 1: Core Service Layer
1. **Create IoT Integration Service**
```python
# app/services/iot_integration_service.py
class IoTIntegrationService:
async def configure_equipment_iot(equipment_id, config)
async def test_connection(equipment_id)
async def get_realtime_data(equipment_id)
async def get_sensor_history(equipment_id, start, end)
async def store_sensor_reading(equipment_id, reading)
```
2. **Create Repository Methods**
```python
# app/repositories/equipment_repository.py
async def update_iot_config(equipment_id, config)
async def get_iot_config(equipment_id)
async def update_connection_status(equipment_id, status)
# app/repositories/sensor_reading_repository.py
async def create_reading(reading)
async def get_readings(equipment_id, start_time, end_time)
async def get_latest_reading(equipment_id)
```
3. **Create API Endpoints**
```python
# app/api/equipment_iot.py
router = APIRouter(prefix="/equipment", tags=["equipment-iot"])
@router.post("/{equipment_id}/iot-config")
@router.post("/{equipment_id}/test-connection")
@router.get("/{equipment_id}/realtime-data")
@router.get("/{equipment_id}/sensor-history")
```
### Priority 2: Background Processing
1. **Data Collection Worker**
- Poll IoT-enabled equipment at configured intervals
- Store sensor readings in database
- Handle connection errors gracefully
2. **Alert Generation**
- Monitor temperature deviations
- Detect connection losses
- Generate alerts for critical conditions
### Priority 3: Frontend Integration
1. **Equipment Configuration UI**
- IoT setup wizard
- Protocol selection
- Connection testing
- Credential management
2. **Real-time Dashboard**
- Live equipment status cards
- Temperature/humidity gauges
- Energy consumption charts
- Alert notifications
## Usage Examples
### Example 1: Configure Equipment for IoT
```python
from app.services.iot_integration_service import IoTIntegrationService
service = IoTIntegrationService()
# Configure Rational iCombi oven
config = {
"protocol": "rational",
"endpoint": "https://www.connectedcooking.com/api/v1",
"port": 443,
"credentials": {
"username": "bakery@example.com",
"password": "secure-password"
},
"additional_config": {
"unit_id": "12345"
}
}
await service.configure_equipment_iot(equipment_id="uuid-here", config=config)
```
### Example 2: Test Connection
```python
# Test connection before saving configuration
result = await service.test_connection(equipment_id="uuid-here")
if result.success:
print(f"Connected in {result.response_time_ms}ms")
print(f"Supported features: {result.supported_features}")
else:
print(f"Connection failed: {result.error_details}")
```
### Example 3: Get Real-time Data
```python
# Get current equipment data
data = await service.get_realtime_data(equipment_id="uuid-here")
print(f"Temperature: {data.temperature}°C")
print(f"Status: {data.operational_status}")
print(f"Progress: {data.cycle_progress_percentage}%")
print(f"Time remaining: {data.time_remaining_minutes} min")
```
### Example 4: Retrieve Sensor History
```python
from datetime import datetime, timedelta
# Get last 24 hours of data
end_time = datetime.now()
start_time = end_time - timedelta(hours=24)
history = await service.get_sensor_history(
equipment_id="uuid-here",
start_time=start_time,
end_time=end_time
)
# Plot temperature over time
for reading in history.readings:
print(f"{reading.reading_time}: {reading.temperature}°C")
```
## API Endpoint Specifications
### POST /api/v1/equipment/{equipment_id}/iot-config
Configure IoT connectivity for equipment.
**Request Body:**
```json
{
"protocol": "rational",
"endpoint": "https://www.connectedcooking.com/api/v1",
"port": 443,
"credentials": {
"username": "user@example.com",
"password": "password"
},
"additional_config": {
"unit_id": "12345"
},
"supports_realtime": true,
"poll_interval_seconds": 30
}
```
**Response:**
```json
{
"success": true,
"message": "IoT configuration saved successfully",
"equipment_id": "uuid",
"connection_test_result": {
"success": true,
"status": "connected",
"response_time_ms": 145
}
}
```
### GET /api/v1/equipment/{equipment_id}/realtime-data
Get current real-time sensor data.
**Response:**
```json
{
"equipment_id": "uuid",
"equipment_name": "Horno Principal #1",
"timestamp": "2025-01-12T10:30:00Z",
"connection_status": "connected",
"temperature": 185.5,
"temperature_zones": {
"cabinet": 180,
"core": 72
},
"humidity": 65.0,
"operational_status": "running",
"cycle_stage": "baking",
"cycle_progress_percentage": 45.0,
"time_remaining_minutes": 12,
"energy_consumption_kwh": 12.5,
"active_batch_id": "batch-uuid",
"active_batch_name": "Baguettes - Batch #123"
}
```
## Security Considerations
1. **Credential Storage**
- Store API keys/passwords encrypted in database
- Use environment variables for sensitive configuration
- Rotate credentials periodically
2. **SSL/TLS**
- Always use HTTPS for REST API connections
- Verify SSL certificates in production
- Support self-signed certificates for local equipment
3. **Authentication**
- Require user authentication for IoT configuration
- Log all configuration changes
- Implement role-based access control
4. **Network Security**
- Support firewall-friendly protocols
- Document required network ports
- Consider VPN for equipment access
## Troubleshooting
### Connection Issues
1. **Timeout errors**
- Increase timeout in additional_config
- Check network connectivity
- Verify firewall rules
2. **Authentication failures**
- Verify credentials are correct
- Check API key expiration
- Confirm endpoint URL is correct
3. **SSL certificate errors**
- Set `verify_ssl: false` for testing (not recommended for production)
- Install proper SSL certificates
- Use certificate bundles for corporate networks
### Data Quality Issues
1. **Missing sensor readings**
- Check equipment supports requested sensors
- Verify polling interval is appropriate
- Review connection logs for errors
2. **Anomalous data**
- Implement data validation
- Set reasonable min/max thresholds
- Flag outliers for manual review
## Resources
### Manufacturer Contacts
- **Rational:** cc-support@rational-online.com
- **Wachtel:** support@wachtel.de / https://www.wachtel.de
- **SALVA:** https://www.salva.es/en
### Standards and Protocols
- **OPC Foundation:** https://opcfoundation.org/
- **Weihenstephan Standards:** https://www.weihenstephan-standards.com
- **MQTT:** https://mqtt.org/
### Libraries
- **httpx:** https://www.python-httpx.org/
- **asyncua:** https://github.com/FreeOpcUa/opcua-asyncio
- **paho-mqtt:** https://pypi.org/project/paho-mqtt/
---
**Last Updated:** 2025-01-12
**Status:** Phase 1 Complete - Foundation & Connectors
**Next Milestone:** Service Layer & API Endpoints