# UI.Library - Sensor Management Library Documentation

## Table of Contents

1. [Overview](https://claude.ai/chat/04749c64-82af-4403-a784-664d5dc353ff#overview)
2. [Architecture](https://claude.ai/chat/04749c64-82af-4403-a784-664d5dc353ff#architecture)
3. [Core Components](https://claude.ai/chat/04749c64-82af-4403-a784-664d5dc353ff#core-components)
    - [Constants](https://claude.ai/chat/04749c64-82af-4403-a784-664d5dc353ff#constants)
    - [Enumerations](https://claude.ai/chat/04749c64-82af-4403-a784-664d5dc353ff#enumerations)
    - [Data Transfer Objects (DTOs)](https://claude.ai/chat/04749c64-82af-4403-a784-664d5dc353ff#data-transfer-objects-dtos)
    - [Services](https://claude.ai/chat/04749c64-82af-4403-a784-664d5dc353ff#services)
    - [Factory Pattern](https://claude.ai/chat/04749c64-82af-4403-a784-664d5dc353ff#factory-pattern)
4. [Workflow Examples](https://claude.ai/chat/04749c64-82af-4403-a784-664d5dc353ff#workflow-examples)
5. [API Communication](https://claude.ai/chat/04749c64-82af-4403-a784-664d5dc353ff#api-communication)
6. [Error Handling](https://claude.ai/chat/04749c64-82af-4403-a784-664d5dc353ff#error-handling)
7. [Sensor Types and Capabilities](https://claude.ai/chat/04749c64-82af-4403-a784-664d5dc353ff#sensor-types-and-capabilities)

## Overview

UI.Library is a comprehensive C# library designed for managing industrial sensors and their data across various phases of operation. The library provides a structured way to communicate with a central datasheet API, allowing applications to retrieve, create, and update sensor information and calibration data.

The library is particularly focused on handling industrial measurement sensors such as refractometers, density meters, and various control units, with support for different operational phases (primarily Phase 2 and Phase 3, which likely correspond to calibration and final configuration phases).

## Architecture

The library follows a layered architecture:

1. **DTO Layer** - Contains Data Transfer Objects for transferring data between the client and server
2. **Service Layer** - Provides services for interacting with the API
3. **Factory Layer** - Instantiates appropriate service implementations based on sensor type and phase

This architecture enables a clean separation of concerns and makes the library extensible for additional sensor types.

## Core Components

### Constants

The library defines constants for API communication:

```csharp
public class Constants
{
    public const string DATASHEET_API_ADDRESS = "http://10.0.0.122/";
}
```

This address serves as the base URL for all API communications.

### Enumerations

The `TipiSensore` enumeration defines all supported sensor types:

```csharp
public enum TipiSensore
{
    DR20 = 1,
    MD01 = 2,
    MD09 = 3,
    MD12 = 4,
    MD15 = 5,
    UR20_TETRA = 6,
    UR24 = 7,
    // ... and many more
}
```

### Data Transfer Objects (DTOs)

The DTO structure is hierarchical, with base classes providing common properties and derived classes adding sensor-specific properties:

#### Base DTOs

- `PhaseBaseRequest` - Base class for all request DTOs
- `PhaseBaseResponse` - Base class for all response DTOs
- `PhaseBaseInsertRequest` - For creating new phase data
- `PhaseBaseUpdateRequest` - For updating existing phase data

#### Phase-Specific DTOs

- Phase2 DTOs: Used for calibration processes
- Phase3 DTOs: Used for final configuration and operational parameters

#### Sensor-Specific DTOs

Each sensor type has its own specialized DTOs that inherit from the base DTOs and add properties specific to that sensor type.

### Services

The library provides two main service interfaces:

#### ISensorService

Responsible for general sensor operations:

```csharp
public interface ISensorService
{
    Task<SensorResponse> GetSensorBySerialNumberAsync(string serialNumber, CancellationToken token = default);
    Task<int?> GetIdBySerialNumberAsync(string serialNumber, CancellationToken token = default);
    Task<SensorResponse> InsertSensorAsync(SensorInsertRequest sensor, CancellationToken token = default);
}
```

#### IPhaseService

Handles phase-specific operations for a particular sensor type:

```csharp
public interface IPhaseService<TInsert, TUpdate, TResponse>
    where TInsert : PhaseBaseInsertRequest
    where TUpdate : PhaseBaseUpdateRequest
    where TResponse : PhaseBaseResponse
{
    Task<TResponse> GetLastRepetitionBySensorIdAsync(int sensorId, CancellationToken token = default);
    Task<bool> InsertAsync(TInsert entity, CancellationToken token = default);
    Task<bool> UpdateAsync(TUpdate entity, CancellationToken token = default);
}
```

### Factory Pattern

The `SensorServiceFactory` implements a factory pattern to create appropriate service instances:

```csharp
public static class SensorServiceFactory
{
    public static IPhaseService<TInsert, TUpdate, TResponse> GetPhase2Service<TInsert, TUpdate, TResponse>()
        where TInsert : PhaseBaseInsertRequest
        where TUpdate : PhaseBaseUpdateRequest
        where TResponse : PhaseBaseResponse
    {
        // Implementation determines which service to return based on generic types
    }

    public static IPhaseService<TInsert, TUpdate, TResponse> GetPhase3Service<TInsert, TUpdate, TResponse>()
        where TInsert : PhaseBaseInsertRequest
        where TUpdate : PhaseBaseUpdateRequest
        where TResponse : PhaseBaseResponse
    {
        // Implementation determines which service to return based on generic types
    }
}
```

## Workflow Examples

### Retrieving Sensor Information

```csharp
// Create a sensor service instance
ISensorService sensorService = new SensorService();

// Get a sensor by its serial number
SensorResponse sensor = await sensorService.GetSensorBySerialNumberAsync("ABC123456");

// Check if the sensor exists
if (sensor != null)
{
    // Process sensor information
    Console.WriteLine($"Sensor ID: {sensor.Id}");
    Console.WriteLine($"Sensor Type: {sensor.TipoId}");
}
```

### Working with Phase Data

```csharp
// Get the appropriate Phase 2 service for a UR20 sensor
var phase2Service = SensorServiceFactory.GetPhase2Service<Phase2UR20InsertRequest, Phase2UR20UpdateRequest, Phase2UR20Response>();

// Get the last Phase 2 data for a sensor
var phase2Data = await phase2Service.GetLastRepetitionBySensorIdAsync(1001);

// Create new Phase 2 data
var newPhase2Data = new Phase2UR20InsertRequest
{
    StrumentoId = 1001,
    Operatore = "John Doe",
    // Set other properties as needed
};

// Insert the new Phase 2 data
bool success = await phase2Service.InsertAsync(newPhase2Data);
```

## API Communication

The library uses HTTP for all API communications:

- **GET** requests for retrieving information
- **POST** requests for creating new data
- **PUT** requests for updating existing data

All communications use JSON for data serialization/deserialization.

Example API endpoint construction:

```csharp
string url = DatasheetApiEndpoints.GetDatasheetEndpointBySensorType(TipiSensore.UR20) + "/phases2/insert";
// Results in: "api/ur20s/phases2/insert"
```

## Error Handling

The library implements error handling through exceptions:

- HTTP errors are propagated as `InvalidOperationException` with the response content as the message
- Input validation is performed before sending requests (e.g., checking for required properties)
- `404 Not Found` responses are handled specially and return `null` instead of throwing an exception

## Sensor Types and Capabilities

The library supports various sensor types, each with specific capabilities:

### Refractometer Sensors (UR Series)

- Measure refractive index and Brix (sugar content)
- Support temperature compensation
- Can include prism temperature control

### Density Meters (DR Series)

- Measure density of liquids
- Support for multiple CCD sensors

### CO2 Sensors (UC Series)

- Measure CO2 concentration
- Support pressure and temperature compensation

Each sensor type has specific calibration parameters and operational settings that can be configured through the library.

---

This documentation provides an overview of the UI.Library functionality. For specific details about individual classes and methods, refer to the inline XML documentation in the source code.