Introduction
In this part of the blog we want to show how to communicate with the TXT controller. It is a prerequisite that you have successfully finished the first part of our blog post series. As mentioned in part one, the communication runs over our message gateway.
TXT Configuration
The TXT controller’s inputs and outputs can be used in various ways, for example an input can be either a digital input or an analog input. For this reason, the TXT needs to be configured. This configuration is done via a json file which has to be placed in the same folder as the overall configuration file from the first chapter. The name of the file has to be “txt0_config.json”. The file looks like that:
{
"configid": 0,
"extensionid": 0,
"motors": [
true,
true,
false,
false
],
"inputs": [
{
"mode": 1,
"digital": true
},
{
"mode": 1,
"digital": true
},
{
"mode": 1,
"digital": true
},
{
"mode": 1,
"digital": true
},
{
"mode": 1,
"digital": true
},
{
"mode": 1,
"digital": true
},
{
"mode": 3,
"digital": true
},
{
"mode": 3,
"digital": true
}
],
"counters": [
true,
true,
true,
true
]
}The first important part is the motors array. The TXT controller has 8 outputs. As each motor needs 2 sockets, this means that we can control up to 4 motors. If in the array for example, the second motor entry is set to true, then output 3 and 4 are combined as one motor output. If a motor is set to false, then the two outputs are normal outputs. The first entry in the array is for output 1 and 2 (=motor 1) and so on.
The next important part is the input array. Again, the first entry in that array is for input 1 and so on. Each input has two parameters. The mode parameter is 0 if the input is a voltage, it is 1 if the input is a resistor, or 3 if it is the Fischertechnik ultrasonic sensor. The parameter digital specifies whether the input is digital or analog. For digital inputs (=switch), set the mode to 1.
The array for counters must not be changed. This is due to the fact, that during development, these fields were not being used by the TXT controller. However, this might change in the future.
If there is no config file found, then the connector uses an internal set of configurations. Since these default settings might change over time, it doesn’t make sense to make them public. Hence, the best way to do it is not to rely on the internal configuration set and to always make sure to have your own configuration file.
Communication Messages
In this chapter we are going to take a look at what type of messages we can send. The commands for the TXT controller are in the JSON format. They look like the following example :
{
"token":"unique_string",
"txtId":0,
"type":"command",
"command":[
{
"id":1,
"motor":true,
"value":400
},
{
"id":2,
"motor":true,
"value":400
}
]
}Let’s take a look at elements of this JSON string. First of all, there is the previously mentioned token. It has to match the token specified in our config file from the first chapter. Using a unique token will ensure that we only execute commands meant for our controller.
The next element in our JSON object is the txtId. It is an integer value. The id is being used in case we have multiple controllers connected. That’s why we can leave it set to 0 for now. If there is only one TXT controller, the txtId parameter can be omitted. Please obey that txtId has a capital "I".
The next element is the type. With this entry we specify what type of command we want to execute. In the example given above, the value is simply “command” as it is the most basic JSON message we can send. In this part of the blog post, we will discuss all possible types of commands. The TXT controller works internally in a way that each command you send will be executed for a few hundred milliseconds. If the command is supposed to get executed for a longer time, you need to resend it again and again. Don’t worry, because upon reading on, you will learn about new types which will do that for you.
The last element is the command array. Each element of this array will be executed simultaneously. The example above would run the motors with ids 1 and 2. The value specifies the strength with which the motor is running and the sign sets the direction. Note that only values between -512 and 512 are allowed. If you don't have a motor, but a light or a vacuum pump for example then set the parameter motor to false. Due to internal handling of the TXT controller it is important to know if the device is a motor or not.
Each command will trigger a JSON response message with input and counter values from the TXT controller. If you don’t want to perform any actions and only want to read these input values, then you can simply send the following empty command to get the required values.
{
"token":"unique_string",
"txtId":0,
"type":"command",
"command":[
]
}This will trigger a response looking like the following:
{
"token":"unique_string",
"txtId":0,
"type":"resultCommand",
"motorCommand":[
0,
0,
0,
0
],
"sessionToken":"",
"counterCommand":[
0,
0,
0,
0
],
"universalInputs":[
0,
1,
0,
0,
0,
0,
0,
0
],
"counterValues":[
0,
0,
0,
5
],
"counterInputs":[
0,
0,
0,
0
],
"soundCommand":0
}
As you can see, the JSON message includes essential information on the counters and inputs.
As mentioned above, different actions may require different types of commands. Now following is a list of command types, each with a working example of the corresponding JSON message.
Time command
This JSON message will execute a given command for a specific time. As seen before, the command value can have multiple entries so that for example two motors can run at the same time. In the JSON message, we see that the type commandTime is being used. The parameter time then specifies the duration for which the given command will be executed. The rest of the JSON structure is similar to the one we have used above. In this case, the desired action is a movement of the motor with id 1 for half a second.
{
"token":"unique_string",
"txtId":0,
"type":"commandTime",
"time":500,
"command":[
{
"id":1,
"motor":true,
"value":-400
}
]
}
Distance Command
This JSON message will run a motor for a specific distance. However, please note that only the red encoder motors have the built-in function to count their rotations. We see that as type, the commandDistance option is being used. Furthermore, each JSON object in the command array has a parameter distance to specify the rotation. The distance value is related to the number of internal pulses. The easiest way to know what value you have to use is by trial and error.
{
"token":"unique_string",
"txtId":0,
"type":"commandDistance",
"command":[
{
"id":1,
"value":-512,
"distance":150,
"motor":true
}
]
}In the picture below, we see how one of the encoder motor is connected to the TXT controller. Note that additionally to the 2 connection sockets with id 1, we need to connect the motor to 9V DC and the counter sockets with same id. This means that a motor connected to M1 must always be connected to C1 and so on.
Input4stop command
This JSON message will run a specific command until a digital input is opened or closed. We see that the type commandStop is being used. The parameter input4stop specifies which digital input will trigger to stop the execution. The sign of the input4stop parameter is important as well. If it is positive, the command will be executed until the circuit of the input is closed. If it is negative, the command will be executed until the circuit is opened. Keep this in mind when setting up the switches for your model. In the example below motor 1 runs at full speed until input 2 is being closed. The switches used as inputs have 3 connection sockets, with each having a number written beside them. Socket number 1 always is connected to the mass. Connecting the remaining cable to socket 3 will then close the input circuit upon pressing the red button, whereas connecting it to socket 2 will open the input circuit upon pressing the red button.
{
"token":"unique_string",
"txtId":0,
"type":"commandStop",
"input4stop":2,
"command":[
{
"id":1,
"motor":true,
"value":-512
}
]
}
Counter Command
This JSON message will execute a command until the specified counter will be triggered a certain amount of times. In this case, the motor with id 1 will run until the counter with id 4 was closed 5 times.
{
"token":"unique_string",
"txtId":0,
"type":"commandCounter",
"counterId":4,
"counterDistance":5,
"command":[
{
"id":1,
"motor":true,
"value":-400
}
]
}
Sequence command
This JSON message will execute a sequence of commands, each able to be a specific command type. The command below for example will run the motor with id 2 for half a second in one direction and after that will run the same motor in the other direction until the input with id 1 is closed.
{
"token":"unique_string",
"txtId":0,
"type":"commandSequence",
"sequence":[
{
"type":"commandTime",
"time":500,
"command":[
{
"id":2,
"motor":true,
"value":-400
}
]
},
{
"type":"commandStop",
"input4stop":1,
"command":[
{
"id":2,
"motor":true,
"value":400
}
]
}
]
}Camera command
The camera can be started with the command type startCamera. The parameter framerate has a maximum value of 30.
{
"token":"unique_string",
"txtId":0,
"type":"startCamera",
"framerate":20
}Once the camera is started, your web socket connection receives messages like:
{
"token":"unique_string",
"type":"frame",
"frame":"/9j/2wCEAAMCAwMDAgMDAMEBAM... "
}These messages contain the recorded frame as a Base64 encoded pictures under the frame entry. Note that the corresponding string was shortened in this example to maintain readability. It is important to ensure that your message gateway can handle large messages. If you experience occasional issues, try to take pictures of a black background in order to check whether these are transferred without errors over a period of time.
The camera can be stopped with this command:
{
"token":"unique_string",
"txtId":0,
"type":"stopCamera"
}Multiple TXT Controllers
As of now we only have used one TXT controller at a time only. Using the demo connector for Fischertechnik we can run five controllers in parallel. First of all we need to adapt our configuration file
url = <IP address of your TXT controller 0>
url_1 = <IP address of your TXT controller 1>
url_2 = <IP address of your TXT controller 2>
url_3 = <IP address of your TXT controller 3>
url_4 = <IP address of your TXT controller 4>
ws = wss://<endpoint of your message gateway>
token = <a_unique_string_without_spaces>As seen above there are additional url parameters with a suffix to specify the controller. The JSON commands you have learned about in the previous chapters contain the parameter txtId, just specify via this parameter what controller should execute the command.
Read on in part 4 of our blog post series.
- SAP Managed Tags:
