Getting started with the Tiny Tapeout 04+ demo board

If you’ve got hold of a TinyTapeout 04 ASIC and demoboard, this quickstart guide will get you going by walking through:

  • overview and bring-up;
  • interaction through the browser, using the commander app;
  • accessing and using the microPython SDK and filesystem; and
  • easy updates to the OS and SDK.

There’s a little video that goes through much of this so you can see it in action

Overview and bring-up

TT04 demoboard

The TT04 ASIC includes 143 different digital designs, any of which may be enabled so that you can send and receive information to it using whichever combination of the

  • 8 input;
  • 8 output; and
  • 8 bi-directional

pins that specific project is using.

The ASIC comes installed on a carrier PCB which is itself installed on the TT Demoboard

The demoboard is designed to allow for interaction with design either through the on-board input DIP switches and 7-segment display, or with external circuits through the various pin headers and PMODs on the board. Having the ASIC on a carrier, rather than directly on the demoboard, leaves the adventurous free to design their own custom PCB and easily migrate the chip.

The demoboard has a number of headers for interaction and expansion. The “PMODs” follow the digilent PMOD spec and spacing and make it pretty simple to create extensions to interact with designs.

Power

Power, and communications with the management RP2040 that is on the demoboard, comes in via the USB Type-C connector, at the top right of the PCB.

All the I/O expects 3.3V logic levels, so the 5V coming in through the USB receptacle isn’t strictly necessary (it could be back-powered by sending 3v3 on a header pin marked as such), but this is a very convenient way to both power and control the system.

Bring-up

After inspecting the boards for damage, and ensuring the carrier board is well seated on the demoboard, give the system 5V through the USB connector.

Operating normally, the power LEDs on the top right of the demoboard will light up (though the 1v8 may be a bit dim), and the letter “t” will hold on the 7-segment for a moment, then go through a speedy little sequence and finally start toggling the segments in a binary counter dance (see the video for an example). pe The is the factory test project, loaded by default, being ticked and shows the system is alive.

If you have a way to monitor power use, you should see a draw of around 180-200 milliAmps, on the 5V supply and not much more.

Selecting Projects

Maybe you’d like to enable a project other than the factory test?

TT04 introduced a brand new, and much faster, way to direct input and output to designs on the chip. This multiplexer (MUX), needs to be told just which project you’d like to interact with.

