Migration Guide from S810-MX-ADL1N (CAN/CAN FD)
This page summarizes implementation differences when migrating from S810-MX-ADL1N (old) to S810-MX-ADL2N (new), focusing on code replacement.
Target protocol is CAN/CAN FD.
Related Links
- Troubleshooting during migration: Common Issues and Solutions
- Migration from an earlier version: Migration from Ver.3.00
- Migration from other products: Migration from SDK2N, Migration from SDK3N
Migration Overview
The following seven points affect implementation when migrating from ADL1N to ADL2N.
- DLL name changes (
MPXCANFDCtrlFree*->MPXCtrlFree*) MPXOpenargument change (Numadded)- CAN API name changes (
MPXSetCANParametc. ->MPXCAN*) - Partial constant name changes (
MPX_MODE_*,CAN_ERR*) MPXGetLogargument type change (StMPXCANLog**->StMPXLog**)- Update type notation for API arguments and structure members used in C/C++ to fixed-width integer types
- Replace callback-function-mode log acquisition with API-mode log acquisition
Preconditions to Confirm First
- Old DLL:
MPXCANFDCtrlFree.DLL/MPXCANFDCtrlFree_x64.DLL - New DLL:
MPXCtrlFree.DLL/MPXCtrlFree_x64.DLL InnerChremains the target channel number (1 or 2)
Type Notation Changes
When implementing in C/C++ using MPXCtrlFree.h, the type notation for ADL2N API arguments and structure members has changed to the following fixed-width integer types.
| Previous notation | ADL2N notation |
|---|---|
char | int8_t |
unsigned char | uint8_t |
unsigned short | uint16_t |
unsigned long | uint32_t |
When MPXCtrlFree.h is included, use the definitions provided by the header file. If API declarations or structure definitions are written independently without using the header file, update them to use the same type notation as MPXCtrlFree.h.
Do not mix old and new type notation in API declarations, callback functions, or structure members, including pointer types.
API Specification Differences (Old -> New)
Fixed-width integer type notation changes for ADL2N API arguments are described in Type Notation Changes and are omitted as specification differences in this section.
Common APIs
Fixed-width integer type changes to argument notation are omitted.
| ADL1N | ADL2N | Compatibility Impact |
|---|---|---|
MPXGetAPIVersion(StMPXAPIVersion*) | Same | No change |
MPXOpen(StMPXDeviceInfo* Devices, unsigned char* Count) | MPXOpen(StMPXDeviceInfo* Devices, uint8_t Num, uint8_t* Count) | Num argument added |
MPXClose() | Same | No change |
MPXSetLED(...) | Same | No change |
MPXGetStatus(...) | Same | No change |
MPXMonitorStart(...) | Same | No change |
MPXMonitorStop(...) | Same | No change |
MPXGetTimeStamp(...) | Same | No change |
MPXSetLogCallBack(...) | Removed | Change to log API mode |
MPXSetGetLogMode(...) | Same | No change in log API mode; change callback mode to log API mode May be omitted |
MPXGetLog(unsigned long, unsigned char, StMPXCANLog**, unsigned short*, unsigned char*) | MPXGetLog(uint32_t, uint8_t, StMPXLog**, uint16_t*, uint8_t*) | 3rd argument type changed |
CAN/CAN FD APIs
| ADL1N | ADL2N | Compatibility Impact |
|---|---|---|
MPXSetCANParam | MPXCANSetParam | API name changed |
MPXGetLogEx | MPXCANGetLogEx | API name changed |
MPXSetSlot | MPXCANSetSlot | API name changed |
MPXChangeSlot | MPXCANChangeSlot | API name changed |
MPXSendSlot | MPXCANSendSlot | API name changed |
MPXDirectSend | MPXCANDirectSend | API name changed |
Constants and Structures Migration Points
Operation Mode Constants (Name Changes)
| ADL1N | ADL2N | Value |
|---|---|---|
MPX_MODE_LISTEN | MPX_CAN_MODE_LISTEN | 0 |
MPX_MODE_MONITOR | MPX_CAN_MODE_MONITOR | 1 |
MPX_MODE_CAN_SIM | MPX_CAN_MODE_SIM | 2 |
MPX_MODE_NONE | MPX_CAN_MODE_NONE | 0xFF |
Values are unchanged, but old constant names are not present in ADL2N headers.
CAN Error Constants (Name Changes)
Error Flags
| ADL1N | ADL2N | Value |
|---|---|---|
CAN_ERRFLG_FALSE | MPX_CAN_ERRFLG_FALSE | 0 |
CAN_ERRFLG_TRUE | MPX_CAN_ERRFLG_TRUE | 1 |
Error Details
| ADL1N | ADL2N | Value |
|---|---|---|
CAN_ERR_NONE | MPX_CAN_ERR_NONE | 0x0000 |
CAN_ERR_BUS | MPX_CAN_ERR_BUS | 0x0001 |
CAN_ERR_WARN | MPX_CAN_ERR_WARN | 0x0002 |
CAN_ERR_PASV | MPX_CAN_ERR_PASV | 0x0004 |
CAN_ERR_BUSOFF | MPX_CAN_ERR_BUSOFF | 0x0008 |
CAN_ERR_BUSWAKE | MPX_CAN_ERR_BUSWAKE | 0x0010 |
CAN_ERR_OVERLOAD | MPX_CAN_ERR_OVERLOAD | 0x0020 |
CAN_ERR_BUSLOCK | MPX_CAN_ERR_BUSLOCK | 0x0040 |
CAN_ERR_ARBLOST | MPX_CAN_ERR_ARBLOST | 0x0080 |
CAN_ERR_STAFF | MPX_CAN_ERR_STAFF | 0x0100 |
CAN_ERR_FORM | MPX_CAN_ERR_FORM | 0x0200 |
CAN_ERR_ACK | MPX_CAN_ERR_ACK | 0x0400 |
CAN_ERR_CRC | MPX_CAN_ERR_CRC | 0x0800 |
CAN_ERR_RECEIVE | MPX_CAN_ERR_RECEIVE | 0x1000 |
CAN_ERR_DOMINANT | MPX_CAN_ERR_DOMINANT | 0x2000 |
CAN_ERR_DELIMITER | MPX_CAN_ERR_DELIMITER | 0x4000 |
Major Constants with No Change
The following definitions are unchanged between ADL1N and ADL2N.
MPX_CAN_PARAM_ABR_*MPX_CAN_PARAM_SP_*MPX_CAN_PARAM_DBR_*MPX_CAN_FRAME_TYPE_*MPX_CAN_SLOT_*MPX_CAN_PROTOCOL_*MPX_CAN_BRS_*MPX_CAN_IDE_*MPX_CAN_RTR_*MPX_CAN_SIM_INC_*
CAN Structure Compatibility
CAN-related structures are compatible between ADL1N and ADL2N (same names and layouts).
StMPXCANParamStMPXCANIDStMPXCANFrameOptionStMPXCANFrameTypeStMPXCANFrameStMPXCANSlotStMPXCANDirectStMPXCANLog
Log Acquisition Flow and Log Structure Changes
ADL2N no longer supports callback-function mode for log acquisition. If the existing application uses callback-function mode, replace it with API mode.
As a result, log acquisition mode is fixed to API mode, and calling MPXSetGetLogMode can be omitted.
MPXGetLog Type Change
MPXGetLog keeps the same function name but return pointer type changed.
- ADL1N:
StMPXCANLog** - ADL2N:
StMPXLog**
When migrating, use one of the following.
- Standardize to
MPXCANGetLogEx(recommended) - Keep using
MPXGetLogand access CAN data viaMisc.CANinStMPXLog
Return Code (ER) Differences
ER codes are the same in ADL1N and ADL2N.
| Constant | Value |
|---|---|
E_OK | 0 |
E_PARAM | 1 |
E_DEVICE | 2 |
E_COMM | 3 |
E_TGT | 4 |
E_TRG_BUSY | 11 |
E_DCT_FULL | 12 |
E_STATUS | 105 |
E_TIMEOUT | 202 |
E_OTHER | 255 |
Implementation Procedure (Replacement Flow)
- Replace DLL references from
MPXCANFDCtrlFree*toMPXCtrlFree* - Update
MPXOpencalls to 3-argument version - Replace CAN API names to
MPXCAN* - Replace
MPX_MODE_*andCAN_ERR*with new constant names - Standardize log acquisition to
MPXCANGetLogEx(or handleMPXGetLogtype change)
Language-Specific Replacement Examples
C/C++ Replacement Example
// ADL1N
StMPXDeviceInfo devs[8] = {};
unsigned char count = 0;
ER er = MPXOpen(devs, &count);
unsigned long serial = (count > 0) ? devs[0].Serial : 0;
er = MPXSetCANParam(serial, innerCh, ¶m);
er = MPXGetLogEx(serial, innerCh, logs, num, &got, &over);
// ADL2N
StMPXDeviceInfo devs[8] = {};
uint8_t count = 0;
ER er = MPXOpen(devs, 8, &count);
uint32_t serial = (count > 0) ? devs[0].Serial : 0;
er = MPXCANSetParam(serial, innerCh, ¶m);
er = MPXCANGetLogEx(serial, innerCh, logs, num, &got, &over);
C/C++ CAN/CAN FD Simulation Replacement Example
// ADL1N
param.Mode = MPX_MODE_CAN_SIM;
MPXSetCANParam(serial, innerCh, ¶m);
MPXSetSlot(serial, innerCh, slots, 2);
MPXMonitorStart(serial, MPX_SYNC_MASTER);
// ADL2N
param.Mode = MPX_CAN_MODE_SIM;
MPXCANSetParam(serial, innerCh, ¶m);
MPXCANSetSlot(serial, innerCh, slots, 2);
MPXMonitorStart(serial, MPX_SYNC_MASTER);
C# (P/Invoke) Replacement Example
// ADL1N
[DllImport("MPXCANFDCtrlFree.dll", EntryPoint = "MPXOpen", CallingConvention = CallingConvention.StdCall)]
public static extern int MPXOpen_Adl1n(
[In, Out] StMPXDeviceInfo[] devices,
ref byte count);
[DllImport("MPXCANFDCtrlFree.dll", EntryPoint = "MPXSetCANParam", CallingConvention = CallingConvention.StdCall)]
public static extern int MPXSetCANParam(uint serial, byte innerCh, ref StMPXCANParam param);
[DllImport("MPXCANFDCtrlFree.dll", EntryPoint = "MPXGetLogEx", CallingConvention = CallingConvention.StdCall)]
public static extern int MPXGetLogEx(uint serial, byte innerCh, [In, Out] StMPXCANLog[] log, ushort num, ref ushort count, ref byte over);
// ADL2N
[DllImport("MPXCtrlFree.dll", CallingConvention = CallingConvention.StdCall)]
public static extern int MPXOpen(
[In, Out] StMPXDeviceInfo[] devices,
byte num,
ref byte count);
[DllImport("MPXCtrlFree.dll", CallingConvention = CallingConvention.StdCall)]
public static extern int MPXCANSetParam(uint serial, byte innerCh, ref StMPXCANParam param);
[DllImport("MPXCtrlFree.dll", CallingConvention = CallingConvention.StdCall)]
public static extern int MPXCANGetLogEx(uint serial, byte innerCh, [In, Out] StMPXCANLog[] log, ushort num, ref ushort count, ref byte over);
C# (P/Invoke) CAN/CAN FD Simulation Replacement Example
// ADL1N
param.Mode = MPX_MODE_CAN_SIM;
er = MPXSetCANParam(serial, innerCh, ref param);
er = MPXSetSlot(serial, innerCh, slots, (byte)slots.Length);
er = MPXMonitorStart(serial, MPX_SYNC_MASTER);
// ADL2N
param.Mode = MPX_CAN_MODE_SIM;
er = MPXCANSetParam(serial, innerCh, ref param);
er = MPXCANSetSlot(serial, innerCh, slots, (byte)slots.Length);
er = MPXMonitorStart(serial, MPX_SYNC_MASTER);
Excel VBA Replacement Example (x64)
' ADL1N
Declare PtrSafe Function MPXOpen Lib "MPXCANFDCtrlFree_x64.DLL" (ByRef Devices As StMPXDeviceInfo, ByRef Count As Byte) As Long
Declare PtrSafe Function MPXSetCANParam Lib "MPXCANFDCtrlFree_x64.DLL" (ByVal Serial As Long, ByVal InnerCh As Byte, ByRef Param As StMPXCANParam) As Long
Declare PtrSafe Function MPXGetLogEx Lib "MPXCANFDCtrlFree_x64.DLL" (ByVal Serial As Long, ByVal InnerCh As Byte, ByRef Log As StMPXCANLog, ByVal Num As Integer, ByRef Count As Integer, ByRef BufferOver As Byte) As Long
Declare PtrSafe Function MPXSetSlot Lib "MPXCANFDCtrlFree_x64.DLL" (ByVal Serial As Long, ByVal InnerCh As Byte, ByRef Slots As StMPXCANSlot, ByVal SlotCount As Byte) As Long
Declare PtrSafe Function MPXChangeSlot Lib "MPXCANFDCtrlFree_x64.DLL" (ByVal Serial As Long, ByVal InnerCh As Byte, ByVal SlotNo As Byte, ByVal SlotEnabled As Byte, ByVal ReqInfo As Byte, ByRef Frame As StMPXCANFrame) As Long
Declare PtrSafe Function MPXSendSlot Lib "MPXCANFDCtrlFree_x64.DLL" (ByVal Serial As Long, ByVal InnerCh As Byte, ByVal SlotNo As Byte) As Long
Declare PtrSafe Function MPXDirectSend Lib "MPXCANFDCtrlFree_x64.DLL" (ByVal Serial As Long, ByVal InnerCh As Byte, ByRef Frame As StMPXCANDirect) As Long
' ADL2N
Declare PtrSafe Function MPXOpen Lib "MPXCtrlFree_x64.DLL" (ByRef Devices As StMPXDeviceInfo, ByVal Num As Byte, ByRef Count As Byte) As Long
Declare PtrSafe Function MPXCANSetParam Lib "MPXCtrlFree_x64.DLL" (ByVal Serial As Long, ByVal InnerCh As Byte, ByRef Param As StMPXCANParam) As Long
Declare PtrSafe Function MPXCANGetLogEx Lib "MPXCtrlFree_x64.DLL" (ByVal Serial As Long, ByVal InnerCh As Byte, ByRef Log As StMPXCANLog, ByVal Num As Integer, ByRef Count As Integer, ByRef BufferOver As Byte) As Long
Declare PtrSafe Function MPXCANSetSlot Lib "MPXCtrlFree_x64.DLL" (ByVal Serial As Long, ByVal InnerCh As Byte, ByRef Slots As StMPXCANSlot, ByVal SlotCount As Byte) As Long
Declare PtrSafe Function MPXCANChangeSlot Lib "MPXCtrlFree_x64.DLL" (ByVal Serial As Long, ByVal InnerCh As Byte, ByVal SlotNo As Byte, ByVal SlotEnabled As Byte, ByVal ReqInfo As Byte, ByRef Frame As StMPXCANFrame) As Long
Declare PtrSafe Function MPXCANSendSlot Lib "MPXCtrlFree_x64.DLL" (ByVal Serial As Long, ByVal InnerCh As Byte, ByVal SlotNo As Byte) As Long
Declare PtrSafe Function MPXCANDirectSend Lib "MPXCtrlFree_x64.DLL" (ByVal Serial As Long, ByVal InnerCh As Byte, ByRef Frame As StMPXCANDirect) As Long
Excel VBA CAN/CAN FD Simulation Replacement Example
' ADL1N
Param.Mode = MPX_MODE_CAN_SIM
Ret = MPXSetCANParam(Serial, InnerCh, Param)
Ret = MPXSetSlot(Serial, InnerCh, Slots(0), 2)
Ret = MPXMonitorStart(Serial, MPX_SYNC_MASTER)
' ADL2N
Param.Mode = MPX_CAN_MODE_SIM
Ret = MPXCANSetParam(Serial, InnerCh, Param)
Ret = MPXCANSetSlot(Serial, InnerCh, Slots(0), 2)
Ret = MPXMonitorStart(Serial, MPX_SYNC_MASTER)
Replacement Guidance for APIs with Large Differences
Notes When Continuing to Use MPXGetLog
In ADL2N, MPXGetLog returns StMPXLog**.
When accessing CAN logs, refer to Misc.CAN.
Standardizing to MPXCANGetLogEx is Recommended
Existing code using MPXGetLogEx can migrate by replacing API name only. Therefore standardizing to MPXCANGetLogEx is the safest approach.
Migration Checklist
- DLL names changed from
MPXCANFDCtrlFree*toMPXCtrlFree* -
MPXOpenupdated to 3-argument version - CAN APIs such as
MPXSetCANParamreplaced withMPXCAN* -
MPX_MODE_*replaced withMPX_CAN_MODE_* -
CAN_ERR*/CAN_ERRFLG_*replaced withMPX_CAN_ERR*/MPX_CAN_ERRFLG_* -
MPXGetLogExreplaced withMPXCANGetLogEx - If using
MPXGetLog, pointer type changed toStMPXLog** - Type notation in C/C++ API declarations, callback functions, structure definitions, and related variables updated to fixed-width integer types
- Log acquisition mode changed from callback-function mode to API mode
- Basic operation of Open/Param/Monitor/Slot/GetLog verified after replacement
Related Pages
- Common API list: /S810-MX-ADL2N/Common/api_list_common
- Common API details: /S810-MX-ADL2N/Common/api_detail_common
- CAN API list: /S810-MX-ADL2N/CAN/api_list_can
- CAN API details: /S810-MX-ADL2N/CAN/api_detail_can
- CAN structure definitions: /S810-MX-ADL2N/CAN/struct_can