# Central system transferts

In RustiQIot, the device has a unique service communicating to a dedicated central system. 

For scaling and simplicity reasons (and handling a lots of devices, and maintaining multiple version of datastructures), the default implementation use an S3 file system. 

Well known from cloud application S3, is largely scalable and permit to not have the need to have instant responses (usefull for intermittent communication, or "rush" during phases from the device).

The central system is used as a file server (for configuration transmission, updates, but also communicating with the device).

Using a File based system, permit also to de-couple API changes during time, This is, then much easy to manage the versions diversity faced in some long terms support for devices.

## Using a "store configuration" for remote access

The transfer service uses a flexible "store" abstraction to manage different storage locations. This design allows configuration-based location management, multiple storage backends, and context-specific storage for different purposes.

### Store Configuration

Stores are configured using JSON serialized configuration. The service supports two main storage backends:

1. **Filesystem Store**
   - Local file/folder storage
   - Used for testing and validation
   - Simple configuration with local paths

2. **AWS S3 Store**
   - Cloud storage implementation
   - Production-ready configuration
   - Supports multiple buckets and regions
   - Requires AWS credentials and bucket configuration

### Store Configuration Example

```json
{
    "store_name": "config",
    "bucket_name": "etabelone-dev-etabelonedevbootstrape71b79bd-kfzemjujlgbe",
    "region": "eu-west-1",
    "prefix": ""
}
```

### Typical Store Types and Their Purposes

The RustiQ IoT system uses several predefined store types, each serving a specific purpose in the device lifecycle and operation:

#### 1. **Config Store** - Configuration Management
- **Purpose**: Stores device configuration files, enrollment data, and system settings
- **Usage**: Device initialization, configuration updates, enrollment verification
- **Example Configuration**:
  ```json
  {
      "store_name": "config",
      "bucket_name": "etablone-test",
      "region": "eu-west-1",
      "prefix": "enrollment"
  }
  ```

#### 2. **Apps Store** - Application Distribution
- **Purpose**: Stores application binaries, updates, and deployment packages
- **Usage**: Application deployment, version updates, new module installation
- **Example Configuration**:
  ```json
  {
      "store_name": "apps",
      "bucket_name": "etablone-test",
      "region": "eu-west-1",
      "prefix": "apps"
  }
  ```

#### 3. **Incoming Store** - Command Reception
- **Purpose**: Receives commands and instructions from the central system
- **Usage**: Administrative commands, scheduled tasks, remote control operations
- **Example Configuration**:
  ```json
  {
      "store_name": "incoming",
      "bucket_name": "etablone-test",
      "region": "eu-west-1",
      "prefix": "simulator_test/incoming"
  }
  ```

#### 4. **Contents Store** - Content Distribution
- **Purpose**: Stores media files, documents, and content for device display/processing
- **Usage**: Image updates, document distribution, media content delivery
- **Example Configuration**:
  ```json
  {
      "store_name": "contents",
      "bucket_name": "etablone-test",
      "region": "eu-west-1",
      "prefix": "simulator_test/contents"
  }
  ```

#### 5. **Status Store** - Device Reporting
- **Purpose**: Receives device status reports, monitoring data, and command results
- **Usage**: Device health monitoring, command execution feedback, diagnostic data
- **Example Configuration**:
  ```json
  {
      "store_name": "status",
      "bucket_name": "etablone-test",
      "region": "eu-west-1",
      "prefix": "simulator_test/status"
  }
  ```

### Complete Store Configuration Example

A typical production configuration includes all store types:





```json
[
    {
        "store_name": "config",
        "bucket_name": "etablone-test",
        "region": "eu-west-1",
        "prefix": "enrollment"
    },
    {
        "store_name": "apps",
        "bucket_name": "etablone-test",
        "region": "eu-west-1",
        "prefix": "apps"
    },
    {
        "store_name": "incoming",
        "bucket_name": "etablone-test",
        "region": "eu-west-1",
        "prefix": "simulator_test/incoming"
    },
    {
        "store_name": "contents",
        "bucket_name": "etablone-test",
        "region": "eu-west-1",
        "prefix": "simulator_test/contents"
    },
    {
        "store_name": "status",
        "bucket_name": "etablone-test",
        "region": "eu-west-1",
        "prefix": "simulator_test/status"
    }
]
```

### Store Naming Conventions

- **store_name**: Identifies the store type and purpose
- **bucket_name**: S3 bucket containing all stores for a project/environment
- **region**: AWS region for the S3 bucket
- **prefix**: Organizational path within the bucket (e.g., `simulator_test/` for test environments)

### Store Architecture Overview

The following diagram illustrates how the different store types work together in the RustiQ IoT system:


```{mermaid}

   graph TB
       subgraph "Central System (AWS S3)"
           subgraph "etablone-test Bucket"
               subgraph "enrollment Prefix"
                   A[Config Store<br/>Device Configs<br/>Enrollment Data]
               end
               subgraph "apps Prefix"
                   B[Apps Store<br/>Application Binaries<br/>Updates & Packages]
               end
               subgraph "simulator_test/incoming Prefix"
                   C[Incoming Store<br/>Commands & Instructions<br/>Remote Control]
               end
               subgraph "simulator_test/contents Prefix"
                   D[Contents Store<br/>Media Files<br/>Documents & Images]
               end
               subgraph "simulator_test/status Prefix"
                   E[Status Store<br/>Device Reports<br/>Monitoring Data]
               end
           end
       end
       
       subgraph "IoT Device"
           F[Transfer Service]
           G[Device Applications]
           H[Device Services]
       end
       
       %% Data Flow
       A -->|Download Configs| F
       B -->|Download Apps| F
       C -->|Download Commands| F
       F -->|Upload Status| E
       F -->|Upload Logs| E
       F -->|Upload Results| E
       
       %% Internal Device Flow
       F -->|Process Commands| G
       F -->|Install Apps| G
       F -->|Apply Configs| H
       F -->|Display Content| H
       
       %% Content Flow
       D -->|Download Media| F
       F -->|Process Content| H
       
       %% Styling
       classDef storeClass fill:#e3f2fd,stroke:#1976d2,stroke-width:2px
       classDef deviceClass fill:#e8f5e8,stroke:#388e3c,stroke-width:2px
       classDef serviceClass fill:#fff3e0,stroke:#f57c00,stroke-width:2px
       
       class A,B,C,D,E storeClass
       class F,G,H deviceClass
       class F serviceClass

```




