The state of the PEX tutorials

As promised I have finally completed the second PEX tutorial.
And subsequently, as promised, this is the thread for discussing the state of the PEX tutorials.

I think it’s necissarily to clarify a few matters before creating any more PEX tutorials (or at least before I go making any more).

Are any of the existing PEX tutorials ‘official’ or are they all just user-contributed tutorials where the contents are up to the discretion of their creators?

I’ve never been entirely certain of this, but erred towards trying to make them somewhat official.

How steep should the learning curve be?

When writing my tutorials I was intentionally aiming mine at people with no prior experience and keeping the learning curve low rather than diving into some of the theory early on in a deliberate attempt to keep the tutorials ‘fun’ and ‘easy’ for beginners.

Evidently not everyone agreed with this approach and we ended up with ‘resitor-gate’, so it would be good to be on the same page with this.

If these tutorials are ‘official’, should we have one person in charge, or should we get different people doing different sections of the series?

Might be a bit awkward if the tone ends up shifting dramatically, but the final result might be a bit more democratic. Plus many hands make light work.

One approach might be to decide what each tutorial is going to be before hand and then have people volunteer to cover a particular topic.

If these tutorials are ‘official’, should someone else be in charge?

I’ll be the first to admit my knowledge of circuits is severly lacking and due to my other commitments one of my tutorials went unfinished for 2-3 months and I can’t guarantee I won’t get sidetracked with other projects again, so perhaps I’m not the best person to be doing the PEX tutorials?

Or perhaps I ought to just do the early tutorials and then hand over the reins to someone who’s more experienced and has more time?

If these tutorials are not ‘official’, should we simply agree to let people manage their own tutorials?

Might be a nice solution to avoid conflict, and a redundancy of tutorials might be benefiical in the long run. Some people get on better with tutorials of a different tone (some like nice gentle/easy ones, some love something that gets straight to the complexities).

Although I haven’t got a full scale plan drawn up, I did have an idea in my head about the general order of topics I was hoping to cover.
I fully admit that until now I haven’t actually discussed this so it might have appeared that I had absolutely no clue what I was doing.
I did have a general plan scribbled on some paper, but I never got round to discussing it until now for the same reasons that I didn’t get round to finishing the part 2 of the tutorial until now.

The general idea was to cover digital output and input (using LEDs and buttons),
then cover analogue input and output (most likely using a potentiometer and a motor or a colour-shifting LED),
then do a few articles about theory (resistor colours, pull-down vs pull-up resistors, general electricity stuff, electrical diagrams)
then move onto something of medium difficulty (maybe using the Pokitto screen as a rudimentary oscilloscope to display sound input or using the Pokitto screen to draw a thermometer corresponding to a thermal input),
and finish up with covering a few communication protocols and similarly advanced techniques (I2C, SPI, BLE).

So the whole thing would have looked something like:


  1. LED+DigitalOut
  2. Button+DigitalIn
  3. Potentiometer+AnalogueIn
  4. Motor/LED+AnalogueOut


  1. Resitors (colour, maybe make a resitor/button ladder)
  2. Reistors pt2 (pull-up/pull-down, configure the button example to not need a resitor)
  3. Circuit diagrams (common circuit symbols)
  4. Serial vs Parallel circuits
  5. Electricity theory (reistance, amps, ohms, all the boring sciency stuff)


  1. Pokitto thermometer
  2. Pokitto oscilloscope-like thing/decibelometer


  1. I2C communication (maybe using @spinal’s nunchuck thing as an example, or something I2C based that’s especially cheap )
  2. SPI communication (no idea, possibly a screen if there’s one cheap enough, or something cheaper if anyone can think of something)
  3. BLE communication (this would be a lot easer with BLE hats)
1 Like

to give a general solution to your issue is how the community tutorials have worked before. we can enable a post to become a wiki (editable by anyone)
if there are gaps they could be filled in and maybe teaming up for a few tutorials isnt a bad idea

i had been looking at different interfaces before cheap I2C things are monochome oleds or APA102 rgb led strips,
for spi again cheap oleds but there also some in color,
for ble and maybe also wifi there is the esp32, i had been looking at it for the wifi hat but its beyond my skill to properly implement it

1 Like

(Sorry if some of this is a bit long. I’m sort of saying it to everyone rather than just aiming it at you specifically @adekto.)

Making them a Wiki afterwards is pretty much a given, but that still leaves the issue of who originally writes them.

Without any consensus or organisation we end up with more of the current situation: two tutorials aimed at beginners covering easy topics written by one person and one tutorial covering an advanced topic like USART written by someone else in a different tone with different assumptions about the reader’s knowledge.

If we can at least agree upon some basic structure or a list of things we want to be covered then we can divide the work up appropriately.

The main reason I’m encouraging this discussion is so we can hopefully get input from a couple of different people and come to some sort of pseudo-consensus from a couple of users here (hopefully including some thoughts from @jonne when he’s not busy making the library even better, and of course @Hanski since his robot tutorial could possibly link in later on (somehow)).

If we at least have an idea of where things are going and/or what the arrangements are then it puts us in a better position and it helps to make sure the tutorials are following a path everyone is happy with.

It’s easier to plan where the tutorials ought to be heading than for people to spend time writing them and then have other people turn around and say “actually we want it done differently”.

I’m hoping that sort of stuff will be covered later rather than sooner, or at least once there’s a plan in place.

It’ll be easier for people to write about the complicated topics like communication protocols if they can make assumptions about what readers will know (i.e. they can tell readers “you must know the material covered in tutorials 1-8 before readin this”).

