# [Wiki] Using The PEX 02 - Adding Extra Buttons

## Introduction:

Now that you have learnt how to use the PEX to send a signal,
the next logical step is to know how to use the PEX to receive a signal.
So for this tutorial I will be showing you how to connect extra buttons to your Pokitto.

## Components:

For this project you will need…

• 1 Pokitto
• 1 Push Button (standard 4-legged button)
• 1 10k Ohm Resistor (Colour coded: Brown Black Orange)
• 1 Short jumper cable
• 3 Long jumper cables (preferably different colours)

You will also need a flat work surface, something to keep your parts in (a small box or bag), and a way to program your Pokitto.

(I will be writing my code in EmBitz, but you are free to use an alternative, the result should be the same.)

## Diagrams

Here’s a preview of what the final circuit should look like:

What Is A Button?

You’re probably sat there thinking “I know what a button is, you don’t need to tell me that”.
But sometimes it pays to be specific, so make sure you read this.

A button is a device that closes a gap in a circuit and allows the electricity to flow down a different path.
Effectively buttons are to electricity what sluice gates are to water - when closed they stop electricity flowing and when open they allow the electricity to flow through.
Buttons come in all shapes and sizes, but for this tutorial I’ll be demonstrating with a common 4-legged button.

The important thing to know about these kinds of buttons is how they work.
Here’s a diagram of how the connections look internally.

See how the top two legs are linked together and the bottom two legs are linked together, but there’s a gap in the middle - that gap is the gap that the switch closes when pressed. It’s important to know how the connections in the switch are arranged so you have a better idea of how the electricity flows through the switch and to make sure that you orient the switch correctly. If you connect the legs up incorrectly your circuit won’t work because the electricity would be flowing across the connected legs rather than trying to go across the gap.

## Instructions - The Circuit:

Step 2 - The Button

Then you’ll need to take your button and place it so it goes across the two halves of the breadboard, like so:

Step 3 - The Small Jumper

Step 4 - The 10k Ohm Resistor

This time around you’ll be using a different kind of resistor. This is a 10k Ohm resistor (10,000 Ohms, or 10 kilo-ohms), which is significantly stronger than the 220 Ohm resistor used in the first tutorial. Don’t worry about the purpose of the resistor for now, that will be covered in a later tutorial.

Take your resistor and use it to connect the breadboard’s ground line to the leg on the opposite side of the button’s ‘gap’.

Although there’s no electricity involved yet, it should be clear already how the electricity is going to flow through the button. It’s going to come in from the power line, travel to the top half of the button, go across the button’s gap (when the button is pressed), then escape from the bottom half of the button through the resistor and end up draining through the breadboard’s ground line. Like so:

Step 4 - The Pokitto

Connect the Pokitto’s `EXT 0` pin to the gap between the button and the resitor.
Then to finish the circuit, connect the Pokitto’s `3.3V` pin to the breadboard’s power line (`+`) and the Pokitto’s `GND` pin to the breadboard’s ground line (`-`).
Your circuit should look something like this:

Last time I used a yellow wire for `GND`, but this time I’m using a green wire for `GND` and a yellow wire for `3.3V`. Technically speaking the colour of a wire doesn’t actually make a difference to the circuit, all wires, regardless of the colour of their casing, are simply a way to allow electricity to flow.

However, the reason wires are coloured in the first place is so that different wire colours can be assigned different meanings. For hobby projects it’s not that important what colour means what as long as there’s some sort of system in place for differentiating meaning. For more important projects, there are certain standards and expectations as to what each wire colour should mean, for example red typically means `5V` (5 volt power) and black typically means `GND` (ground).

Instructions - The Code

Now that the circuit is finished, it’s time to program the Pokitto.
As before I’m going to give you the code and then explain it afterwards. A lot of the structure should be familiar if you read the last tutorial.

``````// The Pokitto library
#include "Pokitto.h"

// The Pokitto Core library object
Pokitto::Core pokitto;

// Create a 'DigitalIn' object to represent the
// digital input pin used to communicate with the button
// The object is set to use the EXT0 pin for input
DigitalIn button0 = DigitalIn(EXT0);

// The main function
int main ()
{
// Initialise the Pokitto
pokitto.begin();

// The main loop
while (pokitto.isRunning())
{
// Update the Pokitto's state
if (pokitto.update())
{
// If the external button is pressed
{
// Fill screen with colour 2 (magenta)
pokitto.display.fillScreen(2);
}
// Else (if the external button isn't pressed)
else
{
// Fill screen with colour 0 (black)
pokitto.display.fillScreen(0);
}

// Write 'Hello World!' to the screen
pokitto.display.print("Hello World!");
}
}

return 0;
}
``````

