MX Foundation 4
Functions
Others
Protocol Specific Functions Reference » Discrete IO

Functions

uint32 mxfDiscreteChannelRead (HMXF_CHANNEL channel, uint64 mask, uint64 *data)
 
uint32 mxfDiscreteChannelWrite (HMXF_CHANNEL channel, uint64 mask, uint64 data)
 
uint32 mxfDiscreteTxAperiodicWrite (HMXF_BUFFER buffer, uint64 options, uint64 startTime, uint64 count, MXF_DISCRETE_DATAREC *rec)
 
uint32 mxfDiscreteRxAcqRead (HMXF_BUFFER buffer, uint64 maxMsgCount, uint64 maxBytesCount, uint64 *status, uint64 *msgCount, uint64 *byteCount, MXF_DISCRETE_DATAREC *rec)
 
uint32 mxfDiscreteRxSamplingRead (HMXF_BUFFER buffer, uint64 flags, uint64 maxMsgCount, uint64 maxBytesCount, uint64 *msgCount, uint64 *byteCount, MXF_DISCRETE_SAMPREC *rec)
 
uint32 mxfDiscreteNextDataRecordPtrGet (MXF_DISCRETE_DATAREC *currentRec, MXF_DISCRETE_DATAREC **nextRec)
 
uint32 mxfDiscreteEmbeddedNVStorageFileMsgRead (HMXF_NVSTORAGE nvStorage, uint64 fileIndex, uint64 maxMsgCount, uint64 maxBytesCount, uint64 *msgCount, uint64 *byteCount, MXF_DISCRETE_DATAREC *msg)
 
uint32 mxfDiscreteEmbeddedNVStorageFileMsgWrite (HMXF_NVSTORAGE nvStorage, uint64 fileIndex, uint64 maxMsgCount, MXF_DISCRETE_DATAREC *msg, uint64 *count)
 

Detailed Description

Function Documentation

uint32 mxfDiscreteChannelRead ( HMXF_CHANNEL  channel,
uint64  mask,
uint64 *  data 
)
C#
public static extern UInt32 mxfDiscreteChannelRead(UInt64 channel, UInt64 mask, out UInt64 data);

Reads the current discrete input lines state on a discrete channel.

Parameters
[in]channelchannel handle.
[in]maskport mask.
[out]datadata returned.

Port Mask Example

The mask bit 0 selects the channel first port, bit 1 the second port, etc.

Therefore, to get the state of the port #1, set the mask to 0x00000002.

Returns
MAXT_SUCCESS is returned when the function has succeeded.
Refer to mxf_error.h for a list of defined errors.
Call mxfSystemErrorStringGet() to transform the return code into a text string.
Availability:
Available in MX Foundation 4.0 and later.
See also
mxfDiscreteChannelWrite()
Examples:
discrete.c, discrete.cs, discrete_Multi.c, and discrete_Multi.cs.
uint32 mxfDiscreteChannelWrite ( HMXF_CHANNEL  channel,
uint64  mask,
uint64  data 
)
C#
public static extern UInt32 mxfDiscreteChannelWrite(UInt64 channel, UInt64 mask, UInt64 data);

Sets the discrete output lines state on a discrete channel.

Parameters
[in]channelchannel handle.
[in]maskport mask.
[in]datadata to set.

Port Mask Example

The mask bit 0 selects the channel first port, bit 1 the second port, etc.

Therefore, to set the state of the port #1, set the mask to 0x00000002.

Returns
MAXT_SUCCESS is returned when the function has succeeded.
Refer to mxf_error.h for a list of defined errors.
Call mxfSystemErrorStringGet() to transform the return code into a text string.
Availability:
Available in MX Foundation 4.0 and later.
See also
mxfDiscreteChannelRead()
Examples:
ar629_alternate.c, ar629_alternate.cs, discrete.c, discrete.cs, discrete_Multi.c, discrete_Multi.cs, mil1553_bc_dual_major_frame.c, mil1553_bc_dual_major_frame.cs, mil1553_cond_branch_2.c, and mil1553_cond_branch_2.cs.
uint32 mxfDiscreteTxAperiodicWrite ( HMXF_BUFFER  buffer,
uint64  options,
uint64  startTime,
uint64  count,
MXF_DISCRETE_DATAREC *  rec 
)
C#
public static extern UInt32 mxfDiscreteTxAperiodicWrite(UInt64 buffer, UInt64 options, UInt64 startTime, UInt64 count, IntPtr rec);

Sends aperiodic data records for transmission. The data items to be transmitted are specified within the records, along with an optional time tag. The first data item is transmitted at the specified starting time.

