6.20. Advanced Features - Bit Rate Detection Feature

The bit rate detection feature determines whether the uplink throughput (bit rate) of the connection meets the minimum requirements of the application.

Operational Overview

  1. When starting the session, specify the minimum bit rate required by the application to operate comfortably and the size of the IP packets to send and receive when measuring the bit rate. Set the IP packet size to the average size of the IP packets that the application sends and receives.
  2. When a new station (C) joins the session, it continuously sends data to an existing participant (S) for several seconds. The data is sent at a rate somewhat faster than the bit rate specified by the application.
  3. Station S receives data from station C for several seconds and calculates the bit rate.
  4. Station S sends the calculated bit rate to station C.
  5. When station C receives the bit rate from station S, the application instance running on station C can get the bit rate of the local station with the GetUplinkBitRate() function.

After Retrieving the Bit Rate

Pia does not prevent a station from joining a session even if the measured bit rate is below the application's requirements. The handling of such stations is up to the application.

Warning:

Consult with Nintendo before restricting the ability of users to join a game based on communication factors such as bit rate.

Coding Sample

The following code sample shows how to use the bit rate detection feature.

Specify whether you will use the bit rate detection feature when instantiating the Session.

Code 6-71. Using the Bit Rate Detection Feature
nn::pia::session::Session::Setting sessionSetting;
sessionSetting.bitRateCheckMode = nn::pia::session::BitRateCheck_Enable; // Using the Bit Rate Detection Feature
   .
   .
   .
nn::pia::session::Session::CreateInstance(setting);

 

You can specify the minimum bit rate required by the application and the IP packet size to use when measuring bit rate when starting up the Session.

When the bit rate detection feature is enabled and you do not want to run bit rate detection without destroying the session instance, you can set the isSkipBitRateCheck member variable to true and skip the bit rate detection processing. When skipping, the bit rate value obtained from GetUplinkBitRate() is not updated, and the value from when bit rate detection was previously run is returned.

Although it is possible to specify the time to perform measurement with the bitRateMeasuringSpan member variable, we recommend that you use the default value. The total required amount of time will be inflated if the time period is set to a value greater than what it takes for the session join process to be completed.

Code 6-72. Setting the Minimum Bit Rate Required by the Application and the IP Packet Size
nn::pia::session::Session::StartupSetting startupSetting;
startupSetting.uplinkBitRateLowerLimit = 200 * 1000; // Bit rate required by the application. In bits per second.
startupSetting.bitRateCheckPacketSize = 1024; // Size of the IP packets to send when measuring the bit rate. The value is in bytes.
startupSetting.isSkipBitRateCheck = false; // Whether to skip the bit rate detection process.
startupSetting.bitRateMeasuringSpan = 1000; // Time to spend measuring the bit rate. The units are in milliseconds.
    .
    .
    .
nn::pia::session::Session::GetInstance()->Startup(startupSetting);

 

After bit rate measurement processing is complete and Session::IsCompleteBitRateCheck() now returns true, call Session::GetUplinkBitRate(). The retrieved bit rate is in bits per second.

A negative value is set if no value could be measured because, for example, the other station did not respond.

Code 6-73. Getting the Bit Rate
nn::pia::session::Session* pSession = nn::pia::session::Session::GetInstance();
if(PIA_IS_VALID_POINTER(pSession))
{
    if (pSession->IsCompleteBitRateCheck())
    {
        s32 bitRate = 0;
        nn::Result r = pSession->GetUplinkBitRate(&bitRate);
        if (r.IsSuccess())
        {
            PIA_BASIC_REPORT("bitRate: %d\n", bitRate); // Prints a negative value if the measured value could not be obtained.
        }
    }
}

Note

  • When this feature is used, joining a session takes several seconds longer and Pia requires a few kilobytes of additional memory.
  • If there is a lot of communication between existing stations when a new station joins the session, the accuracy of the measurement could drop.
  • The bit rate retrieved with the GetUplinkBitRate() function does not necessarily represent the actual capability of the connection. The amount of data sent and received during the measurement is only slightly above the minimum level required by the application. Consequently, if the application specifies a low minimum bit rate, a low bit rate is returned even for a fast connection.
  • If a bottleneck whose bit rate is less than that of the source station's uplink exists along the measurement packet's route between the source station and the destination station, GetUplinkBitRate() may return an underestimated value.