RA8875 Parallel VGA Card

2024-08-28T21:05:06Z

Nuclear:

Main Page

2024-08-28T20:26:58Z

Nuclear: Add RA8875_Parallel_VGA_Card link

<strong>Important Documentation Pages:</strong>
You are probably looking for one of these:

* [[Teensy_4.1_Computer]]
* [[NGT31]]
* [[RA8875_Parallel_VGA_Card]]

Other documentation will be added as needed :)

2024-06-21T09:12:50Z

Nuclear: Update 3D example and add more info

The NGT31 is a Parallax Propeller based VGA driver and graphics device, provided as an Arduino shield. It uses a serial connection to the host device for communication, up to 250,000 baud with current firmware.

This device provides many useful graphics functions, including accelerated sprite drawing, text, and even drawing lines in 3D.

Firmware: https://git.nuclaer-servers.com/Nuclaer/ngt_firmware/-/tree/master

Arduino Library: https://git.nuclaer-servers.com/Nuclaer/nmt_gfx/-/tree/master

== Example Code ==

Here is the demo included in the NMT_GFX library (https://git.nuclaer-servers.com/Nuclaer/nmt_gfx/-/blob/master/Examples/NGT31/NGT31_demo/NGT31_demo.ino):

<pre>
#include <NMT_GFX.h>

byte tree[] = { 1,8,0,0,
0b01010100,0b00010101,
0b01010101,0b01010101,
0b01010101,0b01010101,
0b01010101,0b01010101,
0b10100011,0b00001010,
0b10100000,0b00001010,
0b10100000,0b00001010,
0b10101000,0b00101010
};

unsigned short cat[] = { 0, 0,
0xaaa,0x0000, 0xffff, 0xffff, 0xc000,
0xaaa,0xaaa3, 0xf555, 0x5557, 0xf000,
0xaaa,0xaaa3, 0xd555, 0x5555, 0xf000,
0xaaa,0xaaa3, 0x5555, 0x5555, 0x7000,
0xaaa,0xaaa3, 0x5555, 0x4155, 0x7000,
0xaaa,0xaaa3, 0x5555, 0x3c55, 0x70f0,
0xaaa,0x00a3, 0x5555, 0x3f15, 0x73f0,
0xaaa,0x3c23, 0x5555, 0x3fc0, 0x0ff0,
0xaaa,0x0f03, 0x5555, 0x3fff, 0xfff0,
0xaaa,0x83c3, 0x5554, 0xffff, 0xfffc,
0xaaa,0xa0f3, 0x5554, 0xfe3f, 0xfe3c,
0xaaa,0xa803, 0x5554, 0xfc3f, 0xcc3c,
0xaaa,0xaa83, 0x5554, 0xd7ff, 0xffd4,
0xaaa,0xaaa3, 0xd554, 0xd73f, 0x3cd4,
0xaaa,0xaaa3, 0xf555, 0x3f00, 0x00f0,
0xaaa,0x0000, 0xffff, 0xcfff, 0xffc0,
0xaaa,0x003f, 0x0000, 0x0000, 0x0000,
0xaaa,0x003c, 0x03c0, 0x00f0, 0x3c00
};

NMT_GFX ngt;

void setup() {
Serial.begin(115200);
ngt.begin(11,10);
ngt.print("Hello!\nThis is an arduino writing\non screen with a ");
ngt.println(ngt.get_card_ver());

delay(1200);

ngt.println("Look, I can even do colors!");
ngt.set_color(3);
ngt.print("green ");
ngt.set_color(2);
ngt.print("red ");
ngt.set_color(1);
ngt.println("and white");
ngt.println("(plus much more)");

delay(1400);

ngt.fill(2);
ngt.println("Screen fills can be done very fast.");
delay(1700);

ngt.clear();
ngt.println("I dont only do text though, so");
ngt.println("let me load my graphics");

// This line simply sets the size and center of the sprite.
// It modifies the 'cat' byte data, so that when it is
// uploaded, it will be the correct size, and centered.
// We don't do this for the tree, as this data is specified directly
// in the initialization of the 'tree' array. Either way
// of initializing it works perfectly fine.
Sprite catSprite((byte*)cat, 33, 17, 16, 16);

int treeHandle = ngt.uploadSprite(tree);
int catHandle = ngt.uploadSprite((byte*)cat);

delay(750);

ngt.println("I can do lines and sprites efficiently too.");

byte x_tiles=ngt.x_tiles(); // Get tiles for x and y
byte y_tiles=ngt.y_tiles();
ngt.block_color(64+63,0b001100);
ngt.block_color(128+63,0b011000); // define tree colors
ngt.block_color(192+63,0b010001);
for(byte i=0;i<50;i++){ // make all tiles use text coloring
ngt.tile_color(i,0);
}
for(byte i=x_tiles-1;i<50;i+=x_tiles){ // Make bottom tiles use tree coloring
ngt.tile_color(i,63);
}
ngt.sprite(4, 180, 0, treeHandle);
ngt.sprite(13, 180, 0, treeHandle);
ngt.sprite(48, 180, 2, treeHandle);
ngt.sprite(68, 180, 0, catHandle);
ngt.sprite(28, 180, 1, treeHandle);
ngt.line(0, 150, 30, 130);
ngt.fast(60, 150);
ngt.fast(90, 130);
ngt.fast(120, 150);
ngt.fast(150, 130);

delay(1000);

ngt.println(' ');
ngt.set_color(1);
ngt.println("The trees are drawn as sprites: an image of one is stored and copied to the screen using only one command, instead of resending the entire tree over serial.");

delay(6000);

ngt.set_cursor_pos(10, 190);
ngt.println("Now I'll show you a moving rainbow sprite.");

delay(1750);

ngt.clear();

// This sets up the colors for each tile
for(byte i=0;i<64;i++){
ngt.block_color(128+i,i); // RAINBOW
ngt.block_color(64+i,25); // PINK for Nyan Cat
ngt.block_color(192+i,0b101010); // GREY for Nyan Cat
}

// We only need to call these once. Instead of clearing the screen each frame,
// we will erase the old sprite right before drawing a new one. This allows faster
// rendering, and frees us from the need to write a message over and over again.
ngt.clear();
ngt.set_color(3);
ngt.println("Moving rainbow sprite!");
ngt.set_color(0);

// This tells the NGT31 to draw only when nothing is being displayed.
// Doing this reduces visual artifacts and makes the video data look cleaner.
// This only really affects moving objects and changing images: static
// text is not affected.
// 'B' stands for 'Blanking' - it only draws when no video data is being sent to the monitor.
ngt.set_draw_mode('B');

int lastX = 0;
int lastY = 40;
int vx = 1, vy = 1;

while(true) {
long ls = millis();

int x = lastX + vx;
int y = lastY + vy;
ngt.moveSprite(lastX, lastY, x, y, 0, catHandle);

lastX = x;
lastY = y;
if (x >= 300)
vx = -1;
else if (x <= 0)
vx = 1;
if (y >= 240)
vy = -1;
else if (y <= 30)
vy = 1;

while(ls + 16 > millis());
}
}

void loop() {

}
</pre>

=== 3D Example and Explanation ===

Drawing 3D lines, as part of a very simple 3D videogame demonstration:

<pre>
#include <NMT_GFX.h>
#include <PS2Keyboard.h>

NMT_GFX ngt;

PS2Keyboard keyboard;

uint16_t buffer[256];

void setup() {
Serial.begin(115200);
keyboard.begin(4, 2);
ngt.begin(11,10);
ngt.println("Loading world...");

Object3D world(ngt, buffer);
world.addLine(-1000,-100,-1000,1000,-100,-1000,2);
world.addLine(1000,-100,-1000,1000,100,-1000,2);
world.addLine(1000,100,-1000,1000,100,1000,2);
world.addLine(1000,100,1000,-1000,100,1000,2);
world.addLine(-1000,100,1000,-1000,-100,1000,2);
world.addLine(-1000,-100,1000,-1000,-100,-1000,2);

world.addLine(-1000,-100,1000,1000,-100,1000,2);
world.addLine(1000,-100,-1000,1000,-100,1000,2);

world.addLine(-1000,-100,-1000,-1000,100,-1000,2);
world.addLine(1000,-100,1000,1000,100,1000,2);

world.addLine(-1000,100,-1000,1000,100,-1000,2);
world.addLine(-1000,100,-1000,-1000,100,1000,2);

world.addLine(10,10,10,30,10,10,3);
world.addLine(30,10,10,30,30,10,3);
world.addLine(30,30,10,30,30,30,3);
world.addLine(30,30,30,10,30,30,3);
world.addLine(10,30,30,10,10,30,3);
world.addLine(10,10,30,10,10,10,3);

world.addLine(10,10,30,30,10,30,3);
world.addLine(30,10,10,30,10,30,3);

world.addLine(10,10,10,10,30,10,3);
world.addLine(30,10,30,30,30,30,3);

world.addLine(10,30,10,30,30,10,3);
world.addLine(10,30,10,10,30,30,3);

world.upload();

ngt.println("Setting up colors...");
for(byte i=0;i<64;i++) {
ngt.block_color(128 + i, 0b001011);
ngt.block_color(192 + i, 0b111111);
}

// Supported on newer firmware - reduces flicker
ngt.set_draw_mode('B');

ngt.println("Ready to play...");
delay(500);
double x=0,z=0;
int rot=0;
while(true) {
int32_t time=millis();
if (keyboard.available()) {

// read the next key
char c = keyboard.read();
if (c == PS2_LEFTARROW) {
rot+=3;
} else if (c == PS2_RIGHTARROW) {
rot-=3;
} else if (c == PS2_UPARROW) {
x-=cos(rot*PI/180);
z+=sin(rot*PI/180);
} else if (c == PS2_DOWNARROW) {
x+=cos(rot*PI/180);
z-=sin(rot*PI/180);
}
ngt.rotatef(-rot,0);
ngt.translatef((int32_t)x,0,(int32_t)z);
}

//ngt.clear();
long timer = millis();
world.draw();
//Serial.println(millis() - timer);

delay(max(1,(16+time)-(int32_t)millis()));
}
}

void loop() {
}
</pre>

Here, an <pre>Object3D</pre> is used to construct a bytecode of the 3D world. This bytecode can be rendered significantly faster than if individual commands were issued for each line or shape in the world.
Due to the speed limitations of the serial port, issuing this many commands per frame would cut the FPS to less than 25 - and that does not include draw time. By using <pre>Object3D::draw()</pre>, the
serial communication overhead is limited to less than 0.5ms for each draw.

The same Object3D may also be drawn multiple times at different locations by calling <pre>draw()</pre> multiple times, and calling <pre>translatef()</pre> in-between to change the position each time. Multiple
Object3Ds may be loaded as well, and drawn as needed. This way each object can be kept in VRAM, and quickly drawn each time it needs to be.

NGT31

2024-06-20T05:59:30Z

Nuclear: Add links for firmware and libraries

NGT31

2024-06-20T05:47:34Z

Nuclear: Add basic NGT31 page

UPD7220 Video Card (Revision 2)

2024-06-14T04:49:19Z

Nuclear: Formatting fixes

The uPD7220 Video Card revision 2 is a video card with 128KB of VRAM using the uPD7220 GDC or its variants. It operates at a maximum clock speed of 32Mhz. The card is based on the original uPD7220 card I (Dylan Brophy) made, which had half the VRAM and generally was far simpler. This card solves several issues with the older card, at the cost of greater size and complexity.

== Detailed Specifications ==

* 16-color VGA output
* 128KB of RAM
** 4 RAM chips, 32KB each, 25ns access and write time
** 16 bit bus (8 bits per chip, two chips per byte)
** 4 color bits per pixel, 4 pixels per word in RAM
*** Maximum 262144 pixels (hardware double buffering disabled)
**** Suggested resolutions: 544x480, 640x408
*** Maximum 131072 pixels (hardware double buffering enabled)
**** Suggested resolutions: 448x288, 400x300
* uPD7220 at up to 24Mhz, Z7220 at up to 32Mhz
* uPD7220 wide mode supported
** Allows higher pixel clock frequencies, for higher resolutions and lower visible display times
** Accesses two VRAM words per uPD7220 clock cycle
* Direct access to VRAM is provided to the host CPU

== Video Modes ==

It is assumed that the reader is familiar with VGA display timings. If not, then it is recommended to study it, or to use the video timing calculator and to leave the card in wide mode.

The uPD7220 was invented before the VGA standard, and due to this, was not designed to output a VGA signal. Since VGA was designed to drive CRT monitors, as was the uPD7220, it turns out that
they are fairly compatible. VGA timings work perfectly fine, but to compute them one must keep in mind the pixel and uPD7220 clocks. The uPD7220 clock is always one fourth of the card's clock
speed.

For common VGA signal timings, I would recommend looking at this very useful site: [http://tinyvga.com/vga-timing TinyVGA signal timings]

One must take the timings and convert them to the correct resolution. For an example, let's convert the 640x480 VGA standard timings to a 400x400 resolution. Here are the video timings from [http://tinyvga.com/vga-timing/640x480@60Hz TinyVGA's 640x480 60hz page]:

{| class="wikitable"
|+ Horizontal Timing
|-
! Region !! Pixels !! Microseconds
|-
| Visible area || 640 || 25.4220
|-
| Front porch || 16 || 0.6356
|-
| Sync pulse || 96 || 3.8133
|-
| Back porch || 48 || 1.9067
|-
| Whole line || 800 || 31.778
|}

{| class="wikitable"
|+ Vertical Timing
|-
! Region !! Lines
|-
| Visible area || 480
|-
| Front porch || 10
|-
| Sync pulse || 2
|-
| Back porch || 33
|-
| Whole frame || 525
|}

First, we need to decide on a clock frequency for our card. 24Mhz is slower than the 25.175Mhz recommended, and this will make our pixels wider by about 5%. However, a 24Mhz clock will run our uPD7220 at 6Mhz,
right at the maximum frequency, and 25.175Mhz would overclock it. We will select 24Mhz, as the 5% elongation of pixels is too small to care about, and the timings should be compatible with the uPD7220 IC. We
will enable wide mode, so our pixel clock is set at 24Mhz (the same as the card - without wide mode it would be 12Mhz, or half). This keeps the pixel width close to the intended width. Importantly, this change in clock speed will change the necessary timings for the video signal. Since each uPD7220 clock cycle is 166.7ns at 6Mhz, and each word is two cycles, we will be dividing the horizontal porch and sync widths
by 333.3ns to get the number of words for each of the regions. We cannot compute this yet though, because the visible region still needs to be adjusted for our new resolution.

For our application, we need less pixels, but still need to meet the timing spec. To achieve this, we can increase the back porch and reduce the visible region until we have the resolution we want. We do this
on both the x and y axes. This works because, during the back porch, the video signal is sent a black signal. On older monitors, this corresponds to a dark box around the image, and newer monitors will treat it
as a blank region. Fundamentally, the monitor will still generally treat it as a 640x480, standard VGA signal, because we haven't encroached on the porches, and we haven't changed/moved the sync signals. To
compute the width of the new visible area, we multiply the number of horizontal pixels by the pixel clock period: 41.67ns * 400 pixels = 16.67us. From this, we can calculate the new horizontal front porch, and
then we can recompute the lines per vertical video region:

{| class="wikitable"
|+ Updated Horizontal Timing
|-
! Region !! Microseconds
|-
| Visible area || 16.67
|-
| Front porch || 0.6356
|-
| Sync pulse || 3.8133
|-
| Back porch || 10.6620
|-
| Whole line || 31.7776
|}

The back porch becomes much wider. All we did was move the time over from the visible area to the back porch, such that the visible area has the correct number of pixels at our clock frequency. The vertical
regions are adjusted similarly, but the math is much simpler, because we are only trying to keep constant the number of lines:

{| class="wikitable"
|+ Vertical Timing
|-
! Region !! Lines
|-
| Visible area || 400
|-
| Front porch || 60
|-
| Sync pulse || 2
|-
| Back porch || 63
|-
| Whole frame || 525
|}

You will notice that I added lines to both the front and back vertical porches. This is because the uPD7220 cannot output more than 63 of each porch, so I needed to add to both to obey this limitation. For
lower resolutions, it is usually acceptable to reduce the total number of lines to obey these limitations. It is important, however, that in such a case the horizontal lines are made longer to keep the refresh rate at 60hz, and that the video settings are tested to work on the monitor.

At this point we have the description of the mode we want, now we can convert it into the numbers used by the card. The vertical timings are already in the correct format, but the horizontal timing still must
be converted. To do this, we need to get the number of memory cycles (not uPD7220 clock cycles) for each horizontal region, which is the time for two uPD7220 clock cycles. The exception is the visible region,
which is computed from the amount of memory used to represent the data (4 pixels per word, one word accessed per uPD7220 cycle in wide mode). For the visible region, we divide the number of pixels by 4, and
for the other regions, we divide the time by 333.3ns and round to the nearest whole number. Here is the result:

{| class="wikitable"
|+ uPD7220 timing settings
|-
! Region !! Words
|-
| Visible area || 100
|-
| Front porch || 1.907 => 2
|-
| Sync pulse || 11.4399 => 11
|-
| Back porch || 31.986 => 32
|}

Any VGA monitor should accept these signal timings for a 400x400 resolution. For video memory consumtion, this needs 400 * 400 / 4 = 40000 words of memory. The card has 65536 words total, but only
32768 if automatic double buffering is enabled, so we cannot enable automatic double buffering for this resolution. So, we must enable wide mode and disable double buffering for this video mode.

'''Card Specific Details: Wide Mode'''

This card can reach quite high clock speeds for the uPD7220, and to maintain this high speed for such slow chips, wide mode is used. This allows twice as many pixels to be output per uPD7220 clock cycle. This can be used either to increase the maximum resolution, or to reduce the display time. Reducing the display time gives the uPD7220 and host processor more time to draw to the screen. On the other hand, due to
the high speeds used in wide mode, there is also typically more data that must be written to the display per frame, thus putting more pressure on the host processor. The balance in display characteristics depends on the application.

Due to wide mode support, the card's clock is 4x the uPD7220's clock. When doing calculations for video, this must be kept in mind. If wide mode is disabled, then the pixel clock is only half the card's clock. If the video timing math does not account for this, then the video signal timing will be incorrect.

== Communication with the Host Processor ==

The hardware connection uses a fairly simple 8-bit parallel bus for data exchange. Once connected, the software can read from and write to several registers and addresses on the card to control it.

=== Hardware Protocol ===

Here is a pinout of the card:

{| class="wikitable"
|+ Card Pinout
|-
! Pin !! Name !! Description
|-
| 1 || A0 || Address pin 0 (LSB)
|-
| 2 || A1 || Address pin 1
|-
| 3 || A2 || Address pin 2 (MSB)
|-
| 4 || NC || No connection: this is the key pin and should be blocked
|-
| 5 || GND || Ground connection
|-
| 6 || D0 || Data pin 0 (LSB)
|-
| 7 || D1 || Data pin 1
|-
| 8 || D2 || Data pin 2
|-
| 9 || D3 || Data pin 3
|-
| 10 || D4 || Data pin 4
|-
| 11 || D5 || Data pin 5
|-
| 12 || D6 || Data pin 6
|-
| 13 || D7 || Data pin 7 (MSB)
|-
| 14 || SEL || Select pin (active low input) - selects the card for communication
|-
| 15 || 5v || +5V rail to power the card
|-
| 16 || RD || Read enable pin (active low input)
|-
| 17 || WR || Write enable pin (active low input)
|-
| 18 || WAIT || Wait indication (active low output)
|}

When trying to access VRAM, if the VRAM is being used by the card, then WAIT will be pulled low to tell the CPU not to end the current operation until after the WAIT pin goes high again. After WAIT goes high, wait at least 31.25ns for the read/write operation to complete before releasing any control lines or changing any data/address lines. Never read data while WAIT is low, and wait 31.25ns after WAIT goes high before reading the data to the CPU. WAIT only becomes low when trying to read from or write to VRAM; otherwise WAIT is always high.

Each access cycle should last at least 31.25ns, and SEL should be de-asserted between cycles. Any conventional processor like Z80, 8086, 6502, etc, should have no issue with WAIT or access cycles below an operating frequency of 32Mhz, regardless of the speed of the card. There may be exceptions to this, but there are no known exceptions.

=== Software Protocol ===

{| class="wikitable"
|+ Card Registers
|-
! Register !! Purpose
|-
| 0 || uPD7220 command register (uPD7220 A0 = 0)
|-
| 1 || uPD7220 parameter register (uPD7220 A0 = 1)
|-
| 2 || Card configuration register (write only)
|-
| 3 || Direct VRAM access (accessing this may cause WAIT to go low)
|-
| 4 || VRAM Address bits 0-7 (write only)
|-
| 5 || Reserved - for now same as register 4
|-
| 6 || VRAM Address bits 8-15 (write only)
|-
| 7 || Reserved - for now same as register 6
|}

For this card, a driver should first configure register 2 for the selected video mode and card interface configuration. This register has various bits to tell the card what to do:

{| class="wikitable" style="width:50%"
|+ Configuration Register Bits
|-
! Bit !! Purpose
|-
| 0 || Enables automatic counting of the VRAM address registers if set. If reset, then the VRAM address registers do not change when VRAM is written. More on this later.
|-
| 1 || Setting this bit enables the card's wide mode circutry. When reset, one pixel will be output every other clock cycle. This should match the setting on the uPD7220 IC.
|-
| 2 || Enables automatic double buffering. When set, draws to VRAM from the host CPU or the uPD7220 will happen on the opposite buffer as the one displaying. Setting this halfs the available VRAM for displaying.
|-
| 3 || Reserved
|-
| 4 || Reserved
|-
| 5 || Reserved
|-
| 6 || Reserved
|-
| 7 || Controls which buffer is displaying. Changing this bit will swap the currently displaying buffer. Only works in automatic double buffer mode.
|}

It is recommended to keep track of what buffer is currently displaying, and perhaps this entire configuration register, so that the selected buffer can be switched. This register is important for controlling how the CPU accesses VRAM, how smooth the display is, and the way the image data is displayed. Generally, automatic double buffering is recommended if the resolution demands less than half of the available VRAM, as
double buffering makes the display smoother by removing visual artifacts due to drawing, but doubles VRAM demand.

You can read the [http://www.vintagecomputer.net/fjkraan/comp/qx10/doc/nec7220.pdf programming manual] to get a detailed understanding of how to program the uPD7220, but I will also provide an abridged
version here. Once the card's configuration register is set, the uPD7220 must be initialized. The uPD7220 requires a sequence of commands to be sent to set it up:

# A reset command (write 0x00 to address 0x01)
#* This must be followed by parameter bytes, described below
# Setting the video mode to master (write 0x6f to address 0x01)
# Configuring the pitch
# Initializing the PRAM
#* PRAM is some internal memory in the uPD7220, which configures how it accesses memory, and probably some other things
# CCHAR command to configure the character characteristics
# Disabling zoom (write 0x46 to 0x01, then 0x00 to 0x00)
# Starting the display (write 0x6B to 0x01)
# Disable blanking (write 0x0D to 0x01)

My driver also seems to issue a FIGS command at the end of startup, but this may not be necessary.

Each command starts with a write to address 0x01, and for each parameter a write to address 0x00 follows. Each command I describe will proceed this way, with the first byte being the command byte written to
address 0x01, and all following bytes being parameters written to address 0x00. At the end I will have some example code in C which provides as both an example and an additional explanation.

The first command is the reset command; here is the format:

{| class="wikitable" style="width:50%"
|+ The Reset Command
|-
! Address !! Value / Description
|-
| 1 || 0x00
|-
| 0 || Operation mode. Discussed below.
|-
| 0 || Horizontal display words minus two. Must be an even number. This is equal to ((horizontal_pixels / 4) - 2). Wide mode does not affect this.
|-
| 0 || Lower 5 bits are the HSync width minus 1, in words. Upper 3 bits are the lower 3 bits of the VSync width.
|-
| 0 || Lower 2 bits are the upper 2 bits of the VSync width. Upper 6 bits are the horizontal front porch width minus 1.
|-
| 0 || Horizontal back porch width minus one. Upper two bits must be zero.
|-
| 0 || Vertical front porch width minus one. Upper two bits must be zero.
|-
| 0 || Number of display lines per frame, lower 8 bits.
|-
| 0 || Lower 2 bits are the upper 2 bits of the number of display lines per frame. Upper 6 bits are the vertical back porch length.
|}

Note that the vertical field sizes do not have numbers subtracted from them, but the horizontal field sizes have one or two subtracted from them. If this description is confusing, the uPD7220 manual provided above does contain a nice illustration you may consider looking at.

The operation mode is a bitmask, which controls interlacing, character or graphic mode, as well as DRAM refresh and if drawing is allowed during an active display cycle. Here are some of the options that
one can OR together to control the operation mode:

{| class="wikitable" style="width:50%"
|+ Operation control bits
|-
! Bitmask !! Selected Option
|-
| 0x00 || Leave bits 5 and 1 zero to have mixed character and graphics mode.
|-
| 0x02 || Enables just graphics mode
|-
| 0x20 || Enables just character mode
|-
| 0x00 || Leave bits 3 and 0 zero to disable interlacing
|-
| 0x08 || Enables interlacing
|-
| 0x09 || Enables "Interlaced repeat field for character displays". Read the manual for more information.
|-
| 0x04 || Enables DRAM refresh cycles - not used on this uPD7220 card, as static RAM is used.
|-
| 0x10 || Disables drawing during active display time. Enabling this is recommended.
|}

Generally 0x12 is a good setting for this card, unless you intend on using character mode. 0x10 will also work as a good mode.

The second command one must send is 0x6f, again written to address 0x01, and it does not take any parameters. The third command is the PITCH command:

{| class="wikitable" style="width:50%"
|+ The Pitch Command
|-
! Address !! Value / Description
|-
| 1 || 0x47
|-
| 0 || Number of memory words per line. Usually the same as the number of display words per line. Generally equal to (horizontal_pixels / 4). The only reason it would differ, is if the
|}

The fourth command is a PRAM command, which writes data to the uPD7220 parameter RAM. Here is a recommended usage of the command (although other usages are possible, again read the manual for more info):

{| class="wikitable" style="width:50%"
|+ The PRAM Command
|-
! Address !! Value / Description
|-
| 1 || 0x70 (starts PRAM write at PRAM byte 0)
|-
| 0 || Display partition 1 starting address (lower 8 bits) - it is recommended to leave this as zero.
|-
| 0 || Display partition 1 starting address (bits 8-16) - it is recommended to leave this as zero.
|-
| 0 || Lower 2 bits are the display partition 1 starting address (upper 2 bits). Upper 4 bits are the lower 4 bits of the display partition length, in horizontal lines (NOT words). Bits 2 and 3 should be left as zeros.
|-
| 0 || Lower 6 bits are the upper 6 bits of the image partition length, in horizontal lines (NOT words). Bit 6 (0x40) indicates it is a graphics area, otherwise it is a character area if in mixed mode. Bit 7 (0x80) enables wide mode - ensure to set this bit if you are using wide mode.
|}

The parameter RAM has more variables, but only these really need to be specified. There is another display partition that one can use, and configuration options for drawing and characters, later in the PRAM.

If your display mode uses wide mode, then be sure to set the MSB of the fourth parameter byte of this command, otherwise the memory access will be incorrect for wide mode.

Next, the CCHAR command is used to define the cursor and character characteristics:

{| class="wikitable" style="width:50%"
|+ The CCHAR Command
|-
! Address !! Value / Description
|-
| 1 || 0x4B
|-
| 0 || Setting the MSB will enable the cursor in character mode. The lower 5 bits are the number of lines per character row minus one. My driver leaves this byte as zero.
|-
| 0 || Lower 5 bits define the cursor top line number in the row. Bit 5 makes the cursor steady if set, or blinking if reset. Upper two bits are the lower two bits of the blink rate. My driver leaves this byte as 0xC0.
|}

This is sufficient for non-interlaced modes, but interlaced modes require this command to get a third byte.

Zoom must be disabled with a 0x46 write to address 0x01, followed by writing 0x00 to address 0x00. At this point we can finally enable the display and disable blanking by writing commands 0x6B, then 0x0D, to address 0x01.

My driver executes a FIGS command last, although this probably is not necessary. Just in case, here is the command sequence:

# 0x4C to address 0x01
# 0x02 to address 0x00
# 0x00 to address 0x00
# 0x00 to address 0x00

Here is my code which executes this exact sequence:

<pre>
void setup_upd7220() {
// Reset command
write(1, 0);
write(0, 0x10); // operation mode: draw only during blanking
write(0, HORIZ_WORDS - 2);
write(0, (VERT_SYNC << 5) | (HORIZ_SYNC - 1));
write(0, ((HORIZ_FRONT_PORCH - 1) << 2) | (VERT_SYNC >> 3));
write(0, (HORIZ_BACK_PORCH - 1) & 63);
write(0, VERT_FRONT_PORCH & 63);
write(0, VERT_PIXELS & 255);
write(0, (VERT_BACK_PORCH << 2) | (VERT_PIXELS >> 8));

// set master video mode
write(1, 0x6f);

// set pitch
write(1, 0x47);
write(0, HORIZ_WORDS);

// set some PRAM values
write(1, 0x70);
write(0, 0x00);
write(0, 0x00);
write(0, (VERT_PIXELS << 4) & 255);
write(0, (VERT_PIXELS >> 4) | (WIDE_MODE ? 8 : 0));

// Set character and cursor characteristics
write(1, 0x4B);
write(0, 0x00);
write(0, 0xC0);

// set zoom
write(1, 0x46);
write(0, 0x00);

// Enable the display
write(1, 0x6b);

// Disable blanking
write(1, 0x0D);

// This is probably not necessary
write(1, 0x4c);
write(0, 0x02);
write(0, 0x00);
write(0, 0x00);
}
</pre>

UPD7220 Video Card (Revision 2)

2024-06-14T04:41:44Z

Nuclear: Removed a weird comment from the example code

The uPD7220 Video Card revision 2 is a video card with 128KB of VRAM using the uPD7220 GDC or its variants. It operates at a maximum clock speed of 32Mhz. The card is based on the original uPD7220 card I (Dylan Brophy) made, which had half the VRAM and generally was far simpler. This card solves several issues with the older card, at the cost of greater size and complexity.

== Detailed Specifications ==

* 16-color VGA output
* 128KB of RAM
** 4 RAM chips, 32KB each, 25ns access and write time
** 16 bit bus (8 bits per chip, two chips per byte)
** 4 color bits per pixel, 4 pixels per word in RAM
*** Maximum 262144 pixels (hardware double buffering disabled)
**** Suggested resolutions: 544x480, 640x408
*** Maximum 131072 pixels (hardware double buffering enabled)
**** Suggested resolutions: 448x288, 400x300
* uPD7220 at up to 24Mhz, Z7220 at up to 32Mhz
* uPD7220 wide mode supported
** Allows higher pixel clock frequencies, for higher resolutions and lower visible display times
** Accesses two VRAM words per uPD7220 clock cycle
* Direct access to VRAM is provided to the host CPU

== Video Modes ==

It is assumed that the reader is familiar with VGA display timings. If not, then it is recommended to study it, or to use the video timing calculator and to leave the card in wide mode.

The uPD7220 was invented before the VGA standard, and due to this, was not designed to output a VGA signal. Since VGA was designed to drive CRT monitors, as was the uPD7220, it turns out that
they are fairly compatible. VGA timings work perfectly fine, but to compute them one must keep in mind the pixel and uPD7220 clocks. The uPD7220 clock is always one fourth of the card's clock
speed.

For common VGA signal timings, I would recommend looking at this very useful site: [http://tinyvga.com/vga-timing TinyVGA signal timings]

One must take the timings and convert them to the correct resolution. For an example, let's convert the 640x480 VGA standard timings to a 400x400 resolution. Here are the video timings from [http://tinyvga.com/vga-timing/640x480@60Hz TinyVGA's 640x480 60hz page]:

{| class="wikitable"
|+ Horizontal Timing
|-
! Region !! Pixels !! Microseconds
|-
| Visible area || 640 || 25.4220
|-
| Front porch || 16 || 0.6356
|-
| Sync pulse || 96 || 3.8133
|-
| Back porch || 48 || 1.9067
|-
| Whole line || 800 || 31.778
|}

{| class="wikitable"
|+ Vertical Timing
|-
! Region !! Lines
|-
| Visible area || 480
|-
| Front porch || 10
|-
| Sync pulse || 2
|-
| Back porch || 33
|-
| Whole frame || 525
|}

First, we need to decide on a clock frequency for our card. 24Mhz is slower than the 25.175Mhz recommended, and this will make our pixels wider by about 5%. However, a 24Mhz clock will run our uPD7220 at 6Mhz,
right at the maximum frequency, and 25.175Mhz would overclock it. We will select 24Mhz, as the 5% elongation of pixels is too small to care about, and the timings should be compatible with the uPD7220 IC. We
will enable wide mode, so our pixel clock is set at 24Mhz (the same as the card - without wide mode it would be 12Mhz, or half). This keeps the pixel width close to the intended width. Importantly, this change in clock speed will change the necessary timings for the video signal. Since each uPD7220 clock cycle is 166.7ns at 6Mhz, and each word is two cycles, we will be dividing the horizontal porch and sync widths
by 333.3ns to get the number of words for each of the regions. We cannot compute this yet though, because the visible region still needs to be adjusted for our new resolution.

For our application, we need less pixels, but still need to meet the timing spec. To achieve this, we can increase the back porch and reduce the visible region until we have the resolution we want. We do this
on both the x and y axes. This works because, during the back porch, the video signal is sent a black signal. On older monitors, this corresponds to a dark box around the image, and newer monitors will treat it
as a blank region. Fundamentally, the monitor will still generally treat it as a 640x480, standard VGA signal, because we haven't encroached on the porches, and we haven't changed/moved the sync signals. To
compute the width of the new visible area, we multiply the number of horizontal pixels by the pixel clock period: 41.67ns * 400 pixels = 16.67us. From this, we can calculate the new horizontal front porch, and
then we can recompute the lines per vertical video region:

{| class="wikitable"
|+ Updated Horizontal Timing
|-
! Region !! Microseconds
|-
| Visible area || 16.67
|-
| Front porch || 0.6356
|-
| Sync pulse || 3.8133
|-
| Back porch || 10.6620
|-
| Whole line || 31.7776
|}

The back porch becomes much wider. All we did was move the time over from the visible area to the back porch, such that the visible area has the correct number of pixels at our clock frequency. The vertical
regions are adjusted similarly, but the math is much simpler, because we are only trying to keep constant the number of lines:

{| class="wikitable"
|+ Vertical Timing
|-
! Region !! Lines
|-
| Visible area || 400
|-
| Front porch || 60
|-
| Sync pulse || 2
|-
| Back porch || 63
|-
| Whole frame || 525
|}

You will notice that I added lines to both the front and back vertical porches. This is because the uPD7220 cannot output more than 63 of each porch, so I needed to add to both to obey this limitation. For
lower resolutions, it is usually acceptable to reduce the total number of lines to obey these limitations. It is important, however, that in such a case the horizontal lines are made longer to keep the refresh rate at 60hz, and that the video settings are tested to work on the monitor.

At this point we have the description of the mode we want, now we can convert it into the numbers used by the card. The vertical timings are already in the correct format, but the horizontal timing still must
be converted. To do this, we need to get the number of memory cycles (not uPD7220 clock cycles) for each horizontal region, which is the time for two uPD7220 clock cycles. The exception is the visible region,
which is computed from the amount of memory used to represent the data (4 pixels per word, one word accessed per uPD7220 cycle in wide mode). For the visible region, we divide the number of pixels by 4, and
for the other regions, we divide the time by 333.3ns and round to the nearest whole number. Here is the result:

{| class="wikitable"
|+ uPD7220 timing settings
|-
! Region !! Words
|-
| Visible area || 100
|-
| Front porch || 1.907 => 2
|-
| Sync pulse || 11.4399 => 11
|-
| Back porch || 31.986 => 32
|}

Any VGA monitor should accept these signal timings for a 400x400 resolution. For video memory consumtion, this needs 400 * 400 / 4 = 40000 words of memory. The card has 65536 words total, but only
32768 if automatic double buffering is enabled, so we cannot enable automatic double buffering for this resolution. So, we must enable wide mode and disable double buffering for this video mode.

'''Card Specific Details: Wide Mode'''

This card can reach quite high clock speeds for the uPD7220, and to maintain this high speed for such slow chips, wide mode is used. This allows twice as many pixels to be output per uPD7220 clock cycle. This can be used either to increase the maximum resolution, or to reduce the display time. Reducing the display time gives the uPD7220 and host processor more time to draw to the screen. On the other hand, due to
the high speeds used in wide mode, there is also typically more data that must be written to the display per frame, thus putting more pressure on the host processor. The balance in display characteristics depends on the application.

Due to wide mode support, the card's clock is 4x the uPD7220's clock. When doing calculations for video, this must be kept in mind. If wide mode is disabled, then the pixel clock is only half the card's clock. If the video timing math does not account for this, then the video signal timing will be incorrect.

== Communication with the Host Processor ==

The hardware connection uses a fairly simple 8-bit parallel bus for data exchange. Once connected, the software can read from and write to several registers and addresses on the card to control it.

=== Hardware Protocol ===

Here is a pinout of the card:

{| class="wikitable"
|+ Card Pinout
|-
! Pin !! Name !! Description
|-
| 1 || A0 || Address pin 0 (LSB)
|-
| 2 || A1 || Address pin 1
|-
| 3 || A2 || Address pin 2 (MSB)
|-
| 4 || NC || No connection: this is the key pin and should be blocked
|-
| 5 || GND || Ground connection
|-
| 6 || D0 || Data pin 0 (LSB)
|-
| 7 || D1 || Data pin 1
|-
| 8 || D2 || Data pin 2
|-
| 9 || D3 || Data pin 3
|-
| 10 || D4 || Data pin 4
|-
| 11 || D5 || Data pin 5
|-
| 12 || D6 || Data pin 6
|-
| 13 || D7 || Data pin 7 (MSB)
|-
| 14 || SEL || Select pin (active low input) - selects the card for communication
|-
| 15 || 5v || +5V rail to power the card
|-
| 16 || RD || Read enable pin (active low input)
|-
| 17 || WR || Write enable pin (active low input)
|-
| 18 || WAIT || Wait indication (active low output)
|}

When trying to access VRAM, if the VRAM is being used by the card, then WAIT will be pulled low to tell the CPU not to end the current operation until after the WAIT pin goes high again. After WAIT goes high, wait at least 31.25ns for the read/write operation to complete before releasing any control lines or changing any data/address lines. Never read data while WAIT is low, and wait 31.25ns after WAIT goes high before reading the data to the CPU. WAIT only becomes low when trying to read from or write to VRAM; otherwise WAIT is always high.

Each access cycle should last at least 31.25ns, and SEL should be de-asserted between cycles. Any conventional processor like Z80, 8086, 6502, etc, should have no issue with WAIT or access cycles below an operating frequency of 32Mhz, regardless of the speed of the card. There may be exceptions to this, but there are no known exceptions.

=== Software Protocol ===

{| class="wikitable"
|+ Card Registers
|-
! Register !! Purpose
|-
| 0 || uPD7220 command register (uPD7220 A0 = 0)
|-
| 1 || uPD7220 parameter register (uPD7220 A0 = 1)
|-
| 2 || Card configuration register (write only)
|-
| 3 || Direct VRAM access (accessing this may cause WAIT to go low)
|-
| 4 || VRAM Address bits 0-7 (write only)
|-
| 5 || Reserved - for now same as register 4
|-
| 6 || VRAM Address bits 8-15 (write only)
|-
| 7 || Reserved - for now same as register 6
|}

For this card, a driver should first configure register 2 for the selected video mode and card interface configuration. This register has various bits to tell the card what to do:

{| class="wikitable" style="width:50%"
|+ Configuration Register Bits
|-
! Bit !! Purpose
|-
| 0 || Enables automatic counting of the VRAM address registers if set. If reset, then the VRAM address registers do not change when VRAM is written. More on this later.
|-
| 1 || Setting this bit enables the card's wide mode circutry. When reset, one pixel will be output every other clock cycle. This should match the setting on the uPD7220 IC.
|-
| 2 || Enables automatic double buffering. When set, draws to VRAM from the host CPU or the uPD7220 will happen on the opposite buffer as the one displaying. Setting this halfs the available VRAM for displaying.
|-
| 3 || Reserved
|-
| 4 || Reserved
|-
| 5 || Reserved
|-
| 6 || Reserved
|-
| 7 || Controls which buffer is displaying. Changing this bit will swap the currently displaying buffer. Only works in automatic double buffer mode.
|}

It is recommended to keep track of what buffer is currently displaying, and perhaps this entire configuration register, so that the selected buffer can be switched. This register is important for controlling how the CPU accesses VRAM, how smooth the display is, and the way the image data is displayed. Generally, automatic double buffering is recommended if the resolution demands less than half of the available VRAM, as
double buffering makes the display smoother by removing visual artifacts due to drawing, but doubles VRAM demand.

You can read the [http://www.vintagecomputer.net/fjkraan/comp/qx10/doc/nec7220.pdf programming manual] to get a detailed understanding of how to program the uPD7220, but I will also provide an abridged
version here. Once the card's configuration register is set, the uPD7220 must be initialized. The uPD7220 requires a sequence of commands to be sent to set it up:
1. A reset command (write 0x00 to address 0x01)
** This must be followed by parameter bytes, described below
2. Setting the video mode to master (write 0x6f to address 0x01)
3. Configuring the pitch
4. Initializing the PRAM
** PRAM is some internal memory in the uPD7220, which configures how it accesses memory, and probably some other things
5. CCHAR command to configure the character characteristics
6. Disabling zoom (write 0x46 to 0x01, then 0x00 to 0x00)
7. Starting the display (write 0x6B to 0x01)
8. Disable blanking (write 0x0D to 0x01)

My driver also seems to issue a FIGS command at the end of startup, but this may not be necessary.

Each command starts with a write to address 0x01, and for each parameter a write to address 0x00 follows. Each command I describe will proceed this way, with the first byte being the command byte written to
address 0x01, and all following bytes being parameters written to address 0x00. At the end I will have some example code in C which provides as both an example and an additional explanation.

The first command is the reset command; here is the format:

{| class="wikitable" style="width:50%"
|+ The Reset Command
|-
! Address !! Value / Description
|-
| 1 || 0x00
|-
| 0 || Operation mode. Discussed below.
|-
| 0 || Horizontal display words minus two. Must be an even number. This is equal to ((horizontal_pixels / 4) - 2). Wide mode does not affect this.
|-
| 0 || Lower 5 bits are the HSync width minus 1, in words. Upper 3 bits are the lower 3 bits of the VSync width.
|-
| 0 || Lower 2 bits are the upper 2 bits of the VSync width. Upper 6 bits are the horizontal front porch width minus 1.
|-
| 0 || Horizontal back porch width minus one. Upper two bits must be zero.
|-
| 0 || Vertical front porch width minus one. Upper two bits must be zero.
|-
| 0 || Number of display lines per frame, lower 8 bits.
|-
| 0 || Lower 2 bits are the upper 2 bits of the number of display lines per frame. Upper 6 bits are the vertical back porch length.
|}

Note that the vertical field sizes do not have numbers subtracted from them, but the horizontal field sizes have one or two subtracted from them. If this description is confusing, the uPD7220 manual provided above does contain a nice illustration you may consider looking at.

The operation mode is a bitmask, which controls interlacing, character or graphic mode, as well as DRAM refresh and if drawing is allowed during an active display cycle. Here are some of the options that
one can OR together to control the operation mode:

{| class="wikitable" style="width:50%"
|+ Operation control bits
|-
! Bitmask !! Selected Option
|-
| 0x00 || Leave bits 5 and 1 zero to have mixed character and graphics mode.
|-
| 0x02 || Enables just graphics mode
|-
| 0x20 || Enables just character mode
|-
| 0x00 || Leave bits 3 and 0 zero to disable interlacing
|-
| 0x08 || Enables interlacing
|-
| 0x09 || Enables "Interlaced repeat field for character displays". Read the manual for more information.
|-
| 0x04 || Enables DRAM refresh cycles - not used on this uPD7220 card, as static RAM is used.
|-
| 0x10 || Disables drawing during active display time. Enabling this is recommended.
|}

Generally 0x12 is a good setting for this card, unless you intend on using character mode. 0x10 will also work as a good mode.

The second command one must send is 0x6f, again written to address 0x01, and it does not take any parameters. The third command is the PITCH command:

{| class="wikitable" style="width:50%"
|+ The Pitch Command
|-
! Address !! Value / Description
|-
| 1 || 0x47
|-
| 0 || Number of memory words per line. Usually the same as the number of display words per line. Generally equal to (horizontal_pixels / 4). The only reason it would differ, is if the
|}

The fourth command is a PRAM command, which writes data to the uPD7220 parameter RAM. Here is a recommended usage of the command (although other usages are possible, again read the manual for more info):

{| class="wikitable" style="width:50%"
|+ The PRAM Command
|-
! Address !! Value / Description
|-
| 1 || 0x70 (starts PRAM write at PRAM byte 0)
|-
| 0 || Display partition 1 starting address (lower 8 bits) - it is recommended to leave this as zero.
|-
| 0 || Display partition 1 starting address (bits 8-16) - it is recommended to leave this as zero.
|-
| 0 || Lower 2 bits are the display partition 1 starting address (upper 2 bits). Upper 4 bits are the lower 4 bits of the display partition length, in horizontal lines (NOT words). Bits 2 and 3 should be left as zeros.
|-
| 0 || Lower 6 bits are the upper 6 bits of the image partition length, in horizontal lines (NOT words). Bit 6 (0x40) indicates it is a graphics area, otherwise it is a character area if in mixed mode. Bit 7 (0x80) enables wide mode - ensure to set this bit if you are using wide mode.
|}

The parameter RAM has more variables, but only these really need to be specified. There is another display partition that one can use, and configuration options for drawing and characters, later in the PRAM.

If your display mode uses wide mode, then be sure to set the MSB of the fourth parameter byte of this command, otherwise the memory access will be incorrect for wide mode.

Next, the CCHAR command is used to define the cursor and character characteristics:

{| class="wikitable" style="width:50%"
|+ The CCHAR Command
|-
! Address !! Value / Description
|-
| 1 || 0x4B
|-
| 0 || Setting the MSB will enable the cursor in character mode. The lower 5 bits are the number of lines per character row minus one. My driver leaves this byte as zero.
|-
| 0 || Lower 5 bits define the cursor top line number in the row. Bit 5 makes the cursor steady if set, or blinking if reset. Upper two bits are the lower two bits of the blink rate. My driver leaves this byte as 0xC0.
|}

This is sufficient for non-interlaced modes, but interlaced modes require this command to get a third byte.

Zoom must be disabled with a 0x46 write to address 0x01, followed by writing 0x00 to address 0x00. At this point we can finally enable the display and disable blanking by writing commands 0x6B, then 0x0D, to address 0x01.

My driver executes a FIGS command last, although this probably is not necessary. Just in case, here is the command sequence:
1. 0x4C to address 0x01
2. 0x02 to address 0x00
3. 0x00 to address 0x00
4. 0x00 to address 0x00

Here is my code which executes this exact sequence:

<pre>
void setup_upd7220() {
// Reset command
write(1, 0);
write(0, 0x10); // operation mode: draw only during blanking
write(0, HORIZ_WORDS - 2);
write(0, (VERT_SYNC << 5) | (HORIZ_SYNC - 1));
write(0, ((HORIZ_FRONT_PORCH - 1) << 2) | (VERT_SYNC >> 3));
write(0, (HORIZ_BACK_PORCH - 1) & 63);
write(0, VERT_FRONT_PORCH & 63);
write(0, VERT_PIXELS & 255);
write(0, (VERT_BACK_PORCH << 2) | (VERT_PIXELS >> 8));

// set master video mode
write(1, 0x6f);

// set pitch
write(1, 0x47);
write(0, HORIZ_WORDS);

// set some PRAM values
write(1, 0x70);
write(0, 0x00);
write(0, 0x00);
write(0, (VERT_PIXELS << 4) & 255);
write(0, (VERT_PIXELS >> 4) | (WIDE_MODE ? 8 : 0));

// Set character and cursor characteristics
write(1, 0x4B);
write(0, 0x00);
write(0, 0xC0);

// set zoom
write(1, 0x46);
write(0, 0x00);

// Enable the display
write(1, 0x6b);

// Disable blanking
write(1, 0x0D);

// This is probably not necessary
write(1, 0x4c);
write(0, 0x02);
write(0, 0x00);
write(0, 0x00);
}
</pre>

UPD7220 Video Card (Revision 2)

2024-06-14T04:37:58Z

Nuclear: Checkpoint: finished the initialization section at last!

The uPD7220 Video Card revision 2 is a video card with 128KB of VRAM using the uPD7220 GDC or its variants. It operates at a maximum clock speed of 32Mhz. The card is based on the original uPD7220 card I (Dylan Brophy) made, which had half the VRAM and generally was far simpler. This card solves several issues with the older card, at the cost of greater size and complexity.

== Detailed Specifications ==

* 16-color VGA output
* 128KB of RAM
** 4 RAM chips, 32KB each, 25ns access and write time
** 16 bit bus (8 bits per chip, two chips per byte)
** 4 color bits per pixel, 4 pixels per word in RAM
*** Maximum 262144 pixels (hardware double buffering disabled)
**** Suggested resolutions: 544x480, 640x408
*** Maximum 131072 pixels (hardware double buffering enabled)
**** Suggested resolutions: 448x288, 400x300
* uPD7220 at up to 24Mhz, Z7220 at up to 32Mhz
* uPD7220 wide mode supported
** Allows higher pixel clock frequencies, for higher resolutions and lower visible display times
** Accesses two VRAM words per uPD7220 clock cycle
* Direct access to VRAM is provided to the host CPU

== Video Modes ==

It is assumed that the reader is familiar with VGA display timings. If not, then it is recommended to study it, or to use the video timing calculator and to leave the card in wide mode.

The uPD7220 was invented before the VGA standard, and due to this, was not designed to output a VGA signal. Since VGA was designed to drive CRT monitors, as was the uPD7220, it turns out that
they are fairly compatible. VGA timings work perfectly fine, but to compute them one must keep in mind the pixel and uPD7220 clocks. The uPD7220 clock is always one fourth of the card's clock
speed.

For common VGA signal timings, I would recommend looking at this very useful site: [http://tinyvga.com/vga-timing TinyVGA signal timings]

One must take the timings and convert them to the correct resolution. For an example, let's convert the 640x480 VGA standard timings to a 400x400 resolution. Here are the video timings from [http://tinyvga.com/vga-timing/640x480@60Hz TinyVGA's 640x480 60hz page]:

{| class="wikitable"
|+ Horizontal Timing
|-
! Region !! Pixels !! Microseconds
|-
| Visible area || 640 || 25.4220
|-
| Front porch || 16 || 0.6356
|-
| Sync pulse || 96 || 3.8133
|-
| Back porch || 48 || 1.9067
|-
| Whole line || 800 || 31.778
|}

{| class="wikitable"
|+ Vertical Timing
|-
! Region !! Lines
|-
| Visible area || 480
|-
| Front porch || 10
|-
| Sync pulse || 2
|-
| Back porch || 33
|-
| Whole frame || 525
|}

First, we need to decide on a clock frequency for our card. 24Mhz is slower than the 25.175Mhz recommended, and this will make our pixels wider by about 5%. However, a 24Mhz clock will run our uPD7220 at 6Mhz,
right at the maximum frequency, and 25.175Mhz would overclock it. We will select 24Mhz, as the 5% elongation of pixels is too small to care about, and the timings should be compatible with the uPD7220 IC. We
will enable wide mode, so our pixel clock is set at 24Mhz (the same as the card - without wide mode it would be 12Mhz, or half). This keeps the pixel width close to the intended width. Importantly, this change in clock speed will change the necessary timings for the video signal. Since each uPD7220 clock cycle is 166.7ns at 6Mhz, and each word is two cycles, we will be dividing the horizontal porch and sync widths
by 333.3ns to get the number of words for each of the regions. We cannot compute this yet though, because the visible region still needs to be adjusted for our new resolution.

For our application, we need less pixels, but still need to meet the timing spec. To achieve this, we can increase the back porch and reduce the visible region until we have the resolution we want. We do this
on both the x and y axes. This works because, during the back porch, the video signal is sent a black signal. On older monitors, this corresponds to a dark box around the image, and newer monitors will treat it
as a blank region. Fundamentally, the monitor will still generally treat it as a 640x480, standard VGA signal, because we haven't encroached on the porches, and we haven't changed/moved the sync signals. To
compute the width of the new visible area, we multiply the number of horizontal pixels by the pixel clock period: 41.67ns * 400 pixels = 16.67us. From this, we can calculate the new horizontal front porch, and
then we can recompute the lines per vertical video region:

{| class="wikitable"
|+ Updated Horizontal Timing
|-
! Region !! Microseconds
|-
| Visible area || 16.67
|-
| Front porch || 0.6356
|-
| Sync pulse || 3.8133
|-
| Back porch || 10.6620
|-
| Whole line || 31.7776
|}

The back porch becomes much wider. All we did was move the time over from the visible area to the back porch, such that the visible area has the correct number of pixels at our clock frequency. The vertical
regions are adjusted similarly, but the math is much simpler, because we are only trying to keep constant the number of lines:

{| class="wikitable"
|+ Vertical Timing
|-
! Region !! Lines
|-
| Visible area || 400
|-
| Front porch || 60
|-
| Sync pulse || 2
|-
| Back porch || 63
|-
| Whole frame || 525
|}

You will notice that I added lines to both the front and back vertical porches. This is because the uPD7220 cannot output more than 63 of each porch, so I needed to add to both to obey this limitation. For
lower resolutions, it is usually acceptable to reduce the total number of lines to obey these limitations. It is important, however, that in such a case the horizontal lines are made longer to keep the refresh rate at 60hz, and that the video settings are tested to work on the monitor.

At this point we have the description of the mode we want, now we can convert it into the numbers used by the card. The vertical timings are already in the correct format, but the horizontal timing still must
be converted. To do this, we need to get the number of memory cycles (not uPD7220 clock cycles) for each horizontal region, which is the time for two uPD7220 clock cycles. The exception is the visible region,
which is computed from the amount of memory used to represent the data (4 pixels per word, one word accessed per uPD7220 cycle in wide mode). For the visible region, we divide the number of pixels by 4, and
for the other regions, we divide the time by 333.3ns and round to the nearest whole number. Here is the result:

{| class="wikitable"
|+ uPD7220 timing settings
|-
! Region !! Words
|-
| Visible area || 100
|-
| Front porch || 1.907 => 2
|-
| Sync pulse || 11.4399 => 11
|-
| Back porch || 31.986 => 32
|}

Any VGA monitor should accept these signal timings for a 400x400 resolution. For video memory consumtion, this needs 400 * 400 / 4 = 40000 words of memory. The card has 65536 words total, but only
32768 if automatic double buffering is enabled, so we cannot enable automatic double buffering for this resolution. So, we must enable wide mode and disable double buffering for this video mode.

'''Card Specific Details: Wide Mode'''

This card can reach quite high clock speeds for the uPD7220, and to maintain this high speed for such slow chips, wide mode is used. This allows twice as many pixels to be output per uPD7220 clock cycle. This can be used either to increase the maximum resolution, or to reduce the display time. Reducing the display time gives the uPD7220 and host processor more time to draw to the screen. On the other hand, due to
the high speeds used in wide mode, there is also typically more data that must be written to the display per frame, thus putting more pressure on the host processor. The balance in display characteristics depends on the application.

Due to wide mode support, the card's clock is 4x the uPD7220's clock. When doing calculations for video, this must be kept in mind. If wide mode is disabled, then the pixel clock is only half the card's clock. If the video timing math does not account for this, then the video signal timing will be incorrect.

== Communication with the Host Processor ==

The hardware connection uses a fairly simple 8-bit parallel bus for data exchange. Once connected, the software can read from and write to several registers and addresses on the card to control it.

=== Hardware Protocol ===

Here is a pinout of the card:

{| class="wikitable"
|+ Card Pinout
|-
! Pin !! Name !! Description
|-
| 1 || A0 || Address pin 0 (LSB)
|-
| 2 || A1 || Address pin 1
|-
| 3 || A2 || Address pin 2 (MSB)
|-
| 4 || NC || No connection: this is the key pin and should be blocked
|-
| 5 || GND || Ground connection
|-
| 6 || D0 || Data pin 0 (LSB)
|-
| 7 || D1 || Data pin 1
|-
| 8 || D2 || Data pin 2
|-
| 9 || D3 || Data pin 3
|-
| 10 || D4 || Data pin 4
|-
| 11 || D5 || Data pin 5
|-
| 12 || D6 || Data pin 6
|-
| 13 || D7 || Data pin 7 (MSB)
|-
| 14 || SEL || Select pin (active low input) - selects the card for communication
|-
| 15 || 5v || +5V rail to power the card
|-
| 16 || RD || Read enable pin (active low input)
|-
| 17 || WR || Write enable pin (active low input)
|-
| 18 || WAIT || Wait indication (active low output)
|}

When trying to access VRAM, if the VRAM is being used by the card, then WAIT will be pulled low to tell the CPU not to end the current operation until after the WAIT pin goes high again. After WAIT goes high, wait at least 31.25ns for the read/write operation to complete before releasing any control lines or changing any data/address lines. Never read data while WAIT is low, and wait 31.25ns after WAIT goes high before reading the data to the CPU. WAIT only becomes low when trying to read from or write to VRAM; otherwise WAIT is always high.

Each access cycle should last at least 31.25ns, and SEL should be de-asserted between cycles. Any conventional processor like Z80, 8086, 6502, etc, should have no issue with WAIT or access cycles below an operating frequency of 32Mhz, regardless of the speed of the card. There may be exceptions to this, but there are no known exceptions.

=== Software Protocol ===

{| class="wikitable"
|+ Card Registers
|-
! Register !! Purpose
|-
| 0 || uPD7220 command register (uPD7220 A0 = 0)
|-
| 1 || uPD7220 parameter register (uPD7220 A0 = 1)
|-
| 2 || Card configuration register (write only)
|-
| 3 || Direct VRAM access (accessing this may cause WAIT to go low)
|-
| 4 || VRAM Address bits 0-7 (write only)
|-
| 5 || Reserved - for now same as register 4
|-
| 6 || VRAM Address bits 8-15 (write only)
|-
| 7 || Reserved - for now same as register 6
|}

For this card, a driver should first configure register 2 for the selected video mode and card interface configuration. This register has various bits to tell the card what to do:

{| class="wikitable" style="width:50%"
|+ Configuration Register Bits
|-
! Bit !! Purpose
|-
| 0 || Enables automatic counting of the VRAM address registers if set. If reset, then the VRAM address registers do not change when VRAM is written. More on this later.
|-
| 1 || Setting this bit enables the card's wide mode circutry. When reset, one pixel will be output every other clock cycle. This should match the setting on the uPD7220 IC.
|-
| 2 || Enables automatic double buffering. When set, draws to VRAM from the host CPU or the uPD7220 will happen on the opposite buffer as the one displaying. Setting this halfs the available VRAM for displaying.
|-
| 3 || Reserved
|-
| 4 || Reserved
|-
| 5 || Reserved
|-
| 6 || Reserved
|-
| 7 || Controls which buffer is displaying. Changing this bit will swap the currently displaying buffer. Only works in automatic double buffer mode.
|}

It is recommended to keep track of what buffer is currently displaying, and perhaps this entire configuration register, so that the selected buffer can be switched. This register is important for controlling how the CPU accesses VRAM, how smooth the display is, and the way the image data is displayed. Generally, automatic double buffering is recommended if the resolution demands less than half of the available VRAM, as
double buffering makes the display smoother by removing visual artifacts due to drawing, but doubles VRAM demand.

You can read the [http://www.vintagecomputer.net/fjkraan/comp/qx10/doc/nec7220.pdf programming manual] to get a detailed understanding of how to program the uPD7220, but I will also provide an abridged
version here. Once the card's configuration register is set, the uPD7220 must be initialized. The uPD7220 requires a sequence of commands to be sent to set it up:
1. A reset command (write 0x00 to address 0x01)
** This must be followed by parameter bytes, described below
2. Setting the video mode to master (write 0x6f to address 0x01)
3. Configuring the pitch
4. Initializing the PRAM
** PRAM is some internal memory in the uPD7220, which configures how it accesses memory, and probably some other things
5. CCHAR command to configure the character characteristics
6. Disabling zoom (write 0x46 to 0x01, then 0x00 to 0x00)
7. Starting the display (write 0x6B to 0x01)
8. Disable blanking (write 0x0D to 0x01)

My driver also seems to issue a FIGS command at the end of startup, but this may not be necessary.

Each command starts with a write to address 0x01, and for each parameter a write to address 0x00 follows. Each command I describe will proceed this way, with the first byte being the command byte written to
address 0x01, and all following bytes being parameters written to address 0x00. At the end I will have some example code in C which provides as both an example and an additional explanation.

The first command is the reset command; here is the format:

{| class="wikitable" style="width:50%"
|+ The Reset Command
|-
! Address !! Value / Description
|-
| 1 || 0x00
|-
| 0 || Operation mode. Discussed below.
|-
| 0 || Horizontal display words minus two. Must be an even number. This is equal to ((horizontal_pixels / 4) - 2). Wide mode does not affect this.
|-
| 0 || Lower 5 bits are the HSync width minus 1, in words. Upper 3 bits are the lower 3 bits of the VSync width.
|-
| 0 || Lower 2 bits are the upper 2 bits of the VSync width. Upper 6 bits are the horizontal front porch width minus 1.
|-
| 0 || Horizontal back porch width minus one. Upper two bits must be zero.
|-
| 0 || Vertical front porch width minus one. Upper two bits must be zero.
|-
| 0 || Number of display lines per frame, lower 8 bits.
|-
| 0 || Lower 2 bits are the upper 2 bits of the number of display lines per frame. Upper 6 bits are the vertical back porch length.
|}

Note that the vertical field sizes do not have numbers subtracted from them, but the horizontal field sizes have one or two subtracted from them. If this description is confusing, the uPD7220 manual provided above does contain a nice illustration you may consider looking at.

The operation mode is a bitmask, which controls interlacing, character or graphic mode, as well as DRAM refresh and if drawing is allowed during an active display cycle. Here are some of the options that
one can OR together to control the operation mode:

{| class="wikitable" style="width:50%"
|+ Operation control bits
|-
! Bitmask !! Selected Option
|-
| 0x00 || Leave bits 5 and 1 zero to have mixed character and graphics mode.
|-
| 0x02 || Enables just graphics mode
|-
| 0x20 || Enables just character mode
|-
| 0x00 || Leave bits 3 and 0 zero to disable interlacing
|-
| 0x08 || Enables interlacing
|-
| 0x09 || Enables "Interlaced repeat field for character displays". Read the manual for more information.
|-
| 0x04 || Enables DRAM refresh cycles - not used on this uPD7220 card, as static RAM is used.
|-
| 0x10 || Disables drawing during active display time. Enabling this is recommended.
|}

Generally 0x12 is a good setting for this card, unless you intend on using character mode. 0x10 will also work as a good mode.

The second command one must send is 0x6f, again written to address 0x01, and it does not take any parameters. The third command is the PITCH command:

{| class="wikitable" style="width:50%"
|+ The Pitch Command
|-
! Address !! Value / Description
|-
| 1 || 0x47
|-
| 0 || Number of memory words per line. Usually the same as the number of display words per line. Generally equal to (horizontal_pixels / 4). The only reason it would differ, is if the
|}

The fourth command is a PRAM command, which writes data to the uPD7220 parameter RAM. Here is a recommended usage of the command (although other usages are possible, again read the manual for more info):

{| class="wikitable" style="width:50%"
|+ The PRAM Command
|-
! Address !! Value / Description
|-
| 1 || 0x70 (starts PRAM write at PRAM byte 0)
|-
| 0 || Display partition 1 starting address (lower 8 bits) - it is recommended to leave this as zero.
|-
| 0 || Display partition 1 starting address (bits 8-16) - it is recommended to leave this as zero.
|-
| 0 || Lower 2 bits are the display partition 1 starting address (upper 2 bits). Upper 4 bits are the lower 4 bits of the display partition length, in horizontal lines (NOT words). Bits 2 and 3 should be left as zeros.
|-
| 0 || Lower 6 bits are the upper 6 bits of the image partition length, in horizontal lines (NOT words). Bit 6 (0x40) indicates it is a graphics area, otherwise it is a character area if in mixed mode. Bit 7 (0x80) enables wide mode - ensure to set this bit if you are using wide mode.
|}

The parameter RAM has more variables, but only these really need to be specified. There is another display partition that one can use, and configuration options for drawing and characters, later in the PRAM.

If your display mode uses wide mode, then be sure to set the MSB of the fourth parameter byte of this command, otherwise the memory access will be incorrect for wide mode.

Next, the CCHAR command is used to define the cursor and character characteristics:

{| class="wikitable" style="width:50%"
|+ The CCHAR Command
|-
! Address !! Value / Description
|-
| 1 || 0x4B
|-
| 0 || Setting the MSB will enable the cursor in character mode. The lower 5 bits are the number of lines per character row minus one. My driver leaves this byte as zero.
|-
| 0 || Lower 5 bits define the cursor top line number in the row. Bit 5 makes the cursor steady if set, or blinking if reset. Upper two bits are the lower two bits of the blink rate. My driver leaves this byte as 0xC0.
|}

This is sufficient for non-interlaced modes, but interlaced modes require this command to get a third byte.

Zoom must be disabled with a 0x46 write to address 0x01, followed by writing 0x00 to address 0x00. At this point we can finally enable the display and disable blanking by writing commands 0x6B, then 0x0D, to address 0x01.

My driver executes a FIGS command last, although this probably is not necessary. Just in case, here is the command sequence:
1. 0x4C to address 0x01
2. 0x02 to address 0x00
3. 0x00 to address 0x00
4. 0x00 to address 0x00

Here is my code which executes this exact sequence:

<pre>
void setup_upd7220() {
// Reset command
write(1, 0);
write(0, 0x10); // operation mode: draw only during blanking
write(0, HORIZ_WORDS - 2);
write(0, (VERT_SYNC << 5) | (HORIZ_SYNC - 1));
write(0, ((HORIZ_FRONT_PORCH - 1) << 2) | (VERT_SYNC >> 3));
write(0, (HORIZ_BACK_PORCH - 1) & 63);
write(0, VERT_FRONT_PORCH & 63);
write(0, VERT_PIXELS & 255);
write(0, (VERT_BACK_PORCH << 2) | (VERT_PIXELS >> 8));

// set master video mode
write(1, 0x6f);

// set pitch
write(1, 0x47);
write(0, HORIZ_WORDS);

// set some PRAM values
write(1, 0x70);
write(0, 0x00);
write(0, 0x00);
write(0, (VERT_PIXELS << 4) & 255);
write(0, (VERT_PIXELS >> 4) | (WIDE_MODE ? 8 : 0));//*/

// Set character and cursor characteristics
write(1, 0x4B);
write(0, 0x00);
write(0, 0xC0);

// set zoom
write(1, 0x46);
write(0, 0x00);

// Enable the display
write(1, 0x6b);

// Disable blanking
write(1, 0x0D);

// This is probably not necessary
write(1, 0x4c);
write(0, 0x02);
write(0, 0x00);
write(0, 0x00);
}
</pre>

UPD7220 Video Card (Revision 2)

2024-06-14T04:17:08Z

Nuclear: Software protocol checkpoint

The uPD7220 Video Card revision 2 is a video card with 128KB of VRAM using the uPD7220 GDC or its variants. It operates at a maximum clock speed of 32Mhz. The card is based on the original uPD7220 card I (Dylan Brophy) made, which had half the VRAM and generally was far simpler. This card solves several issues with the older card, at the cost of greater size and complexity.

== Detailed Specifications ==

* 16-color VGA output
* 128KB of RAM
** 4 RAM chips, 32KB each, 25ns access and write time
** 16 bit bus (8 bits per chip, two chips per byte)
** 4 color bits per pixel, 4 pixels per word in RAM
*** Maximum 262144 pixels (hardware double buffering disabled)
**** Suggested resolutions: 544x480, 640x408
*** Maximum 131072 pixels (hardware double buffering enabled)
**** Suggested resolutions: 448x288, 400x300
* uPD7220 at up to 24Mhz, Z7220 at up to 32Mhz
* uPD7220 wide mode supported
** Allows higher pixel clock frequencies, for higher resolutions and lower visible display times
** Accesses two VRAM words per uPD7220 clock cycle
* Direct access to VRAM is provided to the host CPU

== Video Modes ==

It is assumed that the reader is familiar with VGA display timings. If not, then it is recommended to study it, or to use the video timing calculator and to leave the card in wide mode.

The uPD7220 was invented before the VGA standard, and due to this, was not designed to output a VGA signal. Since VGA was designed to drive CRT monitors, as was the uPD7220, it turns out that
they are fairly compatible. VGA timings work perfectly fine, but to compute them one must keep in mind the pixel and uPD7220 clocks. The uPD7220 clock is always one fourth of the card's clock
speed.

For common VGA signal timings, I would recommend looking at this very useful site: [http://tinyvga.com/vga-timing TinyVGA signal timings]

One must take the timings and convert them to the correct resolution. For an example, let's convert the 640x480 VGA standard timings to a 400x400 resolution. Here are the video timings from [http://tinyvga.com/vga-timing/640x480@60Hz TinyVGA's 640x480 60hz page]:

{| class="wikitable"
|+ Horizontal Timing
|-
! Region !! Pixels !! Microseconds
|-
| Visible area || 640 || 25.4220
|-
| Front porch || 16 || 0.6356
|-
| Sync pulse || 96 || 3.8133
|-
| Back porch || 48 || 1.9067
|-
| Whole line || 800 || 31.778
|}

{| class="wikitable"
|+ Vertical Timing
|-
! Region !! Lines
|-
| Visible area || 480
|-
| Front porch || 10
|-
| Sync pulse || 2
|-
| Back porch || 33
|-
| Whole frame || 525
|}

First, we need to decide on a clock frequency for our card. 24Mhz is slower than the 25.175Mhz recommended, and this will make our pixels wider by about 5%. However, a 24Mhz clock will run our uPD7220 at 6Mhz,
right at the maximum frequency, and 25.175Mhz would overclock it. We will select 24Mhz, as the 5% elongation of pixels is too small to care about, and the timings should be compatible with the uPD7220 IC. We
will enable wide mode, so our pixel clock is set at 24Mhz (the same as the card - without wide mode it would be 12Mhz, or half). This keeps the pixel width close to the intended width. Importantly, this change in clock speed will change the necessary timings for the video signal. Since each uPD7220 clock cycle is 166.7ns at 6Mhz, and each word is two cycles, we will be dividing the horizontal porch and sync widths
by 333.3ns to get the number of words for each of the regions. We cannot compute this yet though, because the visible region still needs to be adjusted for our new resolution.

For our application, we need less pixels, but still need to meet the timing spec. To achieve this, we can increase the back porch and reduce the visible region until we have the resolution we want. We do this
on both the x and y axes. This works because, during the back porch, the video signal is sent a black signal. On older monitors, this corresponds to a dark box around the image, and newer monitors will treat it
as a blank region. Fundamentally, the monitor will still generally treat it as a 640x480, standard VGA signal, because we haven't encroached on the porches, and we haven't changed/moved the sync signals. To
compute the width of the new visible area, we multiply the number of horizontal pixels by the pixel clock period: 41.67ns * 400 pixels = 16.67us. From this, we can calculate the new horizontal front porch, and
then we can recompute the lines per vertical video region:

{| class="wikitable"
|+ Updated Horizontal Timing
|-
! Region !! Microseconds
|-
| Visible area || 16.67
|-
| Front porch || 0.6356
|-
| Sync pulse || 3.8133
|-
| Back porch || 10.6620
|-
| Whole line || 31.7776
|}

The back porch becomes much wider. All we did was move the time over from the visible area to the back porch, such that the visible area has the correct number of pixels at our clock frequency. The vertical
regions are adjusted similarly, but the math is much simpler, because we are only trying to keep constant the number of lines:

{| class="wikitable"
|+ Vertical Timing
|-
! Region !! Lines
|-
| Visible area || 400
|-
| Front porch || 60
|-
| Sync pulse || 2
|-
| Back porch || 63
|-
| Whole frame || 525
|}

You will notice that I added lines to both the front and back vertical porches. This is because the uPD7220 cannot output more than 63 of each porch, so I needed to add to both to obey this limitation. For
lower resolutions, it is usually acceptable to reduce the total number of lines to obey these limitations. It is important, however, that in such a case the horizontal lines are made longer to keep the refresh rate at 60hz, and that the video settings are tested to work on the monitor.

At this point we have the description of the mode we want, now we can convert it into the numbers used by the card. The vertical timings are already in the correct format, but the horizontal timing still must
be converted. To do this, we need to get the number of memory cycles (not uPD7220 clock cycles) for each horizontal region, which is the time for two uPD7220 clock cycles. The exception is the visible region,
which is computed from the amount of memory used to represent the data (4 pixels per word, one word accessed per uPD7220 cycle in wide mode). For the visible region, we divide the number of pixels by 4, and
for the other regions, we divide the time by 333.3ns and round to the nearest whole number. Here is the result:

{| class="wikitable"
|+ uPD7220 timing settings
|-
! Region !! Words
|-
| Visible area || 100
|-
| Front porch || 1.907 => 2
|-
| Sync pulse || 11.4399 => 11
|-
| Back porch || 31.986 => 32
|}

Any VGA monitor should accept these signal timings for a 400x400 resolution. For video memory consumtion, this needs 400 * 400 / 4 = 40000 words of memory. The card has 65536 words total, but only
32768 if automatic double buffering is enabled, so we cannot enable automatic double buffering for this resolution. So, we must enable wide mode and disable double buffering for this video mode.

'''Card Specific Details: Wide Mode'''

This card can reach quite high clock speeds for the uPD7220, and to maintain this high speed for such slow chips, wide mode is used. This allows twice as many pixels to be output per uPD7220 clock cycle. This can be used either to increase the maximum resolution, or to reduce the display time. Reducing the display time gives the uPD7220 and host processor more time to draw to the screen. On the other hand, due to
the high speeds used in wide mode, there is also typically more data that must be written to the display per frame, thus putting more pressure on the host processor. The balance in display characteristics depends on the application.

Due to wide mode support, the card's clock is 4x the uPD7220's clock. When doing calculations for video, this must be kept in mind. If wide mode is disabled, then the pixel clock is only half the card's clock. If the video timing math does not account for this, then the video signal timing will be incorrect.

== Communication with the Host Processor ==

The hardware connection uses a fairly simple 8-bit parallel bus for data exchange. Once connected, the software can read from and write to several registers and addresses on the card to control it.

=== Hardware Protocol ===

Here is a pinout of the card:

{| class="wikitable"
|+ Card Pinout
|-
! Pin !! Name !! Description
|-
| 1 || A0 || Address pin 0 (LSB)
|-
| 2 || A1 || Address pin 1
|-
| 3 || A2 || Address pin 2 (MSB)
|-
| 4 || NC || No connection: this is the key pin and should be blocked
|-
| 5 || GND || Ground connection
|-
| 6 || D0 || Data pin 0 (LSB)
|-
| 7 || D1 || Data pin 1
|-
| 8 || D2 || Data pin 2
|-
| 9 || D3 || Data pin 3
|-
| 10 || D4 || Data pin 4
|-
| 11 || D5 || Data pin 5
|-
| 12 || D6 || Data pin 6
|-
| 13 || D7 || Data pin 7 (MSB)
|-
| 14 || SEL || Select pin (active low input) - selects the card for communication
|-
| 15 || 5v || +5V rail to power the card
|-
| 16 || RD || Read enable pin (active low input)
|-
| 17 || WR || Write enable pin (active low input)
|-
| 18 || WAIT || Wait indication (active low output)
|}

When trying to access VRAM, if the VRAM is being used by the card, then WAIT will be pulled low to tell the CPU not to end the current operation until after the WAIT pin goes high again. After WAIT goes high, wait at least 31.25ns for the read/write operation to complete before releasing any control lines or changing any data/address lines. Never read data while WAIT is low, and wait 31.25ns after WAIT goes high before reading the data to the CPU. WAIT only becomes low when trying to read from or write to VRAM; otherwise WAIT is always high.

Each access cycle should last at least 31.25ns, and SEL should be de-asserted between cycles. Any conventional processor like Z80, 8086, 6502, etc, should have no issue with WAIT or access cycles below an operating frequency of 32Mhz, regardless of the speed of the card. There may be exceptions to this, but there are no known exceptions.

=== Software Protocol ===

{| class="wikitable"
|+ Card Registers
|-
! Register !! Purpose
|-
| 0 || uPD7220 command register (uPD7220 A0 = 0)
|-
| 1 || uPD7220 parameter register (uPD7220 A0 = 1)
|-
| 2 || Card configuration register (write only)
|-
| 3 || Direct VRAM access (accessing this may cause WAIT to go low)
|-
| 4 || VRAM Address bits 0-7 (write only)
|-
| 5 || Reserved - for now same as register 4
|-
| 6 || VRAM Address bits 8-15 (write only)
|-
| 7 || Reserved - for now same as register 6
|}

For this card, a driver should first configure register 2 for the selected video mode and card interface configuration. This register has various bits to tell the card what to do:

{| class="wikitable" style="width:50%"
|+ Configuration Register Bits
|-
! Bit !! Purpose
|-
| 0 || Enables automatic counting of the VRAM address registers if set. If reset, then the VRAM address registers do not change when VRAM is written. More on this later.
|-
| 1 || Setting this bit enables the card's wide mode circutry. When reset, one pixel will be output every other clock cycle. This should match the setting on the uPD7220 IC.
|-
| 2 || Enables automatic double buffering. When set, draws to VRAM from the host CPU or the uPD7220 will happen on the opposite buffer as the one displaying. Setting this halfs the available VRAM for displaying.
|-
| 3 || Reserved
|-
| 4 || Reserved
|-
| 5 || Reserved
|-
| 6 || Reserved
|-
| 7 || Controls which buffer is displaying. Changing this bit will swap the currently displaying buffer. Only works in automatic double buffer mode.
|}

It is recommended to keep track of what buffer is currently displaying, and perhaps this entire configuration register, so that the selected buffer can be switched. This register is important for controlling how the CPU accesses VRAM, how smooth the display is, and the way the image data is displayed. Generally, automatic double buffering is recommended if the resolution demands less than half of the available VRAM, as
double buffering makes the display smoother by removing visual artifacts due to drawing, but doubles VRAM demand.

You can read the [http://www.vintagecomputer.net/fjkraan/comp/qx10/doc/nec7220.pdf programming manual] to get a detailed understanding of how to program the uPD7220, but I will also provide an abridged
version here. Once the card's configuration register is set, the uPD7220 must be initialized. The uPD7220 requires a sequence of commands to be sent to set it up:
1. A reset command (write 0x00 to address 0x01)
** This must be followed by parameter bytes, described below
2. Setting the video mode to master (write 0x6f to address 0x01)
3. Configuring the pitch
4. Initializing the PRAM
** PRAM is some internal memory in the uPD7220, which configures how it accesses memory, and probably some other things
5. CCHAR command to configure the character characteristics
6. Disabling zoom (write 0x46 to 0x01, then 0x00 to 0x00)
7. Starting the display (write 0x6B to 0x01)
8. Disable blanking (write 0x0D to 0x01)

My driver also seems to issue a FIGS command at the end of startup, but this may not be necessary.

Each command starts with a write to address 0x01, and for each parameter a write to address 0x00 follows. Each command I describe will proceed this way, with the first byte being the command byte written to
address 0x01, and all following bytes being parameters written to address 0x00. At the end I will have some example code in C which provides as both an example and an additional explanation.

The first command is the reset command; here is the format:

{| class="wikitable" style="width:50%"
|+ The Reset Command
|-
! Address !! Value / Description
|-
| 1 || 0x00
|-
| 0 || Operation mode. Discussed below.
|-
| 0 || Horizontal display words minus two. Must be an even number. This is equal to ((horizontal_pixels / 4) - 2). Wide mode does not affect this.
|-
| 0 || Lower 5 bits are the HSync width minus 1, in words. Upper 3 bits are the lower 3 bits of the VSync width.
|-
| 0 || Lower 2 bits are the upper 2 bits of the VSync width. Upper 6 bits are the horizontal front porch width minus 1.
|-
| 0 || Horizontal back porch width minus one. Upper two bits must be zero.
|-
| 0 || Vertical front porch width minus one. Upper two bits must be zero.
|-
| 0 || Number of display lines per frame, lower 8 bits.
|-
| 0 || Lower 2 bits are the upper 2 bits of the number of display lines per frame. Upper 6 bits are the vertical back porch length.
|}

Note that the vertical field sizes do not have numbers subtracted from them, but the horizontal field sizes have one or two subtracted from them. If this description is confusing, the uPD7220 manual provided above does contain a nice illustration you may consider looking at.

The operation mode is a bitmask, which controls interlacing, character or graphic mode, as well as DRAM refresh and if drawing is allowed during an active display cycle. Here are some of the options that
one can OR together to control the operation mode:

{| class="wikitable" style="width:50%"
|+ Operation control bits
|-
! Bitmask !! Selected Option
|-
| 0x00 || Leave bits 5 and 1 zero to have mixed character and graphics mode.
|-
| 0x02 || Enables just graphics mode
|-
| 0x20 || Enables just character mode
|-
| 0x00 || Leave bits 3 and 0 zero to disable interlacing
|-
| 0x08 || Enables interlacing
|-
| 0x09 || Enables "Interlaced repeat field for character displays". Read the manual for more information.
|-
| 0x04 || Enables DRAM refresh cycles - not used on this uPD7220 card, as static RAM is used.
|-
| 0x10 || Disables drawing during active display time. Enabling this is recommended.
|}

Generally 0x12 is a good setting for this card, unless you intend on using character mode. 0x10 will also work as a good mode.

The second command one must send is 0x6f, again written to address 0x01, and it does not take any parameters. The third command is the PITCH command:

{| class="wikitable" style="width:50%"
|+ The Pitch Command
|-
! Address !! Value / Description
|-
| 1 || 0x47
|-
| 0 || Number of memory words per line. Usually the same as the number of display words per line. Generally equal to (horizontal_pixels / 4). The only reason it would differ, is if the
|}

The fourth command is a PRAM command, which writes data to the uPD7220 parameter RAM. Here is a recommended usage of the command (although other usages are possible, again read the manual for more info):

UPD7220 Video Card (Revision 2)

2024-06-14T01:20:27Z

Nuclear: Finish video modes section

UPD7220 Video Card (Revision 2)

2024-06-14T01:08:53Z

Nuclear: Video modes tutorial; checkpoint/saving work

UPD7220 Video Card (Revision 2)

2024-06-14T00:27:23Z

Nuclear: Fix table formatting

UPD7220 Video Card (Revision 2)

2024-06-14T00:22:35Z

Nuclear: Checkpoint for programming guide and video mode information

UPD7220 Video Card (Revision 2)

2024-06-13T22:49:48Z

Nuclear: Create UPD7220 Video Card (Revision 2) page

Teensy 4.1 Computer

2024-06-13T21:51:23Z

Nuclear: Add more images to the Expansion Ports section

File:Teensy4.1 computer card connector diagram.png

2024-06-13T21:50:14Z

Nuclear:

File:Teensy4.1 computer external headers 1.png

2024-06-13T21:48:39Z

Nuclear:

Teensy 4.1 Computer

2024-06-13T21:47:33Z

Nuclear: Added information about the parallel port

The Teensy 4.1 Computer is more or less described by its name: Its a carrier board for the Teensy 4.1 which provides four USB ports, an Ethernet port, Hi-Fi audio, and several convenient expansion ports.

== Detailed Specifications ==

'''USB:'''

* TUSB2046 USB Hub, providing 4 USB A ports
* Each port has a maximum of 1.5A output - the port will shutdown due to overcurrent above this
* Board power provides a maximum of 2A to the 5v supply
** one should be aware of this when considering the power used by USB devices

'''Audio:'''

* I2S control connected to Teensy I2S 2
* PCM5102 ADC for providing stereo sound
* OPA1688 for the amplifier
* 3.5mm audio jack, maximum 75mA per channel
* Separate ground, connected to main ground through a ferrite bead
* Separate 3.3v and 5v supplies from linear regulators to reduce noise
** Note: 5v line will come from main 5v rail if only powered from USB

'''Power:'''

* 2A 5v buck regulator (Exact part is the VR20S05)
* PMOS switches to prevent regulator backfeeding from USB and to control power flow (U16, U17, and U18 on the PCB)
* External VIN accepted from 8v to 20v
* Separate 5v and 3.3v supplies for audio circutry
* Barrel jack and screw terminal connections for VIN

'''Expansion Ports'''

* I2S, SPI, I2C, and Serial expansion ports
* 5v-capable 8-bit parallel bus port, with 3-bit address, WR, RD, select, and WAIT lines
* Two larger expansion ports, each providing a '''3.3v compatible''' 8-bit parallel bus, various protocols like I2C and SPI, power, and GPIO

== The Audio Circuit ==

[[File:Teensy41_Computer_Audio_circuit.png|thumb|Teensy 4.1 Computer audio circuit|600px]]

The Teensy 4.1 is connected to the audio circuit via the Teensy's I2S 2 port. This connection goes to the PCM5102 ADC. As is recommended in the PCM5102's datasheet, filtering is added to the output, however the filter used on this board is a bit stronger, using a 4.7nF capacitor instead of the 2.2nF capacitor recommended in the datasheet. The filter cutoff is still far above human perception, at 72kHz, and should filter high frequency noise a bit better. The connection to the OPA1688 is DC, not AC, coupled, but this is according to the recommendations in the OPA1688 datasheet. The gain of the amplifier is configured to be 1, so the output voltage of the amp should match the ADC's output voltage, and be in the range of 0v to 3.3v. A voltage divider is used to activate the PCM5102's soft mute function when the 5v line drops, which is designed to prevent any pops in the audio when the power is disconnected.

The circuit was designed with audio quality, but not energy efficiency, in mind. The circuit may sink as much as 400mA from VIN, and an additional 40mA from the main 5v line. However, when the audio circuit is idle, it should be less than 50mA all together. The 3.5mm audio jack can provide a maximum of 75mA per channel.

'''Example Code:'''
<pre>
#include <Audio.h>
#include <SD.h>

// GUItool: begin automatically generated code
AudioPlaySdWav playSdWav1; //xy=719,389
AudioOutputI2S2 i2s2_1; //xy=892,388
AudioConnection patchCord1(playSdWav1, 0, i2s2_1, 0);
AudioConnection patchCord2(playSdWav1, 1, i2s2_1, 1);
// GUItool: end automatically generated code

void setup() {
Serial.begin(115200);
AudioMemory(10);

if (!(SD.begin(BUILTIN_SDCARD))) {
// stop here, but print a message repetitively
while (1) {
Serial.println("Unable to access the SD card");
delay(500);
}
}

Serial.println("Playing audio.wav...");
playSdWav1.play("audio.wav");
}

void loop() {
// Do nothing forever
}
</pre>

== USB Ports ==

[[File:Teensy4.1_computer_USB_schematic.png|thumb|Teensy 4.1 Computer USB circuit|600px]]

The Teensy 4.1's builtin USB port is connected directly to a TUSB2046 IC, which is a USB hub and provides four downstream ports. Each port has overcurrent protection, with a maximum allowed current of 1.5A. There are also TVS diodes on all USB data lines on the downstream ports, provided by three TPD3E001DRLR ICs. Other than that, each downstream USB port has two 15k pulldowns - one on each data line.

'''Example Code:'''

The best example is found in the Mouse_KeyboardBT example from the USBHost_t36 library, which is included in the TeensyDuino package. For convenience, I have included a stripped down version of it below:
<pre>
#include "USBHost_t36.h"

USBHost myusb;
USBHub hub1(myusb);
USBHub hub2(myusb);
KeyboardController keyboard1(myusb);
KeyboardController keyboard2(myusb);
USBHIDParser hid1(myusb);
USBHIDParser hid2(myusb);
USBHIDParser hid3(myusb);
USBHIDParser hid4(myusb);
USBHIDParser hid5(myusb);
MouseController mouse1(myusb);

BluetoothController bluet(myusb); // version assumes it already was paired

USBDriver *drivers[] = {&hub1, &hub2, &keyboard1, &keyboard2, &bluet, &hid1, &hid2, &hid3, &hid4, &hid5};

#define CNT_DEVICES (sizeof(drivers)/sizeof(drivers[0]))
const char * driver_names[CNT_DEVICES] = {"Hub1", "Hub2", "KB1", "KB2", "Bluet", "HID1" , "HID2", "HID3", "HID4", "HID5"};

bool driver_active[CNT_DEVICES] = {false, false, false, false, false, false, false, false, false, false};

// Lets also look at HID Input devices
USBHIDInput *hiddrivers[] = {&mouse1};

#define CNT_HIDDEVICES (sizeof(hiddrivers)/sizeof(hiddrivers[0]))
const char * hid_driver_names[CNT_HIDDEVICES] = {"Mouse1"};

bool hid_driver_active[CNT_HIDDEVICES] = {false};

BTHIDInput *bthiddrivers[] = {&keyboard1, &mouse1};
#define CNT_BTHIDDEVICES (sizeof(bthiddrivers)/sizeof(bthiddrivers[0]))
const char * bthid_driver_names[CNT_BTHIDDEVICES] = {"Keyboard(BT)", "Mouse(BT)"};
bool bthid_driver_active[CNT_BTHIDDEVICES] = {false};

bool show_changed_only = false;

uint8_t joystick_left_trigger_value = 0;
uint8_t joystick_right_trigger_value = 0;
uint64_t joystick_full_notify_mask = (uint64_t) - 1;

void setup() {
while (!Serial); // wait for Arduino Serial Monitor
Serial.begin(115200);
myusb.begin();
keyboard1.attachPress(OnPress);
keyboard2.attachPress(OnPress);
}

void loop() {
// check to see if the device list has changed:
UpdateActiveDeviceInfo();

myusb.Task();

if (mouse1.available()) {
Serial.print("Mouse: buttons = ");
Serial.print(mouse1.getButtons());
Serial.print(", mouseX = ");
Serial.print(mouse1.getMouseX());
Serial.print(", mouseY = ");
Serial.print(mouse1.getMouseY());
Serial.print(", wheel = ");
Serial.print(mouse1.getWheel());
Serial.print(", wheelH = ");
Serial.print(mouse1.getWheelH());
Serial.println();
mouse1.mouseDataClear();
}
}

void OnPress(int key)
{
Serial.print("key '");
switch (key) {
case KEYD_UP : Serial.print("UP"); break;
case KEYD_DOWN : Serial.print("DN"); break;
case KEYD_LEFT : Serial.print("LEFT"); break;
case KEYD_RIGHT : Serial.print("RIGHT"); break;
case KEYD_INSERT : Serial.print("Ins"); break;
case KEYD_DELETE : Serial.print("Del"); break;
case KEYD_PAGE_UP : Serial.print("PUP"); break;
case KEYD_PAGE_DOWN: Serial.print("PDN"); break;
case KEYD_HOME : Serial.print("HOME"); break;
case KEYD_END : Serial.print("END"); break;
case KEYD_F1 : Serial.print("F1"); break;
case KEYD_F2 : Serial.print("F2"); break;
case KEYD_F3 : Serial.print("F3"); break;
case KEYD_F4 : Serial.print("F4"); break;
case KEYD_F5 : Serial.print("F5"); break;
case KEYD_F6 : Serial.print("F6"); break;
case KEYD_F7 : Serial.print("F7"); break;
case KEYD_F8 : Serial.print("F8"); break;
case KEYD_F9 : Serial.print("F9"); break;
case KEYD_F10 : Serial.print("F10"); break;
case KEYD_F11 : Serial.print("F11"); break;
case KEYD_F12 : Serial.print("F12"); break;
default: Serial.print((char)key); break;
}
Serial.print("' ");
Serial.println(key);
}

//=============================================================================
// UpdateActiveDeviceInfo
//=============================================================================
void UpdateActiveDeviceInfo() {
for (uint8_t i = 0; i < CNT_DEVICES; i++) {
if (*drivers[i] != driver_active[i]) {
if (driver_active[i]) {
Serial.printf("*** Device %s - disconnected ***\n", driver_names[i]);
driver_active[i] = false;
} else {
Serial.printf("*** Device %s %x:%x - connected ***\n", driver_names[i], drivers[i]->idVendor(), drivers[i]->idProduct());
driver_active[i] = true;

const uint8_t *psz = drivers[i]->manufacturer();
if (psz && *psz) Serial.printf(" manufacturer: %s\n", psz);
psz = drivers[i]->product();
if (psz && *psz) Serial.printf(" product: %s\n", psz);
psz = drivers[i]->serialNumber();
if (psz && *psz) Serial.printf(" Serial: %s\n", psz);

if (drivers[i] == &bluet) {
const uint8_t *bdaddr = bluet.myBDAddr();
// remember it...
Serial.printf(" BDADDR: %x:%x:%x:%x:%x:%x\n", bdaddr[0], bdaddr[1], bdaddr[2], bdaddr[3], bdaddr[4], bdaddr[5]);
}
}
}
}
for (uint8_t i = 0; i < CNT_HIDDEVICES; i++) {
if (*hiddrivers[i] != hid_driver_active[i]) {
if (hid_driver_active[i]) {
Serial.printf("*** HID Device %s - disconnected ***\n", hid_driver_names[i]);
hid_driver_active[i] = false;
} else {
Serial.printf("*** HID Device %s %x:%x - connected ***\n", hid_driver_names[i], hiddrivers[i]->idVendor(), hiddrivers[i]->idProduct());
hid_driver_active[i] = true;

const uint8_t *psz = hiddrivers[i]->manufacturer();
if (psz && *psz) Serial.printf(" manufacturer: %s\n", psz);
psz = hiddrivers[i]->product();
if (psz && *psz) Serial.printf(" product: %s\n", psz);
psz = hiddrivers[i]->serialNumber();
if (psz && *psz) Serial.printf(" Serial: %s\n", psz);
}
}
}
// Then Bluetooth devices
for (uint8_t i = 0; i < CNT_BTHIDDEVICES; i++) {
if (*bthiddrivers[i] != bthid_driver_active[i]) {
if (bthid_driver_active[i]) {
Serial.printf("*** BTHID Device %s - disconnected ***\n", bthid_driver_names[i]);
bthid_driver_active[i] = false;
} else {
Serial.printf("*** BTHID Device %s - connected ***\n", bthid_driver_names[i]); Serial.flush();
bthid_driver_active[i] = true;
#if 0

const uint8_t *psz = bthiddrivers[i]->manufacturer();
if (psz && *psz) Serial.printf(" manufacturer: %s\n", psz);
psz = bthiddrivers[i]->product();
if (psz && *psz) Serial.printf(" product: %s\n", psz);
psz = bthiddrivers[i]->serialNumber();
if (psz && *psz) Serial.printf(" Serial: %s\n", psz);
#endif
}
}
}
}
</pre>

'''Known Issues:'''
* Version 1.1 of the board leaves TUSB2046's reset line floating. This can be remedied by connecting the TUSB2046's reset line to some other circuit, although this is error prone.

== Power ==

[[File:Teensy4.1_computer_power_circuit.png|thumb|Teensy 4.1 Computer power circuitry|500px]]

The computer's power supply accepts input from four primary sources:
* Barrel jack DC input, 8v to 20v, provides 2A to 5v line
* Screw terminal block, 8v to 20v, provides 2A to 5v line
* Teensy 4.1 micro USB port, 5v input, current limit depends on USB power source
* Expansion ports
** Direct to 5v line, only limited by source current. This allows one to surpass the typical 2A limit on the 5v line.
** Direct to VIN, accepts 8v to 20v. 5v line limited to 2A.
** Direct to 3.3v line, only limited by source current. This can be used to relieve stress from the Teensy 4.1's 3.3v regulator, if needed.

[[File:Teensy4.1_computer_audio_power.png|thumb|Teensy 4.1 Computer audio power circuits|800px]]
There are a few different power planes on the board:
* VIN, 8v to 20v input
** Feeds power to system 5v and audio 5v
** Audio 5v will come from system 5v if VIN is not provided
* System 5v line
** Provides power to the system 3.3v line and the audio 3.3v line
** If coming from VIN, this line is provided by a 2A switching regulator, which may have some noise.
** Is fed through PMOS power switches to downstream USB devices, functions as VUSB.
* System 3.3v line
** Provides power to the Teensy 4.1 and the TUSB
** Provided by the Teensy 4.1's internal 3.3v regulator from the system 5v line
* System Ground
** Connected to all circutry, with the exception of some of the audio circutry, which uses the audio ground instead
* Audio 5v line
** Provided by either a 5v linear regulator from VIN, or from the system 5v line if VIN is not provided
** Powers the OPA1688 audio amplifier
** Is not broken out to the rest of the board
* Audio 3.3v line
** Regulated by a linear regulator, getting input from the system 5v line through a ferrite bead
** Powers the PCM5102 audio ADC
** Is not broken out elsewhere on the board
* Audio Ground
** Connected to System Ground through a ferrite bead
** Connected to audio circutry
** Provides the ground used for the 3.5mm audio jack
** Not broken out elsewhere on the board

When providing power to the board, a few things should be kept in mind. First, for high quality audio, either VIN must be provided, or the system 5v line must be clean. The latter is generally much harder to do, so it is recommended to provide VIN if possible. For a clean system 5v line, generally it is to provide the system 5v line though a linear regulator instead. Adding more ceramic capacitors to the system 5v line can help as well. If providing power from an exteral board through an expansion connector, providing power to both the 5v and VIN lines can boost the maximum current of the system 5v line above 2A. If more than 2A is needed, for example for more current-hungry USB devices, then this may be desirable. Finally, there is a limit on the safe capacitence to be connected to the system 5v line for the 2A switching regulator to work normally. It is unadvisable to connect more than 800uF of external capacitence to the system 5v line, as it may interfere with that regulator. Although, there really usually is no reason to connect to much capacitence to that line.

If providing power to the system 5v line from an external source and the Teensy 4.1's USB port simultaneously, it is a good idea to include an ideal diode or similar circuit to prevent backflow from the USB port into your regulator, or vice versa, depending on your regulators characteristics. For this purpose LM66100 ICs can be used, as are used to protect the onboard switching regulator from the Teensy 4.1's USB port.

'''Capacitence by Power Plane:'''

* VIN:
** 22uF electrolytic
** 4.7uF ceramic (through ferrite bead)
** 26.7uF total
* System 5v
** 2.2uF on Teensy 4.1, ceramic
** 10uF onboard, ceramic
** Specific to onboard switching regulator: 22uF electrolytic
** 12.2uF total when external 5v is provided (Teensy 4.1 micro USB, expansion slots directly to 5v rail)
** 34.2uF total when onboard regulator is used
* System 3.3v
** 7.13uF from Teensy 4.1, ceramic
** 0.3uF onboard for decoupling, ceramic
** 7.43uF total
* System Ground
** 10.3uF ceramic
** 14.7uF ceramic (through ferrite bead)
** 44uF electrolytic
** Approximately 25.13uF on Teensy 4.1, ceramic
** 94.13uF total
* Audio 5v
** 10.1uF ceramic
* Audio 3.3v
** 10.1uF ceramic
* Audio Ground
** 27.2uF ceramic
** Connected to system ground through ferrite bead - technically connected to those capacitors as well.

== Expansion Ports ==

[[File:Teensy4.1_computer_expansion_ports.png|thumb|Expansion port layout, not including the card connector port|800px]]

There are three large expansion ports on the Teensy 4.1 computer board, and 5 smaller ports. Here is a list, describing what each one breaks out:
* Largest expansion port on the back of the board (J11)
** Designed for large expansions to the computer system
** Exposes all power pins, including VIN, 5v, 3.3v, GND, and even the Teensy's VBAT line
** Numerous Teensy 4.1 pins: 0, 1, 11, 12, 13, 18, 19, 28, 29, 40, 41
*** UART1
*** UART7
*** SPI0
*** I2C0
*** Analog inputs: A4, A5, A16, A17
*** CRX2 and CTX2
** '''3.3v-compatible''' 8-bit parallel bus
*** Particularly useful for LCD displays and LCD display controllers, or any other parallel peripheral, for very high speeds
* Right-side expansion port (J12 - reference not shown on board revision 1.1)
** Designed for ATX-compatible expansions to the board
** Exposes 5v and 3.3v lines
** '''3.3v-compatible''' 8-bit parallel bus
** Several Teensy 4.1 pins: 6, 7, 8, 9, 18, 19, 32
*** UART2
*** I2C0
*** Analog inputs: A4, A5
* Card Expansion Port
** Designed to provide a card slot to fit in an ATX case. The card may provide IO to the front.
** Provides a '''5v-compatible''' 8-bit parallel port. The pins are shared with the other parallel ports.
** The direction of all data pins are controlled by the control lines. '''Cannot use data line as input and output at the same time'''
*** Controlled by write, read, and select lines. Select pin is pin 9, pulling it low will enable communication.
** Provides only a 5v line.
* I2S Expansion Port (J10)
** Provides an alternative to the 3.5mm audio output, and allows one to attach a microphone
** Breaks out I2S port 2
** Can be used to add a microphone alongside use of the 3.5mm audio jack
** Provides all power rails: VIN, 5v and 3.3v.
** Breaks out pins 16 and 17
*** I2C1
*** Analog pins A2 and A3
*** UART4
* SPI0 Port (J9)
** Provided for SPI devices. Designed so that a card can be inserted to provide IO to the front of the board.
** Breaks out pins 10-13
** Provides 3.3v, but not 5v
** Breaks out SPI0
* UART6 Port
** This is a small port breaking out pins 24 and 25
*** UART6
*** Analog pins A10 and A11
*** I2C2
** The port is designed so another board can provide IO to the front.
** The pinout is designed to be compatible with Sparkfun devices and serial pinouts
** Can be used also as an additional I2C port, and has the necessary 4.7k resistors connected
** Provides 3.3v and ground
* I2C1 Port
** This is a small port breaking out pins 16 and 17
*** UART4
*** Analog pins A2 and A3
*** I2C1
** Has the necessary 4.7k resistors connected
** The port is designed for internal devices, and is not designed to provide front-facing IO.
** Can be used also as an additional UART port
** Provides 3.3v and ground
* UART3 Port
** This is a small port breaking out pins 14 and 15
*** UART3
*** Analog pins A0 and A1
** The port is designed for internal devices, and is not designed to provide front-facing IO.
** The pinout is designed to be compatible with Sparkfun devices and serial pinouts
** Provides 3.3v and ground

=== About the Parallel Port ===

All three ports that provide parallel share the parallel pins WR, RD, and WAIT, as well as the busses ADDR and DATA. Each connected parallel device should use a separate select pin, however, with pin 9 being reserved as the card connector's select pin. WR, RD, and WAIT are all active low, and it is expected that all select lines also be active low. The address bus (ADDR, shown on the board as A0, A1, and A2) has three pins, allowing for three addresses per device. A parallel port is important to have because of the high bandwidth it provides. The Teensy can write this port extremely fast, thus allowing better framerates and draw times for connected graphics devices. I imagine there are other uses for this port as well.

As ADDR, WR, RD, and any select pins are all output-only from the Teensy, '''there is no level-shifting logic for them.''' For the WAIT line, there is a simple resistor voltage divider to take the 5v from the card connector down to 3.3v. There is only level-shifting logic provided for data lines on the card connector, so that 5v TTL devices and levels can be used with the card connector out of the box.

The card connector was designed to interface with cards for the Z80 computer I previously built, and has a compatible pinout.

Teensy 4.1 Computer

2024-06-13T21:40:45Z

Nuclear: More expansion port docs

The Teensy 4.1 Computer is more or less described by its name: Its a carrier board for the Teensy 4.1 which provides four USB ports, an Ethernet port, Hi-Fi audio, and several convenient expansion ports.

== Detailed Specifications ==

'''USB:'''

* TUSB2046 USB Hub, providing 4 USB A ports
* Each port has a maximum of 1.5A output - the port will shutdown due to overcurrent above this
* Board power provides a maximum of 2A to the 5v supply
** one should be aware of this when considering the power used by USB devices

'''Audio:'''

* I2S control connected to Teensy I2S 2
* PCM5102 ADC for providing stereo sound
* OPA1688 for the amplifier
* 3.5mm audio jack, maximum 75mA per channel
* Separate ground, connected to main ground through a ferrite bead
* Separate 3.3v and 5v supplies from linear regulators to reduce noise
** Note: 5v line will come from main 5v rail if only powered from USB

'''Power:'''

* 2A 5v buck regulator (Exact part is the VR20S05)
* PMOS switches to prevent regulator backfeeding from USB and to control power flow (U16, U17, and U18 on the PCB)
* External VIN accepted from 8v to 20v
* Separate 5v and 3.3v supplies for audio circutry
* Barrel jack and screw terminal connections for VIN

'''Expansion Ports'''

* I2S, SPI, I2C, and Serial expansion ports
* 5v-capable 8-bit parallel bus port, with 3-bit address, WR, RD, select, and WAIT lines
* Two larger expansion ports, each providing a '''3.3v compatible''' 8-bit parallel bus, various protocols like I2C and SPI, power, and GPIO

== The Audio Circuit ==

[[File:Teensy41_Computer_Audio_circuit.png|thumb|Teensy 4.1 Computer audio circuit|600px]]

The Teensy 4.1 is connected to the audio circuit via the Teensy's I2S 2 port. This connection goes to the PCM5102 ADC. As is recommended in the PCM5102's datasheet, filtering is added to the output, however the filter used on this board is a bit stronger, using a 4.7nF capacitor instead of the 2.2nF capacitor recommended in the datasheet. The filter cutoff is still far above human perception, at 72kHz, and should filter high frequency noise a bit better. The connection to the OPA1688 is DC, not AC, coupled, but this is according to the recommendations in the OPA1688 datasheet. The gain of the amplifier is configured to be 1, so the output voltage of the amp should match the ADC's output voltage, and be in the range of 0v to 3.3v. A voltage divider is used to activate the PCM5102's soft mute function when the 5v line drops, which is designed to prevent any pops in the audio when the power is disconnected.

The circuit was designed with audio quality, but not energy efficiency, in mind. The circuit may sink as much as 400mA from VIN, and an additional 40mA from the main 5v line. However, when the audio circuit is idle, it should be less than 50mA all together. The 3.5mm audio jack can provide a maximum of 75mA per channel.

'''Example Code:'''
<pre>
#include <Audio.h>
#include <SD.h>

// GUItool: begin automatically generated code
AudioPlaySdWav playSdWav1; //xy=719,389
AudioOutputI2S2 i2s2_1; //xy=892,388
AudioConnection patchCord1(playSdWav1, 0, i2s2_1, 0);
AudioConnection patchCord2(playSdWav1, 1, i2s2_1, 1);
// GUItool: end automatically generated code

void setup() {
Serial.begin(115200);
AudioMemory(10);

if (!(SD.begin(BUILTIN_SDCARD))) {
// stop here, but print a message repetitively
while (1) {
Serial.println("Unable to access the SD card");
delay(500);
}
}

Serial.println("Playing audio.wav...");
playSdWav1.play("audio.wav");
}

void loop() {
// Do nothing forever
}
</pre>

== USB Ports ==

[[File:Teensy4.1_computer_USB_schematic.png|thumb|Teensy 4.1 Computer USB circuit|600px]]

The Teensy 4.1's builtin USB port is connected directly to a TUSB2046 IC, which is a USB hub and provides four downstream ports. Each port has overcurrent protection, with a maximum allowed current of 1.5A. There are also TVS diodes on all USB data lines on the downstream ports, provided by three TPD3E001DRLR ICs. Other than that, each downstream USB port has two 15k pulldowns - one on each data line.

'''Example Code:'''

The best example is found in the Mouse_KeyboardBT example from the USBHost_t36 library, which is included in the TeensyDuino package. For convenience, I have included a stripped down version of it below:
<pre>
#include "USBHost_t36.h"

USBHost myusb;
USBHub hub1(myusb);
USBHub hub2(myusb);
KeyboardController keyboard1(myusb);
KeyboardController keyboard2(myusb);
USBHIDParser hid1(myusb);
USBHIDParser hid2(myusb);
USBHIDParser hid3(myusb);
USBHIDParser hid4(myusb);
USBHIDParser hid5(myusb);
MouseController mouse1(myusb);

BluetoothController bluet(myusb); // version assumes it already was paired

USBDriver *drivers[] = {&hub1, &hub2, &keyboard1, &keyboard2, &bluet, &hid1, &hid2, &hid3, &hid4, &hid5};

#define CNT_DEVICES (sizeof(drivers)/sizeof(drivers[0]))
const char * driver_names[CNT_DEVICES] = {"Hub1", "Hub2", "KB1", "KB2", "Bluet", "HID1" , "HID2", "HID3", "HID4", "HID5"};

bool driver_active[CNT_DEVICES] = {false, false, false, false, false, false, false, false, false, false};

// Lets also look at HID Input devices
USBHIDInput *hiddrivers[] = {&mouse1};

#define CNT_HIDDEVICES (sizeof(hiddrivers)/sizeof(hiddrivers[0]))
const char * hid_driver_names[CNT_HIDDEVICES] = {"Mouse1"};

bool hid_driver_active[CNT_HIDDEVICES] = {false};

BTHIDInput *bthiddrivers[] = {&keyboard1, &mouse1};
#define CNT_BTHIDDEVICES (sizeof(bthiddrivers)/sizeof(bthiddrivers[0]))
const char * bthid_driver_names[CNT_BTHIDDEVICES] = {"Keyboard(BT)", "Mouse(BT)"};
bool bthid_driver_active[CNT_BTHIDDEVICES] = {false};

bool show_changed_only = false;

uint8_t joystick_left_trigger_value = 0;
uint8_t joystick_right_trigger_value = 0;
uint64_t joystick_full_notify_mask = (uint64_t) - 1;

void setup() {
while (!Serial); // wait for Arduino Serial Monitor
Serial.begin(115200);
myusb.begin();
keyboard1.attachPress(OnPress);
keyboard2.attachPress(OnPress);
}

void loop() {
// check to see if the device list has changed:
UpdateActiveDeviceInfo();

myusb.Task();

if (mouse1.available()) {
Serial.print("Mouse: buttons = ");
Serial.print(mouse1.getButtons());
Serial.print(", mouseX = ");
Serial.print(mouse1.getMouseX());
Serial.print(", mouseY = ");
Serial.print(mouse1.getMouseY());
Serial.print(", wheel = ");
Serial.print(mouse1.getWheel());
Serial.print(", wheelH = ");
Serial.print(mouse1.getWheelH());
Serial.println();
mouse1.mouseDataClear();
}
}

void OnPress(int key)
{
Serial.print("key '");
switch (key) {
case KEYD_UP : Serial.print("UP"); break;
case KEYD_DOWN : Serial.print("DN"); break;
case KEYD_LEFT : Serial.print("LEFT"); break;
case KEYD_RIGHT : Serial.print("RIGHT"); break;
case KEYD_INSERT : Serial.print("Ins"); break;
case KEYD_DELETE : Serial.print("Del"); break;
case KEYD_PAGE_UP : Serial.print("PUP"); break;
case KEYD_PAGE_DOWN: Serial.print("PDN"); break;
case KEYD_HOME : Serial.print("HOME"); break;
case KEYD_END : Serial.print("END"); break;
case KEYD_F1 : Serial.print("F1"); break;
case KEYD_F2 : Serial.print("F2"); break;
case KEYD_F3 : Serial.print("F3"); break;
case KEYD_F4 : Serial.print("F4"); break;
case KEYD_F5 : Serial.print("F5"); break;
case KEYD_F6 : Serial.print("F6"); break;
case KEYD_F7 : Serial.print("F7"); break;
case KEYD_F8 : Serial.print("F8"); break;
case KEYD_F9 : Serial.print("F9"); break;
case KEYD_F10 : Serial.print("F10"); break;
case KEYD_F11 : Serial.print("F11"); break;
case KEYD_F12 : Serial.print("F12"); break;
default: Serial.print((char)key); break;
}
Serial.print("' ");
Serial.println(key);
}

//=============================================================================
// UpdateActiveDeviceInfo
//=============================================================================
void UpdateActiveDeviceInfo() {
for (uint8_t i = 0; i < CNT_DEVICES; i++) {
if (*drivers[i] != driver_active[i]) {
if (driver_active[i]) {
Serial.printf("*** Device %s - disconnected ***\n", driver_names[i]);
driver_active[i] = false;
} else {
Serial.printf("*** Device %s %x:%x - connected ***\n", driver_names[i], drivers[i]->idVendor(), drivers[i]->idProduct());
driver_active[i] = true;

const uint8_t *psz = drivers[i]->manufacturer();
if (psz && *psz) Serial.printf(" manufacturer: %s\n", psz);
psz = drivers[i]->product();
if (psz && *psz) Serial.printf(" product: %s\n", psz);
psz = drivers[i]->serialNumber();
if (psz && *psz) Serial.printf(" Serial: %s\n", psz);

if (drivers[i] == &bluet) {
const uint8_t *bdaddr = bluet.myBDAddr();
// remember it...
Serial.printf(" BDADDR: %x:%x:%x:%x:%x:%x\n", bdaddr[0], bdaddr[1], bdaddr[2], bdaddr[3], bdaddr[4], bdaddr[5]);
}
}
}
}
for (uint8_t i = 0; i < CNT_HIDDEVICES; i++) {
if (*hiddrivers[i] != hid_driver_active[i]) {
if (hid_driver_active[i]) {
Serial.printf("*** HID Device %s - disconnected ***\n", hid_driver_names[i]);
hid_driver_active[i] = false;
} else {
Serial.printf("*** HID Device %s %x:%x - connected ***\n", hid_driver_names[i], hiddrivers[i]->idVendor(), hiddrivers[i]->idProduct());
hid_driver_active[i] = true;

const uint8_t *psz = hiddrivers[i]->manufacturer();
if (psz && *psz) Serial.printf(" manufacturer: %s\n", psz);
psz = hiddrivers[i]->product();
if (psz && *psz) Serial.printf(" product: %s\n", psz);
psz = hiddrivers[i]->serialNumber();
if (psz && *psz) Serial.printf(" Serial: %s\n", psz);
}
}
}
// Then Bluetooth devices
for (uint8_t i = 0; i < CNT_BTHIDDEVICES; i++) {
if (*bthiddrivers[i] != bthid_driver_active[i]) {
if (bthid_driver_active[i]) {
Serial.printf("*** BTHID Device %s - disconnected ***\n", bthid_driver_names[i]);
bthid_driver_active[i] = false;
} else {
Serial.printf("*** BTHID Device %s - connected ***\n", bthid_driver_names[i]); Serial.flush();
bthid_driver_active[i] = true;
#if 0

const uint8_t *psz = bthiddrivers[i]->manufacturer();
if (psz && *psz) Serial.printf(" manufacturer: %s\n", psz);
psz = bthiddrivers[i]->product();
if (psz && *psz) Serial.printf(" product: %s\n", psz);
psz = bthiddrivers[i]->serialNumber();
if (psz && *psz) Serial.printf(" Serial: %s\n", psz);
#endif
}
}
}
}
</pre>

'''Known Issues:'''
* Version 1.1 of the board leaves TUSB2046's reset line floating. This can be remedied by connecting the TUSB2046's reset line to some other circuit, although this is error prone.

== Power ==

[[File:Teensy4.1_computer_power_circuit.png|thumb|Teensy 4.1 Computer power circuitry|500px]]

The computer's power supply accepts input from four primary sources:
* Barrel jack DC input, 8v to 20v, provides 2A to 5v line
* Screw terminal block, 8v to 20v, provides 2A to 5v line
* Teensy 4.1 micro USB port, 5v input, current limit depends on USB power source
* Expansion ports
** Direct to 5v line, only limited by source current. This allows one to surpass the typical 2A limit on the 5v line.
** Direct to VIN, accepts 8v to 20v. 5v line limited to 2A.
** Direct to 3.3v line, only limited by source current. This can be used to relieve stress from the Teensy 4.1's 3.3v regulator, if needed.

[[File:Teensy4.1_computer_audio_power.png|thumb|Teensy 4.1 Computer audio power circuits|800px]]
There are a few different power planes on the board:
* VIN, 8v to 20v input
** Feeds power to system 5v and audio 5v
** Audio 5v will come from system 5v if VIN is not provided
* System 5v line
** Provides power to the system 3.3v line and the audio 3.3v line
** If coming from VIN, this line is provided by a 2A switching regulator, which may have some noise.
** Is fed through PMOS power switches to downstream USB devices, functions as VUSB.
* System 3.3v line
** Provides power to the Teensy 4.1 and the TUSB
** Provided by the Teensy 4.1's internal 3.3v regulator from the system 5v line
* System Ground
** Connected to all circutry, with the exception of some of the audio circutry, which uses the audio ground instead
* Audio 5v line
** Provided by either a 5v linear regulator from VIN, or from the system 5v line if VIN is not provided
** Powers the OPA1688 audio amplifier
** Is not broken out to the rest of the board
* Audio 3.3v line
** Regulated by a linear regulator, getting input from the system 5v line through a ferrite bead
** Powers the PCM5102 audio ADC
** Is not broken out elsewhere on the board
* Audio Ground
** Connected to System Ground through a ferrite bead
** Connected to audio circutry
** Provides the ground used for the 3.5mm audio jack
** Not broken out elsewhere on the board

When providing power to the board, a few things should be kept in mind. First, for high quality audio, either VIN must be provided, or the system 5v line must be clean. The latter is generally much harder to do, so it is recommended to provide VIN if possible. For a clean system 5v line, generally it is to provide the system 5v line though a linear regulator instead. Adding more ceramic capacitors to the system 5v line can help as well. If providing power from an exteral board through an expansion connector, providing power to both the 5v and VIN lines can boost the maximum current of the system 5v line above 2A. If more than 2A is needed, for example for more current-hungry USB devices, then this may be desirable. Finally, there is a limit on the safe capacitence to be connected to the system 5v line for the 2A switching regulator to work normally. It is unadvisable to connect more than 800uF of external capacitence to the system 5v line, as it may interfere with that regulator. Although, there really usually is no reason to connect to much capacitence to that line.

If providing power to the system 5v line from an external source and the Teensy 4.1's USB port simultaneously, it is a good idea to include an ideal diode or similar circuit to prevent backflow from the USB port into your regulator, or vice versa, depending on your regulators characteristics. For this purpose LM66100 ICs can be used, as are used to protect the onboard switching regulator from the Teensy 4.1's USB port.

'''Capacitence by Power Plane:'''

* VIN:
** 22uF electrolytic
** 4.7uF ceramic (through ferrite bead)
** 26.7uF total
* System 5v
** 2.2uF on Teensy 4.1, ceramic
** 10uF onboard, ceramic
** Specific to onboard switching regulator: 22uF electrolytic
** 12.2uF total when external 5v is provided (Teensy 4.1 micro USB, expansion slots directly to 5v rail)
** 34.2uF total when onboard regulator is used
* System 3.3v
** 7.13uF from Teensy 4.1, ceramic
** 0.3uF onboard for decoupling, ceramic
** 7.43uF total
* System Ground
** 10.3uF ceramic
** 14.7uF ceramic (through ferrite bead)
** 44uF electrolytic
** Approximately 25.13uF on Teensy 4.1, ceramic
** 94.13uF total
* Audio 5v
** 10.1uF ceramic
* Audio 3.3v
** 10.1uF ceramic
* Audio Ground
** 27.2uF ceramic
** Connected to system ground through ferrite bead - technically connected to those capacitors as well.

== Expansion Ports ==

[[File:Teensy4.1_computer_expansion_ports.png|thumb|Expansion port layout, not including the card connector port|800px]]

There are three large expansion ports on the Teensy 4.1 computer board, and 5 smaller ports. Here is a list, describing what each one breaks out:
* Largest expansion port on the back of the board (J11)
** Designed for large expansions to the computer system
** Exposes all power pins, including VIN, 5v, 3.3v, GND, and even the Teensy's VBAT line
** Numerous Teensy 4.1 pins: 0, 1, 11, 12, 13, 18, 19, 28, 29, 40, 41
*** UART1
*** UART7
*** SPI0
*** I2C0
*** Analog inputs: A4, A5, A16, A17
*** CRX2 and CTX2
** '''3.3v-compatible''' 8-bit parallel bus
*** Particularly useful for LCD displays and LCD display controllers, or any other parallel peripheral, for very high speeds
* Right-side expansion port (J12 - reference not shown on board revision 1.1)
** Designed for ATX-compatible expansions to the board
** Exposes 5v and 3.3v lines
** '''3.3v-compatible''' 8-bit parallel bus
** Several Teensy 4.1 pins: 6, 7, 8, 9, 18, 19, 32
*** UART2
*** I2C0
*** Analog inputs: A4, A5
* Card Expansion Port
** Designed to provide a card slot to fit in an ATX case. The card may provide IO to the front.
** Provides a '''5v-compatible''' 8-bit parallel port. The pins are shared with the other parallel ports.
** The direction of all data pins are controlled by the control lines. '''Cannot use data line as input and output at the same time'''
*** Controlled by write, read, and select lines. Select pin is pin 9, pulling it low will enable communication.
** Provides only a 5v line.
* I2S Expansion Port (J10)
** Provides an alternative to the 3.5mm audio output, and allows one to attach a microphone
** Breaks out I2S port 2
** Can be used to add a microphone alongside use of the 3.5mm audio jack
** Provides all power rails: VIN, 5v and 3.3v.
** Breaks out pins 16 and 17
*** I2C1
*** Analog pins A2 and A3
*** UART4
* SPI0 Port (J9)
** Provided for SPI devices. Designed so that a card can be inserted to provide IO to the front of the board.
** Breaks out pins 10-13
** Provides 3.3v, but not 5v
** Breaks out SPI0
* UART6 Port
** This is a small port breaking out pins 24 and 25
*** UART6
*** Analog pins A10 and A11
*** I2C2
** The port is designed so another board can provide IO to the front.
** The pinout is designed to be compatible with Sparkfun devices and serial pinouts
** Can be used also as an additional I2C port, and has the necessary 4.7k resistors connected
** Provides 3.3v and ground
* I2C1 Port
** This is a small port breaking out pins 16 and 17
*** UART4
*** Analog pins A2 and A3
*** I2C1
** Has the necessary 4.7k resistors connected
** The port is designed for internal devices, and is not designed to provide front-facing IO.
** Can be used also as an additional UART port
** Provides 3.3v and ground
* UART3 Port
** This is a small port breaking out pins 14 and 15
*** UART3
*** Analog pins A0 and A1
** The port is designed for internal devices, and is not designed to provide front-facing IO.
** The pinout is designed to be compatible with Sparkfun devices and serial pinouts
** Provides 3.3v and ground

Teensy 4.1 Computer

2024-06-13T21:29:10Z

Nuclear: Saving work on the expansion port documentation

The Teensy 4.1 Computer is more or less described by its name: Its a carrier board for the Teensy 4.1 which provides four USB ports, an Ethernet port, Hi-Fi audio, and several convenient expansion ports.

== Detailed Specifications ==

'''USB:'''

* TUSB2046 USB Hub, providing 4 USB A ports
* Each port has a maximum of 1.5A output - the port will shutdown due to overcurrent above this
* Board power provides a maximum of 2A to the 5v supply
** one should be aware of this when considering the power used by USB devices

'''Audio:'''

* I2S control connected to Teensy I2S 2
* PCM5102 ADC for providing stereo sound
* OPA1688 for the amplifier
* 3.5mm audio jack, maximum 75mA per channel
* Separate ground, connected to main ground through a ferrite bead
* Separate 3.3v and 5v supplies from linear regulators to reduce noise
** Note: 5v line will come from main 5v rail if only powered from USB

'''Power:'''

* 2A 5v buck regulator (Exact part is the VR20S05)
* PMOS switches to prevent regulator backfeeding from USB and to control power flow (U16, U17, and U18 on the PCB)
* External VIN accepted from 8v to 20v
* Separate 5v and 3.3v supplies for audio circutry
* Barrel jack and screw terminal connections for VIN

'''Expansion Ports'''

* I2S, SPI, I2C, and Serial expansion ports
* 5v-capable 8-bit parallel bus port, with 3-bit address, WR, RD, select, and WAIT lines
* Two larger expansion ports, each providing a '''3.3v compatible''' 8-bit parallel bus, various protocols like I2C and SPI, power, and GPIO

== The Audio Circuit ==

[[File:Teensy41_Computer_Audio_circuit.png|thumb|Teensy 4.1 Computer audio circuit|600px]]

The Teensy 4.1 is connected to the audio circuit via the Teensy's I2S 2 port. This connection goes to the PCM5102 ADC. As is recommended in the PCM5102's datasheet, filtering is added to the output, however the filter used on this board is a bit stronger, using a 4.7nF capacitor instead of the 2.2nF capacitor recommended in the datasheet. The filter cutoff is still far above human perception, at 72kHz, and should filter high frequency noise a bit better. The connection to the OPA1688 is DC, not AC, coupled, but this is according to the recommendations in the OPA1688 datasheet. The gain of the amplifier is configured to be 1, so the output voltage of the amp should match the ADC's output voltage, and be in the range of 0v to 3.3v. A voltage divider is used to activate the PCM5102's soft mute function when the 5v line drops, which is designed to prevent any pops in the audio when the power is disconnected.

The circuit was designed with audio quality, but not energy efficiency, in mind. The circuit may sink as much as 400mA from VIN, and an additional 40mA from the main 5v line. However, when the audio circuit is idle, it should be less than 50mA all together. The 3.5mm audio jack can provide a maximum of 75mA per channel.

'''Example Code:'''
<pre>
#include <Audio.h>
#include <SD.h>

// GUItool: begin automatically generated code
AudioPlaySdWav playSdWav1; //xy=719,389
AudioOutputI2S2 i2s2_1; //xy=892,388
AudioConnection patchCord1(playSdWav1, 0, i2s2_1, 0);
AudioConnection patchCord2(playSdWav1, 1, i2s2_1, 1);
// GUItool: end automatically generated code

void setup() {
Serial.begin(115200);
AudioMemory(10);

if (!(SD.begin(BUILTIN_SDCARD))) {
// stop here, but print a message repetitively
while (1) {
Serial.println("Unable to access the SD card");
delay(500);
}
}

Serial.println("Playing audio.wav...");
playSdWav1.play("audio.wav");
}

void loop() {
// Do nothing forever
}
</pre>

== USB Ports ==

[[File:Teensy4.1_computer_USB_schematic.png|thumb|Teensy 4.1 Computer USB circuit|600px]]

The Teensy 4.1's builtin USB port is connected directly to a TUSB2046 IC, which is a USB hub and provides four downstream ports. Each port has overcurrent protection, with a maximum allowed current of 1.5A. There are also TVS diodes on all USB data lines on the downstream ports, provided by three TPD3E001DRLR ICs. Other than that, each downstream USB port has two 15k pulldowns - one on each data line.

'''Example Code:'''

The best example is found in the Mouse_KeyboardBT example from the USBHost_t36 library, which is included in the TeensyDuino package. For convenience, I have included a stripped down version of it below:
<pre>
#include "USBHost_t36.h"

USBHost myusb;
USBHub hub1(myusb);
USBHub hub2(myusb);
KeyboardController keyboard1(myusb);
KeyboardController keyboard2(myusb);
USBHIDParser hid1(myusb);
USBHIDParser hid2(myusb);
USBHIDParser hid3(myusb);
USBHIDParser hid4(myusb);
USBHIDParser hid5(myusb);
MouseController mouse1(myusb);

BluetoothController bluet(myusb); // version assumes it already was paired

USBDriver *drivers[] = {&hub1, &hub2, &keyboard1, &keyboard2, &bluet, &hid1, &hid2, &hid3, &hid4, &hid5};

#define CNT_DEVICES (sizeof(drivers)/sizeof(drivers[0]))
const char * driver_names[CNT_DEVICES] = {"Hub1", "Hub2", "KB1", "KB2", "Bluet", "HID1" , "HID2", "HID3", "HID4", "HID5"};

bool driver_active[CNT_DEVICES] = {false, false, false, false, false, false, false, false, false, false};

// Lets also look at HID Input devices
USBHIDInput *hiddrivers[] = {&mouse1};

#define CNT_HIDDEVICES (sizeof(hiddrivers)/sizeof(hiddrivers[0]))
const char * hid_driver_names[CNT_HIDDEVICES] = {"Mouse1"};

bool hid_driver_active[CNT_HIDDEVICES] = {false};

BTHIDInput *bthiddrivers[] = {&keyboard1, &mouse1};
#define CNT_BTHIDDEVICES (sizeof(bthiddrivers)/sizeof(bthiddrivers[0]))
const char * bthid_driver_names[CNT_BTHIDDEVICES] = {"Keyboard(BT)", "Mouse(BT)"};
bool bthid_driver_active[CNT_BTHIDDEVICES] = {false};

bool show_changed_only = false;

uint8_t joystick_left_trigger_value = 0;
uint8_t joystick_right_trigger_value = 0;
uint64_t joystick_full_notify_mask = (uint64_t) - 1;

void setup() {
while (!Serial); // wait for Arduino Serial Monitor
Serial.begin(115200);
myusb.begin();
keyboard1.attachPress(OnPress);
keyboard2.attachPress(OnPress);
}

void loop() {
// check to see if the device list has changed:
UpdateActiveDeviceInfo();

myusb.Task();

if (mouse1.available()) {
Serial.print("Mouse: buttons = ");
Serial.print(mouse1.getButtons());
Serial.print(", mouseX = ");
Serial.print(mouse1.getMouseX());
Serial.print(", mouseY = ");
Serial.print(mouse1.getMouseY());
Serial.print(", wheel = ");
Serial.print(mouse1.getWheel());
Serial.print(", wheelH = ");
Serial.print(mouse1.getWheelH());
Serial.println();
mouse1.mouseDataClear();
}
}

void OnPress(int key)
{
Serial.print("key '");
switch (key) {
case KEYD_UP : Serial.print("UP"); break;
case KEYD_DOWN : Serial.print("DN"); break;
case KEYD_LEFT : Serial.print("LEFT"); break;
case KEYD_RIGHT : Serial.print("RIGHT"); break;
case KEYD_INSERT : Serial.print("Ins"); break;
case KEYD_DELETE : Serial.print("Del"); break;
case KEYD_PAGE_UP : Serial.print("PUP"); break;
case KEYD_PAGE_DOWN: Serial.print("PDN"); break;
case KEYD_HOME : Serial.print("HOME"); break;
case KEYD_END : Serial.print("END"); break;
case KEYD_F1 : Serial.print("F1"); break;
case KEYD_F2 : Serial.print("F2"); break;
case KEYD_F3 : Serial.print("F3"); break;
case KEYD_F4 : Serial.print("F4"); break;
case KEYD_F5 : Serial.print("F5"); break;
case KEYD_F6 : Serial.print("F6"); break;
case KEYD_F7 : Serial.print("F7"); break;
case KEYD_F8 : Serial.print("F8"); break;
case KEYD_F9 : Serial.print("F9"); break;
case KEYD_F10 : Serial.print("F10"); break;
case KEYD_F11 : Serial.print("F11"); break;
case KEYD_F12 : Serial.print("F12"); break;
default: Serial.print((char)key); break;
}
Serial.print("' ");
Serial.println(key);
}

//=============================================================================
// UpdateActiveDeviceInfo
//=============================================================================
void UpdateActiveDeviceInfo() {
for (uint8_t i = 0; i < CNT_DEVICES; i++) {
if (*drivers[i] != driver_active[i]) {
if (driver_active[i]) {
Serial.printf("*** Device %s - disconnected ***\n", driver_names[i]);
driver_active[i] = false;
} else {
Serial.printf("*** Device %s %x:%x - connected ***\n", driver_names[i], drivers[i]->idVendor(), drivers[i]->idProduct());
driver_active[i] = true;

const uint8_t *psz = drivers[i]->manufacturer();
if (psz && *psz) Serial.printf(" manufacturer: %s\n", psz);
psz = drivers[i]->product();
if (psz && *psz) Serial.printf(" product: %s\n", psz);
psz = drivers[i]->serialNumber();
if (psz && *psz) Serial.printf(" Serial: %s\n", psz);

if (drivers[i] == &bluet) {
const uint8_t *bdaddr = bluet.myBDAddr();
// remember it...
Serial.printf(" BDADDR: %x:%x:%x:%x:%x:%x\n", bdaddr[0], bdaddr[1], bdaddr[2], bdaddr[3], bdaddr[4], bdaddr[5]);
}
}
}
}
for (uint8_t i = 0; i < CNT_HIDDEVICES; i++) {
if (*hiddrivers[i] != hid_driver_active[i]) {
if (hid_driver_active[i]) {
Serial.printf("*** HID Device %s - disconnected ***\n", hid_driver_names[i]);
hid_driver_active[i] = false;
} else {
Serial.printf("*** HID Device %s %x:%x - connected ***\n", hid_driver_names[i], hiddrivers[i]->idVendor(), hiddrivers[i]->idProduct());
hid_driver_active[i] = true;

const uint8_t *psz = hiddrivers[i]->manufacturer();
if (psz && *psz) Serial.printf(" manufacturer: %s\n", psz);
psz = hiddrivers[i]->product();
if (psz && *psz) Serial.printf(" product: %s\n", psz);
psz = hiddrivers[i]->serialNumber();
if (psz && *psz) Serial.printf(" Serial: %s\n", psz);
}
}
}
// Then Bluetooth devices
for (uint8_t i = 0; i < CNT_BTHIDDEVICES; i++) {
if (*bthiddrivers[i] != bthid_driver_active[i]) {
if (bthid_driver_active[i]) {
Serial.printf("*** BTHID Device %s - disconnected ***\n", bthid_driver_names[i]);
bthid_driver_active[i] = false;
} else {
Serial.printf("*** BTHID Device %s - connected ***\n", bthid_driver_names[i]); Serial.flush();
bthid_driver_active[i] = true;
#if 0

const uint8_t *psz = bthiddrivers[i]->manufacturer();
if (psz && *psz) Serial.printf(" manufacturer: %s\n", psz);
psz = bthiddrivers[i]->product();
if (psz && *psz) Serial.printf(" product: %s\n", psz);
psz = bthiddrivers[i]->serialNumber();
if (psz && *psz) Serial.printf(" Serial: %s\n", psz);
#endif
}
}
}
}
</pre>

'''Known Issues:'''
* Version 1.1 of the board leaves TUSB2046's reset line floating. This can be remedied by connecting the TUSB2046's reset line to some other circuit, although this is error prone.

== Power ==

[[File:Teensy4.1_computer_power_circuit.png|thumb|Teensy 4.1 Computer power circuitry|500px]]

The computer's power supply accepts input from four primary sources:
* Barrel jack DC input, 8v to 20v, provides 2A to 5v line
* Screw terminal block, 8v to 20v, provides 2A to 5v line
* Teensy 4.1 micro USB port, 5v input, current limit depends on USB power source
* Expansion ports
** Direct to 5v line, only limited by source current. This allows one to surpass the typical 2A limit on the 5v line.
** Direct to VIN, accepts 8v to 20v. 5v line limited to 2A.
** Direct to 3.3v line, only limited by source current. This can be used to relieve stress from the Teensy 4.1's 3.3v regulator, if needed.

[[File:Teensy4.1_computer_audio_power.png|thumb|Teensy 4.1 Computer audio power circuits|800px]]
There are a few different power planes on the board:
* VIN, 8v to 20v input
** Feeds power to system 5v and audio 5v
** Audio 5v will come from system 5v if VIN is not provided
* System 5v line
** Provides power to the system 3.3v line and the audio 3.3v line
** If coming from VIN, this line is provided by a 2A switching regulator, which may have some noise.
** Is fed through PMOS power switches to downstream USB devices, functions as VUSB.
* System 3.3v line
** Provides power to the Teensy 4.1 and the TUSB
** Provided by the Teensy 4.1's internal 3.3v regulator from the system 5v line
* System Ground
** Connected to all circutry, with the exception of some of the audio circutry, which uses the audio ground instead
* Audio 5v line
** Provided by either a 5v linear regulator from VIN, or from the system 5v line if VIN is not provided
** Powers the OPA1688 audio amplifier
** Is not broken out to the rest of the board
* Audio 3.3v line
** Regulated by a linear regulator, getting input from the system 5v line through a ferrite bead
** Powers the PCM5102 audio ADC
** Is not broken out elsewhere on the board
* Audio Ground
** Connected to System Ground through a ferrite bead
** Connected to audio circutry
** Provides the ground used for the 3.5mm audio jack
** Not broken out elsewhere on the board

When providing power to the board, a few things should be kept in mind. First, for high quality audio, either VIN must be provided, or the system 5v line must be clean. The latter is generally much harder to do, so it is recommended to provide VIN if possible. For a clean system 5v line, generally it is to provide the system 5v line though a linear regulator instead. Adding more ceramic capacitors to the system 5v line can help as well. If providing power from an exteral board through an expansion connector, providing power to both the 5v and VIN lines can boost the maximum current of the system 5v line above 2A. If more than 2A is needed, for example for more current-hungry USB devices, then this may be desirable. Finally, there is a limit on the safe capacitence to be connected to the system 5v line for the 2A switching regulator to work normally. It is unadvisable to connect more than 800uF of external capacitence to the system 5v line, as it may interfere with that regulator. Although, there really usually is no reason to connect to much capacitence to that line.

If providing power to the system 5v line from an external source and the Teensy 4.1's USB port simultaneously, it is a good idea to include an ideal diode or similar circuit to prevent backflow from the USB port into your regulator, or vice versa, depending on your regulators characteristics. For this purpose LM66100 ICs can be used, as are used to protect the onboard switching regulator from the Teensy 4.1's USB port.

'''Capacitence by Power Plane:'''

* VIN:
** 22uF electrolytic
** 4.7uF ceramic (through ferrite bead)
** 26.7uF total
* System 5v
** 2.2uF on Teensy 4.1, ceramic
** 10uF onboard, ceramic
** Specific to onboard switching regulator: 22uF electrolytic
** 12.2uF total when external 5v is provided (Teensy 4.1 micro USB, expansion slots directly to 5v rail)
** 34.2uF total when onboard regulator is used
* System 3.3v
** 7.13uF from Teensy 4.1, ceramic
** 0.3uF onboard for decoupling, ceramic
** 7.43uF total
* System Ground
** 10.3uF ceramic
** 14.7uF ceramic (through ferrite bead)
** 44uF electrolytic
** Approximately 25.13uF on Teensy 4.1, ceramic
** 94.13uF total
* Audio 5v
** 10.1uF ceramic
* Audio 3.3v
** 10.1uF ceramic
* Audio Ground
** 27.2uF ceramic
** Connected to system ground through ferrite bead - technically connected to those capacitors as well.

== Expansion Ports ==

[[File:Teensy4.1_computer_expansion_ports.png|caption|Expansion port layout, not including the card connector port|800px]]

There are three large expansion ports on the Teensy 4.1 computer board, and 5 smaller ports. Here is a list, describing what each one breaks out:
* Largest expansion port on the back of the board (J11)
** Designed for large expansions to the computer system
** Exposes all power pins, including VIN, 5v, 3.3v, GND, and even the Teensy's VBAT line
** Numerous Teensy 4.1 pins: 0, 1, 11, 12, 13, 18, 19, 28, 29, 40, 41
*** UART1
*** UART7
*** SPI0
*** I2C0
*** Analog inputs: A4, A5, A16, A17
*** CRX2 and CTX2
** '''3.3v-compatible''' 8-bit parallel bus
*** Particularly useful for LCD displays and LCD display controllers, or any other parallel peripheral, for very high speeds
* Right-side expansion port (J10 - reference not shown on board revision 1.1)
** Designed for ATX-compatible expansions to the board
** Exposes 5v and 3.3v lines
** '''3.3v-compatible''' 8-bit parallel bus
** Several Teensy 4.1 pins: 6, 7, 8, 9, 18, 19, 32
*** UART2
*** I2C0
*** Analog inputs: A4, A5
* Card Expansion Port
** Provides a '''5v-compatible''' 8-bit parallel port. The pins are shared with the other parallel ports. The port is '''not bidirectional'''
*** Controlled by write, read, and select lines. Select pin is pin 9, pulling it low will enable communication.
** Provides only a 5v line.
* I2S Expansion Port
** Provides an alternative to the 3.5mm audio output, and allows one to attach a microphone
** Breaks out I2S port 2
** Can be used to add a microphone alongside use of the 3.5mm audio jack
** Provides all power rails: VIN, 5v and 3.3v.
** Breaks out pins 16 and 17
*** I2C1
*** Analog pins A2 and A3
*** UART4
*

File:Teensy4.1 computer expansion ports.png

2024-06-13T21:10:10Z

Nuclear: Describes all the expansion ports, except the card connector. Most descriptions are present on the board silkscreen, the rest were edited onto the image.

== Summary ==
Describes all the expansion ports, except the card connector. Most descriptions are present on the board silkscreen, the rest were edited onto the image.

Teensy 4.1 Computer

2024-06-13T20:51:52Z

Nuclear:

Teensy 4.1 Computer

2024-06-13T20:50:36Z

Nuclear: Add image for the audio power circuit, change image sizes

The Teensy 4.1 Computer is more or less described by its name: Its a carrier board for the Teensy 4.1 which provides four USB ports, an Ethernet port, Hi-Fi audio, and several convenient expansion ports.

== Detailed Specifications ==

'''USB:'''

* TUSB2046 USB Hub, providing 4 USB A ports
* Each port has a maximum of 1.5A output - the port will shutdown due to overcurrent above this
* Board power provides a maximum of 2A to the 5v supply
** one should be aware of this when considering the power used by USB devices

'''Audio:'''

* I2S control connected to Teensy I2S 2
* PCM5102 ADC for providing stereo sound
* OPA1688 for the amplifier
* 3.5mm audio jack, maximum 75mA per channel
* Separate ground, connected to main ground through a ferrite bead
* Separate 3.3v and 5v supplies from linear regulators to reduce noise
** Note: 5v line will come from main 5v rail if only powered from USB

'''Power:'''

* 2A 5v buck regulator (Exact part is the VR20S05)
* PMOS switches to prevent regulator backfeeding from USB and to control power flow (U16, U17, and U18 on the PCB)
* External VIN accepted from 8v to 20v
* Separate 5v and 3.3v supplies for audio circutry
* Barrel jack and screw terminal connections for VIN

'''Expansion Ports'''

* I2S, SPI, I2C, and Serial expansion ports
* 5v-capable 8-bit parallel bus port, with 3-bit address, WR, RD, select, and WAIT lines
* Two larger expansion ports, each providing a '''3.3v compatible''' 8-bit parallel bus, various protocols like I2C and SPI, power, and GPIO

== The Audio Circuit ==

[[File:Teensy41_Computer_Audio_circuit.png|thumb|Teensy 4.1 Computer audio circuit]]

The Teensy 4.1 is connected to the audio circuit via the Teensy's I2S 2 port. This connection goes to the PCM5102 ADC. As is recommended in the PCM5102's datasheet, filtering is added to the output, however the filter used on this board is a bit stronger, using a 4.7nF capacitor instead of the 2.2nF capacitor recommended in the datasheet. The filter cutoff is still far above human perception, at 72kHz, and should filter high frequency noise a bit better. The connection to the OPA1688 is DC, not AC, coupled, but this is according to the recommendations in the OPA1688 datasheet. The gain of the amplifier is configured to be 1, so the output voltage of the amp should match the ADC's output voltage, and be in the range of 0v to 3.3v. A voltage divider is used to activate the PCM5102's soft mute function when the 5v line drops, which is designed to prevent any pops in the audio when the power is disconnected.

The circuit was designed with audio quality, but not energy efficiency, in mind. The circuit may sink as much as 400mA from VIN, and an additional 40mA from the main 5v line. However, when the audio circuit is idle, it should be less than 50mA all together. The 3.5mm audio jack can provide a maximum of 75mA per channel.

'''Example Code:'''
<pre>
#include <Audio.h>
#include <SD.h>

// GUItool: begin automatically generated code
AudioPlaySdWav playSdWav1; //xy=719,389
AudioOutputI2S2 i2s2_1; //xy=892,388
AudioConnection patchCord1(playSdWav1, 0, i2s2_1, 0);
AudioConnection patchCord2(playSdWav1, 1, i2s2_1, 1);
// GUItool: end automatically generated code

void setup() {
Serial.begin(115200);
AudioMemory(10);

if (!(SD.begin(BUILTIN_SDCARD))) {
// stop here, but print a message repetitively
while (1) {
Serial.println("Unable to access the SD card");
delay(500);
}
}

Serial.println("Playing audio.wav...");
playSdWav1.play("audio.wav");
}

void loop() {
// Do nothing forever
}
</pre>

== USB Ports ==

[[File:Teensy4.1_computer_USB_schematic.png|thumb|Teensy 4.1 Computer USB circuit]]

The Teensy 4.1's builtin USB port is connected directly to a TUSB2046 IC, which is a USB hub and provides four downstream ports. Each port has overcurrent protection, with a maximum allowed current of 1.5A. There are also TVS diodes on all USB data lines on the downstream ports, provided by three TPD3E001DRLR ICs. Other than that, each downstream USB port has two 15k pulldowns - one on each data line.

'''Example Code:'''

The best example is found in the Mouse_KeyboardBT example from the USBHost_t36 library, which is included in the TeensyDuino package. For convenience, I have included a stripped down version of it below:
<pre>
#include "USBHost_t36.h"

USBHost myusb;
USBHub hub1(myusb);
USBHub hub2(myusb);
KeyboardController keyboard1(myusb);
KeyboardController keyboard2(myusb);
USBHIDParser hid1(myusb);
USBHIDParser hid2(myusb);
USBHIDParser hid3(myusb);
USBHIDParser hid4(myusb);
USBHIDParser hid5(myusb);
MouseController mouse1(myusb);

BluetoothController bluet(myusb); // version assumes it already was paired

USBDriver *drivers[] = {&hub1, &hub2, &keyboard1, &keyboard2, &bluet, &hid1, &hid2, &hid3, &hid4, &hid5};

#define CNT_DEVICES (sizeof(drivers)/sizeof(drivers[0]))
const char * driver_names[CNT_DEVICES] = {"Hub1", "Hub2", "KB1", "KB2", "Bluet", "HID1" , "HID2", "HID3", "HID4", "HID5"};

bool driver_active[CNT_DEVICES] = {false, false, false, false, false, false, false, false, false, false};

// Lets also look at HID Input devices
USBHIDInput *hiddrivers[] = {&mouse1};

#define CNT_HIDDEVICES (sizeof(hiddrivers)/sizeof(hiddrivers[0]))
const char * hid_driver_names[CNT_HIDDEVICES] = {"Mouse1"};

bool hid_driver_active[CNT_HIDDEVICES] = {false};

BTHIDInput *bthiddrivers[] = {&keyboard1, &mouse1};
#define CNT_BTHIDDEVICES (sizeof(bthiddrivers)/sizeof(bthiddrivers[0]))
const char * bthid_driver_names[CNT_BTHIDDEVICES] = {"Keyboard(BT)", "Mouse(BT)"};
bool bthid_driver_active[CNT_BTHIDDEVICES] = {false};

bool show_changed_only = false;

uint8_t joystick_left_trigger_value = 0;
uint8_t joystick_right_trigger_value = 0;
uint64_t joystick_full_notify_mask = (uint64_t) - 1;

void setup() {
while (!Serial); // wait for Arduino Serial Monitor
Serial.begin(115200);
myusb.begin();
keyboard1.attachPress(OnPress);
keyboard2.attachPress(OnPress);
}

void loop() {
// check to see if the device list has changed:
UpdateActiveDeviceInfo();

myusb.Task();

if (mouse1.available()) {
Serial.print("Mouse: buttons = ");
Serial.print(mouse1.getButtons());
Serial.print(", mouseX = ");
Serial.print(mouse1.getMouseX());
Serial.print(", mouseY = ");
Serial.print(mouse1.getMouseY());
Serial.print(", wheel = ");
Serial.print(mouse1.getWheel());
Serial.print(", wheelH = ");
Serial.print(mouse1.getWheelH());
Serial.println();
mouse1.mouseDataClear();
}
}

void OnPress(int key)
{
Serial.print("key '");
switch (key) {
case KEYD_UP : Serial.print("UP"); break;
case KEYD_DOWN : Serial.print("DN"); break;
case KEYD_LEFT : Serial.print("LEFT"); break;
case KEYD_RIGHT : Serial.print("RIGHT"); break;
case KEYD_INSERT : Serial.print("Ins"); break;
case KEYD_DELETE : Serial.print("Del"); break;
case KEYD_PAGE_UP : Serial.print("PUP"); break;
case KEYD_PAGE_DOWN: Serial.print("PDN"); break;
case KEYD_HOME : Serial.print("HOME"); break;
case KEYD_END : Serial.print("END"); break;
case KEYD_F1 : Serial.print("F1"); break;
case KEYD_F2 : Serial.print("F2"); break;
case KEYD_F3 : Serial.print("F3"); break;
case KEYD_F4 : Serial.print("F4"); break;
case KEYD_F5 : Serial.print("F5"); break;
case KEYD_F6 : Serial.print("F6"); break;
case KEYD_F7 : Serial.print("F7"); break;
case KEYD_F8 : Serial.print("F8"); break;
case KEYD_F9 : Serial.print("F9"); break;
case KEYD_F10 : Serial.print("F10"); break;
case KEYD_F11 : Serial.print("F11"); break;
case KEYD_F12 : Serial.print("F12"); break;
default: Serial.print((char)key); break;
}
Serial.print("' ");
Serial.println(key);
}

//=============================================================================
// UpdateActiveDeviceInfo
//=============================================================================
void UpdateActiveDeviceInfo() {
for (uint8_t i = 0; i < CNT_DEVICES; i++) {
if (*drivers[i] != driver_active[i]) {
if (driver_active[i]) {
Serial.printf("*** Device %s - disconnected ***\n", driver_names[i]);
driver_active[i] = false;
} else {
Serial.printf("*** Device %s %x:%x - connected ***\n", driver_names[i], drivers[i]->idVendor(), drivers[i]->idProduct());
driver_active[i] = true;

const uint8_t *psz = drivers[i]->manufacturer();
if (psz && *psz) Serial.printf(" manufacturer: %s\n", psz);
psz = drivers[i]->product();
if (psz && *psz) Serial.printf(" product: %s\n", psz);
psz = drivers[i]->serialNumber();
if (psz && *psz) Serial.printf(" Serial: %s\n", psz);

if (drivers[i] == &bluet) {
const uint8_t *bdaddr = bluet.myBDAddr();
// remember it...
Serial.printf(" BDADDR: %x:%x:%x:%x:%x:%x\n", bdaddr[0], bdaddr[1], bdaddr[2], bdaddr[3], bdaddr[4], bdaddr[5]);
}
}
}
}
for (uint8_t i = 0; i < CNT_HIDDEVICES; i++) {
if (*hiddrivers[i] != hid_driver_active[i]) {
if (hid_driver_active[i]) {
Serial.printf("*** HID Device %s - disconnected ***\n", hid_driver_names[i]);
hid_driver_active[i] = false;
} else {
Serial.printf("*** HID Device %s %x:%x - connected ***\n", hid_driver_names[i], hiddrivers[i]->idVendor(), hiddrivers[i]->idProduct());
hid_driver_active[i] = true;

const uint8_t *psz = hiddrivers[i]->manufacturer();
if (psz && *psz) Serial.printf(" manufacturer: %s\n", psz);
psz = hiddrivers[i]->product();
if (psz && *psz) Serial.printf(" product: %s\n", psz);
psz = hiddrivers[i]->serialNumber();
if (psz && *psz) Serial.printf(" Serial: %s\n", psz);
}
}
}
// Then Bluetooth devices
for (uint8_t i = 0; i < CNT_BTHIDDEVICES; i++) {
if (*bthiddrivers[i] != bthid_driver_active[i]) {
if (bthid_driver_active[i]) {
Serial.printf("*** BTHID Device %s - disconnected ***\n", bthid_driver_names[i]);
bthid_driver_active[i] = false;
} else {
Serial.printf("*** BTHID Device %s - connected ***\n", bthid_driver_names[i]); Serial.flush();
bthid_driver_active[i] = true;
#if 0

const uint8_t *psz = bthiddrivers[i]->manufacturer();
if (psz && *psz) Serial.printf(" manufacturer: %s\n", psz);
psz = bthiddrivers[i]->product();
if (psz && *psz) Serial.printf(" product: %s\n", psz);
psz = bthiddrivers[i]->serialNumber();
if (psz && *psz) Serial.printf(" Serial: %s\n", psz);
#endif
}
}
}
}
</pre>

'''Known Issues:'''
* Version 1.1 of the board leaves TUSB2046's reset line floating. This can be remedied by connecting the TUSB2046's reset line to some other circuit, although this is error prone.

== Power ==

[[File:Teensy4.1_computer_power_circuit.png|thumb|Teensy 4.1 Computer power circuitry|500px]]

The computer's power supply accepts input from four primary sources:
* Barrel jack DC input, 8v to 20v, provides 2A to 5v line
* Screw terminal block, 8v to 20v, provides 2A to 5v line
* Teensy 4.1 micro USB port, 5v input, current limit depends on USB power source
* Expansion ports
** Direct to 5v line, only limited by source current. This allows one to surpass the typical 2A limit on the 5v line.
** Direct to VIN, accepts 8v to 20v. 5v line limited to 2A.
** Direct to 3.3v line, only limited by source current. This can be used to relieve stress from the Teensy 4.1's 3.3v regulator, if needed.

[[File:Teensy4.1_computer_audio_power.png|thumb|Teensy 4.1 Computer audio power circuits|800px]]
There are a few different power planes on the board:
* VIN, 8v to 20v input
** Feeds power to system 5v and audio 5v
** Audio 5v will come from system 5v if VIN is not provided
* System 5v line
** Provides power to the system 3.3v line and the audio 3.3v line
** If coming from VIN, this line is provided by a 2A switching regulator, which may have some noise.
** Is fed through PMOS power switches to downstream USB devices, functions as VUSB.
* System 3.3v line
** Provides power to the Teensy 4.1 and the TUSB
** Provided by the Teensy 4.1's internal 3.3v regulator from the system 5v line
* System Ground
** Connected to all circutry, with the exception of some of the audio circutry, which uses the audio ground instead
* Audio 5v line
** Provided by either a 5v linear regulator from VIN, or from the system 5v line if VIN is not provided
** Powers the OPA1688 audio amplifier
** Is not broken out to the rest of the board
* Audio 3.3v line
** Regulated by a linear regulator, getting input from the system 5v line through a ferrite bead
** Powers the PCM5102 audio ADC
** Is not broken out elsewhere on the board
* Audio Ground
** Connected to System Ground through a ferrite bead
** Connected to audio circutry
** Provides the ground used for the 3.5mm audio jack
** Not broken out elsewhere on the board

When providing power to the board, a few things should be kept in mind. First, for high quality audio, either VIN must be provided, or the system 5v line must be clean. The latter is generally much harder to do, so it is recommended to provide VIN if possible. For a clean system 5v line, generally it is to provide the system 5v line though a linear regulator instead. Adding more ceramic capacitors to the system 5v line can help as well. If providing power from an exteral board through an expansion connector, providing power to both the 5v and VIN lines can boost the maximum current of the system 5v line above 2A. If more than 2A is needed, for example for more current-hungry USB devices, then this may be desirable. Finally, there is a limit on the safe capacitence to be connected to the system 5v line for the 2A switching regulator to work normally. It is unadvisable to connect more than 800uF of external capacitence to the system 5v line, as it may interfere with that regulator. Although, there really usually is no reason to connect to much capacitence to that line.

If providing power to the system 5v line from an external source and the Teensy 4.1's USB port simultaneously, it is a good idea to include an ideal diode or similar circuit to prevent backflow from the USB port into your regulator, or vice versa, depending on your regulators characteristics. For this purpose LM66100 ICs can be used, as are used to protect the onboard switching regulator from the Teensy 4.1's USB port.

'''Capacitence by Power Plane:'''

* VIN:
** 22uF electrolytic
** 4.7uF ceramic (through ferrite bead)
** 26.7uF total
* System 5v
** 2.2uF on Teensy 4.1, ceramic
** 10uF onboard, ceramic
** Specific to onboard switching regulator: 22uF electrolytic
** 12.2uF total when external 5v is provided (Teensy 4.1 micro USB, expansion slots directly to 5v rail)
** 34.2uF total when onboard regulator is used
* System 3.3v
** 7.13uF from Teensy 4.1, ceramic
** 0.3uF onboard for decoupling, ceramic
** 7.43uF total
* System Ground
** 10.3uF ceramic
** 14.7uF ceramic (through ferrite bead)
** 44uF electrolytic
** Approximately 25.13uF on Teensy 4.1, ceramic
** 94.13uF total
* Audio 5v
** 10.1uF ceramic
* Audio 3.3v
** 10.1uF ceramic
* Audio Ground
** 27.2uF ceramic
** Connected to system ground through ferrite bead - technically connected to those capacitors as well.

File:Teensy4.1 computer audio power.png

2024-06-13T20:46:25Z

Nuclear: Image of the Teensy 4.1's audio power circuits

== Summary ==
Image of the Teensy 4.1's audio power circuits

Teensy 4.1 Computer

2024-06-13T20:44:24Z

Nuclear: Finish details about the capacitence on various power planes

The Teensy 4.1 Computer is more or less described by its name: Its a carrier board for the Teensy 4.1 which provides four USB ports, an Ethernet port, Hi-Fi audio, and several convenient expansion ports.

== Detailed Specifications ==

'''USB:'''

* TUSB2046 USB Hub, providing 4 USB A ports
* Each port has a maximum of 1.5A output - the port will shutdown due to overcurrent above this
* Board power provides a maximum of 2A to the 5v supply
** one should be aware of this when considering the power used by USB devices

'''Audio:'''

* I2S control connected to Teensy I2S 2
* PCM5102 ADC for providing stereo sound
* OPA1688 for the amplifier
* 3.5mm audio jack, maximum 75mA per channel
* Separate ground, connected to main ground through a ferrite bead
* Separate 3.3v and 5v supplies from linear regulators to reduce noise
** Note: 5v line will come from main 5v rail if only powered from USB

'''Power:'''

* 2A 5v buck regulator (Exact part is the VR20S05)
* PMOS switches to prevent regulator backfeeding from USB and to control power flow (U16, U17, and U18 on the PCB)
* External VIN accepted from 8v to 20v
* Separate 5v and 3.3v supplies for audio circutry
* Barrel jack and screw terminal connections for VIN

'''Expansion Ports'''

* I2S, SPI, I2C, and Serial expansion ports
* 5v-capable 8-bit parallel bus port, with 3-bit address, WR, RD, select, and WAIT lines
* Two larger expansion ports, each providing a '''3.3v compatible''' 8-bit parallel bus, various protocols like I2C and SPI, power, and GPIO

== The Audio Circuit ==

[[File:Teensy41_Computer_Audio_circuit.png|thumb|Teensy 4.1 Computer audio circuit]]

The Teensy 4.1 is connected to the audio circuit via the Teensy's I2S 2 port. This connection goes to the PCM5102 ADC. As is recommended in the PCM5102's datasheet, filtering is added to the output, however the filter used on this board is a bit stronger, using a 4.7nF capacitor instead of the 2.2nF capacitor recommended in the datasheet. The filter cutoff is still far above human perception, at 72kHz, and should filter high frequency noise a bit better. The connection to the OPA1688 is DC, not AC, coupled, but this is according to the recommendations in the OPA1688 datasheet. The gain of the amplifier is configured to be 1, so the output voltage of the amp should match the ADC's output voltage, and be in the range of 0v to 3.3v. A voltage divider is used to activate the PCM5102's soft mute function when the 5v line drops, which is designed to prevent any pops in the audio when the power is disconnected.

The circuit was designed with audio quality, but not energy efficiency, in mind. The circuit may sink as much as 400mA from VIN, and an additional 40mA from the main 5v line. However, when the audio circuit is idle, it should be less than 50mA all together. The 3.5mm audio jack can provide a maximum of 75mA per channel.

'''Example Code:'''
<pre>
#include <Audio.h>
#include <SD.h>

// GUItool: begin automatically generated code
AudioPlaySdWav playSdWav1; //xy=719,389
AudioOutputI2S2 i2s2_1; //xy=892,388
AudioConnection patchCord1(playSdWav1, 0, i2s2_1, 0);
AudioConnection patchCord2(playSdWav1, 1, i2s2_1, 1);
// GUItool: end automatically generated code

void setup() {
Serial.begin(115200);
AudioMemory(10);

if (!(SD.begin(BUILTIN_SDCARD))) {
// stop here, but print a message repetitively
while (1) {
Serial.println("Unable to access the SD card");
delay(500);
}
}

Serial.println("Playing audio.wav...");
playSdWav1.play("audio.wav");
}

void loop() {
// Do nothing forever
}
</pre>

== USB Ports ==

[[File:Teensy4.1_computer_USB_schematic.png|thumb|Teensy 4.1 Computer USB circuit]]

The Teensy 4.1's builtin USB port is connected directly to a TUSB2046 IC, which is a USB hub and provides four downstream ports. Each port has overcurrent protection, with a maximum allowed current of 1.5A. There are also TVS diodes on all USB data lines on the downstream ports, provided by three TPD3E001DRLR ICs. Other than that, each downstream USB port has two 15k pulldowns - one on each data line.

'''Example Code:'''

The best example is found in the Mouse_KeyboardBT example from the USBHost_t36 library, which is included in the TeensyDuino package. For convenience, I have included a stripped down version of it below:
<pre>
#include "USBHost_t36.h"

USBHost myusb;
USBHub hub1(myusb);
USBHub hub2(myusb);
KeyboardController keyboard1(myusb);
KeyboardController keyboard2(myusb);
USBHIDParser hid1(myusb);
USBHIDParser hid2(myusb);
USBHIDParser hid3(myusb);
USBHIDParser hid4(myusb);
USBHIDParser hid5(myusb);
MouseController mouse1(myusb);

BluetoothController bluet(myusb); // version assumes it already was paired

USBDriver *drivers[] = {&hub1, &hub2, &keyboard1, &keyboard2, &bluet, &hid1, &hid2, &hid3, &hid4, &hid5};

#define CNT_DEVICES (sizeof(drivers)/sizeof(drivers[0]))
const char * driver_names[CNT_DEVICES] = {"Hub1", "Hub2", "KB1", "KB2", "Bluet", "HID1" , "HID2", "HID3", "HID4", "HID5"};

bool driver_active[CNT_DEVICES] = {false, false, false, false, false, false, false, false, false, false};

// Lets also look at HID Input devices
USBHIDInput *hiddrivers[] = {&mouse1};

#define CNT_HIDDEVICES (sizeof(hiddrivers)/sizeof(hiddrivers[0]))
const char * hid_driver_names[CNT_HIDDEVICES] = {"Mouse1"};

bool hid_driver_active[CNT_HIDDEVICES] = {false};

BTHIDInput *bthiddrivers[] = {&keyboard1, &mouse1};
#define CNT_BTHIDDEVICES (sizeof(bthiddrivers)/sizeof(bthiddrivers[0]))
const char * bthid_driver_names[CNT_BTHIDDEVICES] = {"Keyboard(BT)", "Mouse(BT)"};
bool bthid_driver_active[CNT_BTHIDDEVICES] = {false};

bool show_changed_only = false;

uint8_t joystick_left_trigger_value = 0;
uint8_t joystick_right_trigger_value = 0;
uint64_t joystick_full_notify_mask = (uint64_t) - 1;

void setup() {
while (!Serial); // wait for Arduino Serial Monitor
Serial.begin(115200);
myusb.begin();
keyboard1.attachPress(OnPress);
keyboard2.attachPress(OnPress);
}

void loop() {
// check to see if the device list has changed:
UpdateActiveDeviceInfo();

myusb.Task();

if (mouse1.available()) {
Serial.print("Mouse: buttons = ");
Serial.print(mouse1.getButtons());
Serial.print(", mouseX = ");
Serial.print(mouse1.getMouseX());
Serial.print(", mouseY = ");
Serial.print(mouse1.getMouseY());
Serial.print(", wheel = ");
Serial.print(mouse1.getWheel());
Serial.print(", wheelH = ");
Serial.print(mouse1.getWheelH());
Serial.println();
mouse1.mouseDataClear();
}
}

void OnPress(int key)
{
Serial.print("key '");
switch (key) {
case KEYD_UP : Serial.print("UP"); break;
case KEYD_DOWN : Serial.print("DN"); break;
case KEYD_LEFT : Serial.print("LEFT"); break;
case KEYD_RIGHT : Serial.print("RIGHT"); break;
case KEYD_INSERT : Serial.print("Ins"); break;
case KEYD_DELETE : Serial.print("Del"); break;
case KEYD_PAGE_UP : Serial.print("PUP"); break;
case KEYD_PAGE_DOWN: Serial.print("PDN"); break;
case KEYD_HOME : Serial.print("HOME"); break;
case KEYD_END : Serial.print("END"); break;
case KEYD_F1 : Serial.print("F1"); break;
case KEYD_F2 : Serial.print("F2"); break;
case KEYD_F3 : Serial.print("F3"); break;
case KEYD_F4 : Serial.print("F4"); break;
case KEYD_F5 : Serial.print("F5"); break;
case KEYD_F6 : Serial.print("F6"); break;
case KEYD_F7 : Serial.print("F7"); break;
case KEYD_F8 : Serial.print("F8"); break;
case KEYD_F9 : Serial.print("F9"); break;
case KEYD_F10 : Serial.print("F10"); break;
case KEYD_F11 : Serial.print("F11"); break;
case KEYD_F12 : Serial.print("F12"); break;
default: Serial.print((char)key); break;
}
Serial.print("' ");
Serial.println(key);
}

//=============================================================================
// UpdateActiveDeviceInfo
//=============================================================================
void UpdateActiveDeviceInfo() {
for (uint8_t i = 0; i < CNT_DEVICES; i++) {
if (*drivers[i] != driver_active[i]) {
if (driver_active[i]) {
Serial.printf("*** Device %s - disconnected ***\n", driver_names[i]);
driver_active[i] = false;
} else {
Serial.printf("*** Device %s %x:%x - connected ***\n", driver_names[i], drivers[i]->idVendor(), drivers[i]->idProduct());
driver_active[i] = true;

const uint8_t *psz = drivers[i]->manufacturer();
if (psz && *psz) Serial.printf(" manufacturer: %s\n", psz);
psz = drivers[i]->product();
if (psz && *psz) Serial.printf(" product: %s\n", psz);
psz = drivers[i]->serialNumber();
if (psz && *psz) Serial.printf(" Serial: %s\n", psz);

if (drivers[i] == &bluet) {
const uint8_t *bdaddr = bluet.myBDAddr();
// remember it...
Serial.printf(" BDADDR: %x:%x:%x:%x:%x:%x\n", bdaddr[0], bdaddr[1], bdaddr[2], bdaddr[3], bdaddr[4], bdaddr[5]);
}
}
}
}
for (uint8_t i = 0; i < CNT_HIDDEVICES; i++) {
if (*hiddrivers[i] != hid_driver_active[i]) {
if (hid_driver_active[i]) {
Serial.printf("*** HID Device %s - disconnected ***\n", hid_driver_names[i]);
hid_driver_active[i] = false;
} else {
Serial.printf("*** HID Device %s %x:%x - connected ***\n", hid_driver_names[i], hiddrivers[i]->idVendor(), hiddrivers[i]->idProduct());
hid_driver_active[i] = true;

const uint8_t *psz = hiddrivers[i]->manufacturer();
if (psz && *psz) Serial.printf(" manufacturer: %s\n", psz);
psz = hiddrivers[i]->product();
if (psz && *psz) Serial.printf(" product: %s\n", psz);
psz = hiddrivers[i]->serialNumber();
if (psz && *psz) Serial.printf(" Serial: %s\n", psz);
}
}
}
// Then Bluetooth devices
for (uint8_t i = 0; i < CNT_BTHIDDEVICES; i++) {
if (*bthiddrivers[i] != bthid_driver_active[i]) {
if (bthid_driver_active[i]) {
Serial.printf("*** BTHID Device %s - disconnected ***\n", bthid_driver_names[i]);
bthid_driver_active[i] = false;
} else {
Serial.printf("*** BTHID Device %s - connected ***\n", bthid_driver_names[i]); Serial.flush();
bthid_driver_active[i] = true;
#if 0

const uint8_t *psz = bthiddrivers[i]->manufacturer();
if (psz && *psz) Serial.printf(" manufacturer: %s\n", psz);
psz = bthiddrivers[i]->product();
if (psz && *psz) Serial.printf(" product: %s\n", psz);
psz = bthiddrivers[i]->serialNumber();
if (psz && *psz) Serial.printf(" Serial: %s\n", psz);
#endif
}
}
}
}
</pre>

'''Known Issues:'''
* Version 1.1 of the board leaves TUSB2046's reset line floating. This can be remedied by connecting the TUSB2046's reset line to some other circuit, although this is error prone.

== Power ==

[[File:Teensy4.1_computer_power_circuit.png|thumb|Teensy 4.1 Computer power circuitry]]

The computer's power supply accepts input from four primary sources:
* Barrel jack DC input, 8v to 20v, provides 2A to 5v line
* Screw terminal block, 8v to 20v, provides 2A to 5v line
* Teensy 4.1 micro USB port, 5v input, current limit depends on USB power source
* Expansion ports
** Direct to 5v line, only limited by source current. This allows one to surpass the typical 2A limit on the 5v line.
** Direct to VIN, accepts 8v to 20v. 5v line limited to 2A.
** Direct to 3.3v line, only limited by source current. This can be used to relieve stress from the Teensy 4.1's 3.3v regulator, if needed.

There are a few different power planes on the board:
* VIN, 8v to 20v input
** Feeds power to system 5v and audio 5v
** Audio 5v will come from system 5v if VIN is not provided
* System 5v line
** Provides power to the system 3.3v line and the audio 3.3v line
** If coming from VIN, this line is provided by a 2A switching regulator, which may have some noise.
** Is fed through PMOS power switches to downstream USB devices, functions as VUSB.
* System 3.3v line
** Provides power to the Teensy 4.1 and the TUSB
** Provided by the Teensy 4.1's internal 3.3v regulator from the system 5v line
* System Ground
** Connected to all circutry, with the exception of some of the audio circutry, which uses the audio ground instead
* Audio 5v line
** Provided by either a 5v linear regulator from VIN, or from the system 5v line if VIN is not provided
** Powers the OPA1688 audio amplifier
** Is not broken out to the rest of the board
* Audio 3.3v line
** Regulated by a linear regulator, getting input from the system 5v line through a ferrite bead
** Powers the PCM5102 audio ADC
** Is not broken out elsewhere on the board
* Audio Ground
** Connected to System Ground through a ferrite bead
** Connected to audio circutry
** Provides the ground used for the 3.5mm audio jack
** Not broken out elsewhere on the board

When providing power to the board, a few things should be kept in mind. First, for high quality audio, either VIN must be provided, or the system 5v line must be clean. The latter is generally much harder to do, so it is recommended to provide VIN if possible. For a clean system 5v line, generally it is to provide the system 5v line though a linear regulator instead. Adding more ceramic capacitors to the system 5v line can help as well. If providing power from an exteral board through an expansion connector, providing power to both the 5v and VIN lines can boost the maximum current of the system 5v line above 2A. If more than 2A is needed, for example for more current-hungry USB devices, then this may be desirable. Finally, there is a limit on the safe capacitence to be connected to the system 5v line for the 2A switching regulator to work normally. It is unadvisable to connect more than 800uF of external capacitence to the system 5v line, as it may interfere with that regulator. Although, there really usually is no reason to connect to much capacitence to that line.

If providing power to the system 5v line from an external source and the Teensy 4.1's USB port simultaneously, it is a good idea to include an ideal diode or similar circuit to prevent backflow from the USB port into your regulator, or vice versa, depending on your regulators characteristics. For this purpose LM66100 ICs can be used, as are used to protect the onboard switching regulator from the Teensy 4.1's USB port.

'''Capacitence by Power Plane:'''

* VIN:
** 22uF electrolytic
** 4.7uF ceramic (through ferrite bead)
** 26.7uF total
* System 5v
** 2.2uF on Teensy 4.1, ceramic
** 10uF onboard, ceramic
** Specific to onboard switching regulator: 22uF electrolytic
** 12.2uF total when external 5v is provided (Teensy 4.1 micro USB, expansion slots directly to 5v rail)
** 34.2uF total when onboard regulator is used
* System 3.3v
** 7.13uF from Teensy 4.1, ceramic
** 0.3uF onboard for decoupling, ceramic
** 7.43uF total
* System Ground
** 10.3uF ceramic
** 14.7uF ceramic (through ferrite bead)
** 44uF electrolytic
** Approximately 25.13uF on Teensy 4.1, ceramic
** 94.13uF total
* Audio 5v
** 10.1uF ceramic
* Audio 3.3v
** 10.1uF ceramic
* Audio Ground
** 27.2uF ceramic
** Connected to system ground through ferrite bead - technically connected to those capacitors as well.

Teensy 4.1 Computer

2024-06-13T20:33:46Z

Nuclear: Add power section, saving work even though not yet finished

The Teensy 4.1 Computer is more or less described by its name: Its a carrier board for the Teensy 4.1 which provides four USB ports, an Ethernet port, Hi-Fi audio, and several convenient expansion ports.

== Detailed Specifications ==

'''USB:'''

* TUSB2046 USB Hub, providing 4 USB A ports
* Each port has a maximum of 1.5A output - the port will shutdown due to overcurrent above this
* Board power provides a maximum of 2A to the 5v supply
** one should be aware of this when considering the power used by USB devices

'''Audio:'''

* I2S control connected to Teensy I2S 2
* PCM5102 ADC for providing stereo sound
* OPA1688 for the amplifier
* 3.5mm audio jack, maximum 75mA per channel
* Separate ground, connected to main ground through a ferrite bead
* Separate 3.3v and 5v supplies from linear regulators to reduce noise
** Note: 5v line will come from main 5v rail if only powered from USB

'''Power:'''

* 2A 5v buck regulator (Exact part is the VR20S05)
* PMOS switches to prevent regulator backfeeding from USB and to control power flow (U16, U17, and U18 on the PCB)
* External VIN accepted from 8v to 20v
* Separate 5v and 3.3v supplies for audio circutry
* Barrel jack and screw terminal connections for VIN

'''Expansion Ports'''

* I2S, SPI, I2C, and Serial expansion ports
* 5v-capable 8-bit parallel bus port, with 3-bit address, WR, RD, select, and WAIT lines
* Two larger expansion ports, each providing a '''3.3v compatible''' 8-bit parallel bus, various protocols like I2C and SPI, power, and GPIO

== The Audio Circuit ==

[[File:Teensy41_Computer_Audio_circuit.png|thumb|Teensy 4.1 Computer audio circuit]]

The Teensy 4.1 is connected to the audio circuit via the Teensy's I2S 2 port. This connection goes to the PCM5102 ADC. As is recommended in the PCM5102's datasheet, filtering is added to the output, however the filter used on this board is a bit stronger, using a 4.7nF capacitor instead of the 2.2nF capacitor recommended in the datasheet. The filter cutoff is still far above human perception, at 72kHz, and should filter high frequency noise a bit better. The connection to the OPA1688 is DC, not AC, coupled, but this is according to the recommendations in the OPA1688 datasheet. The gain of the amplifier is configured to be 1, so the output voltage of the amp should match the ADC's output voltage, and be in the range of 0v to 3.3v. A voltage divider is used to activate the PCM5102's soft mute function when the 5v line drops, which is designed to prevent any pops in the audio when the power is disconnected.

The circuit was designed with audio quality, but not energy efficiency, in mind. The circuit may sink as much as 400mA from VIN, and an additional 40mA from the main 5v line. However, when the audio circuit is idle, it should be less than 50mA all together. The 3.5mm audio jack can provide a maximum of 75mA per channel.

'''Example Code:'''
<pre>
#include <Audio.h>
#include <SD.h>

// GUItool: begin automatically generated code
AudioPlaySdWav playSdWav1; //xy=719,389
AudioOutputI2S2 i2s2_1; //xy=892,388
AudioConnection patchCord1(playSdWav1, 0, i2s2_1, 0);
AudioConnection patchCord2(playSdWav1, 1, i2s2_1, 1);
// GUItool: end automatically generated code

void setup() {
Serial.begin(115200);
AudioMemory(10);

if (!(SD.begin(BUILTIN_SDCARD))) {
// stop here, but print a message repetitively
while (1) {
Serial.println("Unable to access the SD card");
delay(500);
}
}

Serial.println("Playing audio.wav...");
playSdWav1.play("audio.wav");
}

void loop() {
// Do nothing forever
}
</pre>

== USB Ports ==

[[File:Teensy4.1_computer_USB_schematic.png|thumb|Teensy 4.1 Computer USB circuit]]

The Teensy 4.1's builtin USB port is connected directly to a TUSB2046 IC, which is a USB hub and provides four downstream ports. Each port has overcurrent protection, with a maximum allowed current of 1.5A. There are also TVS diodes on all USB data lines on the downstream ports, provided by three TPD3E001DRLR ICs. Other than that, each downstream USB port has two 15k pulldowns - one on each data line.

'''Example Code:'''

The best example is found in the Mouse_KeyboardBT example from the USBHost_t36 library, which is included in the TeensyDuino package. For convenience, I have included a stripped down version of it below:
<pre>
#include "USBHost_t36.h"

USBHost myusb;
USBHub hub1(myusb);
USBHub hub2(myusb);
KeyboardController keyboard1(myusb);
KeyboardController keyboard2(myusb);
USBHIDParser hid1(myusb);
USBHIDParser hid2(myusb);
USBHIDParser hid3(myusb);
USBHIDParser hid4(myusb);
USBHIDParser hid5(myusb);
MouseController mouse1(myusb);

BluetoothController bluet(myusb); // version assumes it already was paired

USBDriver *drivers[] = {&hub1, &hub2, &keyboard1, &keyboard2, &bluet, &hid1, &hid2, &hid3, &hid4, &hid5};

#define CNT_DEVICES (sizeof(drivers)/sizeof(drivers[0]))
const char * driver_names[CNT_DEVICES] = {"Hub1", "Hub2", "KB1", "KB2", "Bluet", "HID1" , "HID2", "HID3", "HID4", "HID5"};

bool driver_active[CNT_DEVICES] = {false, false, false, false, false, false, false, false, false, false};

// Lets also look at HID Input devices
USBHIDInput *hiddrivers[] = {&mouse1};

#define CNT_HIDDEVICES (sizeof(hiddrivers)/sizeof(hiddrivers[0]))
const char * hid_driver_names[CNT_HIDDEVICES] = {"Mouse1"};

bool hid_driver_active[CNT_HIDDEVICES] = {false};

BTHIDInput *bthiddrivers[] = {&keyboard1, &mouse1};
#define CNT_BTHIDDEVICES (sizeof(bthiddrivers)/sizeof(bthiddrivers[0]))
const char * bthid_driver_names[CNT_BTHIDDEVICES] = {"Keyboard(BT)", "Mouse(BT)"};
bool bthid_driver_active[CNT_BTHIDDEVICES] = {false};

bool show_changed_only = false;

uint8_t joystick_left_trigger_value = 0;
uint8_t joystick_right_trigger_value = 0;
uint64_t joystick_full_notify_mask = (uint64_t) - 1;

void setup() {
while (!Serial); // wait for Arduino Serial Monitor
Serial.begin(115200);
myusb.begin();
keyboard1.attachPress(OnPress);
keyboard2.attachPress(OnPress);
}

void loop() {
// check to see if the device list has changed:
UpdateActiveDeviceInfo();

myusb.Task();

if (mouse1.available()) {
Serial.print("Mouse: buttons = ");
Serial.print(mouse1.getButtons());
Serial.print(", mouseX = ");
Serial.print(mouse1.getMouseX());
Serial.print(", mouseY = ");
Serial.print(mouse1.getMouseY());
Serial.print(", wheel = ");
Serial.print(mouse1.getWheel());
Serial.print(", wheelH = ");
Serial.print(mouse1.getWheelH());
Serial.println();
mouse1.mouseDataClear();
}
}

void OnPress(int key)
{
Serial.print("key '");
switch (key) {
case KEYD_UP : Serial.print("UP"); break;
case KEYD_DOWN : Serial.print("DN"); break;
case KEYD_LEFT : Serial.print("LEFT"); break;
case KEYD_RIGHT : Serial.print("RIGHT"); break;
case KEYD_INSERT : Serial.print("Ins"); break;
case KEYD_DELETE : Serial.print("Del"); break;
case KEYD_PAGE_UP : Serial.print("PUP"); break;
case KEYD_PAGE_DOWN: Serial.print("PDN"); break;
case KEYD_HOME : Serial.print("HOME"); break;
case KEYD_END : Serial.print("END"); break;
case KEYD_F1 : Serial.print("F1"); break;
case KEYD_F2 : Serial.print("F2"); break;
case KEYD_F3 : Serial.print("F3"); break;
case KEYD_F4 : Serial.print("F4"); break;
case KEYD_F5 : Serial.print("F5"); break;
case KEYD_F6 : Serial.print("F6"); break;
case KEYD_F7 : Serial.print("F7"); break;
case KEYD_F8 : Serial.print("F8"); break;
case KEYD_F9 : Serial.print("F9"); break;
case KEYD_F10 : Serial.print("F10"); break;
case KEYD_F11 : Serial.print("F11"); break;
case KEYD_F12 : Serial.print("F12"); break;
default: Serial.print((char)key); break;
}
Serial.print("' ");
Serial.println(key);
}

//=============================================================================
// UpdateActiveDeviceInfo
//=============================================================================
void UpdateActiveDeviceInfo() {
for (uint8_t i = 0; i < CNT_DEVICES; i++) {
if (*drivers[i] != driver_active[i]) {
if (driver_active[i]) {
Serial.printf("*** Device %s - disconnected ***\n", driver_names[i]);
driver_active[i] = false;
} else {
Serial.printf("*** Device %s %x:%x - connected ***\n", driver_names[i], drivers[i]->idVendor(), drivers[i]->idProduct());
driver_active[i] = true;

const uint8_t *psz = drivers[i]->manufacturer();
if (psz && *psz) Serial.printf(" manufacturer: %s\n", psz);
psz = drivers[i]->product();
if (psz && *psz) Serial.printf(" product: %s\n", psz);
psz = drivers[i]->serialNumber();
if (psz && *psz) Serial.printf(" Serial: %s\n", psz);

if (drivers[i] == &bluet) {
const uint8_t *bdaddr = bluet.myBDAddr();
// remember it...
Serial.printf(" BDADDR: %x:%x:%x:%x:%x:%x\n", bdaddr[0], bdaddr[1], bdaddr[2], bdaddr[3], bdaddr[4], bdaddr[5]);
}
}
}
}
for (uint8_t i = 0; i < CNT_HIDDEVICES; i++) {
if (*hiddrivers[i] != hid_driver_active[i]) {
if (hid_driver_active[i]) {
Serial.printf("*** HID Device %s - disconnected ***\n", hid_driver_names[i]);
hid_driver_active[i] = false;
} else {
Serial.printf("*** HID Device %s %x:%x - connected ***\n", hid_driver_names[i], hiddrivers[i]->idVendor(), hiddrivers[i]->idProduct());
hid_driver_active[i] = true;

const uint8_t *psz = hiddrivers[i]->manufacturer();
if (psz && *psz) Serial.printf(" manufacturer: %s\n", psz);
psz = hiddrivers[i]->product();
if (psz && *psz) Serial.printf(" product: %s\n", psz);
psz = hiddrivers[i]->serialNumber();
if (psz && *psz) Serial.printf(" Serial: %s\n", psz);
}
}
}
// Then Bluetooth devices
for (uint8_t i = 0; i < CNT_BTHIDDEVICES; i++) {
if (*bthiddrivers[i] != bthid_driver_active[i]) {
if (bthid_driver_active[i]) {
Serial.printf("*** BTHID Device %s - disconnected ***\n", bthid_driver_names[i]);
bthid_driver_active[i] = false;
} else {
Serial.printf("*** BTHID Device %s - connected ***\n", bthid_driver_names[i]); Serial.flush();
bthid_driver_active[i] = true;
#if 0

const uint8_t *psz = bthiddrivers[i]->manufacturer();
if (psz && *psz) Serial.printf(" manufacturer: %s\n", psz);
psz = bthiddrivers[i]->product();
if (psz && *psz) Serial.printf(" product: %s\n", psz);
psz = bthiddrivers[i]->serialNumber();
if (psz && *psz) Serial.printf(" Serial: %s\n", psz);
#endif
}
}
}
}
</pre>

'''Known Issues:'''
* Version 1.1 of the board leaves TUSB2046's reset line floating. This can be remedied by connecting the TUSB2046's reset line to some other circuit, although this is error prone.

== Power ==

[[File:Teensy4.1_computer_power_circuit.png|thumb|Teensy 4.1 Computer power circuitry]]

The computer's power supply accepts input from four primary sources:
* Barrel jack DC input, 8v to 20v, provides 2A to 5v line
* Screw terminal block, 8v to 20v, provides 2A to 5v line
* Teensy 4.1 micro USB port, 5v input, current limit depends on USB power source
* Expansion ports
** Direct to 5v line, only limited by source current. This allows one to surpass the typical 2A limit on the 5v line.
** Direct to VIN, accepts 8v to 20v. 5v line limited to 2A.
** Direct to 3.3v line, only limited by source current. This can be used to relieve stress from the Teensy 4.1's 3.3v regulator, if needed.

There are a few different power planes on the board:
* VIN, 8v to 20v input
** Feeds power to system 5v and audio 5v
** Audio 5v will come from system 5v if VIN is not provided
* System 5v line
** Provides power to the system 3.3v line and the audio 3.3v line
** If coming from VIN, this line is provided by a 2A switching regulator, which may have some noise.
** Is fed through PMOS power switches to downstream USB devices, functions as VUSB.
* System 3.3v line
** Provides power to the Teensy 4.1 and the TUSB
** Provided by the Teensy 4.1's internal 3.3v regulator from the system 5v line
* System Ground
** Connected to all circutry, with the exception of some of the audio circutry, which uses the audio ground instead
* Audio 5v line
** Provided by either a 5v linear regulator from VIN, or from the system 5v line if VIN is not provided
** Powers the OPA1688 audio amplifier
** Is not broken out to the rest of the board
* Audio 3.3v line
** Regulated by a linear regulator, getting input from the system 5v line through a ferrite bead
** Powers the PCM5102 audio ADC
** Is not broken out elsewhere on the board
* Audio Ground
** Connected to System Ground through a ferrite bead
** Connected to audio circutry
** Provides the ground used for the 3.5mm audio jack
** Not broken out elsewhere on the board

When providing power to the board, a few things should be kept in mind. First, for high quality audio, either VIN must be provided, or the system 5v line must be clean. The latter is generally much harder to do, so it is recommended to provide VIN if possible. For a clean system 5v line, generally it is to provide the system 5v line though a linear regulator instead. Adding more ceramic capacitors to the system 5v line can help as well. If providing power from an exteral board through an expansion connector, providing power to both the 5v and VIN lines can boost the maximum current of the system 5v line above 2A. If more than 2A is needed, for example for more current-hungry USB devices, then this may be desirable. Finally, there is a limit on the safe capacitence to be connected to the system 5v line for the 2A switching regulator to work normally. It is unadvisable to connect more than 800uF of external capacitence to the system 5v line, as it may interfere with that regulator. Although, there really usually is no reason to connect to much capacitence to that line.

If providing power to the system 5v line from an external source and the Teensy 4.1's USB port simultaneously, it is a good idea to include an ideal diode or similar circuit to prevent backflow from the USB port into your regulator, or vice versa, depending on your regulators characteristics. For this purpose LM66100 ICs can be used, as are used to protect the onboard switching regulator from the Teensy 4.1's USB port.

'''Capacitence by Power Plane:'''

* VIN:
** 22uF electrolytic
** 4.7uF ceramic (through ferrite bead)
** 26.7uF total
* System 5v
** 10uF ceramic
** Specific to onboard switching regulator: 22uF electrolytic
**
** 32uF total when onboard regulator is used

File:Teensy4.1 computer power circuit.png

2024-06-13T20:03:05Z

Nuclear: Power circuitry for the Teensy 4.1

== Summary ==
Power circuitry for the Teensy 4.1