Teletype 2.0 documentation


Yeah there are a few bits and pieces to install, I’ve written instructions for OSX, but never quite got round to the Linux instructions. I’ll try to find some time today or tomorrow.

(Thanks for the Orca docs, just in time too, I’ve just been updating the builtin help docs, which is the only thing I’ve got left to do before we can release 2.0)


Can you tell me the output from python3 --version please?


i am now back and (finally) able to prioritize helping to get 2.0 released with finished docs. is there anything you’d like to specifically task me with?


for some reason i have different versions on my laptop vs desktop… 3.5.2 on laptop and 3.4.3 on desktop. i get the same error on both when trying to build docs.


Orca ops merged in (thanks @scanner_darkly)

(I’ll come back to the python stuff later on today)


If you could help out with this, that would be grand:

Once I’ve got rc2 uploaded I’ll discuss plans for getting the final version out the door (hopefully this weekend).

Okay, we need python 3.6 or greater, luckily it is possible to have multiple versions of python installed, but it is a bit more complex making sure that the right version is used.

Can you give me some info about the version of Ubuntu you’ve got installed in WSL? Run the following:

lsb_release -a


on desktop:

Distributor ID: Ubuntu
Description:    Ubuntu 14.04.5 LTS
Release:        14.04
Codename:       trusty```

on laptop:

```No LSB modules are available.
Distributor ID: Ubuntu
Description:    Ubuntu 16.04.2 LTS
Release:        16.04
Codename:       xenial```

not sure why they're different - i probably need to update it on my desktop...


Thanks for that. Unfortunately Python 3.6 is not directly available from the Ubuntu 16.04 repos.

You’ve got 2 choices…

Either wait a bit for more Linux options to become available for WSL (see here and here, WSL apparently supports multiple installed distros now).

Or, we can install Python 3.6 onto 16.04 with either a PPA or using pyenv.

The PPA route will teach you more about Ubuntu (as they are specific to it), whereas pyenv is a much more generic Unix solution that will teach you more about Python infrastructure.


thanks @sam! i’m a bit reluctant to use either option to be completely honest :slight_smile: was more curious about generating docs, not likely something i’ll do often, and for ops i’m able to execute from windows without any issues.

so i thought i’d check if i could get docs to work with python for windows, managed to download all the required packages and latex for windows, and was able to build the html version! for pdf ran into another issue, i don’t have helvetica and menlo fonts, updated to use different fonts and i can generate pdf file too now.


If you pull in the latest code for RC2 it has the Roboto TTF files included to stop that issue.

I’m glad you’ve got it working on Windows with a workflow that you’re comfortable with.


I just went through the latest revision of the documentation by @jlmitch5. Pretty excited about all the new stuff, and really thankful for the detailed and well written docs!
I did have just one little problem with the “queue” section. I must admit that I don’t really understand how the queue is supposed to work or to be used. There’s also some contradictions between the old guide and this new one.
So while the original guide states that “Q.N sets the read position”, the new one attributes Q.N to setting the length of it. Maybe that’s the same… but it sounds confusing to me.
Also, what is maybe missing for somebody like me who perhaps lacks the deeper understanding of how a “shift register” works: how do you use the queue, and how do you get the values out of it again? When trying it out, I always just get the last number… and maybe that’s the intended result. But again, I think a more specific description of in in the docs could prevent confusion and doubts about it.

Also… as soon as I’m out of the current swampedness… I’m volunteering to make some compact cheat-sheets for the OPs, interested?


I’ll leave someone else to answer the queue related questions (brain capacity is maxed out right now), but just to say, if you do manage to gain a better understanding of it and fancied writing up a better description we can update the docs (or you could try yourself if you’re familiar with the tools we use, or want to learn).

Will that be dynamic? As in generated on the fly. Or static?

As it stands, there is basically a database of the OPs with their docs, we use that to generate the PDF and HTML files. I was planning on writing some code to generate a cheatsheet too (via Latex), but haven’t had the time yet.

A static cheatsheet would be much more aesthetic, but is much harder to keep up to date. If you wanted to go that route it would depend on how much commitment you wanted to make to it’s future upkeep.


Oh yes! I can totally try to do that! Once I have things figured out :slight_smile:

I was thinking about something static… but you’re right, that would be hard to maintain. Unfortunately I’m totally unfamiliar with Latex and am really not much of a coder…
The idea comes mostly from the fact that I’d make such a cheat sheet for myself anyway, since my memory sometimes struggles with holding all the info needed to operate this module and I like to have something really compact with just the main info, so I can quickly take a peak. It’s not something that is intended to replace the manual, more a companion to it, for people who already know their way around the module but forgot some detail or are not sure anymore how exactly something has to be written.


Great idea @papernoise!

If you would prefer working on these cards statically, I could see about trying to use that as a mockup for pulling the data dynamically and building the layout in html/css–just let me know!

I haven’t used Q in terms of Teletype scripting (so I can’t help with the specific syntax), but you can think of it like a data structure that you can put data on, and pulling it off will get you the first values you put on. A simple use for a queue to keep a schedule for executing things that you don’t want to (or can’t) execute immediately (maybe you’re waiting for a trigger on a certain input to continue stepping through execution).

It’s basically the opposite of the stack data structure, which gives you the last piece of data that you put on it. An undo feature would work well as implemented by a stack, where the last action the user did is the one you want to revert first.


@jlmitch5 makes a good point, if it’s going to be done in HTML/CSS then it is something that could be converted.

Otherwise I too wish to have a cheatsheet to keep near the modular, so I’m incentivised to do it. But I doubt I’ll have the time before the summer holidays finish.

(as an aside, I seem to recall you mentioning baby wearing on a previous thread… I had my son in the sling for about 45 minutes this afternoon while playing on the modular… it was awesome!)


I would also like a cheat sheet to have near my rack.


thanks for the info! Indeed I had interpreted Q to be the opposite of the stack, but there’s one puzzling difference. While the stack has the S.POP OP, Q doesn’t seem to have something like that. Executing Q will always

just give you the last item, so there seems not to be any way to access the other items.
For now the most useful use of Q seems to be for using the Q.AVG code and maybe that’s what it was designed to do in the first place.

Caution adviced. I did that as well and now my son now tries to patch cables into the modular every time he gets near to it… and he’s only 17 months old :smiley:



Are the commands on the Ansible documentation page for Kria and MP current for teletype 2.0?


The list of OPs in the Teletype 2.0 docs (the PDF is included in the firmware zip) should be authoritative. The list of OPs is automatically cross referenced with the Teletype source code to try and avoid omissions.

Is there something specific you’ve noticed?

(Maybe once the HTML version of the Teletype docs is online, we can remove that section from the Ansible docs, and instead reference the Teletype ones to reduce duplication)



I did not have the PDF in the version I had installed. Now I do!