Obsidean_VM/01-Documentation/Dispositivos - Manuales/Maselli/Maselli - Utility/Maselli Proprietary Serial-Socket Protocol.md

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):

// 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);