The goal of this lesson is learn how to use the member functions of objects. We'll do this by customizing the behavior of a three way switch. The program will first set the switch in the 'left' position; wait 1 second before setting the switch in the 'straight' position, wait another second before putting the switch in the 'right' position. This program requires two types of operations: actuating the switch and waiting.

Flipping a track switch consists of series of operations: activating the servo motors, moving the servo to another position, deactivating the servo motor, updating the track layout in nControl, updating the tile, etc. However, programming our automation sequence is actually pretty easier due to the object oriented nature of Python programming language.
In objected oriented languages the program is structured with objects. For example, in this lesson we're going to use a three way switch tile object. Objects are entities that have properties and functions¹. Properties store information, for example, the three way switch tile object stores which motors are used on the switch. Functions are a combination of instructions, for example, the three way switch tile has functions to move the switch to a particular position.

The first step of our program is to put the switch in the 'left' position. We're going to do that with a function of the three way switch tile object. To figure out which function you need for this, you have to consult the documentation of the three way switch tile. You can find the full documentation here but for convenience we copied a part of it below: Based on this, it's clear we need the setSwitchLeft() function to move the switch in the 'left' position.

Start the nControl software, go to the Configuration Mode and add a three way switch tile:

Let's first check the tiles default behavior. To do this, go to Simulation Mode and click on the tile:

• click on the top of the tile to put the switch in the 'left' position
• click in the middle of the tile to put the switch in the 'straight' position
• click on the bottom of the tile to put the switch in the 'right' position

Let's now reprogram that behavior with a Python program.

To reprogram the tile, go to Configuration Mode, double click on the tile and open the code editor:

Based on the documentation, it's clear we need the setSwitchLeft function for the first step. So the first line of our program becomes: We start with the keyword² self to refer to the three way switch tile we're working in because that's the object we're going to manipulate. Next you write a '.' to specify that what follows is a property or function of that object. And finally you add setSwitchLeft() because that's the function we want to call. Note that we put parenthesis () after the function name. The parenthesis normally contain additional information that we want to send along with our request. However, the setSwitchLeft function does not require any additional information; it can get everything it needs from the properties of the three way switch tile object. But even if you don't need to specify any additional information you have to add the parenthesis. If you don't put parenthesis Python would consider setSwitchLeft to be property. So to make clear that we are calling a function you have to add '()' behind setSwitchLeft.

To wait for one second before flipping the switch again, we can use the tile's sleep function. Function arguments are the additional information that you pass along when calling a function. As shown in the documentation, the sleep function has one argument; being the number of seconds that the program has to wait. For this exercise we are going to use a value of 1 to stop the program for one second. So the second line of our program becomes:

We can implement the rest of the automation sequence in a similar way. Use the setSwitchStraight function to move the switch to the 'straight' position. Wait for one second by calling the the sleep function. And move the switch to its final position using the setSwitchRight function. The last three lines of our program this become:

We now have our complete Python program:
To run your program, start by closing the Code Editor. Switch back to Simulation Mode and click the three way switch tile once. You'll see that it now behaves differently. If your Python program is correct, it should put the switch in the left position, wait a second, put it in the straight position, wait another second and finally put it in the right position. If you click the tile again, it will repeat this behavior.

You can see that our short program, it only consists of 5 lines of code, redefined the behavior of the switch like we wanted. But in the background, our little program does a lot of additional things we don't see yet. To illustrate this, let's add a three way switch to the track layout. To do this, go to Design Mode and repeat the actions shown in the animated image below: If you now go back to Simulation Mode and click the three way switch tile, you will see that the behavior of the switch in the track layout is modified by our Python program as well. If you connect two track switch motors to your computer and link them to the three way switch tile, our Python script will have changed their behavior as well. This illustrates the power of the objected oriented approach. You don't need to know all the details of the operations that have to be performed: how to change the switch icon in the track layout, how to actuate to motors, how to communicate with the controllers, etc. You just have to call the relevant member functions the objects you're working with, three way switch tiles in our case, and they take care of things. In this way you can quickly build powerful applications by reusing large amounts of code of predefined objects. With an object oriented language, writing a program becomes similar to building a MOC³; but instead of having the find the right LEGO® bricks you need to find the appropriate objects and member functions.

---

¹The correct term is method or member function but we will use the term function for the sake of simplicity. ²Technically speaking self is not a reserved keyword in Python; it's a convention. You can use any name to point to the instance of the class, however, it's strongly advised to use self for that and not for anything else. nControl has been implemented using self, so in nControl you have to use self to point to the object you're working in. ³MOC stands for My Own Creation. It's the standard term used by AFOLs (Adult Fans Of LEGO) for their custom LEGO® creations.