tbf/GenesisCordonelInterface/docs/articles/API/InterfaceOutsideToGCI.md

# InterfaceOutsideToGCI

## High-Level Overview

![GCI Overview](../../images/GCI__Onboarding_Overview_drawio.svg)

## Purpose

Public API facade for external applications.

## Architecture

External App
↓
InterfaceOutsideToGCI
↓
InterfaceGCIToLaatzen
↓
Meter

## Purpose

`InterfaceOutsideToGCI` is the public-facing API entry point of Genesis Cordonel Interface (GCI).

The class exposes a simplified and controlled interface intended for external applications while hiding internal implementation details.

Responsibilities:

- input validation
- public API exposure
- request model mapping
- forwarding calls into internal GCI services
- status notifications
- preadjustment workflow access

---

## Architecture Position

```text
External Application
        ↓
InterfaceOutsideToGCI
        ↓
InterfaceGCIToLaatzen
        ↓
ApiWorker
        ↓
MeterBatch
        ↓
GenesisMeter
```

This layer intentionally acts as a facade and should contain minimal business logic.

---

## Design Goals

The API layer exists to:

- expose stable external contracts
- isolate external consumers from internal changes
- centralize validation
- simplify integration
- hide internal meter implementation details

---

## Request Flow

Typical operation flow:

```text
External caller
        ↓
parameter validation
        ↓
model mapping
        ↓
InterfaceGCIToLaatzen
        ↓
worker execution
        ↓
meter communication
```

---

## Slot Management

Supports:

- slot initialization
- slot update
- slot cleanup
- slot information retrieval

Methods:

- InitSlotAsync()
- UpdateSlotAsync()
- GetSlotAsync()
- GetAllSlotsAsync()
- CleanSlotAsync()
- CleanAllSlotsAsync()

---

## Port Detection

Supports automatic communication port detection.

Available operations:

### DetectRequestPortAsync()

Attempts PCB communication through request channel.

### DetectStreamingPortAsync()

Attempts streaming communication detection.

Purpose:

- automatic setup
- communication diagnostics
- hardware discovery

---

## Meter Lifecycle

Supported lifecycle operations:

```text
Initialize
      ↓
Login
      ↓
Connect
      ↓
Read/Write
      ↓
Disconnect
      ↓
Clean
```

Methods:

- LoginOneSlotAsync()
- ConnectOneSlotAsync()
- DisconnectAsync()

---

## Register Access

Provides firmware register access.

### ReadRegisterAsync()

Reads register values from meter firmware.

### WriteRegisterAsync()

Writes register values.

Optional behavior:

- storeToDevice
- refreshSystemState

---

## Password Management

Supports runtime password changes.

Methods:

- SetPasswordAsync()
- SetMeterPasswordAsync()

Validation:

- slot id required
- password cannot be empty

---

## PCB Operations

Supports meter PCB identification.

Methods:

- GetPcbIdAsync()

Purpose:

- hardware identification
- diagnostics
- meter pairing

---

## Debug Support

Provides runtime diagnostics.

Methods:

- GetWorkerDebugStatuses()
- GetMeterBatchDebugStatuses()

Exposes:

- worker queues
- activity states
- slot status
- connection state

---

## Slot Selection Support

Supports selection state management.

Methods:

- SetSlotSelected()
- IsSlotSelected()
- GetSelectedSlots()

Purpose:

Used by UI and batch operations.

---

## Meter Batch Notifications

Event:

```csharp
MeterBatchStatusChanged
```

Purpose:

Notify external consumers whenever meter batch state changes.

Typical usage:

```csharp
api.MeterBatchStatusChanged += UpdateUi;
```

---

## PreAdjustment Support

Exposes standalone preadjustment workflow execution.

Supported processes:

- Detect
- Preparation
- Amplitude Test
- Temperature Calibration
- Offset Test
- Completion

Execution flow:

```text
Detect
   ↓
Preparation
   ↓
Amplitude Test
   ↓
Temperature Calibration
   ↓
Offset Test
   ↓
Completion
```

---

## Threading

Public operations are asynchronous.

Pattern:

```csharp
await api.ConnectOneSlotAsync(slot);
```

Internally:

```text
API
 ↓
InterfaceGCIToLaatzen
 ↓
ApiWorker
 ↓
slot-specific execution
```

This prevents concurrent access conflicts.

---

## Notes

Important constraints:

- API should not contain business logic
- validation belongs here
- execution belongs to internal GCI
- external applications should use this layer only