MP API Introduction

Introduction

The MP API is a library used to implement DS Wireless Play and DS Download Play with the Nintendo DS system. Communication among Nintendo DS systems is implemented using a unique protocol known as MP communications. This library enables MP communication on the Wii.

For more on MP communications, see the Wireless Communications Library Description in the Nintendo DS developer's kit, NITRO-SDK.

Differences with the NITRO-SDK Communications Library

Due to hardware and software limitations, the following differences with the NITRO-SDK WM library exists.

• Parent only.
  Wii can only be a parent in MP communications.
• Changes to initialization and ending functions.
  Combined the initialization functions WM_Initialize, WM_StartParent, and WM_StartMP into the MPStartup function.
  Similarly, the ending functions were brought together as MPCleanup.
• Port settings can be changed only before communication begins.
  To set the callbacks for each port, you need to call and complete the MPSetPortConfig function before calling the MPStartup function.
  Changes to callback settings cannot occur during communication.
• In addition, communication parameters can also be changed only before communication begins.
  The MP parameters, including the parent and child device's send capacities, the MP communication frequency, and so on, must be specified in advance in the MPConfig structure, an argument to the MPStartup function.
• Priorities are now parameters for each port.
  The WM library allows you to specify priorities for each piece of send data. However, in the MP library priorities are set at the port level.
  These are specified in the MPSetPortConfig function.
• A synchronous version of the send function is available.
  Although the WM library had only an asynchronous version of the send function, the MP library has both a synchronous version, MPSend(), and an asynchronous version, MPSendAsync().
  The MPSend function does not return until an attempt is made to send the specified data. An AID bit row in the *restBits argument stores whether the send succeeded.
• The beacon's data settings function has been changed.
  The beacon's UserGameInfo is not updated by directly creating the GameInfo structure as before, but new data is set with the MPSetUserInfo function. That update is sent and reflected in the beacon by the MPUpdateBeacon function.
• The beacon's send notification has been eliminated.
  In its place, the synchronous MPUpdateBeacon function is returned from the function when the first beacon is sent after being called. The asynchronous MPUpdateBeaconAsync function similarly calls a callback when the first beacon is sent after being called.
• The method for getting the link level has changed.
  To get the child device's link level, call the specialized function MPGetLinkLevel().
• The same disconnect notification is issued whether you disconnect yourself or the child device disconnects you.
  While WM library divides notifications by type, the same notification is issued in both cases with the MP library. The cause of disconnection can be determined by passing the reason value to the function macro MP_IS_DISCONNECTED_FROM_MYSELF.
• The number of available channels may be lower.
  In some countries the Wii may be able to use only channels 1 through 11, whereas the Nintendo DS can use channels 1 through 13.
  In that case, MP communication on the Wii can use only channels 1 and 7.
• Asynchronous functions take the MPCallbackInfo structure as an argument.
  The MPCallbackInfo structure must be passed as an argument when calling an asynchronous function so there is a work region for asynchronous processes.
• There is no way to determine the usage status of a wireless channel.
  There is no function corresponding to WM_MeasureChannel(). Instead, the appropriate channel is automatically selected by specifying MP_CHANNEL_AUTO for MPConfig.channel.
• There is no way to find a permitted channel.
  When a specified channel cannot be used, the MPStartup function fails with MP_RESULT_NOT_ALLOWED. Assign MP_CHANNEL_AUTO to MPConfig.channel so that the library selects the appropriate channel in normal applications.
• Threads are created internally.
  Four threads are created internally for the processing of MP communication.
  Use MPConfig.threadPriority to specify the highest priority for this created group of threads. The threads can have one of four levels of priority, ranging from threadPriority to threadPriority+3. To enable MP communications to proceed in real time, specify a priority that is higher than the priority of the main thread.
• Callbacks are called with interrupts enabled.
  The callbacks for asynchronous functions labeled with Async and for the Receive callbacks set by MPSetPortConfig() are called with interrupts enabled from the thread for callbacks created by the MP library. Note that you should not issue the call to the next callback until the processing has completed for the current callback.
  Further note that some internal processes of MP communications wait for related callbacks to completely end. For the sake of stable MP communications, do not perform processes that take several milliseconds of time during a callback.
• Wii does not perform V-Blank synchronization with a child DS.
  Because the parent Wii cannot change the V-Blank period, the MP communications timing is controlled independently of the parent's V-Blank cycle.
  V-Blank synchronization between child DS systems connected to a parent Wii will occur without a problem.
  Please be particularly aware that the Wii V-Blank and MP communications cycles will be completely different in PAL's 50Hz cycle. The MP communications timing will be off little by little even when the V-Blank cycle is 60Hz.
• If using sequential communications, we recommend connecting only eight children at the most.
  If you are using sequential communications on ports 12 through 15, we recommend restricting the number of children that connect to the Wii to eight. When more than eight children are connected, there is no guarantee with sequential communications that data sent 'successfully' has actually arrived.
• Data Sharing functionality is provided by the MPDS library.
  The library that carries out Data Sharing is the MPDS library, which is separate from the MP library.
  Unlike WM_StepDataSharing from the NITRO-SDK, the MPDSStep function for sharing data is provided as a synchronous function so data can be shared even when the V-Blank period of the Wii differs from that of the DS. The separately provided MPDSTryStep function can perform processing in the conventional way.
• It may not be possible to use notifications from a child device to a parent device if the former used an SSID at connection time.
  When using firmware with a version of 35 or earlier, the parent device cannot get the value that is set for the ssid argument of the child device's WM_StartConnect() function. MPPortCallbackInfo_Connected.ssidUserData is always zeroed out. This restriction has been fixed in versions 36 and later.
• Unique modes do not exist that allow any PollBitmap operation.
  There are no modes corresponding to minPollBmpMode in the WM library.
• There is no special mode for sending just one packet.
  There is no mode for sending just one packet in a single MP sequence, such as when singlePacketMode is specified in the WM library.
• WEP keys cannot be used.
  Although the WM library allows WEP key authentication at connection time only, this is not supported.

Revision History

2007/11/28 Made corrections in notation.
2007/11/21 Revised text specific to SSID notifications.
2007/10/26 Made changes in line with implementation of the MPDS library.
2007/09/26 Made changes in line with implementation of MP library features.
2007/07/25 Added an explanation of the problem that relates to SSID notifications from child devices at connection time.
2007/01/29 Revised text specific to sequential communications.
2007/01/29 Indicated the lack of V-Blank synchronization among the Wii and the DS devices.
2006/07/19 Eliminated restrictions related to V-Blank synchronization.
2006/06/29 Initial version.

CONFIDENTIAL