Application-Note PiXtend Python Library

Application-Note PiXtend Python Library Installation, Orientation and Programming APP-PX-401 Status: 05.03.2018, V1.01 Qube Solutions UG (haftungsbeschränkt) Arbachtalstr. 6, 72800 Eningen, Germany http://www.qube-solutions.de/ https://www.pixtend.de www.pixtend.de Copyright by Qube Solutions UG (haftungsbeschränkt) 1 / 32

Change History Version Description Sign 1.00 Document created RT 1.01 Link for download changed to PPL-Version 0.1.1 zip file RT Table of contents 1. Introduction... 3 2. Installation with PiXtend Image...6 3. Installation on original Raspbian...7 3.1 Python Version...8 3.2 PiXtend Python Library... 9 3.3 Programming Tool...10 3.4 SSH-Client...11 3.5 WinSCP (Windows Secure Copy)...12 4. Programming...13 4.1 The PiXtend Python Library (PPL)...16 4.2 First program...18 5. Further information...23 5.1 Available PiXtend I/Os... 23 5.2 Dealing with the auto(matic) mode... 23 5.3 Start Python automatically... 23 5.4 Using the serial interface... 25 5.5 Using the CAN bus... 25 6. Frequently Asked Questions (FAQ)... 26 7. Appendix A... 27 www.pixtend.de Copyright by Qube Solutions UG (haftungsbeschränkt) 2 / 32