Explaining The Code:

Here the code is using the `DigitalIn` class, which is a class provided to all mbed-compatible boards and the partner-in-crime to the `DigitalOut` class from the previous tutorial.
`DigitalIn` represents a digital input connection.

Just like `DigitalOut`, to initialise it you simply tell it which pin you want to use, which can be any of the Pokitto’s EXT pins (all 18 of which, `EXT0` through to `EXT17` are pre-defined in the `Pokitto.h` header).
Again, in our case it’s going to be `EXT0` because that’s the slot that’s been wired up.

``````DigitalIn button0 = DigitalIn(EXT0);
``````

The function for reading input from the pin is `read`, which works in reverse to `write`. Instead of giving it a value and getting nothing back like with `write`, `read` doesn’t accept any input and instead it gives back a value.

It returns `1` when there’s power flowing into the pin (i.e. a ‘high’ signal), and it returns `0` when there’s no power getting to the pin (i.e. a ‘low’ signal).

Which is where the following code comes in:

``````// If the external button is pressed
``````

`read` returns an integer (i.e. `int`) which is a number rather than a truth value (i.e. `bool`) so it’s compared to another number to produce a truth value. `if(button0.read() != 0)` can effectively be read as “if the digital input of button0 is not 0”.

Using `button0.read() == 1` would have worked as well, as would many other alternatives, but here I am using `!= 0` because it’s what I find most readable and it can have benefits over other methods (e.g. it can be optimised more easily in some cases).

Lastly the function:

``````pokitto.display.fillScreen(0);
``````

Fills the screen with a specific colour picked from a colour palette.
The Pokitto has many different screen modes, and the size of the palette varies between screen modes. By default the Pokitto uses Hi-res screen mode which permits 4 different colours in the palette.
Of these, colour 0 is black, colour 1 is white, and colour 2 is magenta.
(I’ll leave discovering what colour 3 is as an end-of-tutorial test.)

The Result:

Once the code has compiled correctly and you have it loaded on to your Pokitto (and the Pokitto is wired up correctly) then you can begin testing the code.

If you have wired everything up correctly and the code compiled properly then the screen should be black (with the hello world message on top) when the button isn’t pressed.
When you press the external button, the screen background should turn magenta.

To make sure you know how the electricity is flowing, here’s a picture demonstrating the flow of electricity with arrows:

Note that the path splits in two after passing through the button.
Part of the power goes along the wire into the PEX to deliver the required signal, the other part goes through the resitor and drains into the ground line.

It’s actually possible to configure the PEX in a way that means the resistor isn’t needed because the PEX can function as a resistor if configured correctly. However, that requires further explanation so it’s beyond the scope of this tutorial. It will most likely be covered in a later tutorial.

Do It Yourself Challenges:

Now that you’ve got a working circuit, why stop there?
Why not test how much you understood by having a go at these challenges?

(Note that not all of the information to complete these challenges can be found in this tutorial, you might have to read some others first and come back to the challenges.)

Code challenges:

• Change the code to fill the screen with colour 3 when the button is pressed
• Make the external button cycle through the 4 screen colours

Code + Circuit challenges:

• Add a second button connected to a different Pokitto pin
• Wire an LED up alongside the button and make the LED come on when the button is pressed
6 Likes

Excellent work @Pharap!!

2 Likes

Why the resistor? I would have thought the pokitto could handle 3v to ground?

Just thought I’d get the photos in first this time so I don’t end up forgetting them like last time.
(I’ve got the ‘end result’ ones too if I can’t find something more interesting to do than printing text to the screen.)
The full write up will come sometime in the week.

I’ve only been doing hardware stuff for a few weeks, I’m basing my tutorials on stuff I learnt from some Arduino tutorials (and of course Arduino is 5V).

No idea `¯\_(ツ)_/¯`

If someone (preferably multiple people) can confirm this I’ll leave out the resistor, but I don’t want to risk damaging my Pokitto without confirmation.

Though I’ll want another resistor in at some point so I can discuss the colour coding system in depth instead of continually glossing over it.

1 Like

The I/O pins can be configured as inputs with an internal pull-up or pull-down resistor. No external pull-up or pull-down resistor is necessary.

The resistor you use in your LED project is necessary and suitable for this purpose.

