Guida · Interfacce
Documento di controllo delle interfacce (ICD): cosa contiene e come mantenerlo aggiornato
Ascolta questa guida 20 min
Un documento di controllo delle interfacce registra ciò che attraversa il confine tra due parti di un sistema, e vincola i team di entrambe le parti alla stessa definizione. Questa guida tratta cosa contiene un ICD, chi ne è responsabile, come trovare le interfacce in primo luogo e come mantenere il documento coerente con il progetto mentre cambia, con un esempio svolto su due sottosistemi di un piccolo satellite di osservazione della Terra.
In questa pagina
- Che cos’è un documento di controllo delle interfacce
- Chi è responsabile di un ICD
- Cosa contiene un ICD
- Trovare le interfacce nell’architettura
- Mantenere l’ICD legato al modello
- Controllo delle modifiche alle interfacce
- Errori comuni
- Esempio svolto: dal C&DH alle comunicazioni su un CubeSat
- Provarlo in Holarch
- Dove andare dopo
Che cos’è un documento di controllo delle interfacce
La maggior parte dei problemi di integrazione non sta dentro un sottosistema; sta nella giunzione tra due di essi. Un team presume che il connettore sia polarizzato in un verso, l’altro team presume il contrario. Una parte invia un messaggio di stato ogni 100 ms, il timeout dell’altra parte è di 80 ms. Un documento di controllo delle interfacce esiste per rendere esplicita quella giunzione: stabilisce, in un unico punto concordato da entrambe le parti, cosa passa tra di esse e a quali condizioni.
Un ICD descrive un’interfaccia dall’esterno. Non dice come è costruita nessuna delle due parti, ma solo cosa ciascuna deve presentare al confine: il connettore e i suoi pin, tensione e corrente, la struttura e la temporizzazione dei messaggi, i punti di fissaggio, l’ambiente a cui l’interfaccia deve sopravvivere. Ogni team progetta poi la propria parte in modo che corrisponda.
Tre nomi di documenti correlati vengono spesso confusi:
| Documento | Risponde a | Contenuto tipico |
|---|---|---|
| Specifica dei requisiti di interfaccia (IRS) | Che cosa deve fare l’interfaccia? | Requisiti su una o più interfacce, scritti come enunciati «shall» verificabili prima che il progetto sia definito. |
| Descrizione del progetto dell’interfaccia (IDD) | Come la realizza una delle parti? | Il progetto di un’interfaccia così come realizzata da una parte, spesso un elemento software o hardware, con dettaglio sufficiente per costruirlo e testarlo. |
| Documento di controllo delle interfacce (ICD) | Su cosa si sono accordate entrambe le parti? | La definizione controllata e approvata congiuntamente dell’interfaccia tra due parti specifiche, posta sotto controllo delle modifiche. |
I programmi li combinano in modi diversi. Alcuni includono i requisiti nell’ICD; altri scrivono presto un IRS, poi un ICD quando il progetto matura. Ciò che conta è che requisiti e definizione concordata siano registrati entrambi, e che uno dei due sia chiaramente quello di riferimento.
Chi è responsabile di un ICD
Un ICD ha due parti, a volte di più, e un solo responsabile. Le parti sono le organizzazioni o i team responsabili di ciascun lato: due team di sottosistema, un prime contractor e un fornitore, un team del veicolo e un team del payload. Il responsabile è la persona o il gruppo che tiene il documento, sollecita i punti aperti e gestisce l’approvazione. Nei programmi più grandi è un gruppo di lavoro per il controllo delle interfacce (ICWG): rappresentanti di ciascuna parte più l’ingegnere di sistema responsabile dell’integrazione, che si riuniscono con cadenza regolare.
Alcune regole sulla responsabilità prevengono la maggior parte delle controversie:
- Un responsabile per interfaccia, nominato nel documento. «Il team di sistema» non è un responsabile; un responsabile con nome e cognome sì.
- Entrambe le parti approvano. Un ICD firmato da una sola parte è una lista dei desideri, non un documento di controllo.
- Il livello che integra è responsabile delle interfacce tra i suoi figli. L’interfaccia tra due sottosistemi appartiene al livello di sistema, perché nessuno dei due sottosistemi può definirla da solo.
- Le interfacce esterne, verso apparecchiature o sistemi al di fuori del programma, sono di responsabilità del programma e concordate con la parte esterna, che può avere un proprio documento prevalente.
Cosa contiene un ICD
La struttura esatta dipende dal dominio e dagli standard del programma, ma un ICD completo copre gli stessi aspetti. Lasciare una sezione con «non applicabile» invece di eliminarla, così che un revisore veda che è stata considerata.
| Sezione | Cosa registra |
|---|---|
| Identificazione e parti | Numero e nome dell’interfaccia, le due parti, il responsabile, lo stato del documento e le approvazioni. |
| Panoramica dell’interfaccia | Un diagramma delle due parti e di ogni collegamento tra di esse, e una breve formulazione dello scopo dell’interfaccia. |
| Elenco delle interfacce | Ogni singolo collegamento (cablaggio, bus, linea, tubazione, fissaggio) con il proprio numero, le estremità e lo stato. |
| Meccanica e fisica | Punti di fissaggio e schemi di foratura, ingombri e zone di esclusione, proprietà di massa all’interfaccia, allineamento, tipi e posizioni dei connettori. |
| Elettrica | Assegnazione dei pin, intervalli di tensione e corrente, qualità dell’alimentazione, messa a terra e collegamento equipotenziale, schermatura, isolamento, livelli dei segnali. |
| Dati e protocollo | Protocolli e livelli fisici, definizioni dei messaggi con nomi dei campi, tipi, intervalli, unità e scalature, identificativi, gestione degli errori. |
| Temporizzazione | Frequenze e periodi dei messaggi, budget di latenza, sequenze di avvio e risveglio, timeout e cosa fa ciascuna parte quando uno scade. |
| Fluidica, termica e ottica | Portate, pressioni e temperature al confine, calore trasferito attraverso di esso, percorsi ottici e campi visivi, dove applicabili. |
| Ambientale | Condizioni di vibrazione, urto, temperatura, umidità, ingresso di corpi estranei e compatibilità elettromagnetica a cui l’interfaccia deve sopravvivere. |
| Requisiti di interfaccia | I requisiti che l’interfaccia deve soddisfare, ciascuno tracciato al proprio requisito padre. |
| Verifica | Come viene verificato ogni requisito all’interfaccia (test, analisi, ispezione, dimostrazione), a quale livello e con quali apparecchiature. |
| Punti aperti | Ogni TBD (valore non ancora determinato) e TBR (valore proposto ma non ancora confermato), ciascuno con un responsabile e una data di chiusura. |
| Cronologia delle modifiche | Ogni revisione con la sua richiesta di modifica, cosa è cambiato e chi l’ha approvata. |
Dati e temporizzazione meritano il maggior dettaglio
Le interfacce meccaniche ed elettriche tendono a essere verificate fisicamente presto, alle prove di accoppiamento e alla prima accensione. Le discrepanze di dati e temporizzazione sopravvivono molto più a lungo, spesso fino all’integrazione di sistema, perché ciascuna parte testa contro il proprio simulatore, costruito sulla propria lettura del documento. Per ogni messaggio, annotare l’identificativo, il periodo e la sua tolleranza, tipo, intervallo, unità e scalatura di ogni campo, l’ordine dei byte e cosa fa il ricevitore quando il messaggio è in ritardo, mancante o fuori intervallo. Una definizione di messaggio che dice «corrente della batteria» senza unità, convenzione di segno (carica o scarica positiva) e risoluzione non è ancora controllata.
Verificare l’interfaccia stessa
I requisiti di interfaccia si verificano come qualsiasi altro requisito (la guida alla matrice di verifica dei requisiti tratta metodi, livelli ed evidenze), ma le evidenze hanno una forma particolare: richiedono entrambe le parti. Un test di compatibilità tra le unità reali, o tra un’unità reale e un emulatore convalidato dell’altra, vale più di due test separati contro due letture private dell’ICD. Pianificare questi test nell’ICD, così che apparecchiature e calendario esistano quando servono.
Trovare le interfacce nell’architettura
Un ICD può controllare solo le interfacce che qualcuno ha trovato. Il modo affidabile per trovarle è partire dall’architettura, non dalla memoria.
- Partire dalle funzioni. Scomporre la missione in funzioni con i loro ingressi e uscite (la guida all’analisi funzionale mostra come). Un diagramma N² pone le funzioni (o i sottosistemi) sulla diagonale; la cella nella riga A, colonna B contiene ciò che A invia a B. Ogni cella piena fuori dalla diagonale è uno scambio che ha bisogno di un percorso. I gruppi di celle piene mostrano quali funzioni vanno insieme; una riga o una colonna affollata indica una funzione da cui molte altre dipendono.
- Allocare le funzioni ai componenti. Una volta che ogni funzione è svolta da una parte fisica, ogni scambio tra funzioni in parti diverse diventa uno scambio che attraversa il confine di una parte. La guida all’architettura di sistema mostra come si effettua e si verifica questa allocazione.
- Dare a ogni scambio che attraversa un confine un percorso fisico. Un cablaggio, un bus, un collegamento radio, una tubazione o un giunto meccanico. Uno scambio senza percorso è una lacuna nel progetto; un percorso che non trasporta nulla è superfluo oppure non ancora compreso.
- Disegnare il diagramma delle interfacce. Per ogni coppia di parti, mostrare entrambi i lati, le loro parti interne al confine e ogni collegamento con ciò che trasporta. Questo diventa la figura di panoramica dell’ICD.
Numerare le interfacce man mano che si trovano. L’esempio svolto più avanti numera i suoi collegamenti da IF-01 a IF-25 e dà a un collegamento interno a un’interfaccia più ampia un decimale (IF-14.1 dentro IF-14). I numeri rendono le interfacce citabili in requisiti, procedure di test e richieste di modifica, e mantengono stabile un elenco di interfacce quando i nomi cambiano.
Mantenere l’ICD legato al modello
Un ICD scritto come file autonomo di un elaboratore di testi comincia ad allontanarsi dal progetto il giorno stesso in cui viene approvato. Un pin viene riassegnato nel disegno del cablaggio, il periodo di un messaggio cambia nel software, un nuovo segnale viene aggiunto per un requisito tardivo, e l’ICD viene aggiornato settimane dopo o mai. I revisori finiscono allora per confrontare documenti tra loro invece che con il progetto.
L’ingegneria dei sistemi basata su modelli ribalta la situazione. Ogni interfaccia è un elemento del modello di sistema, collegato alle sue due estremità, agli elementi che trasporta e ai requisiti che la governano. L’ICD è un rapporto generato da quegli elementi. Quindi:
- Lo stesso collegamento compare con gli stessi valori nell’ICD, nel diagramma delle interfacce, nella tracciabilità dei requisiti e nella matrice di verifica, perché tutti leggono un’unica definizione.
- Una modifica alla frequenza di un messaggio o a un connettore compare nel successivo ICD generato, e la cronologia delle modifiche viene dal registro del modello stesso.
- I controlli vengono eseguiti sul modello: uno scambio tra due parti senza un collegamento che lo trasporti, un collegamento con una sola estremità, un collegamento il cui carico supera la sua capacità, un collegamento senza responsabile o stato.
- I requisiti su un’interfaccia sono tracciati a essa, così le sezioni dei requisiti e della verifica dell’ICD restano complete (vedere la guida alla tracciabilità dei requisiti per i tipi di collegamento e i controlli delle lacune).
Non tutto va negli attributi del modello. Disegni dettagliati dei connettori, diagrammi temporali e lunghi cataloghi di messaggi possono restare in documenti allegati o referenziati. Il modello contiene comunque l’interfaccia, il suo stato, il suo responsabile e il riferimento, così l’ICD generato rimanda alla revisione giusta.
Controllo delle modifiche alle interfacce
La definizione di un’interfaccia matura per fasi, e la fase decide come viene gestita una modifica. Uno schema semplice in quattro fasi funziona per la maggior parte dei programmi:
| Stato | Significato | Come si effettua una modifica |
|---|---|---|
| Bozza | La prima definizione di una delle parti. | Il responsabile la modifica liberamente. |
| Proposto | Sottoposto all’altra parte per la revisione. | Le modifiche vengono discusse nel gruppo di lavoro e registrate. |
| Concordato | Entrambe le parti lo accettano; i progetti possono procedere su questa base. | Una modifica richiede il consenso di entrambe le parti e una valutazione d’impatto per ciascun lato. |
| In baseline | Parte di una baseline di configurazione approvata. | Una richiesta di modifica formale, valutata e approvata dal comitato di modifica, con nuova emissione dell’ICD. |
Una cadenza comune prevede interfacce in bozza entro la revisione dei requisiti di sistema, concordate prima della revisione preliminare del progetto e in baseline prima della revisione critica del progetto. Qualunque sia la cadenza, una richiesta di modifica su un’interfaccia in baseline dovrebbe indicare il motivo, i collegamenti e gli elementi interessati, l’impatto sul progetto, sui costi e sui tempi di ciascuna parte, i requisiti e la verifica interessati, e l’applicabilità: da quale build o numero di serie si applica la modifica. Come trovare e dimensionare questi effetti è mostrato passo per passo nella guida all’analisi dell’impatto delle modifiche.
Tracciare i TBD e i TBR come un elenco che deve ridursi. Un’interfaccia ancora piena di punti aperti alla revisione critica del progetto è un rischio per i tempi, qualunque cosa dica il suo stato.
Errori comuni
- Interfacce che nessuno ha trovato. A uno scambio tra funzioni non è mai stato dato un percorso fisico, oppure un’interfaccia esterna (apparecchiature di terra, apparecchiature di test, l’operatore) è stata omessa. Costruire l’elenco delle interfacce dall’architettura, non dall’elenco dei cablaggi.
- Documenti unilaterali. Un team scrive l’ICD, l’altro non lo approva mai formalmente, e il disaccordo emerge all’integrazione. Richiedere entrambe le approvazioni prima dello stato Concordato.
- Unità e convenzioni mancanti. Un valore senza unità, convenzione di segno, ordine dei byte o scalatura invita a due letture diverse. In revisione trattare ciascuna mancanza come un difetto.
- Carico non confrontato con la capacità. Ogni messaggio ci sta, ma insieme superano il bus; ogni carico ci sta nel cablaggio, ma insieme superano la sua portata nominale. Sommare i carichi su ogni collegamento e confrontarli con la sua capacità, con margine. Nel modello d’esempio più avanti, IF-05 Payload Interface trasporta una striscia d’immagine da 480 Mbps più un programma dei comandi da 0,02 Mbps su un collegamento da 400 Mbps: 480,02 su 400 Mbps, il 120 %, segnalato dal modello prima dell’integrazione invece che scoperto al banco.
- Temporizzazione lasciata implicita. Le frequenze sono indicate, le tolleranze e il comportamento al timeout no. Registrare entrambi e cosa fa ciascuna parte quando l’altra è in ritardo.
- Copie non aggiornate. L’ICD, il disegno del cablaggio e la tabella dei messaggi del software hanno ciascuno la propria versione. Generare da un’unica fonte, o almeno indicare quale è quella di riferimento.
- Punti aperti senza responsabile. Un TBR senza una persona e una data resta aperto. Assegnare a ciascuno entrambe.
- Verifica pianificata troppo tardi. I test delle interfacce richiedono l’hardware di entrambe le parti o emulatori convalidati. Pianificarli quando l’ICD viene concordato, non quando arrivano le unità.
Esempio svolto: dal C&DH alle comunicazioni su un CubeSat
L’esempio è EO-1, un CubeSat 6U di osservazione della Terra che riprende terreni agricoli da un’orbita eliosincrona a 500 km; la guida all’esempio di progetto MBSE percorre l’intero modello. Qui prendiamo una giunzione all’interno del veicolo: tra 1.4 C&DH (comando e gestione dei dati, un computer di bordo con 64 GB di memoria per il payload) e 1.5 Communications (il 1.5.1 UHF Transceiver per i comandi e il 1.5.2 S-band Transmitter per i dati del payload). Team diversi costruiscono i due lati, e ogni comando che il satellite esegue e ogni immagine che invia a terra attraversa questo confine.
Trovare gli scambi
Il passaggio di ripresa nominale del modello, OPS Run Nominal Imaging Pass, è scomposto in dodici funzioni, da OPS.1 a OPS.12, e undici di esse sono allocate all’asset che le svolge. Il suo diagramma N² le pone sulla diagonale e gli elementi che si scambiano nelle celle:
Due celle attraversano il confine tra C&DH e Communications:
- Riga OPS.2 Receive Imaging Plan (svolta dall’UHF Transceiver), colonna OPS.3 Load Command Schedule (svolta dal C&DH): Command Packets, i pacchetti di comando decodificati provenienti dalla radio.
- Riga OPS.7 Encode and Store Image (C&DH), colonna OPS.8 Transmit Image Data (l’S-band Transmitter): Downlink Frames, dati immagine compressi e suddivisi in pacchetti.
Un terzo scambio non compare in questo passaggio perché deriva dalla logica delle modalità del veicolo: l’azione di ingresso del C&DH Enable S-band Transmitter invia un Transmitter Enable Command a F9 Transmit Payload Data, svolta dall’S-band Transmitter. Un elenco di interfacce costruito da un solo scenario lo avrebbe perso, ed è per questo che le funzioni vengono allocate agli asset in tutto il modello prima di elencare le interfacce.
I collegamenti e ciò che trasportano
La demo dà già a ogni scambio un percorso fisico. Per ricavarne un’unica interfaccia controllata, abbiamo aggiunto un solo elemento al progetto demo: un conduit padre, IF-26 C&DH to Communications Interface, collegato a entrambi i sottosistemi, stato Concordato, responsabile Comms Lead, con i due collegamenti esistenti come figli. Tutto il resto qui di seguito è la demo così come viene fornita.
| Collegamento | Estremità | Mezzo e connettore | Trasporta | Capacità | Stato |
|---|---|---|---|---|---|
| IF-07 Radio Command Interface | UHF Transceiver → C&DH | UART, 115,2 kbaud; J3 (Micro-D 9) | Command Packets, 0,0096 Mbps (9,6 kbps) | 0,1 Mbps | In baseline |
| IF-08 Payload Data Interface | C&DH → S-band Transmitter | SpaceWire; J4 (Micro-D 9) | Downlink Frames, 10 Mbps; Transmitter Enable Command, nessuna frequenza impostata | 100 Mbps | Concordato |
Ogni collegamento è tracciato al requisito che lo determina: IF-07 soddisfa 5.2 UHF Command Uplink («The UHF transceiver shall receive ground commands at 9.6 kbps»), e IF-08 soddisfa 5.1 S-band Downlink Rate («The S-band transmitter shall downlink payload data at 10 Mbps»).
Il diagramma delle interfacce
Il Diagramma di controllo delle interfacce mostra le due parti come fasce, l’interfaccia padre al centro, ogni collegamento come una barra con il suo stato, la sua capacità e i suoi elementi, e una linea da ogni collegamento alla parte che collega:
La fascia del C&DH non contiene parti perché il modello tratta il computer di bordo come un’unica unità: entrambi i collegamenti terminano sul C&DH stesso. Sul lato Communications ogni collegamento termina su una radio diversa, ed è esattamente ciò che il team dei cablaggi deve sapere.
L’ICD generato
L’ICD viene esportato dagli stessi elementi come documento Word. La prima pagina contiene il registro delle interfacce e un riepilogo degli stati; ogni conduit ha poi una propria sezione con estremità, connettore e pin, mezzo, elementi trasportati con direzione e frequenza, i requisiti collegati e il controllo della capacità.
Scaricare l’ICD: ICD di EO-1 per l’interfaccia tra C&DH e Communications (.docx), il documento completo di tre pagine così come lo ha esportato Holarch, senza la data di esportazione. Contiene solo i dati immaginari della demo EO-1.
Cosa mostra l’esempio
- Il registro è l’ordine del giorno del gruppo di lavoro. IF-07 è in baseline, quindi una sua modifica passa da una richiesta di modifica. IF-08 è concordato: una modifica richiede comunque sia il team del C&DH sia quello delle comunicazioni. Nessuno dei due ha un TBD o un TBR aperto, quindi questa interfaccia è pronta per entrare in baseline nel suo insieme.
- Confrontare la capacità con ciò che il mezzo fornisce davvero. IF-07 trasporta 9,6 kbps su una capacità registrata di 0,1 Mbps, che il documento riporta come 10 %. Una UART a 115,2 kbaud con un bit di start e uno di stop per byte trasferisce 115.200 × 8 / 10 = 92.160 bit/s di dati, quindi la capacità reale è di circa 92 kbps e il carico ne è circa il 10,4 %. Il margine è ampio in ogni caso, ma il valore registrato arrotonda per eccesso; su un collegamento più carico quell’arrotondamento nasconderebbe un problema.
- Un collegamento può essere a posto mentre il suo sistema fallisce. IF-08 fa passare 10 Mbps di frame su un collegamento SpaceWire da 100 Mbps, il 10 % della capacità. Il vincolo si trova un’interfaccia più a valle: IF-12 S-band Downlink trasporta 9,6 Mbps su un collegamento radio da 10 Mbps, il 96 %. Un flusso di frame più veloce passerebbe facilmente IF-08 e fallirebbe all’antenna, quindi una revisione dell’ICD guarda la catena, non un singolo collegamento.
- Un elemento senza frequenza non viene controllato. Il Transmitter Enable Command non ha una velocità di trasmissione, quindi il controllo della capacità lo esclude. È minimo, ma un valore vuoto è un punto aperto: assegnargli una frequenza, o un TBD con un responsabile.
- L’interfaccia padre non ha una capacità propria. Raggruppa gli elementi dei suoi collegamenti (qui tre) e dà alla coppia di parti un solo documento, un solo responsabile e un solo stato; i controlli del carico vengono eseguiti su ogni collegamento.
- Una modifica è tracciabile. Se la missione passa a una trasmissione a terra più veloce, la frequenza di Downlink Frames cambia in un solo punto, i controlli su IF-08 e IF-12 vengono rieseguiti, e il requisito 5.1, tracciato a IF-08, indica cosa riverificare.
Provarlo in Holarch
- Creare la demo con Gestisci progetti → File di progetto ▾ → Nuovo progetto demo → CubeSat (ingegneria dei sistemi guidata).
- Aprire Interfacce → Diagrammi N² e aprire il Diagramma N² dell’azione OPS Run Nominal Imaging Pass per vedere gli scambi tra le sue funzioni.
- Aprire Interfacce → ICD, fare clic su + Nuovo diagramma e scegliere C&DH come asset padre di sinistra e Communications come asset padre di destra.
- Trascinare i conduit esistenti IF-07 Radio Command Interface e IF-08 Payload Data Interface dalla tavolozza al riquadro centrale. I loro elementi e le loro connessioni li seguono.
- Selezionare un collegamento per rivederne Stato dell’interfaccia, Proprietario, TBD/TBR, Capacità e Unità, e i requisiti collegati.
- Fare clic su Esporta documento ICD per il documento Word, o su Esporta ICD (CSV) per una tabella.
Interfacce → Registro delle interfacce elenca ogni interfaccia del progetto con il suo stato e il controllo della capacità; nella demo mostra IF-05 oltre la capacità. Le istruzioni passo per passo si trovano in produrre un documento di controllo delle interfacce; le interfacce in baseline cambiano tramite richieste di modifica.
Dove andare dopo
- Le interfacce in Holarch: il registro delle interfacce, i controlli della capacità e gli ICD generati dal modello.
- Documentazione delle interfacce: conduit, elementi, il Diagramma di controllo delle interfacce, i diagrammi N² e Physical I/O.
- Documentazione delle richieste di modifica: controllo della configurazione per gli elementi in baseline.
- Che cos’è l’MBSE?: perché gli ingegneri tengono il sistema in un modello.