Milbus Modelling
This document describes the TEMU MIL-STD-1553 bus model and its interfaces. The MIL-STD-1553 standard is often referred to as simply milbus or 1553.
The 1553 protocol is described in detail in the well known "MIL-STD-1553 Tutorial" document from AIM GmbH (formerly published by Condor). It is recommended that persons involved with modelling bus controllers and remote terminals keep a copy of that document at close hand.
The TEMU support for the 1553 protocol consist of
a bus interface (Mil1553BusIface), a bus model (MilStd1553Bus)
and a bus client interface (Mil1553DevIface).
This approach enables the user to not only implement remote terminal models, but also to implement their own bus models. The latter is of interest if the bundled model is found not suitable.
Most users will be interested in implementing remote terminal models, but bus controllers are also possible as they use the same interface.
Bus Model
The 1553 bus model is available as a class with the name MilStd1553Bus
in the TEMU "BusModels" plugin.
Configuration
The bus model is configured using the Mil1553BusIface.
This is done by calling the connect function
in order to attach remote terminal at given subaddress.
SetBusController should be called to set the current bus controller
| It is possible to set the current bus controller at runtime, this is useful for handovers. |
The construction of a network with 1553 devices is simplified by using the following commands in the command line interface:
-
mil-std-1553-connect bus=b rt=rt addr=1
-
mil-std-1553-disconnect bus=b addr=1
-
mil-std-1553-setbc bus=b bc=bc
@MilStd1553Bus Reference
MilStd1553Bus Reference
Properties
| Name | Type | Description |
|---|---|---|
Class |
*void |
Class object |
Component |
*void |
Pointer to component object if part of component |
LoggingFlags |
uint64_t |
Flags for logging info |
Name |
*char |
Object name |
TimeSource |
*void |
Time source object |
bc |
temu_IfaceRef/ <unknown> |
Bus controller. |
devices |
[temu_IfaceRef; 32]/ <unknown> |
Remote terminals. |
inhibitChA |
uint8_t |
|
inhibitChB |
uint8_t |
|
lastCmd |
uint16_t |
|
receiverRT |
int8_t |
|
stats.lastReportSentWords |
uint64_t |
|
stats.sentWords |
uint64_t |
|
transmitterRT |
int8_t |
Commands
| Name | Description |
|---|---|
connect |
Connect device to 1553 bus. |
delete |
Dispose instance of MilStd1553Bus |
disconnect |
Disconnect device from 1553 bus. |
setBC |
Set bus controller for 1553 bus. |
@MilStd1553BusLogger Reference
MilStd1553BusLogger Reference
Properties
| Name | Type | Description |
|---|---|---|
Class |
*void |
Class object |
Component |
*void |
Pointer to component object if part of component |
LoggingFlags |
uint64_t |
Flags for logging info |
Name |
*char |
Object name |
TimeSource |
*void |
Time source object |
bus |
*void |
Bus object to monitor. |
statPeriod |
double |
Statistics report period in seconds, set to positive enables reports. |
Notifications
The default TEMU milbus model issues the following notifications:
| Name | Description | Param Type |
|---|---|---|
temu.mil1553Stat |
Statistics notification. |
temu_Mil1553Stats* |
temu.mil1553Send |
Valid message in transit. |
temu_Mil1553Msg* |
The statistics notification is issued when calling
the reportStats function in the bus interface.
The user can call this function from a timed event handler if needed.
It would be possible to force statistics reporting at a PPS tick,
i.e. by having the a PPS device issue the call.
This way the stat event can be used to monitor
whether the system keeps the milbus budget.
The send notification receives a pointer with the actual message in transit. Before it has been delivered to the remote terminal, but after the bus object has rejected any messages transmitted illegally. The notification handler is free to modify the message. For example it is possible to set the Err field in the message struct to inject a transfer error. The RT can then set the message error bit in the status word.
Limitations
The bus object does not support bus monitors in the normal sense.
However, it is possible to turn on the temu.mil1553Send notification
and listen in on all traffic using this notification interface.
For the command line support, only models with one and only one device
interface with the name Mil1553DevIface is supported.
This may change in the future.
API
Interfaces
typedef struct temu_Mil1553BusIface {
void (*connect)(void *Bus, int Subaddr, temu_Mil1553DevIfaceRef Device);
void (*disconnect)(void *Bus, int Subaddr);
void (*reportStats)(void *Bus);
void (*send)(void *Bus, void *Sender, temu_Mil1553Msg *Msg);
// Controls whether events should be issued at send calls
void (*enableSendEvents)(void *Bus);
void (*disableSendEvents)(void *Bus);
void (*setBusController)(void *Bus, temu_Mil1553DevIfaceRef Device);
} temu_Mil1553BusIface;typedef struct temu_Mil1553DevIface {
void (*connected)(void *Device, temu_Mil1553BusIfaceRef Bus, int SubAddr);
void (*disconnected)(void *Device, temu_Mil1553BusIfaceRef Bus, int SubAddr);
void (*receive)(void *Device, temu_Mil1553Msg *Msg);
} temu_Mil1553DevIface;Writing Clients
Bus Controllers and Remote Terminals
Bus controllers and remote terminals can be implemented
using the Mil1553BusIface interface.
This interface is defined in temu-c/Bus/MilStd1553.h.
The interface consist of the connected, disconnected and receive functions. These are all mandatory and they are called whenever a virtual cable is connected and disconnected, or when a 1553 bus message is received.
A remote terminal needs to know about the bus it is connected to so it can use the send function in the Mil1553BusIface interface.
| Do not call the bus send function from the device receive function, doing so will result in undefined behaviour. If a response is to be issued due to handling of a receive, ensure that an event is posted on the model’s event queue source. |
The 1553 API follows the standard and subdivides transactions in phases.
The phases are: command, data, status and mode command phases.
To send a receive command, the bus controller will
first send a message of the type teMT_Cmd, followed by a teMT_Data message.
The remote terminal is then expected to respond with a teMT_Stat message.
The RT and BC models are responsible for issuing the different messages with delays.
Delays can be computed using the temu_mil1553TransferTime()` function.
Messages should be sent in whole when they are supposed to arrive. This means that the bus controller model can immediately raise any needed interrupts when a message is complete.
| The TEMU default 1553 bus model will print error messages if an RT does not follow the 1553 protocol phases correctly. E.g. sending a status response to a broadcast message, will trigger a message. |
void
receive(void *Device, temu_Mil1553Msg *Msg)
{
MyRT *RT = (MyRT*)Device;
//...
// Start sending response
temu_eventPostNanos(RT->Super.TimeSource, RT->TransferCompleteEvent,
temu_mil1553TransferTime(1), // One word for status message
teSE_Cpu);
}
void
transferComplete(temu_Event *Ev)
{
MyRT *RT = (MyRT*)Ev->Obj;
uint16_t Stat = computeStatWord(RT);
temu_Mil1553Msg Msg = temu_mil1553CreateStatMsg(&Stat);
RT->Bus.Iface->send(RT->Bus.Obj, RT, &Msg); // Send the message
}Bus Monitors
The 1553 bus interface does not support the implementation of bus monitors directly. The reason for this is that, the notifications already allows the simulator to inspect all the bus traffic. The notification interface can also be used to modify traffic in flight (e.g. to flip the error flags in the message object).
Terma appreciates that there may be need for some users to support modelling of bus monitors, please contact Terma if this is needed.
Capture Device
TEMU is bundled with a MILBUS capture device that enables capturing of the bus traffic. There are three supported options for message capture:
-
Logging command words issued to the TEMU log with partial decoding
-
CSV output with command words and partial decodes of them
-
PCAPNG file with all data transferred. File can be loaded in Wireshark if needed.
To create a logging capture device, create the bus capture instance using:
For logging:
object-create class=MilStd1553BusCapturer name=milbus-cap0 \ args='fmt:log,bus:milbus0'
For CSV output (into milbus0.csv):
object-create class=MilStd1553BusCapturer name=milbus-cap0 \ args='fmt:csv,bus:milbus0'
For PCAPNG output (into milbus0.pcapng):
object-create class=MilStd1553BusCapturer name=milbus-cap0 \ args='fmt:pcapng,bus:milbus0'
Do not forget to set the time source for the capture device:
While the logging and CSV modes should be clear enough, there are some notes to be providede regarding the PCAPNG format.
Firstly, the capture model captures logical units in the protocol. That is, command words are captured by themselves, as is status messages and data messages.
Secondly, the capture model use the flags in the frame block to mark where the data came from. That is, it flags unicast, and broadcast messages as such, and it also flags the direction as outbound for frames emitted by the BC (e.g. command words, mode codes, data sent to RTs etc) and inbound for data sent from RTs.
Thirdly, LINKTYPE_USER0 is used for the device type
(there is no standardised milbus link type).
This linktype is not supported directly by Wireshark,
and a dissector needs to be implemented to make frames more human readable.