[![](http://es-lab.de:60085/attachments/904235a3-41ce-413c-9683-68346310886e)](https://www.hs-anhalt.de/startseite.html) #
🗃 Xcom-API
[![]( https://img.shields.io/badge/version-v1.0-red.svg?style=plastic )](http://es-lab.de:60085/mueller_to/Xcom-API) [![]( https://img.shields.io/badge/python-3.4,_3.5,_3.6-green.svg?style=plastic )](https://www.python.org/) [![]( https://img.shields.io/badge/license-GNU%20GPL%20v3-blue.svg?style=plastic )](http://es-lab.de:60085/mueller_to/Xcom-API/src/master/LICENSE) [![]( https://img.shields.io/badge/documentation-wiki-yellow.svg?style=plastic)](http://es-lab.de:60085/mueller_to/Xcom-API/wiki) [![]( https://img.shields.io/badge/download-zip-orange.svg?style=plastic)](http://es-lab.de:60085/mueller_to/Xcom-API/archive/master.zip)📜 Table of Contents
* [Introduction](#introduction) * [Xcom-API-Class](#xcom-api-class) * [Create and Delete an Object](#create-and-delete-an-object) * [Class-Attributes](#class-attributes) * [Information-Methods](#information-methods) * [get_source_address](#get_source_address) * [get_destination_address](#get_destination_address) * [is_crc_check_active](#is_crc_check_active) * [get_object_counter](#get_object_counter) * [get_prog_name](#get_prog_name) * [get_prog_version](#get_prog_version) * [Public-Class-Methods](#public-class-methods) * [get_read_frame](#get_read_frame) * [get_read_frame_ext](#get_read_frame_ext) * [get_write_frame](#get_write_frame) * [get_write_frame_ext](#get_write_frame_ext) * [get_data_from_frame](#get_data_from_frame) * [get_data_from_frame_ext](#get_data_from_frame_ext) * [get_bin_from_frame_flags](#get_bin_from_frame_flags) * [get_text_from_frame_flags](#get_text_from_frame_flags) * [get_text_from_error_id](#get_text_from_error_id) * [Hardware Setup](#hardware-setup) * [Hardware Information](#hardware-information) * [Xcom-232i-Setup](#xcom-232i-setup) * [Raspberry Pi Setup](#raspberry-pi-setup) * [Copy Image to a SD-Card](#copy-image-to-a-sd-card) * [Create your own Image](#create-your-own-image) * [Test-Program](#test-program) * [Run Test-Program](#run-test-program) * [Xcom-Test-Loop-Program](#xcom-test-loop-program) * [Xcom-Test-Program](#xcom-test-program) * [References](#references) ---ℹ Introduction
Welcome to the Wiki of the Xcom-API. This project is about an API (**A**pplication **P**rogramming **I**nterface) designed as a python-class, which is used to encode and decode byte-frames for communication between a Xtender-System and a PC, especially a Raspberry Pi with a Raspicomm extension module. The class also contains methods for error and frame-flag decoding and methods to get object or class informations. >**Note:** The API and the Test-Program was created with Microsoft's integrated development environment (IDE) Visual Studio Code (VSC). This is an Open-Source IDE from Microsoft for many different programming-languages for Windows, Linux and Mac with an easy to use git integration. So you can easily add this project to VSC by cloning this Git-Repository. Of course you can open the python-files with other IDE's you prefer too. > >####☁ Git-Repository-Link: http://es-lab.de:60085/mueller_to/Xcom-API
On the following pages you will find many informations about the usage of the API such like: An explanation of the methods of the API and how to invoke these methods inside a python-script. Furthermore there are test-programs called "Xcom-Test-Program" and "Xcom-Test-Loop-Program", which you can use for testing the Xcom-API and where you get some impressions of how to use the Xcom-API. There are also explanation for how to use these test-programs. This concerns the hardware and software setup of the Raspberry Pi, if you won't use the given Raspberry Pi image.🗃 Xcom-API-Class
This class is used to encode byte-frames, which are needed to communicate with Xtender-Modules over the RS232-BUS with the help of the Xcom-232i. After encoding the byte-frame, you can use the module "pyserial" to communicate with the Serial-BUS and to put the byte-frame into the write-method of "pyserial". You can also decode read-frames of the Serial-BUS with this class. The class contains methods to generate read- or write-frames, and methods to decode frames. There are pre-defined types, properties and formats for the most important parameter- and information-numbers. This reduces the effort for generating byte-frames, but there are extended methods to encode byte-frames with other parameter- and information-numbers too, that you can find in the documentation of the Xcom-232i. The class also contains methods for error and frame-flag decoding and methods to get object or class informations >**Note:** The link to the documentation of the Xcom-232i can you find under the section: [Hardware Information](#hardware-information). On the following sections, there will be describe the [Information-Methods](#information-methods), [Public-Class-Methods](#public-class-methods), [Class-Attributes](#class-attributes) and how to [create and delete an object](#create-and-delete-an-object). ### Create and Delete an Object ##### Import Xcom-API-Class: To use the Xcom-API, either you need to import the class into your python-script, or you write your code directly inside the "*Xcom_API.py*" file. If you want to import the "*Xcom_API.py*" into your own python script, make sure, that the "*Xcom_API.py*" file is located inside the python-module search path. This is either the folder/directory where your script is located or under Microsoft Windows the path: ```text💻 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://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 | [🔗
](http://www.studer-innotec.com/en/accessoires/xtender-series/communication-module-xcom-232i-770) | [🔗
](http://www.studer-innotec.com/media/document/0/studer-manuel-xcom-232i-v1.3.0_en.pdf) [🔗
](http://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 | [🔗
](http://www.studer-innotec.com/en/accessoires/xtender-series/rcc-02-remote-control-and-programming-centre-767) | [🔗
](http://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 | [🔗
](http://www.studer-innotec.com/en/products/xtender-series/) | [🔗
](http://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:** [http://www.studer-innotec.com/media/document/0/xcomconfiguratorsetup_1.0.26.0.zip](http://www.studer-innotec.com/media/document/0/xcomconfiguratorsetup_1.0.26.0.zip) The picture below shows the Xcom-Configurator program. ![](http://es-lab.de:60085/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:** [http://es-lab.de:60085/mueller_to/Xcom-API/src/master/Raspberry-Pi-Image](http://es-lab.de:60085/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 -dLogin-informations:
Username: pi
Password: iotraspi
Login-informations:
Username: pi
Password: iotraspi
⁉ 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📚 References
**[1]** Raspberry PiTobias Müller, M. Eng.
📧 Tobias.Mueller@HS-Anhalt.de
© es-lab.de, 10.07.2018