### Environment Variables for Store Configuration

| Environment Variable | Description | Example |
|---------------------|-------------|---------|
| AWS_ACCESS_KEY_ID | AWS Access key for authentication | xxxxxxxxxxx |
| AWS_SECRET_ACCESS_KEY | AWS Secret key for authentication | xxxxxxxxxxxxx |
| S3_STORE_CUSTOM_HOSTANDPORT_ENDPOINT | Custom S3-compatible endpoint host and port | localhost:9000 |
| S3_STORE_CUSTOM_HTTP_SCHEME | Protocol scheme for custom S3 store | http or https |
| STORE_CONFIGURATION | JSON serialized store configuration | See store configuration example above |

## Communication patterns

### Sending Events (Uploading files to the server)

The transfer service provides a unified interface for uploading device information, logs, and monitoring data to the central system. This includes:

- Device status reports
- Application logs and diagnostics
- Monitoring data and metrics
- Configuration updates and acknowledgments

### Getting Commands (Downloading and processing commands)

The central system communicates with devices by placing command files in designated locations. Devices download these files, process the commands, and upload results.

#### Command File Structure

Commands are formatted as JSON arrays containing command objects:

```json
[
    {
        "command": "get_app_status()"
    },
    {
        "command": "stop_app('mock_powermanagement-1.0')"
    },
    {
        "command": "get_next_execution_time_for_all_jobs()"
    },
    {
        "command": "call_service('scheduler', 'update_or_create_job', 'display', 'display_image', \"call_service('display_image', 'IMAGE_PATH')\",'',True)"
    }
]
```

#### Command Processing Flow

1. **Download Phase**: Device downloads command file from `incoming/{service-name}/commands.json`
2. **Execution Phase**: Commands are executed sequentially by the appropriate service
3. **Result Collection**: Results are collected and formatted
4. **Upload Phase**: Results are uploaded to `./status/{service-name}/last_monitoring_status.json`

#### Result Format

The service uploads results in the following format:

```json
{
   "general_status": "ok",
   "general_error": "",
   "commands": [
      {
         "command": "get_app_status()",
         "result": "{\"monitoring-1.0\":{\"application_id\":\"monitoring-1.0\",\"status\":null,\"restarted_count\":0}}",
         "status": "ok"
      }
   ]
}
```

### HTTP Communication Standardization

The transfer service also provides standardized HTTP communication for other modules:

```python
call_service('transfer', 'http_request', 'https://www.google.fr', 'GET', {}, "")
```

This returns structured responses with headers, HTTP status codes, and response bodies:

```json
{
  "headers": ["date: Sun, 23 Feb 2025 15:57:58 GMT", "content-type: text/html; charset=ISO-8859-1"],
  "httpcode": 200,
  "response_body": "<!doctype html>..."
}
```

## Transaction handling

### File-based Transaction Model

In the synchronization process, downloads are completed and presented to the file system before processing. This ensures:

- **Atomic Operations**: Files are either completely downloaded or not at all
- **Consistency**: No partial file states during processing
- **Recovery**: Failed downloads can be retried without corruption

### Command Processing Transaction

1. **Download Verification**: Ensure command file is completely downloaded
2. **Command Parsing**: Parse JSON commands and validate syntax
3. **Sequential Execution**: Execute commands in order, collecting results
4. **Result Aggregation**: Compile all results into a single response
5. **Upload Confirmation**: Upload results and confirm successful processing

### Error Handling and Recovery

- **Network Failures**: Automatic retry mechanisms for failed downloads/uploads
- **Command Errors**: Individual command failures don't affect other commands
- **Partial Failures**: Graceful degradation when some operations fail
- **State Persistence**: Maintain command state across service restarts

## Service Integration

### Application Configuration

The transfer service can be configured as part of the application definition:

```json
{
    "application_id": "aws_factory_transfert-1.0",
    "service_name": "transfer",
    "service_port": 8015,
    "application_description": "transfer files to aws, with default aws device enrollment access",
    "additional_properties": {
        "AWS_ACCESS_KEY_ID": "xxxxxxxxxx",
        "AWS_SECRET_ACCESS_KEY": "xxxxxxxxxxx",
        "AWS_STORE_CONFIGURATION": "[{\"store_name\":\"config\",\"bucket_name\":\"etabelone-dev-etabelonedevbootstrape71b79bd-kfzemjujlgbe\",\"region\":\"eu-west-1\",\"prefix\":\"\"}]"
    }
}
```

### Use Cases

- **Application Updates**: Download and install new application versions
- **Configuration Management**: Retrieve device-specific configurations
- **Monitoring and Diagnostics**: Upload device health and performance data
- **Command Execution**: Receive and execute administrative commands
- **Data Synchronization**: Sync device data with central systems
- **Content Distribution**: Distribute content and media files to devices