The records to transmit on time tag must be placed in chronological order in the array. The same time tag must not appear more than once in the array. When the start time is specified the time tag of the first record or the start time should be at least 50 msec in advance to be relatively precise otherwise it will be sent as soon as possible. Also, the cumulative time of all record’s time tag and the start time must be smaller than 30 seconds.

Note
This function is the specific version for Discrete IO of the multi-protocol mxfTxAperiodicWrite() function.
Parameters
[in]bufferbuffer handle.
[in]optionsoptions for controlling the transmitter before sending the data records. The details of the options are explained below.
  • MXF_TXAPERIODIC_FLAG_DEFAULT
  • MXF_TXAPERIODIC_FLAG_USE_RECORD_ABSOLUTE_TIME
  • MXF_TXAPERIODIC_FLAG_ABSOLUTE_START_TIME
  • MXF_TXAPERIODIC_FLAG_USE_RECORD_RELATIVE_TIME
[in]startTimestart time based on the timebase. This is the time at which the data held in the first record is transmitted by the device. The time is either expressed accordingly to the process time base or relative to the current real-time clock value (i.e. offset in the future). If the bit MXF_TXAPERIODIC_FLAG_ABSOLUTE_START_TIME of the transmit flag is set, then the start time is specified in absolute time (rather than relative). MXF_TXAPERIODIC_FLAG_USE_RECORD_ABSOLUTE_TIME or MXF_TXAPERIODIC_FLAG_USE_RECORD_RELATIVE_TIME options cannot be used with a start time.
[in]countnumber of records to write.
[in]recpointer to MXF_DISCRETE_DATAREC records to write. The records in the buffer need to be indexed using the mxfDiscreteNextDataRecordPtrGet() function.


The options modifies the transmission scheme as described below;

  • MXF_TXAPERIODIC_FLAG_DEFAULT

    This is the default transmission flag, the scheduling priority defined when the buffer area was defined (see mxfTxAperiodicBufferAlloc()) is used to schedule the transmissions.

    The time tag field is not used and must be set to 0. The records are transmitted with minimum delay between them.

  • MXF_TXAPERIODIC_FLAG_USE_RECORD_ABSOLUTE_TIME

    When set, the absolute transmit time of each data must be set in the record time tag. The time tag must be formatted according to the process time base.

    This flag cannot be used with MXF_TXAPERIODIC_FLAG_USE_RECORD_RELATIVE_TIME, MXF_TXAPERIODIC_FLAG_ABSOLUTE_START_TIME or a start time.

  • MXF_TXAPERIODIC_FLAG_USE_RECORD_RELATIVE_TIME

    When set, the relative transmit time of each data must be set in the record time tag. The process time base resolution is used, but the time base itself is ignored.

    This option causes transmission of the first record at the specified offset and transmission of the remaining records after a delay that is computed by subtracting the record time tag from the time tag of preceding records (i.e. delta time).

    Let’s assume N data records to be transmitted with the MXF_TXAPERIODIC_FLAG_USE_RECORD_RELATIVE_TIME.

    The actual record data transmit time will be computed as follows:

    Time rec1 = Transmission offset (min 50 msec)
    Time rec2 = Time rec1 + (rec2 time tag – rec1 time tag )
    Time rec3 = Time rec2 + (rec3 time tag – rec2 time tag )
    …
    Time recN = Time recN-1 + (recN time tag - recN-1 time tag )

    This flag can’t be used with MXF_TXAPERIODIC_FLAG_USE_RECORD_ABSOLUTE_TIME, MXF_TXAPERIODIC_FLAG_ABSOLUTE_START_TIME or a start time.

  • MXF_TXAPERIODIC_FLAG_ABSOLUTE_START_TIME

    When set, the startTime parameter must be formatted according to the process time base.

    If not set, the startTime parameter is expressed as a relative time from the current real time clock value.The process time base resolution is used, but the time base itself is ignored.

    This flag cannot be used with MXF_TXAPERIODIC_FLAG_USE_RECORD_ABSOLUTE_TIME or MXF_TXAPERIODIC_FLAG_USE_RECORD_RELATIVE_TIME options.
