API Details (Common)
This page describes details of common APIs available in this product.
Read This First
- If you need task-based call order first: Common API by Task
- If you need common constants: Constant Definitions (Common)
- If you need common structures: Structure Definitions (Common)
- If you need CAN/LIN implementation mappings: CAN API Mapping, LIN API Mapping
API Quick Reference (Constants / Structures / Preconditions / Minimal Examples)
| API | Constants used by this API | Structures used by this API | Callable precondition status | Minimal code examples (C++/C#/VBA) |
|---|---|---|---|---|
| MPXGetAPIVersion | API Return Values | StMPXAPIVersion | Not recognized / Recognized | Common First |
| MPXOpen | API Return Values | StMPXDeviceInfo | Not recognized | Common First |
| MPXClose | API Return Values | - | Recognized | Common First |
| MPXSetLED | LED Settings | - | RUN/PARAM | Common First |
| MPXGetStatus | MicroPeckerX Status | - | Recognized | Common First |
| MPXMonitorStart | Sync Mode, MicroPeckerX Status | - | PARAM | Common First |
| MPXMonitorStop | API Return Values | - | SYNC/NONE/MON/SIM | Common First |
| MPXGetTimeStamp | API Return Values | - | NONE/MON/SIM | Common First |
| MPXSetGetLogMode | Log Acquisition Mode | - | RUN/PARAM | CAN C# Sample, LIN VBA Sample |
| MPXGetLog | Buffer Overrun Presence | StMPXLog | NONE/MON/SIM | CAN C++ Sample, LIN C++ Sample |
Notation
On this page, each API is described in the following format.
| Format | [Function type] [Function name]([argument], ...) | |||
|---|---|---|---|---|
| Argument | [Argument type] | [Argument name] | [in/out] | [Argument description] |
| Return value | [Return type] | [Return value (error code)] | [Description of return value (error code)] | |
| Function | [Function behavior] | |||
| Note | [Supplementary information] | |||
If an argument type is a structure, refer to Structure Definitions (struct) for values to set or values that are set.
For [in/out], in means set by caller before invocation, and out means set by the function during processing.
API Details
MPXGetAPIVersion
Gets version information of this API.
| Format | ER MPXGetAPIVersion(StMPXAPIVersion * Version) | |||
|---|---|---|---|---|
| Argument | StMPXAPIVersion * | Version | out | API version information |
| Return value | ER | E_OK | Success | |
| E_PARAM | Parameter error (for example, NULL pointer) | |||
| Function | Gets version information of this API. | |||
MPXOpen
Detects connected MicroPeckerX device(s).
| Format | ER MPXOpen(StMPXDeviceInfo * Devices, uint8_t Num, uint8_t * Count) | |||
|---|---|---|---|---|
| Argument | StMPXDeviceInfo * | Devices | in/out | Device information structure array |
| uint8_t | Num | in | Number of elements in device information structure array | |
| uint8_t * | Count | out | Number of detected MicroPeckerX devices | |
| Return value | ER | E_OK | Success | |
| E_DEVICE | Device not found | |||
| E_COMM | Communication error | |||
| E_TIMEOUT | Communication timeout | |||
| Function | Detects MicroPeckerX devices connected to the PC. Set Devices to a structure array for storing detected device information, and set Num to the array length.Number of acquired device entries is returned in Count. | |||
| Note | If multiple MicroPeckerX devices are connected, up to Num devices (maximum 4) can be detected at the same time. However, you cannot arbitrarily choose which specific devices are detected. | |||
MPXClose
Releases detection of MicroPeckerX device(s).
| Format | ER MPXClose(void) | |||
|---|---|---|---|---|
| Return value | ER | E_OK | Success | |
| Function | Releases all currently detected MicroPeckerX devices. | |||
MPXSetLED
Controls LEDs on MicroPeckerX.
| Format | ER MPXSetLED(uint32_t Serial, uint8_t LEDRed, uint8_t LEDGreen, uint8_t LEDGreenBlink, uint8_t LEDYellow, uint8_t LEDYellowBlink) | |||
|---|---|---|---|---|
| Argument | uint32_t | Serial | in | Serial number of target MicroPeckerX device |
| uint8_t | LEDRed | in | Red LED on/off (see LED Settings) | |
| uint8_t | LEDGreen | in | Green LED on/off (see LED Settings) | |
| uint8_t | LEDGreenBlink | in | Green LED blinking on/off (see LED Settings) | |
| uint8_t | LEDYellow | in | Yellow LED on/off (see LED Settings) | |
| uint8_t | LEDYellowBlink | in | Yellow LED blinking on/off (see LED Settings) | |
| Return value | ER | E_OK | Success | |
| E_PARAM | Parameter error | |||
| E_DEVICE | Device not found | |||
| E_COMM | Communication error | |||
| E_TIMEOUT | Communication timeout | |||
| Function | Controls LEDs of the device specified by Serial.Red LED turns on with MPX_LED_ON and off with MPX_LED_OFF.Green LED turns on with MPX_LED_ON and off with MPX_LED_OFF. If LEDGreenBlink is MPX_LED_ON, it blinks regardless of LEDGreen.Yellow LED turns on with MPX_LED_ON and off with MPX_LED_OFF. If LEDYellowBlink is MPX_LED_ON, it blinks regardless of LEDYellow. | |||
MPXGetStatus
Gets status of MicroPeckerX device.
| Format | ER MPXGetStatus(uint32_t Serial, uint16_t * StatusCh1, uint16_t * StatusCh2) | |||
|---|---|---|---|---|
| Argument | uint32_t | Serial | in | Serial number of target MicroPeckerX device |
| uint16_t * | StatusCh1 | out | Status of CH1 (see MicroPeckerX Status) | |
| uint16_t * | StatusCh2 | out | Status of CH2 (see MicroPeckerX Status) | |
| Return value | ER | E_OK | Success | |
| E_PARAM | Parameter error | |||
| E_DEVICE | Device not found | |||
| E_COMM | Communication error | |||
| E_TIMEOUT | Communication timeout | |||
| Function | Gets status of each channel for the device specified by Serial. | |||
MPXMonitorStart
Starts monitoring.
| Format | ER MPXMonitorStart(uint32_t Serial, uint8_t SyncMode) | |||
|---|---|---|---|---|
| Argument | uint32_t | Serial | in | Serial number of target MicroPeckerX device |
| uint8_t | SyncMode | in | Sync mode (see Sync Mode) | |
| Return value | ER | E_OK | Success | |
| E_PARAM | Parameter error | |||
| E_DEVICE | Device not found | |||
| E_COMM | Communication error | |||
| E_STATUS | Status error | |||
| E_TIMEOUT | Communication timeout | |||
| Function | Starts monitoring on the device specified by Serial.MPX_SYNC_MASTER runs in master mode, and MPX_SYNC_SLAVE runs in slave mode.For CAN communication, if slot information has been set by MPXCANSetSlot, frame transmission also starts for slots whose frame type is MPX_CAN_FRAME_TYPE_PERIODIC or MPX_CAN_FRAME_TYPE_EVENTPERIODIC.For LIN communication, if master simulation has been set by MPXLINSetMasterSim, frame transmission also starts using the schedule selected by MPXLINChangeMasterSchedule. | |||
| Note | Before calling this API, you must set communication parameters by calling MPXCANSetParam or MPXLINSetParam. When operating multiple devices, start monitoring on all slave-mode devices first, then start monitoring on master-mode devices. | |||
MPXMonitorStop
Stops monitoring.
| Format | ER MPXMonitorStop(uint32_t Serial, uint32_t * mSec, uint16_t * uSec) | |||
|---|---|---|---|---|
| Argument | uint32_t | Serial | in | Serial number of target MicroPeckerX device |
| uint32_t * | mSec | out | Timestamp (milliseconds) | |
| uint16_t * | uSec | out | Timestamp (microseconds) | |
| Return value | ER | E_OK | Success | |
| E_PARAM | Parameter error | |||
| E_DEVICE | Device not found | |||
| E_COMM | Communication error | |||
| E_STATUS | Status error | |||
| E_TIMEOUT | Communication timeout | |||
| Function | Stops monitoring on the device specified by Serial and gets timestamp at that point.Timestamp values in mSec and uSec indicate that logs received up to that point are guaranteed. | |||
| Note | When operating multiple devices, stop monitoring on master-mode devices first, then stop monitoring on slave-mode devices in sequence. | |||
MPXGetTimeStamp
Gets timestamp.
| Format | ER MPXGetTimeStamp(uint32_t Serial, uint32_t * mSec, uint16_t * uSec) | |||
|---|---|---|---|---|
| Argument | uint32_t | Serial | in | Serial number of target MicroPeckerX device |
| uint32_t * | mSec | out | Timestamp (milliseconds) | |
| uint16_t * | uSec | out | Timestamp (microseconds) | |
| Return value | ER | E_OK | Success | |
| E_PARAM | Parameter error | |||
| E_DEVICE | Device not found | |||
| E_COMM | Communication error | |||
| E_STATUS | Status error | |||
| E_TIMEOUT | Communication timeout | |||
| Function | Gets current timestamp of the device specified by Serial.Acquired timestamp is set to mSec and uSec. | |||
| Note | Timestamp values set to mSec and uSec may have time lag from actual function call timing. | |||
MPXSetGetLogMode
Sets how to acquire monitoring log data (TX/RX data).
| Format | ER MPXSetGetLogMode(uint32_t Serial, uint8_t InnerCh, uint8_t Mode) | |||
|---|---|---|---|---|
| Argument | uint32_t | Serial | in | Serial number of target MicroPeckerX device |
| uint8_t | InnerCh | in | Target CH number (1 or 2) | |
| uint8_t | Mode | in | Log acquisition mode (see Log Acquisition Mode) | |
| Return value | ER | E_OK | Success | |
| E_PARAM | Parameter error | |||
| E_DEVICE | Device not found | |||
| Function | Sets log receiving method from the channel specified by Serial and InnerCh.Only MPX_GETLOG_GETLOGAPI (log acquisition API mode) can be specified for Mode, so this API call may be omitted. | |||
| Note | In log acquisition API mode, you must periodically call one of MPXGetLog, MPXCANGetLogEx, or MPXLINGetLogEx. | |||
MPXGetLog
Gets monitoring log data (TX/RX data) from log structure buffer allocated inside DLL.
| Format | ER MPXGetLog(uint32_t Serial, uint8_t InnerCh, StMPXLog ** Log, uint16_t * Count, uint8_t * BufferOver) | |||
|---|---|---|---|---|
| Argument | uint32_t | Serial | in | Serial number of target MicroPeckerX device |
| uint8_t | InnerCh | in | Target CH number (1 or 2) | |
| StMPXLog ** | Log | out | Pointer to log structure array | |
| uint16_t * | Count | out | Number of acquired logs | |
| uint8_t * | BufferOver | out | Buffer overrun (see Buffer Overrun Presence) | |
| Return value | ER | E_OK | Success | |
| E_PARAM | Parameter error | |||
| E_DEVICE | Device not found | |||
| Function | Gets logs from channel specified by Serial and InnerCh.Pointer to start of internal DLL log buffer is set to Log, and number of logs is set to Count.If buffer overrun occurs, BufferOver is set to MPX_LOG_BUFOVER_TRUE. | |||
| Note | No caller-side log structure array preparation is required for this API. | |||