Rumble Pak

What is the Rumble Pak?
The Rumble Pak is a peripheral device that, when connected to the Controller , can send vibrations to the game player. This chapter provides a description of the Rumble Pak.

The Rumble Pak offers only two levels of control: motor on and motor off. Three types of processing are necessary to control the Rumble Pak motor: “Rumble Pak Initialization,” “Start Rumble Pak,” and “Stop Rumble Pak.” These three Rumble Pak functions are described in this chapter.

Basic Use of the Rumble Pak

Make Initial Settings to Use the SI Device
The first thing you need to do is make the initial settings to use the SI device, then check whether a pak-type SI device is connected to the Controller. To do this, call the osContInit function to perform the initial settings, then call the osContStartQuery, and osContGetQuery functions to check for a pak-type device.

Initialize the Rumble Pak
When the Controller is confirmed to be properly connected, the Rumble Pak inserted into that Controller must be initialized. The function for initializing the Rumble Pak is osMotorInit. At this time, the function’s return value must be checked to determine whether the Rumble Pak is properly inserted. When the error code is 0, the Rumble Pak is properly inserted. When the error code is PFS_ERR_NOPACK, nothing is inserted into the Controller. When it is PFS_ERR_DEVICE, a device other than the Rumble Pak is inserted into the Controller. The return of another error code indicates that the Controller or Rumble Pak connection is bad or, in the absence of such a problem, that the Controller or Rumble Pak is damaged.

Starting and Stopping the Rumble Pak Motor
To start the Rumble Pak motor, the function osMotorStart is called. If the return value is 0, the motor was successfully started, and there are no problems. If the return value is not 0, the motor cannot be started for reasons such as an error in communication with PIF. In this case, please issue the call osMotorStart, again.

To stop a running Rumble Pak , call the function osMotorStop. The return values for this function are the same as those for osMotorStart.

The Sample Program
A sample program for checking the operation of the Rumble Pak is available in /usr/src/PR/demos/motortest. This program is operated as follows:

- Press the A Button of the Controller to turn the motor ON.

- To turn the motor OFF press the B Button of the Controller.

- With the Z Button depressed, the strength of the vibration changes in response to the degree that the Control Stick is pushed, in any direction.

Note: There is no support for removal and insertion of the Rumble Pak during operation. Once the Rumble Pak is removed, the motor will not start again if the pak is reinserted and the A button is pressed, and the error message will not be displayed.

Rumble Pak Function Specifications
Following is an explanation of the library functions used to handle the Rumble Pak in an N64 program. These functions include:

- osMotorInit
  Initializing the Rumble Pak

- osMotorStart
  Starting the Rumble Pak

- osMotorStop
  Stopping the Rumble Pak

Function Name - osMotorInit

Syntax

    #include <ultra64.h>
    s32 osMotorInit(OSMesgQueue *siMessageQ, OSPfs *pfs, int channel);

The osMotorInit function initializes the Rumble Pak motor. When the Rumble Pak is used, this must be the first function called. However, because of synchronous initialization at a low level of the OS, you must call osContInit before calling this function (osMotorInit).

If an error occurs, the error codes returned by this function are:

PFS_ERR_NOPACK
Nothing is inserted in the specified Controller.

PFS_ERR_DEVICE
A device other than the Rumble Pak has been inserted into the Controller.

PFS_ERR_CONTRFAIL
A failure in the transmission of data to the Controller is indicated. Either the Controller is improperly connected, or the Rumble Pak or Controller connector is damaged.

Function Name - osMotorStart, osMotorStop

Syntax

    #include <ultra64.h>
    s32 osMotorStart(OSPfs *pfs);

    s32 osMotorStop(OSPfs *pfs);

The osMotorStart and osMotorStop functions start and stop the Rumble Pak.

The osMotorStart function starts the Rumble Pak motor. Its argument is the OSPfs structure pointed to by pfs. Internally, it simply sends data to the Rumble Pak. For increased processing speed, it does not perform processes such as Rumble Pak status checking. Consequently, when the Rumble Pak is removed and reinserted, the motor cannot be operated without again calling osMotorInit. Of course, osMotorStart also uses the serial interface (SI) and performs message waiting internally, which you should consider when calling it.

If the error code PFS_ERR_CONTRFAIL is returned, communication has failed, and the motor cannot be operated. Although the chance of a transmission error is small, this error code must be checked to confirm whether the motor is actually operating.

The osMotorStop function stops the motor. Its argument is the OSPfs structure pointed to by pfs. Internally, it performs the same processing as osMotorStart.

Notes Regarding the Rumble Pak Functions
To produce a suitable vibration strength, the application program must repeatedly turn the Rumble Pak ON and OFF in appropriate cycles. For a specific example, please refer to the sample program provided in the Nintendo 64 Software Library.

If the Rumble Pak is removed and re-inserted by the user during a game, osMotorInit must be called again, before the Rumble Pak motor can be started. However, frequent calls to osMotorInit may cause a decline in the performance of the Rumble Pak. Therefore, to encourage caution on the part of the user, please include a note in the Instruction Booklet or display a warning on the screen such as: "Please do not remove the Rumble Pak during a game."

If data from the Controller is not being read properly, determine if the Rumble Pak function is called between osContStartReadData and osContGetReadData. When another thread is accessing SI, calls to Rumble Pak functions can result in strange behavior. If Rumble Pak functions are used with Controller read, some type of exclusion processing is required.

Copyright © 1999 Nintendo of America Inc. All Rights Reserved Nintendo and N64 are registered trademarks of Nintendo Last Updated January, 1999