## Table of Contents

1. [The Project](#the-project)
2. [The Serial Protocol](#the-serial-protocol)
   1. [Definitions](#definitions)
   2. [Diagrams](#diagrams)
   3. [Pseudocode](#pseudocode)
3. [The Gameboy Printer](#the-gameboy-printer)
4. [Important Notes](#important-notes)

<iframe width="536" height="301" src="https://www.youtube.com/embed/EhVYzfLQQ70" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>

<a href="https://www.patreon.com/bePatron?u=34519148" data-patreon-widget-type="become-patron-button">Become a Patron!</a><script async src="https://c6.patreon.com/becomePatronButton.bundle.js"></script>

## The Project

The objective is to document the Gameboy Printer, it's protocol, and the image format in a single source, and use that information to create a printer driver using a Raspberry Pi Pico.

I originally did this project on the Arduino back in 2014 using a project that was already available, but I'm writing all of this from the ground up to better document, integrate into other Gameboy related projects, and of course bring the Gameboy Printer to the Pi family. The project I originally used was [davedarko/GBPrinter](https://github.com/davedarko/GBPrinter) that generated PHP page to handle generating some of the code, but more recently I found that someone forked that project to bring us the improved [octavifs/GBPrinter](https://github.com/octavifs/GBPrinter) that uses Go for generating images.

The Raspberry Pi company have now released a $4 ARM microcontroller, and I wanted this to be as cheap as possible for other people to try.

## The Serial Protocol

The Gameboy Original/Color/Advance, and by extension the Gameboy Printer, use an SPI-esque protocol to talk to each other. SPI is avery simple synchronous protocol, involving only a TX (outbound data), RX (inbound data), CLK (clock), and the CS (chip select) which the gameboy does not use. The Gameboy excludes the CS pin as it only expects to have a single master device and a single slave device.

### Definitions

- Master
  - The primary device that manages the interaction
- Slave
  - The device being controlled by the master
- CLK
  - Clock
  - A signal that goes `HIGH` then `LOW` to let the slave know that the next piece of data is coming
- TX
  - Digital signal out from the master or slave device. Connects to the other device's RX.
- RX
  - Digital signal in to the master or slave device. Connects to the other device's TX.
- CS
  - Chip Select (unused)
- GND
  - Ground

### Diagrams

Below is the Gameboy Color Cable pinout.

```text
    _________   1 -> 5v*
   / 1  2  3 \  2 -> RX
  /           \ 3 -> CLK
  |           | 4 -> TX
  |  4  5  6  | 5 -> Reserved*
  +-----------+ 6 -> GND

* means we do not need that pin
```

It is important to test these pins with a voltmeter because the inner cable colors are rarely correctly colored on 3rd party cables, and sources that rely on color coded wires may cause damage to your microcontroller. When you use a voltmeter to identify the TX and RX pins, remember that the TX from one end is the RX for the other and vice versa. Below will hopefully clarify what I am saying:

```text
  Master        Slave
  | TX ___   ___ TX |
  |        \/       |
  |        /\       |
  | RX ---   --- RX |
```

Each clock cycle (HIGH/LOW or 1/0) only one bit of data is transferred. Data is sent and read on the rising edge of the clock; rising edge meaning the short ±1 microsecond when the clock goes from LOW to HIGH. The following is an ASCII diagram from the oscilloscope where the number `162` (`0xA2` in hex or `10100010` in binary). The Gameboy has a clock speed of 8192 bits per second (8kb/s), which is 1KB/s or 1 bit every ~122μs.

Both the master and slave can send and receive data at the same time. Once 8 bits have been sent/received they are processed as a byte.

```
Clock: ^ denotes rising edge, * denotes falling edge
TX: sending `10100010` in binary (`0xA2` in hex)
RX: receiving `0b11001100` in binary (`0xCC` in hex)

                       ┏━━━━━━━━┓
    ┏━━━━━━━━━━━━━━━━━━┛ 1 byte ┗━━━━━━━━━━━━━━━━━━┓
       __    __    __    __    __    __    __    __
CLK __/  \__/  \__/  \__/  \__/  \__/  \__/  \__/  \
      ^  *  ^  *  ^  *  ^  *  ^  *  ^  *  ^  *  ^  *
       __          __                      __
TX  __/  \________/  \____________________/  \______
      1     0     1     0     0     0     1     0
       __    __                __    __
RX  __/  \__/  \______________/  \__/  \____________
      1     1     0     0     1     1     0     0
```

### Pseudocode

Generally, the master would look like this pseudocode where it drives the clock:

```
byte data_to_send = 0xA2;
byte data_receiving = 0x00;

// Used for bit-shifting data
int data_bit_position = 0;

// 1 is HIGH, 0 is LOW
state clock_state = 1;

int clock_speed = 8192;

while (data_bit_position < 8) {
  // Flip the state to what we're about to process
  clock_state = clock_state == 1 ? 0 : 1;
  // Send the clock state to the Gameboy Printer cable
  set_clock(clock_state);

  // Send data on rising edge
  if (clock_state == 1) {
    // Send data
    state bit_to_send = (data_to_send >> data_bit_position) & 0b00000001; // Results in  1 or 0
    set_tx(bit_to_send);

    // Receive Data
    data_receiving = (get_rx() << data_bit_position) | data_receiving;

    // Set the position for the next bit
    if (++data_bit_position == 8) {
      // Reset to read and send the next byte
      data_bit_position = 0;
      data_receiving = 0x00;
    }
  }

  // 1,000,000μs in a second
  // Wait 1,000,000/clock_speed in microseconds to match the clock speed
  // Divide it by 2 so that the rising edge and falling edge take place within one cycle period
  sleep_us(1000000 / clock_speed / 2);
}
```

And generally, the slave would look like this pseudocode where it waits for a state change from the clock:

```
byte data_to_send = 0xA2;
byte data_receiving = 0x00;

// Used for bit-shifting data
int data_bit_position = 0;

state last_clock_state = 1;

while (data_bit_position < 8) {
  state current_clock_state = get_clock();

  // Send data on rising edge
  if (current_clock_state == 1 && current_clock_state !== last_clock_state) {
    last_clock_state = current_clock_state;

    // Send data
    state bit_to_send = (data_to_send >> data_bit_position) & 0b00000001; // Results in  1 or 0
    set_tx(bit_to_send);

    // Receive Data
    data_receiving = (get_rx() << data_bit_position) | data_receiving;

    // Set the position for the next bit
    if (++data_bit_position == 8) {
      // Reset to read and send the next byte
      data_bit_position = 0;
      data_receiving = 0x00;
    }
  }
}
```

That pseudocode should give you an idea about what we're working with here.

### The Gameboy Printer

Here's the thing, this is where it gets complicated. I'll try to break it down.

#### Master to Slave

Master TX to Slave RX is described below

##### Magic Bytes (2)

This is the simplest part of the protocol. It never changes. The first byte the master sends is always `0x88` and the second byte is always `0x33`. All this does is tell the printer we are here and that we are about to send something it needs to listen to. That's all!

##### Command Byte (1)

This tells the printer what we want to do.

### Important Notes

#### Voltage Warnings

The Pico is not 5v tolerant and can only send and receive 3.3v. **_Do not hook the Pico directly to the Gameboy Printer._** There is a risk that a 5v signal to the Pico's serial pins will release [the magic smoke](https://en.wikipedia.org/wiki/Magic_smoke). The pi doesn't have any big capacitors so no smoke will be seen, but I think it is a lot scarier when it just silently dies and you don't know why.

The Gameboy Printer can only send and receive 5v, and won't read data from the 3.3v Pico as it doesn't seem to reach the minimum `HIGH` threshold the GBP is trying to read. This doesn't damage anything, but it's a major bummer.

You will need a 3.3v to 5v logic level shifter to safely transmit and receive data, which will avoid both of these issues.

Gameboy Printer with a RP2040 (Pi Pico) Microcontroller

This article is a work in progress and will be revised several times. This is a loose series of words and code blocks to put my thoughts into words to help myself better understand the work I am doing. Please note that Metal is a c++-**_like_** language and is missing many core features of C++11 such as `new` & `delete` operators, `memalloc`, `memset`, `free`, inheritance/derived classes, the foundational `stdlib` (though it comes with it's own stripped down `metal_stdlib` with apple branded alternatives such as `vec<T, n>` instead of `std::vector<T>`), etc.

This is meant to be a reference article for non-scientific projects. This article has been heavily simplified for performance and "close enough" approximations.

## Interpolation

If you're here reading this, you probably know that _interpolation_ is used when you have a series of data, either through time or space, and you want to estimate the data between your data points. If X₀=0, Y₀=0 and X₂=2, Y₂=4, then X₁=1 means Y₁ probably equals 2. We can guess this because we can see the 2 values make up a line similar to Y=2X, or maybe it's Y=X^2. Who's to say? What's important is using the data we have around us to best-guess this.

## Problem & Requirements before Interpolation

Map Distortion and Scaling were unique to our project, however they may interest you in similar projects. These are not required for interpolation at all. These are for if you were planning on putting a view with an X/Y coordinate system on a map and these problems weren't handled for you.

### Map Distortion

Our data was given to us in a 2D space with an XY coordinate system, however it was not processed for distortion. To do that, I found these scary looking equations:

x = R (λ - λ₀)

y = R ln(tan(π/4 + θ/2))

Key points that hopefully help:

- R is the radius of the given sphere (6378137.0 meters, according to the WGS 1984 semimajor axis. I don't know what this means, it's just important)

- λ₀ is the central meridian (for the Mercator projection as we're using, this is 0.0˚ longitude)

- λ is the longitude in degrees (for example: -79.876884˚)

- θ is the latitude in degrees (for example: 32.808445˚)

The following example is given in Metal and Python:

#### Metal

```c++
// We use LongLat. We all know it as LatLong, but it is standard in math and mapping to use LongLat.
// This is important for GIS, GeoJSON, MapBox, Google Maps, etc.
float2 longLatToXY(float2 coords) {
    float radius = 6378137.0;
    float centralMeridian = 0.0;
    float pi_approx = 3.1415926;
    float x = radius * (coords.x - centralMeridian);
    float y = radius * log(tan((pi_approx / 4) + (coords.y / 2)));
    // return in X/Y format, even though we passed in as LongLat
    return float2(x, y);
}
```

#### Python 3

```python
from numpy import log as ln
from math import pi, tan

# We use LongLat. We all know it as LatLong, but it is standard in math and mapping to use LongLat.
# This is important for GIS, GeoJSON, MapBox, Google Maps, etc.
def longLatToXY(long: float, lat: float):
    radius = 6378137.0
    centralMeridian = 0.0
    x = radius * (long - centralMeridian)
    y = radius * ln(tan((pi / 4) + (lat / 2)))
    # return in X/Y tuple format, even though we passed in as LongLat
    return (x, y)
```

If that sucks, skip it for now. I did.

### Map scaling

Maps are scaled on an often used zoom level of 0 to ~23. 0 means the map is zoomed all the way out and a single pixel represents several hundred/thousand miles of land, while zoom level ~23 means you could zoom into a blade of grass. This scaling is exponential, and thankfully the math is super easy. If you were to overlay a view of a known size perfectly over the map, the math would be as follows to make the view scale with the map:

`scale = 2^(zoom_level)`

That's it! Now for code examples.

#### Metal

```c++
float getMapScale(float zoomLevel) {
    return pow(2.0, zoomLevel);
}

// Some arbitrary view size that fits perfectly over the map
float2 screenWidthHeight = float2(300.0, 100.0);
// Some arbitrary zoom level I choose. Get this from your map software/library.
float zoomLevel = 4.6;

float2 screenScaledWidthHeight = screenWidthHeight * getMapScale(zoomLevel);
```

#### Python 3

```python
def getMapScale(zoom_level: float):
    return pow(2, zoom_level)

# Some arbitrary view size that fits perfectly over the map
screenWidth = 300
screenHeight = 100
# Some arbitrary zoom level I choose. Get this from your map software/library.
zoom_level = 4.6

scale = getMapScale(zoom_level)
screenScaledWidth = scale * screenWidth
screenScaledHeight = scale * screenHeight
```

### Bilinear Interpolation

Finally, we are handling interpolation. I don't know the exact name for this method, but I do know it is a form of bilinear interpolation (with a twist) that I accidentally made but then later found a ResearchGate post - by an actual scientist with a degree - that did the same method but significantly better. So I just copied the scientist's version and claimed it as my own, as is the engineering way.

My method of Bilinear Interpolation is regular Linear Interpolation, but its used a few times to get the values on the X axis and the Y axis separately and then together. The purpose of using Bilinear Interpolation here is because if I pick a position at random from within the view (with my 2D data overlayed) it is not going to be a clean whole number (or will be a whole number not in my evenly spaced data), so I will not have data for it. If I picked point (63.829, 12.236) but I only had data for (63, 12), (64, 12), (63, 13), (64, 13), I'd need to find what the data would be without making the visual have hard edges (aka just taking the data from the closest point [64, 12] until it gets closer to another point, creating a square around each point). That would look terrible.

The first thing you need to do is have an angle in degrees (example: 270˚). Radians work, I just don't want to explain how to do it in radians even though we're turning the angle into radians anyway. It's like 3am and I just want a drop-in method, sue me. If you want to turn your radians into degrees then do the following:

`degrees = 180 / π`

Once you have your angle in degrees and a number value for your speed (miles per hour, kilometers per hour, meters per second, nautical miles per quarter-century, it doesn't matter, just get a number), we're going to break up our angle and speed into U/V values. U and V values are a way to flatten our circular angle into 2 sin/cosine lines that can be interpolated independently and rejoined. For that I have this code that might explain better:

#### Metal

```c++
float2 velocityToUVComponents(int degrees, float speed) {
    float pi_approx = 3.1415926;
    // To receive interpolatable rotational degrees, we must seperate the
    // angle into it's U and V values. U and V are the values that would
    // be graphed as X and Y values respectively
    float u = -speed * sin(2 * pi_approx * degrees / 360);
    float v = -speed * cos(2 * pi_approx * degrees / 360);
    return float2(u,v);
}
```

#### Python 3

```python
from math import sin, cos, pi

def velocityToUVComponents(degrees: float, speed: float):
    # To receive interpolatable rotational degrees, we must seperate the
    # angle into it's U and V values. U and V are the values that would
    # be graphed as X and Y values respectively
    u = (-1 * speed) * sin(2 * pi * degrees / 360)
    v = (-1 * speed) * cos(2 * pi * degrees / 360)
    return (u, v)
```

and to go from UV values to degrees:

#### Metal

```c++
float uvComponentstoVelocity(float2 uv) {
    float pi_approx = 3.1415926;
    // Despite what most sources will tell you about atan2, do NOT put atan2(u, v) aka atan2(x, y).
    // atan2(v, u) aka atan2(y, x) is the correct order
    return (atan2(uvs.y, uvs.x) * 360 / 2 / pi_approx) + 180;
}
```

#### Python 3

```python
from math import pi, atan2

def uvComponentsToVelocity(u: float, v: float):
    # Despite what most sources will tell you about atan2, do NOT put atan2(u, v) aka atan2(x, y).
    # atan2(v, u) aka atan2(y, x) is the correct order for this use case. Don't ask why, I don't know.
    return (atan2(v, u) * 360 / 2 / pi) + 180
```

As I said, the purpose of this is to interpolate these U and V values independently of each other. As an added bonus, the returning angles when we're finally done with this will always be between 0-360 and wrap around appropriately. What's so special about that? Have you tried averaging 1˚ and 359˚? It comes out to 180˚ instead of 0˚ or 360˚, which is wrong. U and V values are also good if you want to find just the simple average between two angles, which is the first step of interpolation!

Before continuing, please note that in Metal I'm passing around a pointer to a 1D array (representing a flat 2D array for Swift<->Metal compatibility) array of `WindGridPoint` values called `WindGridPoint *windGrid`. `WindGridPoint` is described below:

#### Objective-C

```objective-c
// This is in an Objective-C header (.h) file so that I can use the struct in both Swift and Metal.
// You will need to add a simple Bridging-Header file to do this.
struct WindGridPoint {
    vector_float2 position;
    float speed;
    uint angle;
};
```

That is all the data I have for every point on the grid. Before I continue, I first want to mention that if you are following my example of passing around a 1D array representing a 2D array (not recommended but its easier), you need to know the size of the grid ahead of time or pass in another object like above called `WindGridInfo`:

#### Objective-C

```objective-c
// This is in an Objective-C header (.h) file so that I can use the struct in both Swift and Metal.
// You will need to add a simple Bridging-Header file to do this.
struct WindGridInfo {
    uint width;
    uint height;
    uint screenWidth;
    uint screenHeight;
};
```

Now we can use this object to map over a 1D array as if it were a 2D array:

#### Swift

```swift
// Renderer.swift
let info: WindGridInfo = WindGridInfo(
    width: 300,     // number of data points on the X axis
    height: 100,    // number of data points on the Y axis
    screenWidth: self.view.currentDrawable.width,
    screenHeight: self.view.currentDrawable.height
)
// Now pass this into your Metal pipeline
```

#### Metal

```c++
// Shaders.metal

uint arr2DtoArr1D (uint x, uint y, WindGridInfo *info) {
    return x + (y * info.width);
}

// A Vertex Pipeline that takes and executes our data from Swift. Can also be a Compute or any other pipeline type.
vertex VertexOut vertexShader(
  device Particle *particleArray [[buffer(0)]],
  const device WindGridPoint *windGridPoints [[buffer(1)]],
  const device WindGridInfo *windGridInfo [[buffer(2)]],
  unsigned int vid [[vertex_id]]
) {
    // particleArray is our array of particles on the screen
    // windGridPoints is the data for the grid
    // * windGridInfo is what we just created that stores our grid information *
    // vid is the index of the particleArray

    WindGridInfo* info = windGridInfo;
    uint dataPointX = 32;
    uint dataPointY = 61;
    uint dataPointIndex = arr2DtoArr1D(dataPointX, dataPointY, info);
    WindGridPoint neededPoint = windGridPoints[dataPointIndex];
}
```

That's how I look up a data point from a properly ordered array!

The next step is described by the `getUVsOfRelativePosition` function below. What we are doing is making a square around the arbitrary point and getting the data from the 4 nearest points that create a square. For each of those points, we would use the `getUVsOfAbsolutePosition` function to get the data for that point. `getUVsOfAbsolutePosition` is using the method described above in regards to indexing a flattened 2D array.

One more note: I now use a float3 for UV values to include the speed as a z value. The "degrees to UV code" above has changed.

The full code for the bilinear interpolation functions for Metal, including the UV components, are below

#### Metal

```c++
# define pi_approx 3.1415926

float2 velocityToUVComponents(int degrees, float speed) {
    // To receive interpolatable rotational degrees, we must seperate the
    // angle into it's U and V values. U and V are the values that would
    // be graphed as X and Y values respectively
    float u = -speed * sin(2 * pi_approx * degrees / 360);
    float v = -speed * cos(2 * pi_approx * degrees / 360);
    return float2(u,v);
}

float uvComponentstoVelocity(float3 uvs) {
    return (atan2(uvs.y, uvs.x) * 360 / 2 / pi_approx) + 180;
}

float3 getUVsOfAbsolutePosition(int2 position, const device WindGridPoint *windGrid) {
    // Get UV of a known point
    WindGridPoint data_point = windGrid[int(position.x) + (127 * int(position.y))];
    float2 uv = velocityToUVComponents(data_point.angle - 90, data_point.speed);
    return float3(uv.x, uv.y, data_point.speed);
}

float4x3 getUVsOfRelativePosition(float4 positions, const device WindGridPoint *windGrid) {
    // Get the values of the surrounding 4 corner coordinates
    // Values are returned as UV values, described in uvComponents function
    int lowX = positions[0];
    int lowY = positions[1];
    int highX = positions[2];
    int highY = positions[3];
    float3 tl_uvs = getUVsOfAbsolutePosition(int2(lowX, lowY), windGrid);    // Top Left Coord;      Relative 0,0
    float3 tr_uvs = getUVsOfAbsolutePosition(int2(highX, lowY), windGrid);    // Top Right Coord;     Relative 1,0
    float3 bl_uvs = getUVsOfAbsolutePosition(int2(lowX, highY), windGrid);    // Bottom Left Coord;   Relative 0,1
    float3 br_uvs = getUVsOfAbsolutePosition(int2(highX, highY), windGrid); // Bottom Right Coord;  Relative 1,1

    return float4x3(tl_uvs, tr_uvs, bl_uvs, br_uvs);
}

float3 interpolateVelocity(float2 position, const device WindGridPoint *windGrid) {
    // position is the adjusted position to fit the grid. X is 0-127, Y is 0-68

    float lowX = floor(position.x);
    float lowY = floor(position.y);
    float highX = ceil(position.x);
    float highY = ceil(position.y);

    float4x3 uvs = getUVsOfRelativePosition(float4(lowX, lowY, highX, highY), windGrid);

    float3 topLeftUVS = uvs[0];      // 0,0
    float3 topRightUVS = uvs[1];     // 1,0
    float3 bottomLeftUVS = uvs[2];   // 0,1
    float3 bottomRightUVS = uvs[3];  // 1,1
    const uint U = 0; // U value
    const uint V = 1; // V value
    const uint S = 2; // Speed value

    // Interpolate U values
    // x with y1
    float lowerXU1 = ((highX - position.x) / (highX - lowX)) * topLeftUVS[U];
    float lowerXU2 = ((position.x - lowX) / (highX - lowX)) * topRightUVS[U];
    float lowerXU = lowerXU1 + lowerXU2;
    // x with y2
    float upperXU1 = ((highX - position.x) / (highX - lowX)) * bottomLeftUVS[U];
    float upperXU2 = ((position.x - lowX) / (highX - lowX)) * bottomRightUVS[U];
    float upperXU = upperXU1 + upperXU2;
    // y with interpolated x
    float yU1 = ((highY - position.y) / (highY - lowY)) * lowerXU;
    float yU2 = ((position.y - highY) / (highY - lowY)) * upperXU;
    float yU = yU1 + yU2;

    // Repeat the same interpolation on the V values
    // x with y1
    float lowerXV1 = ((highX - position.x) / (highX - lowX)) * topLeftUVS[V];
    float lowerXV2 = ((position.x - lowX) / (highX - lowX)) * topRightUVS[V];
    float lowerXV = lowerXV1 + lowerXV2;
    // x with y2
    float upperXV1 = ((highX - position.x) / (highX - lowX)) * bottomLeftUVS[V];
    float upperXV2 = ((position.x - lowX) / (highX - lowX)) * bottomRightUVS[V];
    float upperXV = upperXV1 + upperXV2;
    // y with interpolated x
    float yV1 = ((highY - position.y) / (highY - lowY)) * lowerXV;
    float yV2 = ((position.y - highY) / (highY - lowY)) * upperXV;
    float yV = yV1 + yV2;

    // Repeat the same interpolation on the Speed
    // x with y1
    float lowerXS1 = ((highX - position.x) / (highX - lowX)) * topLeftUVS[S];
    float lowerXS2 = ((position.x - lowX) / (highX - lowX)) * topRightUVS[S];
    float lowerXS = lowerXS1 + lowerXS2;
    // x with y2
    float upperXS1 = ((highX - position.x) / (highX - lowX)) * bottomLeftUVS[S];
    float upperXS2 = ((position.x - lowX) / (highX - lowX)) * bottomRightUVS[S];
    float upperXS = upperXS1 + upperXS2;
    // y with interpolated x
    float yS1 = ((highY - position.y) / (highY - lowY)) * lowerXS;
    float yS2 = ((position.y - highY) / (highY - lowY)) * upperXS;
    float yS = abs(yS1) + abs(yS2);

    float3 resUVS = float3(yU, yV, yS);
    float resultDirection = uvComponentstoVelocity(resUVS);
    return float2(resultDirection, resUVS.z);
}
```

Now we can just call `interpolateVelocity` with an arbitrary point within our grid and we have our rotation in degrees as our X and our speed as our Y.

#### Metal

```c++
// Get these from the buffer:
WindGridPoint* windGridPointArr = windGridPoints
WindGridInfo* info = windGridInfo;

// Separated for clarity
float arbitraryX = 38.382921;
float arbitraryY = 71.881391;
float2 arbitraryPosition = float2(arbitraryX, arbitraryY);
float2 directionAndSpeed = interpolateVelocity(arbitraryPosition, windGridPointArr);
float directionInDegrees = directionAndSpeed.x;
float speed = directionAndSpeed.y;
```

That's it! Email me at [brad@bread.codes](mailto://brad@bread.codes) if you have any questions or want to raise concerns about the efficacy of my work.

How to interpolate wind data

## Please Note

This is not my work, but I am hosting it here for archival purposes. The source I am rehosting is [here](https://web.archive.org/web/20110723013725/http://www.bottledlight.com/ds/index.php/Wifi/WMBProtocol), which is an archival rehost of a website no longer hosting the content, a website which is rehosting parts of a paper from 2005 by the same author entitled _Inferring a Proprietary Wireless L3 Protocol From Packet Traces_.

This came up in my research for the NDS Download Play protocol and it appears that the only place hosting this content is the WaybackMachine. I am hosting it here for archival purposes. If you are the original author and wish for me to take it down, please contact me at [brad@bread.codes](mailto:brad@bread.codes).

## Archived Content:

Original Note from `bottledlight.com`: This is a reformatted version of the technical content from _Inferring a Proprietary Wireless L3 Protocol From Packet Traces_ paper, and should probably be split up / otherwise wikified at some point. The ... represents a bit of the original paper that was cut.

There was also an associated [presentation](https://web.archive.org/web/20110723013725/http://www.cs.unc.edu/~jasleen/Courses/Fall05/projects/wmb_presentation.pdf) to go with the paper.

....

See [Wireless Basics](https://web.archive.org/web/20110723013725/http://www.bottledlight.com/ds/index.php/Wifi/WirelessBasics) for more 802.11 frame information.

# Available Game Advertisement

WMB uses beacon frames to advertise available games for download. The beacon frames are normally used to advertise available access points in most 802.11 systems, but there is nothing preventing their use in this capacity. The advertisement data is fragmented and stored partially in each [beacon frame](https://web.archive.org/web/20110723013725/http://www.bottledlight.com/ds/index.php/Wifi/WirelessBasics) as the payload of a custom information element (tag: 0xDD).

The DS Download Play menu only lists games when the beacons are broadcasted on one of the following channels: 1, 3, 4, 5, 7, 9, 10, 11, 13, and 14. However, the DS hosting mechanism only seems to transmit on channels 1, 7, and 13 (apparently selected at random).

All beacon frames transmitted by a DS host have the following format:

|     |
| --- |
| 802.11 management frame |
| 802.11 beacon header |
| Supported rates (tagged IE, advertises 1 Mbit and 2 Mbit) |
| DS parameter set (tagged IE, note: Distribution System, not Nintendo DS) |
| TIM vector (tagged IE, transmitted as empty) |
| Custom extension (tagged IE, tag `0xDD`) |

Nintendo specific beacon fragment format (information element code 0xDD):

| Offset | Description |
| --- | --- |
| `0x00` | Manufacturer (`00 09 BF`) |
| `0x03` | `00` |
| `0x04` | `0A 00 00 00` |
| `0x08` | `01 00 40 00` |
| `0x0C` | `24 00 40 00` |
| `0x10` | Randomly generated stream code |
| `0x12` | `70 0B` |
| `0x14` | `00 01 08 00` |
| `0x18` | `24 00 40 00` (varies from game to game) |
| `0x1C` | End of advertisement flag (`00` for non-end, `02` for end packets) |
| `0x1D` | Always `00`, `01`, `02`, or `04` |
| `0x1E` | Number of players already connected |
| `0x1F` | Sequence number (0 .. total\_advertisement\_length) |
| `0x20` | Checksum (2 byte little-endian) |
| `0x22` | Sequence number in non-final packet, # of players in final packet |
| `0x23` | Total advertisement length – 1 (in beacons) |
| `0x24` | Payload size in bytes (2 byte little-endian) |
| `0x26` | Payload begins |

The checksum is a custom algorithm, I have included example source in the appendix.

The advertisement fragments are reordered and assembled according to their internal sequence number, to form the overall advertisement payload, as defined below:

| Offset | Size | Description |
| --- | --- | --- |
| `0x000` | 32  | Icon palette (16 RGB555 entries) |
| `0x020` | 512 | Icon tiles (4x4 8x8 4 bit palletized tiles) |
| `0x220` | 1   | Unknown (0x0B) |
| `0x221` | 1   | Length of hosting name |
| `0x222` | 20  | Name of hosting DS (10 UCS-2) |
| `0x236` | 1   | Max number of players |
| `0x237` | 1   | Unknown (0x00) |
| `0x238` | 96  | Game name (48 UCS-2) |
| `0x298` | 192 | Game description (96 UCS-2) |
| `0x358` | 64  | 00’s if no users are connected |
| `0x398` | 0   | End of data if no users are connected |

The game name and game description are parsed out of the 128 characters stored in the .NDS file banner area. The game name comes from the first line of the banner, and the remaining lines go into the description. No WMB downloads have been observed that had more than 128 characters for these two fields combined, but it should be possible.

The icon format is a standard DS graphics format, constructing the 32x32 icon out of 8x8 pixel tiles, where each pixel is a 4-bit index into a 16-color palette. The 0th palette index is designated as transparent, allowing the background to show through. This also comes from the banner area of the original NDS file.

# Authentication process

Once a user B chooses a download offered by a host A, the following standard 802.11 authentication process observed.

1.  Host A advertises a game in beacon frames as described above
2.  Client B sends an authentication request (sequence 1) to A
3.  Host A replies with an ACK
4.  Host A sends an authentication reply (sequence 2) to B
5.  Client B replies with an association request
6.  Host A replies with an ACK
7.  Host A sends an association response
8.  Client B responds with an ACK

After this, the two are associated, and will remain so until the transfer is complete or one is idle for several seconds, at which point they will de-associate. For more information on the association process, see the 802.11 standard.

# Download process

After authentication:

1.  Host sends Pings (type 0x01, replies are 0x00, 0x07)
2.  Host sends RSA frame (type 0x03, replies 0x08)
3.  Host sends NDS header (type 0x04, replies 0x09)
4.  Host sends ARM9 binary (type 0x04, replies 0x09)
5.  Host sends ARM7 binary (type 0x04, replies 0x09)
6.  Host terminates transfer (type 0x05, no replies)

The WMB protocol ostensibly implements layers 3 to 7 of the OSI network model, but does not define a new type of network addresses. However, it does define a couple of special broadcast-like MAC addresses within the assigned Nintendo namespace (`00:09:BF`).

The three channels or flows used for all communications after the MAC broadcast beacons take the form `03:09:BF:00:00:xx`, where xx is:

*   00 for the main data flow, from host to client
*   10 for the client to host replies
*   03 for the feedback flow, host to client (acknowledges the replies)

Observed commands:

| Command | Description |
| --- | --- |
| 0x01 | Ping / Name request |
| 0x03 | RSA signature frame |
| 0x04 | Data packet |
| 0x05 | Post-idle / unknown |

Observed replies

| Reply ID | Description |
| --- | --- |
| 0x00 | Pong (ping reply) |
| 0x07 | Name reply |
| 0x08 | RSA frame reply |
| 0x09 | Data packet reply |

The host does something unusual with the 802.11 sequence control field, each packet sent out on the 00 flow has a sequence control number 2 greater than the previous one, even if they are sent sequentially. When the host acknowledges a reply (on flow 03) from the client about a particular packet, it uses the sequence number one after the original packet number it sent out on 00. This is the root of one of the major problems in finding a PC card that can transmit WMB packets, as very few cards provide user control over it. Even when a card is capable of ‘raw’ 802.11 transmission, it typically takes care of the sequence control field in hardware or firmware, filling it with a constantly incrementing number.

# Host-to-client packets (on the 0x00 flow)

| 0   | 1   | 2   | 3   | 4   | 5   | 6..e-3 | e-2 | e-1 | e-0 |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| 06  | 01  | 02  | 00  | Size | Flags | Payload | 00  | 02  | 00  |

Notes:

*   The size field is in terms of half-words (16 bits), and includes the flags byte along with the payload (so a size of 0x03 represents a flag byte, a command byte, and 4 bytes of payload).
*   When flags is 0x11, the first byte of the payload is a command. There seems to be no important data when flags is not 0x11 (seen occasionally as 0x01), and ignoring them still results in a complete dump.

The Ping messages (type 0x00) have a payload size of 0x03, but always contain zeroes in the payload. They seem to be used only to keep the connection alive while waiting for the host DS to start the transfer, to prevent a time-out de-association.

The RSA frame format (type 0x03) sends a table of information about the game being downloaded (most of it redundant with the NDS header, see Appendix), as well as the RSA signature for the DS. I have not looked into computing the signature, as homebrew developers are not privy to Nintendo’s private key, making signing a fruitless activity, but it is my understanding that the signature is a 128 byte public key and an 8 byte SHA-1 message digest over the NDS header, ARM9 binary, and ARM7 binary. Notably: the RSA frame itself is not included as part of the data being signed, bringing up various security issues and making Nintendo’s firmware engineers look amateurish at best.

There are several abortive sendings of empty RSA frames with a size field of 0x03, before the real frame is sent (always with a size field of 0x75).

RSA signature frame payload (type 0x03)

| Offset | Size | Description |
| --- | --- | --- |
| `0x00` | `4` | ARM9 execute address |
| `0x04` | `4` | ARM7 execute address |
| `0x08` | `4` | `0x00` |
| `0x0C` | `4` | Header destination |
| `0x10` | `4` | Header destination |
| `0x14` | `4` | Header size (0x160) |
| `0x18` | `4` | `0x00` |
| `0x1C` | `4` | ARM9 destination address |
| `0x20` | `4` | ARM9 destination address |
| `0x24` | `4` | ARM9 binary size |
| `0x28` | `4` | `0x00` |
| `0x2C` | `4` | `0x022C0000` |
| `0x30` | `4` | ARM7 destination address |
| `0x34` | `4` | ARM7 binary size |
| `0x38` | `4` | `0x01` |
| `0x3C` | `136` | Signature block |
| `0xC4` | `36` | `0x00`’s |
| `0xE8` | `0` | End of frame payload |

Notes:

*   The offsets in the table are from after the command byte, i.e. two bytes into the 234 bytes of payload including the flags.
*   The unknown address 0x022C0000 is probably ARM7 related, by comparison with the duplicated header and ARM9 destination addresses 32 and 16 bytes before it, although it has no known significance according to the NDS header.

The data packets (type 0x04) include a transport-layer sequence number inside of the data packet itself, but no destination offset or other mechanism to allow the packets to be processed out-of-order. The only way to place the data at the correct location in memory is to re-order the packets according to the sequence number and process them sequentially.

Data packet (type 0x04)

|0|1|2|3|..|End|
|---|---|---|---|---|---|
|00|\[Sequence#\]||xx|..|yy|

The sequence number is a zero based little-endian number. Each packet only contains data for one of the three destination blocks (header, ARM9, ARM7), so the change-of-destination check only needs to be made on packet boundaries.

# Client to Host Replies (on the 0x10 flow)

The replies from client to host are sent on the 0x10 flow. The client uses an incrementing sequence control number for all of its packets, with no unusual trickery. Each reply is sent as a standard 802.11 data frame (typically as a Data + CF-Acknowledgement), consisting of 10 data bytes for the WMB payload. The first two are always 0x04 0x81, with the third byte indicating the type of reply, and the remaining 7 bytes being reply-specific.

One type of packet frequently sent before a download gets underway is what I have termed the Idle or Pong packet (in response to 0x00 ‘Pings’). It has a reply type field of 0x00, and does not contribute any additional information.

Idle / Pong reply (type 0x00)

|0|1|2|3|4|5|6|7|8|9|
|---|---|---|---|---|---|---|---|---|---|
|`04`|`81`|`00`|`00`|`00`|`00`|`00`|`00`|`00`|`00`|

The name reply (type 0x07) is sent shortly after association is completed, although I am not certain what triggers it. There are a variable number of pings preceding this reply, but most are replied via Pongs. The name reply sends the user-configured DS name (set in the firmware menu) split over four messages (with the 4th byte of the packet specifying which message fragment this is, 1 based). This can be a total length of 10 UCS-2 characters, although all four messages are still sent if it is shorter (padded with nulls to 10 characters, and then 01 and then nulls until the end of the frame).

Name reply (type 0x07)

|0|1|2|3|4|5|6|7|8|9|
|---|---|---|---|---|---|---|---|---|---|
|`04`|`81`|`07`|`01`|\[Character0\]||\[Character1\]||\[Character2\]||
|`04`|`81`|`07`|`02`|\[Character3\]||\[Character4\]||\[Character5\]||
|`04`|`81`|`07`|`03`|\[Character6\]||\[Character7\]||\[Character8\]||
|`04`|`81`|`07`|`04`|\[Character9\]||`01`|`00`|`00`|`00`|

The RSA frame receipt reply contains no extra information; it only acknowledges receipt of a type 0x03 host packet on the main flow (0x00). Bizarrely, the xx bytes in the table below are not driven to a particular value when replying to an RSA frame, and usually contain the same data as the second (of four) name response frames.

|     |     |     |     |     |     |     |     |     |     |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |RSA frame receipt reply (type 0x08)
| 0   | 1   | 2   | 3   | 4   | 5   | 6   | 7   | 8   | 9   |
| `04` | `81` | `08` | `xx` | `xx` | `xx` | `xx` | `xx` | `xx` | `xx` |

The data packet receipt reply implements is interesting in that it includes both an immediate acknowledgement and something akin to a cumulative acknowledgement. It specifies the transport layer sequence number for both the packet just received, and the highest continuously addressed packet received.

Data packet receipt reply (type 0x09)

|0|1|2|3|4|5|6|7|8|9|
|---|---|---|---|---|---|---|---|---|---|
|`04`|`81`|`09`|\[Last packet\]||\[Best packet\]||`00`|`00`|`00`|

Notes:

*   \[last packet\] is the packet number being acknowledged
*   \[best packet\] is the highest continuous packet number seen so far
*   Packet IDs are little-endian numbers, like other Nintendo provided data.

# Host to client acknowledgements (on the 0x03 flow)

These packets contain four data bytes, but three are always zero. The first seems to be random, with no connection to the acknowledged data. The actual indication of acknowledgement is the sequence control number of the packet. It is set to be one greater than the sequence control number of the initial host packet (sent on flow 0x00) that the client has just responded to, to indicate that the reply was received.

Host-to-client acknowledgement

|0|1|2|3|
|---|---|---|---|
|`??`|`00`|`00`|`00`|

# Experimental Verification of Protocol

An experiment was setup to test some assumptions about the protocol and verify that clean working dumps of WMB transfers could be made.

1.  The Peanuts program was run on a laptop placed near to a DS running the game Polarium.
2.  The Send a Demo option in the Polarium menu was invoked, and Peanuts was checked to make sure both were operating on the same channel.
3.  Another DS was turned on in a different room, and the hosted Polarium demo was selected in the DS Download Play menu, and the transfer was allowed to complete.
4.  Peanut wrote out a reassembled .NDS file as well as an annotated trace log.
5.  The trace log was checked to make sure the reassembly completed.
6.  The reassembled file was also checked for file integrity with DSgrok.
7.  The WMB program was invoked with the captured demo, and a DS with unmodified firmware (i.e. will reject a game with even a single modified byte due to the RSA signature) was used to download the demo.
8.  The demo ran successfully without the characteristic faded logo lockup indicating a failed signature check, indicating that the capture and reassembly process works, at least for this demo.

# Conclusions and Future Work

The NiFi protocol, simply put, isn’t. Although both PictoChat and the DS Download Play have some similarities indicating that the same people wrote both programs (which seems likely considering they are both part of the same firmware), there is not a common layer 3 / 4 protocol shared between them.

The Nintendo DS does not appear to violate the letter of the 802.11 standard. However, most cards are not capable of providing application level control of the sequence number, and many card drivers do not even allow non-IP transmission over 802.11, filtering out incoming packets and providing no interface to send outbound ones.

The RSA signature frame is a curious design decision. They had to send a signature of the binaries across, but the RSA frame also contains duplicated header fields, including execute addresses. Under other circumstances, this would be a trivial waste of space; except that the signature does not cover the RSA frame itself, and it’s fields are preferentially used over the original header! This means that a DS download server can also operate as a software-based passthrough. Arbitrary code cannot be sent, as the binaries are still signed, but execution can be redirected to a flash cartridge in the GBA slot.

... The additional information in the RSA firmware is ignored by newer versions of the [firmware](https://web.archive.org/web/20110723013725/http://www.bottledlight.com/ds/index.php/Main/Firmware), completely preventing the WifiMe soft-passthrough. ...

The passive method of capture currently implemented in Peanut is sufficient when the client DS is sufficiently far away from the host DS to commonly request the same packet several times. By the very nature of wireless systems, packets have a high loss rate, even when the sender (host) and receiver (laptop) are quite close. If even a single packet is completely lost (i.e. the laptop missed it each time it was (re)transmitted to the client), then reassembly is impossible. The client DS gets around this by not acknowledging packets that were dropped, allowing the host to timeout and retransmit. As a passive snooper, we can’t work around this if the client receives the packet and we do not.

Moving to an active capture system, where Peanut pretends to be a client DS will provide flawless captures every time, and could also lead to a program running on the DS, providing WMB style downloads on DS units that do not have FlashMe installed. As most of the machinery associated with being an active client is common to being an active server, hopefully this would also lead to the first homebrew WMB broadcasts from a DS.

...

# Appendix

The beacon checksum is a custom algorithm, operating over the payload as half-words. Here is an example of how to compute it.

 
// The checksum is computed over halfwords for the last 4 bytes
// of the ninty beacon header, plus the payload
// This func takes length in halfwords
uint16 computeBeaconChecksum(uint16 \* data, int length) {
  uint32 sum = 0;
  for (int j = 0; j < length; j++) sum += \*data++;
  sum = (-((sum >> 16) + (sum & 0xFFFF) + 1)) & 0xFFFF;
  return sum;
}

The .NDS format is the standard format for Nintendo DS programs; it originated on original game cards and also appears to a limited extent in WMB binaries. The WMB process only transfers the first 0x160 bytes of the header, the ARM9 binary, and the ARM7 binary (in that order), ignoring the file name and file allocation tables, the overlay data, and some information stored in the banner (the rest is transmitted partially via the beacon advertisement process).

(No point in duplicating NDS header info here, see the [NDS Format](https://web.archive.org/web/20110723013725/http://www.bottledlight.com/ds/index.php/FileFormats/NDSFormat) page instead.)