Also when it comes to picking components I think the most important things to consider are price, availability and maybe substitutability. (The Pokitto might well get intrest in some less well developed countries and/or countries with a lower level of income so it pays to bear that in mind.)

You might have experience by the time comes to cover it.
If not you, then someone else will know how or be able to figure it out.

fair enough, but what it looks like to stay consistent is to have 1 person write it or at-least edit it to stay consistent

just an idea but maybe anyone who is interested and knows there stuff can come together (some chat room) to debate about every topic in order of difficulty, the tutorials you listed seems reasonable,

additional research like looking for stuff thats explained already well by other websites or even videos might help especially in the theory section

true but the pokitto isnt cheap for that target aswell, and i would consider that if they can get a pokitto they might aswell get a tiny oled screen of ebay/aliexpress or similar retailer, a breadboard is more expensive then these. but this could be solved by selling a experiment kit with the pokitto

1 Like

Inside this massive fountain of text from @Pharap and @adekto is some kind of a question for me. I’m struggling to find it. :smile:

Ok. @Pharap:

Official/community wikis:
I am planning to reorganize the wikis by topics (the official/unofficial thing is kind of secondary). Topics will be like “PEX”, “MicroPython”, and will combine both wikis by me and by community. This is not hard to do, I just need to rewrite some scripts.

Anyone can make / edit wikis but I am the “chief editor” like they have in newspapers. The quality of the stuff others have made is in many cases much better than what I can do myself.

You may have noticed I occasionally edit topics, titles and add gifs etc to community contributions. So far no-one has objected to it, so I take it as an unspoken OK to continue this kind of “main editor” role.

In summary, just make wikis, I will edit small detail and try to make everything fit together.

1 Like

Yeah, consistency edits would be good.
Although if there’s no coordination then that might be difficult if two people write in completely different styles.

A PM would probably work since those can involve multiple people.

Yeah, maybe a couple of ‘external resource’ links would be good in a few of the tutorials.
For example, that sparkfun page where I read about pull-up/pull-down resistors made far more sense than the wikipedia page about them (of course, sparkfun is generally pretty good with tutorials).

In a way I think that maybe the tutorials ought to focus more on ‘how to control the PEX’ rather than getting too hung up on teaching people theory precisely because there are good tutorials like sparkfun out there.

I’ve also thought about this since the Arduino start kit I bought is pretty handy.
That would be a good goal for when there’s more tutorials available.

I put the questions in bold at the top to make sure they stand out from my ramblings. :P

Ok, sounds like a good plan.


The edits are usually constructive minor edits, so I’m fairly sure most people are fine with that.

The main thing that sparked all this was the incident in the comments section of the second PEX tutorial that I wrote where there was a fairly substantial disagreement about the pull-up/pull-down resistors. I’d like to avoid something like that happening again if possible and the only way I could think to do that was to try to coordinate things

Upon reflection, I’m thinking maybe it would be best to just keep doing what I’m doing and ignore the detractors.
I.e. keep the series I’ve been working on as my own series and ignore other PEX tutorials until it makes sense to link them up or until someone expresses interest in collaborating and/or I feel like I need a helping hand.

1 Like

you could hack away on your own and later merge it into an official “complete guide to PEX”
but all things considered we could look at porting over popular tutorials from sparkfun, adafruit, arduino etc…
slap them together and iterate over these till it makes sense for anyone

We’d need to consider licencing if we wanted to ‘port’ them, or even include any substantial amount of information on them. I think most tutorials tend to opt for creative commons licences so there might be some room to do that in some cases.

I think taking them as inspiration or very loosely basing tutorials on their contents would be less of an issue though.

1 Like

Regarding basic electricity write ups, I’ve written about a switched LED circuit here. It overlaps the discussion on the Simple LED Project page, but maybe there is something to use. I’m glad to help write up some content based on the Pokitto.


Interesting read.

I had to look up DIP switch because I’d heard the name but didn’t know what makes them different from regular switches.
(I didn’t realise you discuss them halfway down so I looked them up before reading everything.)
They remind me of household circuit breakers.

I particularly like the disection of the circuit diagram.
Something like that would be good to have when covering circuit diagrams in the ‘theory’ bit.

And it’s good to see the comparison of electricity to flowing water.
That’s an anology that crops up quite a lot.

(Is that breadboard diagram hand-made by the way?)

Dual Inline Package, its the a type of chip that works in a breadboard
there are also SIL single inline package see resistor packs

sorry i know its of-topic

but if the device isn’t one of these there hard to prototype with on breadboards and i would avoid people soldering stuff if possible

1 Like

I know, I looked it up :P.

That I didn’t know. Interesting.

Yeah, that’s another thing in the same vein as the ‘keeping things cheap’ point - stick to breadboard stuff instead of soldering (where possible).

I drew the breadboard internals. I think I used the Pinta drawing program. It’s funny that it is hard to find this sort of illustration, and for a beginner there is no indication which paths the internal connections make.

I’ll look for a place to chip in on the Wiki.

1 Like

Yeah, I ran into the same issue, hence I made this for the first PEX tutorial:

At the moment I’m planning to go ahead with the next two parts doing analogue input and analogue output.
You could either wait until I’m done and then I’ll come back here and try to coordinate something or you could go off and do your own thing for the time being, maybe do a short write-up about circuit diagrams or something.

It’s early days yet so I think maybe getting ideas down and available for people to look at is the main thing, it should be easy enough to modify things and knit them together later on if need be.