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."
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.
Once it is confirmed that the Controller is 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.
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.
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.
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 Rumble Pak is reinserted and the A button is pressed, and the error message will not be displayed.
Following is an explanation of the library functions used to handle the Rumble Pak in an N64 program. These functions include:
Function
osMotorInit
Initializing the Rumble Pak
Syntax
#include <ultra64.h> s32 osMotorInit(OSMesgQueue *mq, OSPfs *pfs, int controller_no);
Description
The osMotorInit function initializes the Rumble Pak motor. After initializing overall SI devices with the osContInit function, please initialize the Rumble Pak using the osMotorInit function. If SI devices are used, call the osContInit function once at the beginning before calling the osMotorInit function because SI requires its own initialization to be used.
The controller_no specifies the controller port number(0~3). This function is for the Rumble Pak which is inserted into the controller port specified by the controller_no.
To control the Rumble Pak, use pfs, the OSPfs structure. The osMotorInit function initializes this pfs. The message queue, mq is initialized relating to OS_EVENT_SI. See osSetEventMesg() in the N64 Function Reference Manual regarding usage. Because mq is used for waiting for a message within the function, there is no need to wait for a message using mq in an application after exiting the function.
The return value is an error code. If the function ends normally, the return value is 0. 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
osMotorStart, osMotorStop
Starting/Stopping the Rumble Pak
Syntax
#include <ultra64.h> s32 osMotorStart(OSPfs *pfs); s32 osMotorStop(OSPfs *pfs);
Description
The osMotorStart function start the Rumble Pak. Its argument is the OSPfs structure pointed to by pfs. Please use the pfs structure which is already initialized by the osMotorInit function. By calling this function, the motor operates.
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. *13
The return value is an error code. If the function ends normally, the return value is 0. 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. By calling this function the motor stops. Internally, it sends the command data to stop the motor.
*13 See Q3 in Section 26.4.5 "Notes Regarding the Rumble Pak Functions (Q&A Format)".
Q1) I'd like to change the vibration strength.
A1) Keeping the motor continuously running or turning it off are the only two ways to control the motor. Due to this reason, 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.
Q2) The Rumble Pak does not work properly when it is removed and re-inserted during a game.
A2) 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."
Q3) Data from the Controller is not being read properly.
A3) Is the Rumble Pak function 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.