To handle most of the details, we put a microcontroller (an RP2040, like on the Raspberry Pi Pico on the demoboard. But you still have to somehow tell it which project you’d like to enable.

There are a few ways to do this, the commander app being the easiest, but there’s also a config.ini file and a whole Python SDK you can use. All are described below.

Commander App

The commander app can let interact with and configure the demoboard from a web browser.

It uses the web serial API, so is currently limited to either Chrome, Edge or Opera .

With the demoboard USB plugged into a computer, use one of those browsers to access https://commander.tinytapeout.com/.

Commander connect page

Clicking on CONNECT TO BOARD will, assuming the board is connected and detected, open a popup from which you can select the device.

Commander select device

The one marked “Board connected in FS mode” or somethnig to that effect is the one you want. Select it and click connect.

If all went well you’ll see something like this:

Commander connected

With the shuttle being set to tt04. Some debug output is visible in the black box at the bottom, where you can glean more info, such as the SDK release detected.

To activate a project:

  1. Click the project drop-down and find the project you want

Commander project selection

  1. Click the SELECT button to actually enable the project

  2. If this is a design that needs to be clocked (a synchronous logic design), you can set the clock frequency and press SET to start the clocking.

You might skip that step and single step the clock, using the INTERACT tab.

Commander interaction tab

Here you can also reset the project, set the inputs. If the author provided it, some information on the project pinout and access to the REPL are available in their own tabs.

SDK and REPL

The microcontroller on the demoboards, the RP2040 is powerful enough to run MicroPython–a lean implementation of Python3–and is connected not only to the project MUX but to all the ASIC I/O as well as the clock and reset pins.

So a micropython SDK was was created to make common tasks simple and most interactions with projects quite easy.

Accessing the REPL

You can interact with the SDK and projects in real-time, through a REPL (a Read-Evaluate-Print Loop, a kind of interactive programming shell), and write scripts to automate testing and interaction with designs on the board.

The same serial terminal used by the commander app, e.g. /dev/ttyACM0 under linux or COM4 under windows, can be accessed using a serial terminal program instead similar to those used with the Arduino IDE to access Serial.print() messages and such, on that platform.

This is over USB and the baudrate doesn’t really matter, so I just use gtkterm or even


screen /dev/ttyACM0

to get in. Once you’ve accessed the REPL, by default you’ll have access to a tt object, which is a DemoBoard object and the main handle into the system.

Selecting and controlling Projects

The Demoboard object, tt, has a shuttle attribute that allows you to list, find and enable projects easily.

If you already know the project’s official fullname, say tt_um_myproject it is a simple matter of calling

tt.shuttle.tt_um_myproject.enable()

to select and enable it.

You can search projects by (partial) name matching:

tt.shuttle.find('traffic')
[<Design 71: wokwi_german_traffic_light>, <Design 180: wokwi_traffic_light>, <Design 115: wokwi_traffic_light_1>]


tt.shuttle.find('traffic')[1].enable()
ttboard.project_mux: Enable design wokwi_traffic_light

And tab-completion will work, too: tt.shuttle.<TAB><TAB> will list all the attributes, including all the projects you can enable.

You can control the auto-clocking using

tt.clock_project_once() # just toggle clock a single time

# or

tt.clock_project_PWM(10e6) # start auto-clocking at 10MHz

# stop it with

tt.clock_project_stop() # or, equivalently
tt.clock_project_PWM(0) # 0Hz == stopped.

Scripting

Once you are familiar with the SDK through the REPL, you may want to automate tasks.

You can simply edit main.py and get it to do what you want, or create independent modules and scripts to keep the seperation nice and clean.

In your scripts and modules, the easiest thing is to treat the DemoBoard object as a singleton, and get access to it like this:

from ttboard.demoboard import DemoBoard

mytt = DemoBoard.get()

mytt.shuttle.tt_um_myproject.enable()

mytt.input_byte = 0xfe
print(f'Output from project is now: {mytt.output_byte}')

# ... etc

Other than that, the SDK documentation and various sample tests will be your best guides.

Filesystem Access

The underlying micropython OS is the standard system used by the Raspberry Pi Pico and if you want to use uPython shouldn’t need much thought or maintenance. The SDK, scripts and configuration reside in the filesystem provided and you may want to tweak these, add your own scripts, etc.

The important things on the filesystem are:

  • config.ini: default startup and project-specific configuration
  • main.py: runs on boot
  • ttboard/ has all the SDK modules
  • shuttles/ contains the design listings as JSON files for the chip

Any standard means of accessing the micropython FS should work. I’ve used rshell a great deal but have found it lacking in some regards. Of late, I’ve turned to mpy-repl-tool.

You can learn about that in its documentation. I like that it lets you easily detect connected boards

python3 -m there detect

inspect files

python3 -m there cat /config.ini

and transfer files back and forth

# recursively pull all the SDK under /ttboard
python3 -m there pull -r /ttboard /tmp

I do find the -m there syntax cumbersome and a bit weird, so I added a function


tt() {
	python3 -m there $@; 
}

to my ~/.bashrc file and a shorthand, so now I can just use tt in its place


$ tt  ls
/config.ini
/examples
/first_boot.log
/main.py
/release_v1.0.0
/shuttles
/ttboard

$ tt push config.ini /

OS/SDK Updates

The complete directions for OS updates are part of the SDK documentation, under Installation but really the process is simply to:

  • download anything on the FS that you wish to preserve (it will all be overwritten by this process)
  • get the UF2 file for the latest SDK release
  • hold the BOOT button on the demoboard while connecting to USB
  • release the BOOT button, see the RPI-RP2 drive appear
  • copy the UF2 file, e.g. tt-demo-rp2040-v1.0.0.uf2, to the RPI-RP2 drive
  • wait until the drive disappears

At this point, the entire flash will have be re-written with a fresh OS, SDK and supporting files.