1. Introduction We are pleased to present you a further possibility for programming PiXtend, and for opening the door to the world of Python at the same time. (Image source: https://www.python.org/, The Python Brochure) The programming language Python is described as a universal and interpretable language. It should have a short and readable form to make programming easier. For instance, a key feature of Python is that the programming code is structured by the indention of the code 1. The enthusiasm and spread of Python is not only due to a very large library base you can find something for nearly every application but also the large community that has developed around Python makes this language very popular. Furthermore, Python is freely available to everyone and can thus be used for professional training, studies, at home, as well as commercially. The programming language can be used by beginners as well as advanced programmers to create computer programs for different systems. Therefore, it is not surprising that the Raspberry Pi Foundation has decided to integrate Python directly into their Raspbian Image 2. Immediately after the first start, you can begin programming with Python, everything is already pre-installed. Access to the on-board GPIOs or SPI bus, for example, works Out of the Box. Raspberry Pi, PiXtend, and Python are a perfect match. 1 Source: Wikipedia April 2017: https://de.wikipedia.org/wiki/python_(programmiersprache) 2 https://www.raspberrypi.org/documentation/usage/python/ and https://www.raspberrypi.org/downloads/raspbian/ www.pixtend.de Copyright by Qube Solutions UG (haftungsbeschränkt) 3 / 32

Hence we have decided to make PiXtend available in combination with Raspberry Pi to the Python Community, and we have launched our own Python module, the PiXtend Python Library (PPL). The PPL is open-source and therefore can be used, modified, and extended by anyone. We would be pleased if you post your PPL version in the forum. In this application note, we would like to show you step by step how quickly and easily you can set up the PiXtend Python Library (PPL) on your PiXtend system and create your first Python program. We hope you enjoy testing, programming, and experimenting as much as we do! For further information, tips and tricks visit our support forum at: https://www.pixtend.de/forum/. The latest versions of all documents and software components can be found in the download section of our website: https://www.pixtend.de/downloads/ www.pixtend.de Copyright by Qube Solutions UG (haftungsbeschränkt) 4 / 32

1.1 Requirements The driver supports PiXtend with Python 2.7.9 and later versions (not Python 3) as well as PiXtend V1.2 und V1.3. You can use any PiXtend system. Moreover, you are not set on for a particular model of Raspberry Pi. However, we recommend one of the following models: B, B+, 2 B, 3 B. Download the PiXtend Image - PiXtend Python Library SD card image from our download section and use it as the initial point for your projects. Alternatively, you can also use the original Raspbian Jessie image. You will find the appropriate installation steps in chapter 3. You can either access the Raspberry Pi by cable-connected keyboard and monitor, or by SSH (TeraTerm / Putty) from a computer. If you are using an original Raspbian Image directly, the Raspberry Pi needs an active Internet connection to carry out the steps shown in this document. We further recommend keeping the app notes Control- and Status-Bytes ready as well as the Process Data of PiXtend ready. These documents contain information on the configuration of the PWM-outputs and analogue inputs as well as interesting facts about the GPIOs, the digital in- and outputs, and the PiXtend relays. 1.2 Disclaimer Qube Solutions UG cannot be held responsible for any damages that may result from the use of the provided software, hardware, drivers or the steps described in this application note or software by third-party manufacturers. 1.3 Safety instructions PiXtend must not be used in safety-critical systems. Before use, please check the suitability of Raspberry Pi and PiXtend for your application. www.pixtend.de Copyright by Qube Solutions UG (haftungsbeschränkt) 5 / 32

2. Installation with PiXtend Image In the PiXtend Image PiXtend Python Library SD card image, the PiXtend Python Library is already pre-installed and can be used immediately. On the Raspberry Pi, you will find all the files in folder /home/pi/ppl/. You can therefore skip the beginning of chapter 3 and continue directly with chapter 3.3 Programming Tool. If you have already installed an SSH client, and a program to transfer files to the Raspberry Pi, or you are working directly on the Raspberry Pi with a monitor and keyboard, you can go straight to Chapter 4. Programming. www.pixtend.de Copyright by Qube Solutions UG (haftungsbeschränkt) 6 / 32

3. Installation on original Raspbian The installation of the required software is explained below: We start with an original Raspbian Jessie Image (Release: 10.04.17). With this image, the new PIXEL interface automatically starts after the first booting. We disable the interface because we do not need it here. The subsequent steps require a monitor, keyboard and mouse. Logging via Ethernet using SSH does not work, because the SSH server is disabled by default. Click on the terminal icon in the PIXEL interface's menu bar and open a console window. It s best to maximize the window. Now we can open the configuration on the Raspberry Pi: sudo raspi-config The configuration program for the RPi is started. In the "3 Boot Options" menu item, select "B1 Desktop / CLI" and then in the sub menu "B2 Console Autologin". Answer the following question with <Yes> and then go back to the main menu with <Ok>. 3 Boot Options B1 Desktop / CLI B2 Console Autologin <Yes> <Ok> We can also use this opportunity to activate the SPI bus. This is also done in the configuration program raspi-config: 5 Interfacing Options P4 SPI <Yes> <Ok> In order to be able to access the Raspberry Pi over the network via SSH to run your own Python program for example, the SSH server must be activated at this point: 5 Interfacing Options P2 SSH <Yes> <Ok> www.pixtend.de Copyright by Qube Solutions UG (haftungsbeschränkt) 7 / 32

Now we can leave the configuration program. Simply press the Tab key twice, until the word <Finish> is highlighted in red and then press the Enter key. After these changes a reboot must be carried out. If raspi-config should not offer this when leaving the program, enter the following command: sudo reboot Now we can download and install the required components in the next steps. To download the necessary files from the Internet, the Raspberry Pi must have an active Internet connection. 3.1 Python Version The PiXtend Python Library (PPL) requires Python version 2.7.9 or later, but not Python 3. Python is already pre-installed in Raspbian, the version is easy to find: python --version Python should report version 2.7.9. For the PPL to have access to the GPOs and the SPI bus of the Raspberry Pi, two other Python packages must be installed. The packages are called RPi.GPIO 3 and spidev 4 and can be found easily with the pip program: pip freeze The program prints a list of all installed Python packages, and in this list you should find RPi.GPIO in the upper part and spidev in the lower part. Please note: If you are using the Raspbian Lite image to start off your programming with Python, you have to install it first as it is not included. Use the following command to install Python on your Raspberry Pi using: sudo apt-get install python-dev 3 RPi.GPIO is installed in Version 0.6.3 4 spidev is available in Version 3.0 www.pixtend.de Copyright by Qube Solutions UG (haftungsbeschränkt) 8 / 32

3.2 PiXtend Python Library Since all requirements for the installation of the PPL are fulfilled, in the first step we create a directory for the PPL package, then download the package and unpack it into the created directory. In the last step we install the PPL package. Once this is done, the PiXtend Python Library can be used globally in all Python 2.7.9 programs. The installation of a Python package can produce a lot of output on the console, this is completely normal. Execute the followings steps in sequence: mkdir ppl wget http://www.pixtend.de/files/downloads/ppl_v0.1.1.zip unzip ppl_v0.1.1.zip -d./ppl/ cd ppl sudo python setup.py install If the last command was successfully executed, the PiXtend Python Library is now installed and can be used in your own Python programs. The installation of the PPL package can be verified with pip freeze as shown in the previous chapter. The entry pixtendlib == 0.1.1 can now be found in the list of installed packages. All we need now is an editor to write Python programs, one to transfer the created programs to the Raspberry Pi and execute them. NOTE: The functions and features of the PPL must not be called faster than every 100 ms! www.pixtend.de Copyright by Qube Solutions UG (haftungsbeschränkt) 9 / 32

3.3 Programming Tool There are a great number of program and programming environments to create Python programs. We have picked one program out of this multitude of programs and show all examples using this program. In this manual, we use Notepad ++ for Windows to create Python programs. The 32Bit version of the program is completely sufficient and provides everything which is necessary to write our first Python programs. You can download the program from the following website: https://notepad-plus-plus.org (Image source: https://notepad-plus-plus.org) Run the Notepad ++ installation program and follow the steps shown by the installation wizard. Usually, the installation does not have to be customized and all steps can be simply confirmed with Next. After the first start, Notepad ++ shows the program modifications compared to the previous version. This editor window can be closed by clicking on the white X in the red rectangle. The text in the window disappears and you get an empty editor window. www.pixtend.de Copyright by Qube Solutions UG (haftungsbeschränkt) 10 / 32

If you do not like using Windows, and prefer to work directly on the Raspberry Pi with monitor and keyboard, you can use the pre-installed text editor nano. For more information on this and other editors, please visit the Raspberry Pi Org website: https://www.raspberrypi.org/documentation/linux/usage/text-editors.md or the nano website at: https://www.nano-editor.org. Chapters 3.4 and 3.5 can be skipped in this case, since no SSH client is required and the program WinSCP is also omitted. All advanced users and programmers who already have a lot of experience and are looking for a more comprehensive solution, can look at the program PyCharm of the Czech company JetBrains. This is a complete Python development environment with many additional features. For more information on this tool, please visit: https://www.jetbrains.com/pycharm/ 3.4 SSH-Client A SSH client (Secure Shell Client) is necessary to run commands on the Raspberry Pi over the network. Further information about SSH can be found on Wikipedia for example: https://de.wikipedia.org/wiki/secure_shell. Such a SSH client is, for example, the program PuTTY.exe www.putty.org. In the following chapters we will use this program to connect to the Raspberry Pi via network and to execute commands. On the programs homepage you will find a setup program, which allows a comfortable installation under Microsoft Windows. www.pixtend.de Copyright by Qube Solutions UG (haftungsbeschränkt) 11 / 32

3.5 WinSCP (Windows Secure Copy) WinSCP allows you to transfer files from one computer to another using different data transfer protocols, including the SSH protocol, which is also used by PuTTY. Compared with PuTTY, WinSCP offers the possibility to load files on or take files from the Raspberry Pi using a graphical user interface (GUI). The reason we use two programs is, within WinSCP the built-in console or rather the SSH client to send commands to the Raspberry Pi is not as convenient as using PuTTY. We have now prepared all software components. The next chapter is about testing and programming! www.pixtend.de Copyright by Qube Solutions UG (haftungsbeschränkt) 12 / 32

4. Programming The first step is to use a sample program that is already on the Raspberry Pi. It is part of the PiXtend Python Library and is located in the folder /home/pi/ppl/examples. Those working directly with the Raspberry Pi can skip the first step and start directly with the second. All those who want to connect to the Raspberry Pi via network, using SSH with PuTTY start with step 1. 1. Login Start PuTTY and enter the name or the IP address of the Raspberry Pi under host name (or IP address). Ensure that the port is set to Port 22 and SSH is selected under Connection type. Clicking on Open will initiate the connection to the Raspberry Pi. The username is "pi" and the password is "raspberry" without quotes. www.pixtend.de Copyright by Qube Solutions UG (haftungsbeschränkt) 13 / 32

2. Example directory After the login, we are in the pi-user home directory (/home/pi). Here is already the folder ppl that was created in the beginning and where the source code of the PiXtend Python Library and the sub-folder examples with the examples are located. We change to the directory with the examples: cd./ppl/examples/ 3. Starting an example In order to see something happening on the PiXtend Board, we start the example for the digital outputs and relays. The switching of the relays can be heard quite well and the LEDs indicate the status additionally. We use the following command: sudo python px_digital_output_demo.py www.pixtend.de Copyright by Qube Solutions UG (haftungsbeschränkt) 14 / 32

After the program has started, the digital outputs and the relays change their states about every 2.5 seconds. In the console, the current state is displayed in text form, with 0 meaning Off and 1 meaning On. There is also a cycle counter that increases by one every 100 ms. Not that someone thinks the program is standing still. With the keys Ctrl + C you can end the Python program. 4. Done If the Python program has been ended with the keystroke Ctrl + C, we have completed the first test with Python and the PiXtend Board successfully, and can continue with the programming in the next chapter and start to create our first program. www.pixtend.de Copyright by Qube Solutions UG (haftungsbeschränkt) 15 / 32

4.1 The PiXtend Python Library (PPL) So far, we have used the PiXtend Python Library together with an example. In order to create a program, some knowledge about the PPL itself is necessary, namely what properties are there and which functions must be used so that something is working at all. The following is a brief description of the most important functions and properties that are required to work with the digital inputs and outputs. A complete overview of all properties and functions can be found in Appendix A of this document. We also recommend using the WinSCP program to download the Python examples from the Raspberry Pi and to look at them, e.g. if you would like to use the analog inputs and outputs, GPIOs or model-building servomotors. In the PPL folder on the Raspberry Pi is a folder named doc, here you will find a HTML file created with the Python program pydoc. This is a purely technical (automatically generated) documentation of the entire PPL package, which shows all public functions and properties along with comments from the source code. The PPL essentially contains one Python class: the 'Pixtend' class derived from a Python object. This class offers the user a set of properties and functions to configure the microcontroller on the PiXtend board and to work with the digital and analog inputs and outputs as well as the GPIOs. The following table shows the most important functions and properties: 5 Name Type Description open function The open function starts the Python SPI driver, opens the SPI master 0 with chip select line 0, and sets the transfer speed to100 khz required for the micro-controller. The open function must be called right after the creation of the PiXtend object, if another function or property is used, an IOError will be thrown. Example: p = Pixtend() p.open() auto_mode function The auto_mode function facilitates the communication with the micro-controller and should be called next after the open function, preferably in an infinite loop or until the function returns 0 and the uc_status property has the value 1. From this point on, the auto_mode function can also be called sporadically, e.g. whenever new values are required or an output needs to be set. A cyclic call is recommended but is not mandatory. There is one restriction: The auto_mode function must not be called faster than every 100 ms. Example: if p.auto_mode() == 0: p.relay0 = p.on close function If the Python program is to be closed, it is recommended to call the close function first and then delete the PiXtend object subsequently. The close function resets all internal variables and objects and closes the SPI driver. This approach is to help to prevent memory leaks and to end the Python program "cleanly". This way you can restart your Python program immediately without an error message. 5 The meaning of (r) and (rw) behind a property: = read only and rw = read and write www.pixtend.de Copyright by Qube Solutions UG (haftungsbeschränkt) 16 / 32

Example: p.close() p = None digital_input0.. 7 Property (r) With these 8 read only properties (digital_input0 to digital_input7), the states of the digital inputs can be read from the PiXtend board. The properties provide either the value 0 for OFF or the value 1 for ON. digital_output0.. 5 Property (rw) The 6 digital outputs can be read as well as written to via the properties digital_output0 to digital_output5. If the property is assigned the value 0, the corresponding digital output turns OFF or when the value 1 is assigned, the output turns ON. relay0.. 3 Property (rw) The 4 relays on the PiXtend board can be read as well as written to via the properties relay0 to relay3. If the property is assigned the value 0, the corresponding relay turns OFF or when the value 1 is assigned, the relay turns ON. uc_board_version Property (r) The PiXtend Board version can be read from this read-only property. The value 12 denotes board version 1.2.x, 13 for board version 1.3.x etc. uc_fw_version Property (r) Using this read-only property, the firmware version of the microcontroller on the PiXtend board can be read. uc_status Property (r) The uc_status property provides the current state of the microcontroller on the PiXtend board. A 0 means OFF or Auto mode is not active. In contrast, a 1 indicates that the MC is operating in Auto mode and has the status Run. ON Constant Corresponds to decimal value 1. OFF Constant Corresponds to decimal value 0. www.pixtend.de Copyright by Qube Solutions UG (haftungsbeschränkt) 17 / 32

4.2 First program The basics for programming the PiXtend with the PPL in Python are covered, now we can write our first program. The following steps show you how to create your own Python programs. 1. Start First, we need a text editor, under Windows the aforementioned Notepad++ for example or under Linux the editor nano, into which we can enter our program. The following steps are done under Windows, and the programs Notepad++, WinSCP and PuTTY mentioned in the beginning are used. 2. Open the editor Start the Notepad++ editor and create a new blank text file. The file should be stored immediately, e.g. program1.py. The saving of the file causes Notepad++ to automatically set the editors language to Python and enables syntax highlighting for this language, which helps us when programming. www.pixtend.de Copyright by Qube Solutions UG (haftungsbeschränkt) 18 / 32

3. Writing the program Everything is ready, now we can start with the Python programming. As our first program we let relay 0 cyclically turn on and off every second. The following program will do this task for us. Simply enter the program in Notepad++ or copy it over and save it. For manual input please pay attention to the indentation and do not mix blanks with tabulators, otherwise the program does not run later on and there will be error messages, for Python this is not a joke. The first program: #!/usr/bin/env python from pixtendlib import Pixtend import time p = Pixtend() p.open() while True: if p.auto_mode() == 0: if p.relay0 == p.off: p.relay0 = p.on else: p.relay0 = p.off time.sleep(1) Program explanation: In the first line we declare that this is a Python program, this will run later on the Raspberry Pi. To wait at the end of the program we import the time class, too. Then the Pixtend class has to be imported, so we get access to the mentioned properties and functions, and a communication with the micro-controller and DAC on the PiXtend board will be possible. In a while loop, we call the auto_mode function, which in Python we can combine with an if query, that gives us a short code line. We compare the response of the auto_mode function to the number 0 (zero), i.e. we check if everything is working. If the function returns the value -1, there is a problem with the communication with the micro-controller. CAUTION: Do not call the auto_mode function faster than 100 ms (0,1 second) If the query was successful, we can turn the relay 0 cyclically on and off for example. www.pixtend.de Copyright by Qube Solutions UG (haftungsbeschränkt) 19 / 32

The constants ON and OFF can be substituted with1 and 0. Working with names helps to illustrate the actual procedure. At the end, we wait a second to avoid overstretching relay 0. As mentioned above, waiting is a must! 4.Program transfer to Raspberry Pi With the WinSCP program, we transfer or copy the program (the Python file) to the Raspberry Pi. If you work directly on the RPi, you can skip this step and continue with step 5. After the start of the program, a new connection (site) must be created, we choose SCP as protocol, and we can also specify the Raspberry Pi user pi and the password. Clicking on Save will setup the new connection, then clicking on Login will connect to the Raspberry Pi. WinSCP Login Screen www.pixtend.de Copyright by Qube Solutions UG (haftungsbeschränkt) 20 / 32

If this is the first connection with WinSCP to the Raspberry Pi, a security question will appear, which must be confirmed. If the connection has been established, the Python file program1.py can be transferred / copied to the Raspberry Pi. This can be done in WinSCP simply by drag & drop, and with the small file size the transfer takes only a moment to complete. 5. Execute the program With the PuTTY program, we can establish a SSH connection to the Raspberry Pi and run commands via a text-based console, such as our Python program. Simply enter the name or the IP address for a connection to the RPi, set the Port to 22 and select SSH as the connection type. Click on Open to connect to the minicomputer. If this is the first connection made with the Raspberry Pi, a warning or note will appear, which must be confirmed. Then we get a prompt, where we first enter the user pi and then the corresponding password. Each input must be confirmed with the Enter key. If the login works, a few texts, notes, and the prompt from the Linux operating system on the Raspberry Pi will be displayed. We start our program with the following command: sudo python program1.py www.pixtend.de Copyright by Qube Solutions UG (haftungsbeschränkt) 21 / 32

After 1 second or so, the relay 0 starts to turn on and off. As programmed by us, this happens now every second. As long as we run the program or the Raspberry Pi is powered, the relay 0 will click every second. The Python program can be terminated with the key combination Ctrl + C. The error message which appears and states that the program has been interrupted, that's okay. We did not integrate / setup any error handling in our program, which deals with this special keyboard input. The examples for the PPL show how such an error handling can be accomplished. Congratulations! You have started your first Python program on PiXtend. The first Python program is done, now you can change it, expand it or re-start it completely as you like. Now you have access to the PiXtend board with Python and the PPL. We hope you have lots of fun and success with the programming! www.pixtend.de Copyright by Qube Solutions UG (haftungsbeschränkt) 22 / 32

5. Further information In this chapter, we would like to give you further information so you can use more PiXtend features in your Python programs. 5.1 Available PiXtend I/Os The current version of the PPL (as of April 2017) supports all digital and analog inputs and outputs of the PiXtend board. Since the analog outputs run via a DAC and this depends on the SPI bus on Chip Select 1, this must be taken into account in the Python program. There is another function called open_dac to start the communication with the chip. The 4 GPIOs on the PiXtend board can either be used directly or each can be used as a DHT11 / 22 sensor input. The two PWMs are also available. Information on the various modes of the PWMs, analog inputs and GPIOs can be found in the download area at https://www.pixtend.de/downloads/ after you have selected your PiXtend version. See also the app notes Control- and Status-Bytes and Process data of PiXtend. 5.2 Dealing with the auto(matic) mode Auto mode is the most efficient way to use the functions of PiXtend in Python. Here one can get new values every 100 ms, e.g. from the analog inputs, or one can turn the digital inputs and outputs on or off. This function must be called at the latest whenever the state of the PiXtend board is to be changed. A cyclic call is recommended, but not mandatory. However, if you do not want to use this part or if a slow response of the PiXtend board is sufficient, you can leave the auto mode aside and use all properties in the so-called manual mode. The required call to the auto_mode function can therefore be omitted. The manual mode, however, is very slow because a complete SPI data transfer takes place with every change of a property and the data must be processed by the micro-controller. www.pixtend.de Copyright by Qube Solutions UG (haftungsbeschränkt) 23 / 32

5.3 Start Python automatically After a reboot / power-up of the Raspberry Pi, a Python program does not start automatically. As already mentioned, a Python program can be started with the following command, please replace the myprogram.py with your own program name: sudo python myprogram.py We can also run this command automatically when the Linux system is booted. After all, we are Automators! The change is done quickly in the Linux console: sudo nano /etc/rc.local The file "rc.local" opens with some content. We insert two new lines before the line "exit 0" with the assumption that the program to be started is located in the home directory: cd /home/pi/ sudo python myprogram.py & The "&" is not a typo. This starts the Python program as a process in the background. Save and exit with Ctrl + X Reboot CAUTION: Please test the program well beforehand! If the program has an error, e.g. that the digital outputs are activated uncontrolled or very fast, this may damage the connected peripherals, and because the defective program is set up as an "Autostart program", a restart also does not help to solve the problem. www.pixtend.de Copyright by Qube Solutions UG (haftungsbeschränkt) 24 / 32

5.4 Using the serial interface The use of the serial interface is not included in the PPL package, for that you can use the pyserial module for example, because this is more a Raspberry Pi and Python topic and is not directly related to the PiXtend board. For the Raspbian version used in this app note, the serial interface runs via the Linux device /dev/ttys0. It is also important to note that the outputs of the Linux console are displayed there, so you have to edit the /boot/cmdline.txt file before you use it and remove the part console=serial0,115200 from the first line. A note: The PiXtend board runs the serial interface of the RPi to the outside and the RS232 interface is addressed by default. Since there is also a RS485 interface, a switch over must take place. This switching can be done with the PPL. The switch to RS485 can be done like this: # RS232 mode (default) p.serial_mode = p.rs232 # switch on RS485 mode p.serial_mode = p.rs485 5.5 Using the CAN bus The use of the CAN bus is not covered by the PPL, as this is part of the Raspberry Pi in conjunction with PiXtend and requires additional preparation steps. In our download area you will find an app note on starting the CAN bus on the Raspberry Pi, so that the MCP2515 CAN chip can be used on PiXtend. Although the app note was created for the CODESYS V3 runtime, the introductory steps up until to the end of Chapter 3 are generally valid, the part related to CODESYS V3 can be simply ignored. Direct link to app note (German only): https://www.pixtend.de/files/manuals/app-px-530_codesys_can_de.pdf www.pixtend.de Copyright by Qube Solutions UG (haftungsbeschränkt) 25 / 32

6. Frequently Asked Questions (FAQ) I cannot start my program, Python displays an error message about an invalid indentation? There is probably a problem with the indentation of the different code lines in the program. Look again thoroughly that each line has the correct indentation. We use e.g. always 4 blanks per indentation level, if only one blank is missing, or blanks and tabs have been mixed, Python displays an error message. In Notepad ++ e.g. you can have the "nonprintable" characters displayed, so you can see very fast where something is wrong, furthermore Python says itself in which line it has detected the error. Can I run my program without sudo? This seems to be possible with Python in conjunction with Raspbian as shown in this App- Note, but we still recommend using sudo, so Python can also perform system functions. Otherwise, problems can occur, whose cause may not be explained very easily. The stated 100 ms cycle time is too slow for me, can't PiXtend be accessed faster? Yes! This is possible. The 100 ms is a suggestion from us, so that all functions of PiXtend can be used. If you do not use DHT11 / 22 sensors on the GPIO0 - GPIO3, you can communicate with the PiXtend in a 25 ms cycle time, i.e. four times faster. But you cannot not go faster then this. We would like to invite you to the Qube Solutions forums for information exchange: https://www.pixtend.de/forum/ www.pixtend.de Copyright by Qube Solutions UG (haftungsbeschränkt) 26 / 32

7. Appendix A Following is a table showing all the public properties and functions of the PiXtend Python Library which an end user can use. name type data type access 6 values description auto_mode() function int - 0 = OK, -1 = Error close() function - - Activation of the auto mode and communication with the micro-controller on the PiXtend board, should be called cyclically, minimum is 100ms. Close the SPI driver and reset all internal variables and objects. Call up before the end of your own program. open() function - - open_dac() function - - pwm_ctrl_configure() function - - set_dac_output() function - - update_rtc() function - - analog_input0 property float R 0 V.. 5 V/10 V Open the SPI master 0 with Chip Select 0 to communicate with the micro-controller on the PiXtend board. May only be called once. Open the SPI master 0 with Chip Select 1 to communicate with the DAC. Configuration of the PWM channels, must be called up after every change of the PWM settings. Transfer of the configuration and analog values for DAC A and DAC B. Before calling, define dac_selection target DAC. Write Linux system time into the RTC on the PiXtend board. Analog input on the PiXtend, provides values always in the unit Volt. Value range depending on analog_input0_10volts_jumper. analog_input0_10volts_ jumper property int R / W 0 = OFF, 1 = ON Information whether the 5V / 10V jumper on the PiXtend board is physically plugged in. analog_input0_nos property int R / W 1, 5, 10, 50 analog_input0_raw property int R 16 bit value analog_input1 property float R 0 V.. 5 V/10 V Number of samples to be taken by the MC. The default value is 10. Raw value from the micro-controller without conversion. Analog input on the PiXtend board, always supplies values in the unit Volt. Value range depending on analog_input1_10volts_jumper. analog_input1_10volts_ jumper property int R / W 0 = OFF, 1 = ON Information whether the 5V / 10V jumper on the PiXtend board is physically plugged in. analog_input1_nos property int R / W 1, 5, 10, 50 analog_input1_raw property int R 16 bit value analog_input2 property float R 0 ma.. 20 ma Number of samples to be taken by the MC. The default value is 10. Raw value from micro-controller without conversion. Converted analog value from the microcontroller in 0 to 20 milliamps. 6 R = Reading, W = Writing, R / W = Reading and Writing www.pixtend.de Copyright by Qube Solutions UG (haftungsbeschränkt) 27 / 32

name type data type access values description analog_input2_nos property int R / W 1, 5, 10, 50 Number of samples to be taken by the MC. The default value is 10. analog_input2_raw property int R 16 bit value analog_input3 property float R 0 ma.. 20 ma analog_input3_nos property int R / W 1, 5, 10, 50 analog_input3_raw property int R 16 bit value Raw value from micro-controller without conversion. Converted analog value from micro-controller in 0 to 20 milliamps. Number of samples to be taken by the MC. The default value is 10. Raw value of micro-controller without conversion. analog_input_nos_freq property float R / W 0.125, 0.250, 0.500, 1.0, 2.0, 4.0, 8.0 MHz Sampling frequency of the analog inputs. dac_selection property int R / W 0 = DAC A, 1 = DAC B dht0 property int R / W 0 = OFF, 1 = ON dht1 property int R / W 0 = OFF, 1 = ON dht2 property int R / W 0 = OFF, 1 = ON dht3 property int R / W 0 = OFF, 1 = ON Selection of the DAC that is to be changed. DAC A = AO 0, DAC B = AO 1. Configuration of GPIO 0 as DHT11/22 input. If 1 (ON), all other GPIO settings are ignored. Configuration of GPIO 1 as DHT11/22 input. If 1 (ON), all other GPIO settings are ignored. Configuration of GPIO 2 as DHT11/22 input. If 1 (ON), all other GPIO settings are ignored. Configuration of GPIO 3 as DHT11/22 input. If 1 (ON), all other GPIO settings are ignored. di0 property int R 0 = OFF, 1 = ON State of the digital input in abbreviated form. di1 property int R 0 = OFF, 1 = ON State of the digital input in abbreviated form. di2 property int R 0 = OFF, 1 = ON State of the digital input in abbreviated form. di3 property int R 0 = OFF, 1 = ON State of the digital input in abbreviated form. di4 property int R 0 = OFF, 1 = ON State of the digital input in abbreviated form. di5 property int R 0 = OFF, 1 = ON State of the digital input in abbreviated form. di6 property int R 0 = OFF, 1 = ON State of the digital input in abbreviated form. di7 property int R 0 = OFF, 1 = ON State of the digital input in abbreviated form. digital_input0 property int R 0 = OFF, 1 = ON State of the digital input. digital_input1 property int R 0 = OFF, 1 = ON State of the digital input. digital_input2 property int R 0 = OFF, 1 = ON State of the digital input. digital_input3 property int R 0 = OFF, 1 = ON State of the digital input. digital_input4 property int R 0 = OFF, 1 = ON State of the digital input. digital_input5 property int R 0 = OFF, 1 = ON State of the digital input. digital_input6 property int R 0 = OFF, 1 = ON State of the digital input. www.pixtend.de Copyright by Qube Solutions UG (haftungsbeschränkt) 28 / 32

name type data type access values description digital_input7 property int R 0 = OFF, 1 = ON State of the digital input. digital_output0 property int R / W 0 = OFF, 1 = ON digital_output1 property int R / W 0 = OFF, 1 = ON digital_output2 property int R / W 0 = OFF, 1 = ON digital_output3 property int R / W 0 = OFF, 1 = ON digital_output4 property int R / W 0 = OFF, 1 = ON digital_output5 property int R / W 0 = OFF, 1 = ON do0 property int R / W 0 = OFF, 1 = ON do1 property int R / W 0 = OFF, 1 = ON do2 property int R / W 0 = OFF, 1 = ON do3 property int R / W 0 = OFF, 1 = ON do4 property int R / W 0 = OFF, 1 = ON do5 property int R / W 0 = OFF, 1 = ON gpio0 property int R / W 0 = OFF, 1 = ON gpio0_direction property int R / W 0 = input, 1 = output gpio1 property int R / W 0 = OFF, 1 = ON gpio1_direction property int R / W 0 = input, 1 = output State of the digital output. Reading and writing are always possible. State of the digital output. Reading and writing are always possible. State of the digital output. Reading and writing are always possible. State of the digital output. Reading and writing are always possible. State of the digital output. Reading and writing are always possible. State of the digital output. Reading and writing are always possible. State of the digital output. Reading and writing are always possible. This is an abbreviated form of the corresponding digital output and not a further output. State of the digital output. Reading and writing are always possible. This is an abbreviated form of the corresponding digital output and not a further output. State of the digital output. Reading and writing are always possible. This is an abbreviated form of the corresponding digital output and not a further output.. State of the digital output. Reading and writing are always possible. This is an abbreviated form of the corresponding digital output and not a further output. State of the digital output. Reading and writing are always possible. This is an abbreviated form of the corresponding digital output and not a further output. State of the digital output. Reading and writing are always possible. This is an abbreviated form of the corresponding digital output and not a further output. State of the GPIO, Attention! The "setting" of this property is only possible if the GPIO is configured as "output", otherwise there will be an IOError. Configuration of the GPIO either as input (default) or as output. State of the GPIO, Attention! The "setting" of this property is only possible if the GPIO is configured as "output", otherwise there will be an IOError. Configuration of the GPIO either as input (default) or as output. www.pixtend.de Copyright by Qube Solutions UG (haftungsbeschränkt) 29 / 32

name type data type access values description gpio2 property int R / W 0 = OFF, 1 = ON State of the GPIO, Attention! The "setting" of this property is only possible if the GPIO is configured as "output", otherwise there will be an IOError. gpio2_direction property int R / W 0 = input, 1 = output gpio3 property int R / W 0 = OFF, 1 = ON gpio3_direction property int R / W 0 = input, 1 = output h0_dht11 property float R rel. humidity in % h0_dht22 property float R rel. humidity in % h1_dht11 property float R rel. humidity in % h1_dht22 property float R rel. humidity in % h2_dht11 property float R rel. humidity in % h2_dht22 property float R rel. humidity in % h3_dht11 property float R rel. humidity in % h3_dht22 property float R rel. humidity in % Configuration of the GPIO either as input (default) or as output. State of the GPIO, Attention! The "setting" of this property is only possible if the GPIO is configured as "output", otherwise there will be an IOError. Configuration of the GPIO either as input (default) or as output. Converted value from the sensor according to the specifications of the data sheet of the sensor. Converted value from the sensor according to the specifications of the data sheet of the sensor. Converted value from the sensor according to the specifications of the data sheet of the sensor. Converted value from the sensor according to the specifications of the data sheet of the sensor. Converted value from the sensor according to the specifications of the data sheet of the sensor. Converted value from the sensor according to the specifications of the data sheet of the sensor. Converted value from the sensor according to the specifications of the data sheet of the sensor. Converted value from the sensor according to the specifications of the data sheet of the sensor. hum_input0_raw property int R hum_input1_raw property int R hum_input2_raw property int R hum_input3_raw property int R 16-bit integer value from the sensor 16-bit integer value from the sensor 16-bit integer value from the sensor 16-bit integer value from the sensor This property supplies only the raw value of the sensor without conversion. This property supplies only the raw value of the sensor without conversion. This property supplies only the raw value of the sensor without conversion. This property supplies only the raw value of the sensor without conversion. pwm0 property int R / W 0.. 65000 PWM 0 duty cycle. pwm1 property int R / W 0.. 65000 PWM 1 duty cycle. pwm_ctrl_cs0 property int R / W 0 = OFF, 1 = ON PWM clock select bit 0. www.pixtend.de Copyright by Qube Solutions UG (haftungsbeschränkt) 30 / 32

name type data type access values description pwm_ctrl_cs1 property int R / W 0 = OFF, 1 = ON PWM clock select bit 1. pwm_ctrl_cs2 property int R / W 0 = OFF, 1 = ON PWM clock select bit 2. pwm_ctrl_mode property int R / W 0 = Servo Mode, 1 = PWM Mode Operating mode of the PWM outputs. pwm_ctrl_od0 property int R / W 0 = OFF, 1 = ON Overdrive setting for PWM 0. pwm_ctrl_od1 property int R / W 0 = OFF, 1 = ON Overdrive setting for PWM 1. pwm_ctrl_period property int R / W 0.. 65000 Frequency of PWM's. relay0 property int R / W 0 = OFF, 1 = ON State of relay 0. relay1 property int R / W 0 = OFF, 1 = ON State of relay 1. relay2 property int R / W 0 = OFF, 1 = ON State of relay 2. relay3 property int R / W 0 = OFF, 1 = ON State of relay 3. serial_mode property bool R / W False = RS232, True = RS485 Define the mode of the serial interface on the PiXtend board. servo0 property int R / W 0.. 250 servo1 property int R / W 0.. 250 Unit for setting the motor position of the model-building servomotor. Unit for setting the motor position of the model-building servomotor. t0_dht11 property float R temperature in degrees Celsius, e.g. 9.0 Values from a DHT11 sensor connected to GPIO0. t0_dht22 property float R temperature in degrees Celsius, e.g. 9.5 Values from a DHT22 sensor connected to GPIO0. t1_dht11 property float R temperature in degrees Celsius, e.g. 9.0 Values from a DHT11 sensor connected to GPIO1. t1_dht22 property float R temperature in degrees Celsius, e.g. 9.5 Values from a DHT22 sensor connected to GPIO1. t2_dht11 property float R temperature in degrees Celsius, e.g. 9.0 Values from a DHT11 sensor connected to GPIO2. t2_dht22 property float R temperature in degrees Celsius, e.g. 9.5 Values from a DHT22 sensor connected to GPIO2. t3_dht11 property float R temperature in degrees Celsius, e.g. 9.0 Values from a DHT11 sensor connected to GPIO3. t3_dht22 property float R temperature in degrees Celsius, e.g. 9.5 Values from a DHT22 sensor connected to GPIO3. www.pixtend.de Copyright by Qube Solutions UG (haftungsbeschränkt) 31 / 32

name type data type access values description temp_input0_raw property int R 16-bit integer value from the sensor Direct raw value from the sensor without conversion. temp_input1_raw property int R temp_input2_raw property int R temp_input3_raw property int R 16-bit integer value from the sensor 16-bit integer value from the sensor 16-bit integer value from the sensor Direct raw value from the sensor without conversion. Direct raw value from the sensor without conversion. Direct raw value from the sensor without conversion. uc_board_version property int R 12 = 1.2.x, 13 = 1.3.x Hardware version of the PiXtend board, e.g. Ver. 1.2.x which can not read back the digital outputs and relays states. uc_control property int R uc_fw_version property int R 0 = Man. Mode, 16 = Auto Mode 1, 2, 3, 4, 5 equates firmware version Setting the operating mode of the microcontroller on the PiXtend board. Firmware version of the micro-controller on the PiXtend board. uc_status property int R 0 = Init, 1 = Run State of the micro-controller. use_fahrenheit property bool R / W False = C, True = F The temperatures from T0 to T3 are given in C by default, if this value is "True", you get F. www.pixtend.de Copyright by Qube Solutions UG (haftungsbeschränkt) 32 / 32