#### get_text_from_error_id
##### Definition
```python
def get_text_from_error_id(self, error_id):
```
##### Description
The "*get_text_from_error_id*" method is used to get the error message from the "*error_id*".
##### Arguments
The "*self*" argument is pointing to the object, which calls the method.
The "*error_id*" argument is an integer value send from the Xtender-system.
##### Return Value
Type -> string
##### Example Code
```python
>>> # create an object of the Xcom-API-Class
>>> Object = Xcom_API()
>>>
>>> # create a variable with an Error_ID
>>> Error_ID = 0x0022
>>>
>>> # call the Method 'get_text_from_error_id'
>>> Answer = Object.get_text_from_error_id(Error_ID)
>>>
>>> # print Answer
>>> print(Answer)
'OBJECT_ID_NOT_FOUND'
```
##
💻 Hardware Setup
This section explains the hardware configuration, which is necessary to use the test-programs. The test-programs were designed especially for using a Raspberry Pi with the RaspiComm module. Of course the Xcom-API-Class itself can be used in own programs with other distributions and plattforms, which can run python code. The chart below shows the connection of the hardware.
![](https://gogs.es-lab.de/attachments/f121d125-dff9-4564-ae72-e85f82777cd9)
The Raspberry Pi is used to execute the test-program and with the help of the RaspiComm module is a RS232 connection to the Xcom-232i ensue. The Xcom-232i is a bridge betwenn the RS232 serial-Bus and the CAN-BUS, which handles the communication between the Xtender-System.
In the following sections you will get hardware-information and setup descriptions for the Raspberry Pi and the Xcom-232i.
### Hardware Information
The following table shows the needed hardware components and their usage and give you links to the product information and documentation. These components are necessary if you want to use the Xcom-Test-Program and Xcom-Test-Loop-Program.
| Component | Function | Product Information | Documentation |
|:----|:----|:----:|:----:|
| Raspberry Pi 3 | single board computer, on which is running the program | [
🔗
](https://www.raspberrypi.org/products/raspberry-pi-3-model-b/) | [
🔗
](https://www.raspberrypi.org/documentation/) |
| RasPiComm | expansion board for the Raspberry Pi, which provides a RS232-Port over the GPIOs (UART) of the Raspberry Pi | Product is EOL | Product is EOL |
| Xcom-232i | CAN to RS232 Bridge, which is used to communicate with the Xtender-Modules | [
🔗
](https://www.studer-innotec.com/en/accessoires/xtender-series/communication-module-xcom-232i-770) | [
🔗
](https://www.studer-innotec.com/media/document/0/studer-manuel-xcom-232i-v1.3.0_en.pdf) [
🔗
](https://www.studer-innotec.com/media/document/0/technical-specification-xtender-serial-protocol-v1.6.24.zip) |
| RCC-02 | remote control and programming unit for displaying the status informations and to program parameters of the Xtender-Modules | [
🔗
](https://www.studer-innotec.com/en/accessoires/xtender-series/rcc-02-remote-control-and-programming-centre-767) | [
🔗
](https://www.studer-innotec.com/media/document/0/manuel-rcc-v4.6.0_en.pdf) |
| Xtender-Series| is used as Battery charger and as DC to AC converter and to supply electrical power | [
🔗
](https://www.studer-innotec.com/en/products/xtender-series/) | [
🔗
](https://www.studer-innotec.com/media/document/0/manuel-xtender-v4.7.0_en-1.pdf)
### Xcom-232i-Setup
The Xcom-232i is a bridge for the RS232-BUS to the CAN-BUS. The test-programms for the Xcom-API-Class will ask you for the baudrate. So it is essential, that you know the baudrate of the Xcom-232i, otherwise the communication between the Raspberry Pi and the Xcom-232i will fails. The standard baudrate for the RS232-BUS is 38400, but you are able to change this value to 115200. To do that you need the Xcom-Configurator, which is only available for a windows operating system.
> **Download-Link Xcom-Configurator:** [https://www.studer-innotec.com/media/document/0/xcomconfiguratorsetup_1.0.26.0.zip](https://www.studer-innotec.com/media/document/0/xcomconfiguratorsetup_1.0.26.0.zip)
The picture below shows the Xcom-Configurator program.
![](https://gogs.es-lab.de/attachments/e9025954-b549-4ea3-817c-f1aeacf68b5e)
After downloading and installing the Xcom-Configurator, you are able to change the baudrate:
* Remove the Micro-SD-card from the Xcom-232i and insert it into your PC.
* Start the Xcom-Configurator.
* Choose the SD-Card-Drive, where the SD-Card of Xcom-232i is located.
* Choose a Xcom-Mode, which is either "*232i (38400 bps)*" or "*232i (115200 bps)*".
* Finally click on the "*Generate*" button and a new configuration-file will be
stored on the SD-Card.
* Remove the SD-Card from the PC and insert it into the Xcom-232i.
* The LED of the Xcom-232i should be now blinking red. This indicates, that the Xcom-232i is updating. The update is finish, when the LED is blinking green. The baudrate of the Xcom-232i is now set.
>**Note:** More Informations about the LED-state can you find in the documentation of the Xcom-232i under the section: [Hardware Information](#hardware-information).
### Raspberry Pi Setup
This section describes how to setup your Raspberry Pi, so that you are able to execute the test-programs. There are two ways possible: either you use the given Raspberry Pi image-file, which is ready to use, or you configure your own Raspberry Pi distribution/image.
#### Copy Image to a SD-Card
This section describes how to copy the given Raspberry PI image-file to a SD-card. There is a [Linux](#linux) and a [Windows](#windows) instruction available.
> **Download-Link Raspberry Pi Image-File:** [https://gogs.es-lab.de/mueller_to/Xcom-API/src/master/Raspberry-Pi-Image](https://gogs.es-lab.de/mueller_to/Xcom-API/src/master/Raspberry-Pi-Image)
##### Linux Instruction
After downloading you need to unzip the image-file first, which can be done for example with the bash-command:
```bash
unzip Raspberry_Pi_Image.zip -d
```
If "*unzip*" is not installed, you can install it with the bash-command:
```bash
sudo apt-get install unzip
```
Copying the image-file to a SD-Card will be done with the ```dd``` command.
> **Note:** Use of the ```dd``` tool can overwrite any partition of your machine. If you specify the wrong device in the instructions below, you could delete your primary Linux partition. Please be careful.
* Insert a SD-Card into your computer with at least 8 GB storage capacity.
* Run the bash-command:
```
bash df -h
```
* The left column of the results from ```df -h``` command gives the device name of your SD card. It will be listed as something like ```/dev/mmcblk0p1``` or ```/dev/sdX1```, where "*X*" is a lower case letter indicating the device. The last part (p1 or 1 respectively) is the partition number. You want to write to the whole SD card, not just one partition. You therefore need to remove that section from the name. You should see something like ```/dev/mmcblk0``` or ```/dev/sdX``` as the device name for the whole SD card. Note that the SD card can show up more than once in the output of ```df```. It will do this if you have previously written a Raspberry Pi image to this SD card, because the Raspberry Pi SD images have more than one partition.
* Now you have noted the device name, you need to unmount it so that files can't be read or written to the SD card while you are copying over the SD image. So run the bash-command ```umount /dev/sdX1```, replacing ```sdX1``` with whatever your SD card's device name is, including the partition number. If your SD card shows up more than once in the output of ```df```, this shows that the card has multiple partitions. You should unmount all of these partitions.
* Now in a terminal window, write the image to the card with the command below, making sure you replace the input file ```if=``` argument with the path to your ```img``` file, and the ```/dev/sdX``` in the output file ```of=``` argument with the correct device name. This is very important, as you will lose all the data on the hard drive if you provide the wrong device name. Make sure the device name is the name of the whole SD card as described above, not just a partition. For example: ```sdd```, not ```sdds1``` or ```sddp1```, and ```mmcblk0```, not ```mmcblk0p1```.
```bash
dd bs=4M if=Raspberry_Pi_Image.img of=/dev/mmcblk0 conv=fsync
```
> **Note:** The block size set to ```4M``` will work most of the time. If not, try ```1M```, although this will take considerably longer. Also note that if you are not logged in as root you will need to prefix this with ```sudo```.
* After copying the image-file to the SD-Card, you can insert the SD-Card to your Raspberry Pi and boot it up [**[1](#references)**].
Login-informations:
Username: pi
Password: iotraspi
The test-programs can you find under `/home/pi/pythonapps`.
> **Note:** DHCP for the ethernet port of the Raspberry Pi has been disabled. The static ip-address is: 192.168.137.2. You can change this by opening the file `/etc/dhcpcd.conf` with an editor like "*nano*" and with admin privilege.
##### Windows Instruction
After downloading the image-file, you can unzip the archive with windows itself or with a third party tool like "*7-ZIP*".
> **Download-Link 7-ZIP:** [http://www.7-zip.de/](http://www.7-zip.de/)
Now you need a tool called "*Win32DiskImager*" to copy the image-file to a SD-Card.
> **Download-Link Win32DiskImager:** [https://sourceforge.net/projects/win32diskimager/](https://sourceforge.net/projects/win32diskimager/)
The picture below shows the "*Win32DiskImager*".
* Insert a SD-Card into your computer with at least 8 GB storage capacity.
* In "*Win32DiskImager*" choose the image-file and the drive of your SD-Card.
* Click on the button write (at the picture the german word "*schreiben*") to copy the image-file to the SD-Card.
* After copying the image-file to the SD-Card, you can insert the SD-Card to your Raspberry Pi and boot it up
Login-informations:
Username: pi
Password: iotraspi
The test-programs can you find under `/home/pi/pythonapps`.
> **Note:** DHCP for the ethernet port of the Raspberry Pi has been disabled. The static ip-address is: 192.168.137.2. You can change this by opening the file `/etc/dhcpcd.conf` with an editor like "*nano*" and with admin privilege.
#### Create your own Image
Sometimes it is necessary, that you create your own image-file. For Example: If you want to use a newer or another Raspberry Pi Linux-Version as the given Raspberry Pi image-file. To do so, you need to do some configurations at the fresh installation of the Raspberry Pi operating system. The first step is to download your favorite Linux operating system for the Raspberry Pi and to install the image file to a SD-Card. This is the same procedure, which was explained in section: [Copy Image to a SD-Card](#copy-image-to-a-sd-card).
> **Note:** Other Linux operating systems especially for the Raspberry Pi can you find under: https://www.raspberrypi.org/downloads/
To setup your own raspberry pi image-file is classified into the following steps:
* [Raspberry Pi Config](#raspberry-pi-config)
* [Activate UART](#activate-uart) (Raspberry Pi 3 only)
* [Install Python-Packages](#install-python-packages)
* [Activate PiGPIO-Daemon](#activate-pigpio-daemon)
After completing the setup of your Raspberry Pi Image you can download the API and the test-programs from the repository and test it.
##### Raspberry Pi Config
After booting up your Raspberry Pi you need to activate the serial port. If you want to communicate with the Pi over ethernet, you also need to activate SSH. To do so, run the bash-command:
```bash
sudo raspi-config
```
The picture below shows the ```raspi-config```.
![](https://gogs.es-lab.de/attachments/4e8f88cf-e5df-4ab7-8759-2a4ffe8ab2c5)
Under the category "*Interfacing-Options*" you can activate SSH and the serial-port. If you want, you can also do changes at the localization, hostname, etc. or you can activate other interfaces you need [**[2](#references)**].
##### Activate UART
> **Note:** This step is only necessary, if you use a Raspberry Pi 3.
The biggest change of Raspberry Pi 3 was the integrated WLAN and Bluetooth. But the Bluetooth module uses the serial (UART) interface of the Pi. So after activating the serial interface with ```raspi-config```, there only a Mini-UART available over the GPIO pins. The Mini-UART has a big disatvantage: the baudrate of the Mini-UART depends of the Clock-Speed of the CPU, so a stable serial connection is not possible. You can change that by disabling the Bluetooth module and reconfigure the UART to the GPIO pins.
Open the "*config.txt*" at the boot directory with admin privilege.
```bash
sudo nano /boot/config.txt
```
Add a new line with ```dtoverlay=pi3-disable-bt``` and if it is not set by ```raspi-config```, add a line with ```enable_uart=1``` [**[3](#references)**]. Now open the file:
```bash
sudo nano /boot/cmdline.txt
```
Delete the part with ```console=serial0,115200``` [**[4](#references)**]. Now you need to stop BT modem trying to use UART:
```bash
sudo systemctl disable hciuart
```
After a reboot, the UART should work like at the previous Raspberry Pi version. The UART is available under "*/dev/ttyAMA0*".
##### Install Python-Packages
The test-programs needs the following python-modules:
* ptvsd
* serial (pyserial)
* pigpio
You can check, whether these modules are available with the bash-command:
```bash
pip3 list
```
If one of these modules are missing, you can install it with the bash-command:
```bash
pip3 install
```
##### Activate PiGPIO-Daemon
The test-programs uses PiGPIO to access the GPIO pins. The PiGPIO module needs a daemon-process, which handles the communication between GPIOs and the module [**[5](#references)**]. You can start the daemon-process with:
```bash
sudo pigpiod
```
If you want to start the daemon-process with every bootup of the Raspberry pi, you need to open the ```rc.local```:
```bash
sudo nano /etc/rc.local
```
There you add a line with ```pigpiod``` before ```exit 0```. The file should be look like:
```bash
#!/bin/sh -e
#
# rc.local
#
# This script is executed at the end of each multiuser runlevel.
# Make sure that the script will "exit 0" on success or any other
# value on error.
#
# In order to enable or disable this script just change the execution
# bits.
#
# By default this script does nothing.
# Print the IP address
_IP=$(hostname -I) || true
if [ "$_IP" ]; then
printf "My IP address is %s\n" "$_IP"
fi
pigpiod
exit 0
```
##
⁉ Test-Program
The test-programs demonstrate the functionality of the Xcom_API-class. To use these programs a Raspberry Pi with a Raspicomm extender module and a RS232-bridge called Xcom-232i is required. Make sure you have setup your Raspberry Pi correctly, just like explained in section [Hardware Setup](#hardware-setup) or you use the available Image-File of the Raspberry Pi, where everything is ready configured.
There are two test-programs available:
* [Xcom-Test-Loop-Program](#xcom-test-loop-program)
* [Xcom-Test-Program](#xcom-test-program)
In the following sections, there will be described these programs and explained how to run these programs.
### Run Test-Program
To run the test-programs make sure, that the Xcom_API.py is inside the python search-path. More Informations about that can you find in section: [Create and Delete an Object](#create-and-delete-an-object). The test-programs needs the following python-modules:
* ptvsd
* serial (pyserial)
* pigpio
You can check, whether these modules are available with the bash-command:
```bash
pip3 list
```
If one of these modules are missing, you can install it with the bash-command:
```bash
pip3 install
```
You can start the test-program with the bash-command:
```bash
python3 .py
```
The "*\*" should be either "*Xcom_Test_Loop_Program*" or "*Xcom_Test_Program*". After starting one of these test-programs, it will start the program-setup and will ask you for some initialize parameters. These are:
* COM-Port (Normally: /dev/ttyAMA0)
* Baudrate (depends on your Xcom-232i setup)
* Destination-Address (Xtender-Module)
* Soure-Address (Normally your-Raspberry Pi: 1)
* CRC-Check (True/1 or False/0)
You can skip the program-setup by starting the test-program with the mentioned parameters. The sequence of the parameters must not be changed. For example:
```bash
python3 .py /dev/ttyAMA0 115200 101 1 True
```
If everything is ok, you are now inside the main menu of the test-program and you can follow the instructions, which are displayed.
### Xcom-Test-Loop-Program
The Xcom-Test-Loop-Program sends cyclical a request to a Xtender-System and display whose answer. After starting the Xcom-Test-Loop-Program and after finishing the program-setup, you need to enter an Object-ID, which is used to encode the request-frame with the method "*get_read_frame*". The Object_IDs are mentioned under section: [Class-Attributes](#class-attributes). Then the test-program sends the request and receive the answer over the serial connection. The answer will be decode with the method "*get_data_from_frame*" and displayed. The loop of the test-program run as fast as possible and is limited by the transfer speed of the serial connection and of the CAN-BUS load.
### Xcom-Test-Program
This program demonstrate the functionality of the Xcom_API-class. After starting the Xcom-Test-Program and after finishing the program-setup, you can either enter an Information-Method to test their functionallity or you enter a function, which demonstrate the functionallity of the Public-Class-Methods. The Xcom-Test-Program is user-friendly designed, so you only need to follow the displayed instructions.
>**Note:** If you want to use the function, which uses the extended Public-Class-Methods, you will need background informations of the byte-frame structure, which are well explained in the technical documentation of the Xcom-232i. Otherwise the Xtender-System or the program will not understand you and will display an error. The link to the documentation of the Xcom-232i can you find under the section: [Hardware Information](#hardware-information).
##
📚 References
**[1]** Raspberry Pi
*Installing operating system images on Linux*
[https://www.raspberrypi.org/documentation/installation/installing-images/linux.md](https://www.raspberrypi.org/documentation/installation/installing-images/linux.md)
(20/08/2017)
**[2]** Raspberry Pi
*Raspi-Config*
[https://www.raspberrypi.org/documentation/configuration/raspi-config.md](https://www.raspberrypi.org/documentation/configuration/raspi-config.md) (20/08/2017)
**[3]** Hudson, G.
*Raspberry Pi 3 compatibility (BT disable & serial port remap fix)*
[https://openenergymonitor.org/forum-archive/node/12311.html](https://openenergymonitor.org/forum-archive/node/12311.html) (20/08/2017)
**[4]** Raspberry Tips
*UART auf dem RaspberryPi nutzen*
[https://raspberry.tips/raspberrypi-einsteiger/uart-auf-dem-raspberrypi-nutzen/](https://raspberry.tips/raspberrypi-einsteiger/uart-auf-dem-raspberrypi-nutzen/) (20/08/2017)
**[5]** PiGPIO
*PiGPIO Daemon*
[http://abyz.co.uk/rpi/pigpio/pigpiod.html](http://abyz.co.uk/rpi/pigpio/pigpiod.html) (20/08/2017)
---
**Hochschule Anhalt | Anhalt University of Applied Sciences | Department 6 EMW
Xcom-API**
Tobias Müller, M. Eng.
📧 Tobias.Mueller@HS-Anhalt.de
© es-lab.de, 10.07.2018