We could implement this scenario starting from previous project, but we're not going to do this. Instead, we going to start from scratch... Practice makes prefect, especially in coding, so starting from scratch will get you accustomed with coding in Python™. Before we can start coding, you need to create a train control tile so you can access the train and a generic tile to execute your custom script. If you need help with that consult Start - Stop project. Once that's done, you start by creating a variable that contains the object of our train control tile. We can do this by calling the getTile() function of the generic tile we're working in:

train = self.getTile('Train 1')

Now we can pilot our train through the variable train. We can make the train go forward, at 50% motor power, by calling the .goForward() function of the train object.

train.goForward(50)

To keep the train going for 5 seconds, we need to add a delay of 5 seconds and then stop the train. This can be done with the following two lines of code:

self.sleep(5)
train.stop()

To keep the train stopped for 2 seconds before it starts going back, we need to add a 2 second delay before we call the .goBackward() function.

self.sleep(2)
train.goBackward(50)

To keep the train going backward for 5 seconds, we need to add another delay and then stop the train. We can do this with the following two lines of code:

self.sleep(5)
train.stop()

So our full script becomes:

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

# Make the train go forward at 50% power for 5 seconds
train.goForward(50)
self.sleep(5)

# Stop the train for 2 seconds
train.stop()
self.sleep(2)

# Make the train go backward at 50% power for 5 seconds
train.goBackward(50)
self.sleep(5)

We told you to use the .goBackward() function to put the train in reverse, but how can you figure out yourself what function to use? For that, you need to check the API reference¹. The API reference provides an overview of all the functions that are available in each tile of nControl. The documentation of the train control tile, which can be found here, provides the following information on the .goBackward() function:



By browsing through the API reference you can find the function that you need for what you want to do. Once you found it, the reference explains what arguments the function takes, the order in which they have to be provided and the units in which they have to be expressed. In case of the .goBackward() function, the reference shows there is one input argument: power. And that it should be expressed as a percentage of the maximal motor power. The API reference is one of the most, if not the most, important information source when programming in nControl™. Learning how to use reference manuals is an important skill. Any software application in which you can program custom scripts will provide a comparable API documentation.

Once the script works as expected in simulation mode you can run it with an actual train. It should give something like this:

In this project we learned:

• Why we need the API reference
• How to use the API reference
• Practiced our basic Python™ scripting skills

---

¹API is an acronym which stands for Application Programming Interface. An API is a set of specifications that you can use to access resources provided by a software program. It's essentially a communication channel through which you can access the functionalities of another software and use them in your own programs. The nControl API provides you access to all the functionalities of the trains, switches motors, sensors, lights, etc. and lets you control them in your own Python™ scripts.