# Maselli Proprietary Serial/Socket Protocol

This document describes the proprietary communication protocol used by Maselli instruments, as implemented in the provided C# software, primarily within the `Uc09_Utility.ClassSerialeStrumenti` and related classes. The protocol is used for both direct serial communication and when bridged over TCP/IP sockets.

## 1. Core Principles

* **Master-Slave:** The software acts as the master, sending commands to instrument slaves.
* **Addressed Communication:** Each instrument on a communication line is assigned an address.
* **Function-Oriented:** Commands target specific functions or parameters within the instrument using numeric codes (Function Numbers).
* **Text-Based:** The primary protocol commands and responses are text-based strings.
* **Checksum Protected:** Commands include a checksum for integrity validation.
* **Bridged over TCP/IP:** The same serial protocol strings can be encapsulated and transmitted over TCP/IP when the Ethernet bridge functionality is enabled.

## 2. Command Structure

The general structure of a command sent from the master (software) to the instrument (slave) is:

`>` + `LLLL` + `AA` + ` ` + `T` + `;` + `FFF` + `VALUE` + `;` + `cc` + `\r`

Where:

* `>`: Start of command character.
* `LLLL`: Four-digit hexadecimal representation of the **total length of the command string**, starting from `AA` up to and including the checksum `cc`. Padded with leading zeros if necessary (e.g., "001A").
* `AA`: Two-digit hexadecimal instrument address. Padded with a leading zero if necessary (e.g., "01", "0A").
* ` `: A space character.
* `T`: Command Type (a single character). See section "Command Types" below.
* `;`: Semicolon delimiter.
* `FFF`: Three-digit decimal function number (parameter ID). Padded with leading zeros (e.g., "001", "023", "100").
* `VALUE`: The value associated with the command, if applicable. Its format depends on the command type and function.
    * For read commands (`V`), this part might be absent or ignored by the instrument.
    * For modify commands (`M`), this contains the data to be written.
* `;`: Semicolon delimiter.
* `cc`: Two-character hexadecimal checksum. Calculated on the string portion from `AA` up to (but not including) the preceding semicolon. See section "Checksum Calculation".
* `\r`: Carriage return (ASCII 13), command terminator.

**Example Command Preparation (from `ClassSerialeStrumenti.PreparaComando`)**:

```csharp
// Simplified logic
string comando = string.Format("{0} {1};{2:000}{3}",
    addressHex, // AA
    tipoComando, // T
    numeroFunzione, // FFF
    valoreComando // VALUE
);
string lunghezza = string.Format("{0:X4}", comando.Length + 3); // LLLL (+3 for ";cc")
string checksum = CalcolaChecksum(comando); // cc
string finalCommand = string.Format(">{0}{1};{2}\r", lunghezza, comando, checksum);