Returns
MAXT_SUCCESS is returned when the function has succeeded.
Refer to mxf_error.h for a list of defined errors.
Call mxfSystemErrorStringGet() to transform the return code into a text string.
Availability:
Available in MX Foundation 4.0 and later.
See also
mxfTxAperiodicWrite()
mxfTxAperiodicBufferAlloc()
mxfTxAperiodicBufferStatusGet()
mxfTxAperiodicClear()
mxfSystemTimeBaseSet()
mxfDiscreteNextDataRecordPtrGet()
Examples:
ar429_embedded_discrete.c, ar429_embedded_discrete.cs, discrete_event_handler.c, discrete_event_handler.cs, discrete_fifo.c, discrete_fifo.cs, discrete_pulse_clock.c, discrete_pulse_clock.cs, irigb_1pps.c, irigb_1pps.cs, mil1553_bc_extclock.c, and mil1553_bc_extclock.cs.
uint32 mxfDiscreteRxAcqRead ( HMXF_BUFFER  buffer,
uint64  maxMsgCount,
uint64  maxBytesCount,
uint64 *  status,
uint64 *  msgCount,
uint64 *  byteCount,
MXF_DISCRETE_DATAREC *  rec 
)
C#
public static extern UInt32 mxfDiscreteRxAcqRead(UInt64 buffer, UInt64 maxMsgCount, UInt64 maxBytesCount, out UInt64 status, out UInt64 msgCount, out UInt64 byteCount, IntPtr rec);

Transfers the records from the channel acquisition buffer to the calling application.

Note
This function is the specific version for Discrete IO of the multi-protocol mxfRxAcqRead() function.
Parameters
[in]bufferbuffer handle.
[in]maxMsgCountmaximum messages to read (0 means all messages).
[in]maxBytesCountmaximum number of bytes to be read.
[out]statuslast status set.
[out]msgCountnumber of records returned.
[out]byteCountnumber of bytes returned.
[out]recaddress of data records. The records in the buffer need to be indexed using mxfDiscreteNextDataRecordPtrGet() function.
Note
For IPM-DIO-32-FIFO input channels, the first record read after a mxfRxAcqStart() call is the current state of discrete input pins. The following records are generated according to specified discrete input transitions.
Returns
MAXT_SUCCESS is returned when the function has succeeded.
Refer to mxf_error.h for a list of defined errors.
Call mxfSystemErrorStringGet() to transform the return code into a text string.
Availability:
Available in MX Foundation 4.0 and later.
See also
mxfRxAcqRead()
mxfRxAcqStart()
mxfRxAcqBufferAlloc()
mxfRxAcqStop()
mxfDiscreteNextDataRecordPtrGet()
Examples:
discrete_event_handler.c, discrete_event_handler.cs, discrete_fifo.c, discrete_fifo.cs, discrete_rx_acquisition_trigger.cs, mil1553_bc_buserror_trigger.c, and mil1553_bc_buserror_trigger.cs.
uint32 mxfDiscreteRxSamplingRead ( HMXF_BUFFER  buffer,
uint64  flags,
uint64  maxMsgCount,
uint64  maxBytesCount,
uint64 *  msgCount,
uint64 *  byteCount,
MXF_DISCRETE_SAMPREC *  rec 
)
C#
public static extern UInt32 mxfDiscreteRxSamplingRead(UInt64 buffer, UInt64 flags, UInt64 maxMsgCount, UInt64 maxBytesCount, out UInt64 msgCount, out UInt64 byteCount, IntPtr rec);

Reads the sampling record from the sampling buffer to the application buffer.

The sampling process keeps the last record received. A record is considered received if it were received within the kill-time period. A record refresh from the receive port resets the kill-time timer and an updated copy is made available to the application.

The sampling record contains information on the arrival rate as well as the latest discrete input lines state.

Note
This function is the specific version for Discrete IO of the multi-protocol mxfRxSamplingRead() function.
Parameters
[in]bufferbuffer handle.
[in]flagsoption flag.
Flags Description
MXF_RXSAMPLING_FLAG_DEFAULT The record is kept in the buffer and the same record can be read again by the current or another application.
MXF_RXSAMPLING_FLAG_ERASE_WHEN_READ After the sampling record is returned, it is removed from the buffer.
[in]maxMsgCountmaximum number of messages to read. Normally one, maximum of one sampling record available.
[in]maxBytesCountmaximum number of bytes to read. Normally sizeof MXF_DISCRETE_SAMPREC structure.
[out]msgCountnumber of messages returned.
[out]byteCountnumber of bytes returned.
[out]recpointer to MXF_DISCRETE_SAMPREC record structure.
Returns
MAXT_SUCCESS is returned when the function has succeeded.
Refer to mxf_error.h for a list of defined errors.
Call mxfSystemErrorStringGet() to transform the return code into a text string.
Availability:
Available in MX Foundation 4.0 and later.
See also
mxfRxSamplingRead()
mxfRxSamplingBufferAlloc()
mxfRxSamplingMsgSelectSet()
mxfRxSamplingStart()
uint32 mxfDiscreteNextDataRecordPtrGet ( MXF_DISCRETE_DATAREC *  currentRec,
MXF_DISCRETE_DATAREC **  nextRec 
)
C#
public static extern UInt32 mxfDiscreteNextDataRecordPtrGet(IntPtr currentRec, out IntPtr nextRec);

