Before we can start programming you have to make sure your train is connected to nControl™:

• If you have a Power Functions train, you need to replace the Power Functions IR receiver by a 4DBrix™ WiFi train controller. Make sure the train controller is configured so it can access your WiFi network. This page explains in detail how to do that.
• If you have a Powered Up train, you need to connect to it with a BLE112 dongle. The following getting started guide walks you through the process of connecting to the PU trains.

Also make sure your can control the train manually with a train control panel. The following getting started guide walks you through the process of setting up a train control panel. To control your train with a train control panel you should have a project that looks like this:

If you can control your train with the control panel you're ready to move on to automating your train with Python™ scripts!

In nControl™ the program scripts are written in tiles. In this demo we want to start and stop the train by clicking a tile. Start by adding a generic tile to your project; the animation below shows how to do that. To remember what the tile does, we're naming it Start.


We're going to write our program in the code editor of the generic tile. When we will click the generic tile, it will execute this program.

The train is controlled by the train control tile, so to pilot our train we need to send instructions to the train control tile. To do this, we first need to create a variable that contains the train control tile. We can do that with the following line of code:

train = self.getTile('Train 1')

Let's analyze this line of code so you understand what it means. In Python™ the code is organized in objects. We're not going to go into the details at this point, but you can look at objects like small toolboxes that can help you get things done. We're currently programming in the generic tile, which is an object. In Python™ the keyword¹ to access the object you're working in is self. So in this line of code self means our generic tile. We want our generic tile to have access to the train control panel. We can get access to any tile by calling the getTile() function of our the generic tile. You do this by adding a dot and the name of the function, this gives us:

self.getTile()

We also need to specify which tile we want to access, in this case we need to access the train control tile Train 1; Train 1 being the label of the train control tile. To pass that information to the function, you need to put it in between the parenthesis. As the value we're passing is a text you also have to put it between quotes, so we get:

self.getTile('Train 1')

The line of code above will ask the generic tile to give us the object to access our train control panel. To be able to use that object in our program, we need to save it in a variable. That explains the train = part of the code. It makes the progam store the requested object in the variable train. So finally we get our line of code:

train = self.getTile('Train 1')

In plain English, it asks the tile we're working in to retrieve the object of the train control panel Train 1 and store it in the variable train.

Now that we have an object of our train control tile, we can start piloting our train. To start the train we can use the goForward() function of our train object.

train.goForward(50)

The argument 50 specifies that we want to train to run at 50% of the motor power. As the value 50 is a number and not text, we don't put any quotes. We want the train to drive for 5 seconds. So after starting the train, we need to wait for 5 seconds and then stop the train. This can be done by calling the sleep() function of our generic tile. The value passed to the sleep function specifies the delay in seconds. As this is a number, you should not use any quotes.

self.sleep(5)

After waiting 5 seconds, we need to stop the train. The train can be stopped by calling the stop() function of the train object.

train.stop()

So your complete program becomes:

train = self.getTile('Train 1')
train.goForward(50)
self.sleep(5)
train.stop()

If you download the project file at the top of this page you'll see that the script looks lightly different:

# Get the train control panel object
train = self.getTile('Train 1')

# Make the train go forward at 50% power
train.goForward(50)

# Wait for 5 seconds
self.sleep(5)

# Stop the train
train.stop()

The lines that start with a '#' symbol are comments. They are ignored by Python™ but they help you to understand the code. Commenting code is good practice, you should use comments to explain why you're doing certain things. The way you tackled the problem is clear to you when you write the code, but most likely you will not remember the details when you look at the code several month or years later. At that point, comments can be useful to quickly understand what the code does and how it does it. Note that the comments in these example projects are too detailed; you normally don't add a comment for each line of code but these projects are intended to get your started so the comments are there for educational purposes.

It's good practice to test the automation scripts in Simulation Mode before running the automation project with a real train. When you click the generic tile in simulation mode you should see that the train starts with 50% power and stops 5 seconds later.

Once the script works as expected in simulation mode you can run it with an actual train. Switch the train on, connect it to nControl™ and go to Operational Mode mode by clicking on the button. Then click on the generic tile. Your train should go forward for 5 seconds and then stop. If you hit the tile for a second time, it will go again.

In this first project we learned a number fundamental concepts of Python™ and nControl™:

• Using the self keyword¹ to access the object you're working in
• Using the .getTile() function to get access to other tiles
• Calling functions in Python™
• Adding comments in Python™

---

¹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.