@uXe I skimmed that but could only make so much sense of it. I’m too tired at the moment to deal with Wikipedia’s technical cruft, so I read sparkfun’s tutorial instead (and one from resistorguide) which made more sense. Aparently the resistor I’m using is a pull-down resistor rather than a pull-up resistor:

For simplicity, we will focus on pull-ups since they are more common than pull-downs. They operate using the same concepts, except the pull-up resistor is connected to the high voltage (this is usually 3.3V or 5V and is often refereed to as VCC) and the pull-down resistor is connected to ground.

I read a bit more from other places as well.
I think I’ll explain it in a later tutorial, but not this early in.

I didn’t discuss the colour codes first time because I think it’s important to keep early tutorials fairly simple so people aren’t scared off and people doing this stuff casually can have fun without needing all the details.
Then the more important/more in-depth stuff can be packed into the later tutorials for the more serious people who want to take it further.

Having read into it, that means introducing setting the pin mode in this tutorial. I think it would be better to cover that in a later tutorial where I can explain it as an alternative to pull-up and pull-down resistors (and thus I’d have to have explained pull-up and pull-down resistors beforehand, so I’d need to explain that in a prior tutorial, maybe the one directly before setting the pin mode).

1 Like

The pins have the pull-up resistor enabled after a reset. So if you’re using a pull-up resistor, you can leave it off and still ignore it in the first tutorial.

The first tutorial is about powering an LED so no pull-up resistors involved.

I think I’d rather stick to pull-down where possible anyway.
Having a low signal represent ‘not enabled’/‘not powered’ is more intuitive than a high signal.

I thought it was pretty obvious I meant the tutorial I was commenting on as opposed to the later tutorial you proposed that dealt with setting pin modes.

And while having low mean of be “more intuitive” (whatever that means), it’s also less common and - in this case - required more setup.

You said ‘first tutorial’ so I thought you meant the actual first one.
This is the second tutorial (or subjectively the second part of the same tutorial).

By ‘more intuitive’ I mean that most people are used to the idea of 0 being equivalent to ‘low’ or ‘false’ and 1 being equivalent to ‘high’ or ‘true’ and having the button read 1 when it’s not pressed and 0 when it is pressed seems a little backwards.

It might well be less common, but this is supposed to be about making it easy for beginners (potentially quite young beginners - the Pokitto has a lot of appeal to children).

It might require a tiny bit more set up, but at this point the person following the tutorials has already used a resistor once so it’s not like I’m asking the reader to do something they haven’t already done.

That wasn’t the first tutorial posted, just the first one you posted (maybe). Since none have moved to the WIKI yet, any kind of ordering of the talking about adding buttons is pretty arbitrary. It makes as much sense to assume I meant the tutorial on using the serial port, as that’s the first one I posted. Meaning none whatsoever, as neither needs a pull-up or pull-down resistor.

But yeah, whichever way you think makes it easier is best.

Ultimately I’d rather be safe than sorry so I’m going to get ‘the word of god’ on this matter.

@jonne - what do you think I ought to do for the tutorial?

Include a pull-down resistor so that the logic is 0 for ‘not pressed’ and 1 for ‘pressed’?

Or not use a resistor and thus have the button logic set to 1 for ‘not pressed’ and 0 for ‘pressed’?

I will chime in at some point. IMHO, external pullups/pulldowns is a good concept to explain and visualize, especially in the context of teaching how to build electronics. I see no real harm in that.

I used external pull (ups?) I think, with the multiplayer snake thing, in order to make the button presses more precise (the internal pullup/pulldown is quite weak)

1 Like

Sorry to have to call you in on this since I know you’re very busy, but I thought it would be the best way to settle this since it seems to be going in circles a bit.

I’ll take that as a recommendation to keep the resitor in then!?

In that case I definitely think it makes sense to use the external pull-down resistor.

I don’t want people complaining that their button isn’t very precise/responsive if I can help it, people should be happy/proud with the end result, not sat there thinking “oh, that’s naff”.

I think when this tutorial is finished I’ll make a thread for discussing the state of the PEX tutorials as a whole. I think there’s some confusion as to what the tutorials are about, who the audience are, who is supposed to be writing what and how the PEX tutorials are going to pan out, so it would be good to resolve all that amicably.

Preliminary text for the circuit portion of the tutorial has been added.

Sorry for delays on this.
I’ve been busy on other projects and helping out at home.

As soon as I get chance I’ll upload the pictures I’ve got remaining in order to get the tutorial in an acceptable state and then worry about whether I need to change the ending afterwards.