Returns the next buffer address in a MXF_DISCRETE_DATAREC buffer array.

Note
This function is the specific version for Discrete IO of the multi-protocol mxfNextRecordPtrGet() function.
Parameters
[in]currentRecpointer to the beginning or the current record in the buffer.
[out]nextRecpointer to next record in the buffer.
Returns
MAXT_SUCCESS is returned when the function has succeeded.
Refer to mxf_error.h for a list of defined errors.
Call mxfSystemErrorStringGet() to transform the return code into a text string.
Availability:
Available in MX Foundation 4.0 and later.
See also
mxfNextRecordPtrGet()
mxfDiscreteRxAcqRead()
mxfDiscreteTxAperiodicWrite()
Examples:
ar429_embedded_discrete.c, ar429_embedded_discrete.cs, discrete_event_handler.c, discrete_event_handler.cs, discrete_pulse_clock.c, discrete_pulse_clock.cs, mil1553_bc_buserror_trigger.c, mil1553_bc_buserror_trigger.cs, mil1553_bc_extclock.cs, multi.c, and multi.cs.
uint32 mxfDiscreteEmbeddedNVStorageFileMsgRead ( HMXF_NVSTORAGE  nvStorage,
uint64  fileIndex,
uint64  maxMsgCount,
uint64  maxBytesCount,
uint64 *  msgCount,
uint64 *  byteCount,
MXF_DISCRETE_DATAREC *  msg 
)
C#
public static extern UInt32 mxfDiscreteEmbeddedNVStorageFileMsgRead(UInt64 storage, UInt64 fileIndex, UInt64 maxRecCount, UInt64 maxBytesCount, out UInt64 recCount, out UInt64 bytesCount, IntPtr rec);

Reads the records from a specific file. The messages format must be of type MXF_EMBEDDED_NVSTORAGE_MSGTYPE_DISCRETE.

Note
This function is the specific version for Discrete IO of the multi-protocol mxfEmbeddedNVStorageFileMsgRead() function.
Parameters
[in]nvStoragenon-volatile storage handle
[in]fileIndexfile index
[in]maxMsgCountmaximum number of messages that can be returned
[in]maxBytesCountmaximum byte count that can be returned
[out]msgCountcount of messages returned
[out]byteCountnumber of bytes returned in the msg buffer
[out]msgpointer to read buffer containing messages. The records in the buffer need to be indexed using the mxfDiscreteNextDataRecordPtrGet() function.
Returns
MAXT_SUCCESS is returned when the function has succeeded.
Refer to mxf_error.h for a list of defined errors.
Call mxfSystemErrorStringGet() to transform the return code into a text string.


Availability:
Available in MX Foundation 4.0 and later.
See also
mxfEmbeddedNVStorageHandleGet()
mxfEmbeddedNVStorageFileStatusGet()
uint32 mxfDiscreteEmbeddedNVStorageFileMsgWrite ( HMXF_NVSTORAGE  nvStorage,
uint64  fileIndex,
uint64  maxMsgCount,
MXF_DISCRETE_DATAREC *  msg,
uint64 *  count 
)
C#
public static extern UInt32 mxfDiscreteEmbeddedNVStorageFileMsgWrite(UInt64 storage, UInt64 fileIndex, UInt64 maxRecCount, IntPtr rec, out UInt64 recCount);

Writes messages to the specified file. The messages format must be of type MXF_EMBEDDED_NVSTORAGE_MSGTYPE_DISCRETE.

Note
This function is the specific version for Discrete IO of the multi-protocol mxfEmbeddedNVStorageFileMsgWrite() function.
Parameters
[in]nvStoragenon-volatile storage handle
[in]fileIndexfile index
[in]maxMsgCountmaximum number of messages to write
[in]msgpointer to messages to write. The records in the buffer need to be indexed using mxfDiscreteNextDataRecordPtrGet() function.
[out]countnumber of messages actually written
Returns
MAXT_SUCCESS is returned when the function has succeeded.
Refer to mxf_error.h for a list of defined errors.
Call mxfSystemErrorStringGet() to transform the return code into a text string.


Availability:
Available in MX Foundation 4.0 and later.
See also
mxfEmbeddedNVStorageHandleGet()
mxfEmbeddedNVStorageFileStatusGet()
Updated 10/23/2023