TECNOLOGÍAS, SERVICIOS TELEMÁTICOS Y SISTEMAS, S.A. Calle Albert Einstein, 12, 1º [PCTCAN] Santander (Cantabria) Spain C.I.

Transcription

1 TSmarT User Manual April 2 nd, 2014

2 Document Information Document ID: TSmarT User Manual Version Date: Total Number of Pages: 76 April 2 nd, 2014 Authors Name Department Sergio Martin Embedded SW info@tst-sistemas.es Bruno Cendón Technical Director info@tst-sistemas.es Aránzazu Sanz Marketing & Sales info@tst-sistemas.es Miguel Camus Hardware Engineer info@tst-sistemas.es Document History Revision Date Modification 1.0 October 1 st, 2012 Initial version 1.1 December 12 th, 2012 Change in document structure New chapter January 9 th, 2013 Minor errata corrections 1.3 April 8 th, 2013 Added Serial Board 1.5 May 17 th, 2013 Added Cellular 2G May-28 th,-2013 Minor errata corrections July-5 th,-2013 New Cellular GPRS module January 15 th, 2014 New WiFi Module 2.0 April 2 nd, 2014 New TSgaTe version May 5 h, 2014 Fixed Bug in TSgaTe pinout May 19 th, 2014 Fixed Bug in TSgaTe technical table

3 Table of Contents TECNOLOGÍAS, SERVICIOS TELEMÁTICOS Y SISTEMAS, S.A. 1 Introduction System overview Hardware architecture Software architecture Real-Time Operating System FreeRTOS Integrated Development Environment Getting Started TSkiT development kit Scope of supply Debug Board Hardware connections Install software toolchain Run a sample program Hardware TSgaTe Pinout Technical characteristics TSmoTe Pinout Technical characteristics Add-on boards GPRS modem NFC/RFID reader/writer GPS module Industrial Sensors Adapter Serial Board Wi-fi Module ZigBee radio Digimesh / IEEE radio Wi-Fi radio RF below 1 GHz Software Application structure FreeRTOS State machines Tasks... 56

4 5.2.3 Queues Semaphores and mutex API Coding rules Return codes Initialization and configuration functions Other functions Toolchain Eclipse Codesourcery Compiler OpenOCD GDB Debugger Application Example Folder structure Preparing the application Initialize and configure your application Writing the application code... 71

5 Table of Figures TECNOLOGÍAS, SERVICIOS TELEMÁTICOS Y SISTEMAS, S.A. Figure 2 1. TSmarT hardware components... 3 Figure 2 2. TSmarT software architecture... 4 Figure 2 3. Function to send SMS messages... 5 Figure 2 4. Code structure... 6 Figure 2 5. FreeRTOS mechanisms... 7 Figure 2 6. FreeRTOS multitasking support... 7 Figure 2 7. FreeRTOS heap structure... 8 Figure 2 8. TSmarT toolchain... 8 Figure 3 1. TSkiT development kit Figure 3 2. Debug Board Figure 3 3. Debug Board Pinout Figure 3 4. Debug Board Jumpers Figure 3 5. TSmarT mother boards TSgaTe (left) & TSmoTe (right) Figure 4 1. TSgaTe Figure 4 2. TSgaTe building blocks Figure 4 3. TSgaTe J2 connector Figure 4 4. TSgaTe M1 connector Figure 4 5. TSgaTe JT1 connector Figure 4 6. TSmoTe Figure 4 7. TSmoTe building blocks Figure 4 8. TSmoTe J2 connector Figure 4 9. TSmoTe M1 connector Figure TSmoTe JT1 connector Figure GPRS modem Figure GPRS modem J1 connector Figure RFID/NFC reader Figure RFID/NFC reader connector Figure GPS module Figure GPS module connector Figure Industrial sensors interface board Figure Industrial sensors interface board P1 connector Figure Industrial sensors interface board external sensor connectors Figure Serial Board Figure J1 Expansion connector Figure Serial Board J1 connector pinout Figure RS-232 J4 Serial adapter Figure RS-485 Serial adapter Figure mini USB Serial adapter Figure Wi-fi Module J1 connector pinout Figure ZigBee radio module Figure Digimesh / IEEE radio module Figure Wi-Fi radio module Figure MHz radio module Figure 5 1. Structure of TSmarT applications Figure 5 2. Code structure for TSmarT applications Figure 5 3. Application headers Figure 5 4. State machine for applications in FreeRTOS Figure 5 5. Queues Figure 5 6. GPRS function handler... 59

6 Figure 5 7. Example of API function Figure 5 8. TST software toolchain Figure 5 9. Download SDK Figure Main window for Eclipse Figure Debugger options Figure Jump to a line of code Figure Check variable status Figure Example application Figure Folder structure Figure Folder and file structure for example application Figure Definitions file... 68

7 Table of Tables Table 2 1. Compatibility overview... 4 Table 4 1. TSgaTe J2 connector pinout Table 4 2. TSgaTe M1 connector pinout Table 4 3. TSgaTe JT1 connector pinout Table 4 4. TSgaTe technical characteristics Table 4 5. TSmoTe J2 connector pinout Table 4 6. TSmoTe M1 connector pinout Table 4 7. TSmoTe JT1 connector pinout Table 4 8. TSmoTe technical characteristics Table 4 9. GPRS J1 connector pinout table Table 4 10 GPRS J2 connector pinout table Table GPRS modem technical characteristics Table RFID/NFC reader pinout table Table RFID/NFC reader technical characteristics Table GPS module pinout table Table GPS module technical characteristics Table Industrial sensors interface board P1 pinout table Table Industrial sensors interface board external connector pinout table Table Serial Board J1 pinout table Table RS-232 J4 DB9 female connector pinout Table RS-485 J3 connector pinout Table RS-485 J5 connector function Table Serial adapter board technical characteristics Table Wi-fi Module J1 pinout table Table Wi-fi Module technical characteristics Table 5 1. FreeRTOS data types... 55

8 List of Acronyms Acronym AIs DIOs FTP GPRS GPS I2C IoT JTAG M2M NFC OEM OS RF RFID RTOS SPI TCP/IP UART USB Wi-Fi WSN Meaning Analog Inputs Digital Input/Output File Transfer Protocol General Packet Radio System Global Positioning System Inter-Integrated Circuit Internet of Things Joint Test Action Group Machine-to-Machine Near Field Communications Original Equipment Manufacturer Operating System Radio Frequency Radio Frequency IDentification Real Time Operating System Serial Peripheral Interface Transmission Control Protocol / Internet Protocol Universal asynchronous receiver/transmitter Universal Serial Bus Wireless Fidelity Wireless Sensor Network

9 1 Introduction The main design goal for creating the TSmarT platform was to offer a simple and easyto-use, programmable embedded system to build WSN and M2M solutions, which enables fast application development and short time-to-market, so as to create a realworld IoT platform. The philosophy followed during the desing phase was trying to enhance the computational and communication capabilities of M2M devices while keeping it simple to use, and maintaining both low-power consumption and price ranges. The platform s first generation is made up of two different devices. The idea is to respect the node-repeater-gateway architecture, developing two different modules with a hardware and software common basis, but with different capabilities and prices. For the node and repeater functions, TSmoTe device is presented, with optimized costs and enhanced capabilities in comparison to available commercial solutions. TSgaTe is the other device conceived, with IP gateway features and enhanced connectivity features. The combination of both devices, along with the expansion modules for different communication technologies, creates the TSmarT family. This TSmarT family enables fast and simple development of wireless monitoring, remote control and M2M applications. These devices provide a complete and intuitive development tool for OEMs, engineering companies and system integrators looking for an easy way to embed wireless technologies into their products with a short timeto-market. TSmarT platform provides communications using the most popular wireless technologies nowadays (ZigBee, Wi-Fi, GPRS, NFC/RFID, GPS, etc ) and offers a powerful API to program and interact with them. TSmarT devices implement a modular design, enabling the connection with any kind of embedded or external sensor, actuator or other similar devices. The programming language is the well-known ANSI C, thus developers can start right away programming their applications. TST offers a software development kit with sample programs, open source tools, complete documentation and customized software libraries for the TSmarT family. This document is oriented to provide guidance through the programming and configuring stages when using TSmarT family. It is structured in two main parts: A quick reference guide, composed by sections 2 and 3, oriented to those who want to start working with TSmarT devices with just some precise and easy to follow instructions. A high level system overview is provided before introducing the way to connect and operate with devices. A detailed system architecture, comprising both hardware and software features, for programmers and end users interested on customizing devices and creating their own applications. o Section 4 describes all technical specifications regarding not only TSmarT devices, but also the add-on boards available to expand them. Pinout and main characteristics are given for each element suitable to be integrated into the platform. 1 TSmarT User Manual

10 o The Software architecture is depicted in section 5, on which programmers can find a step-by-step guide about how to program and modify the applications embedded in nodes, starting from the environment configuration at PC level. All this information provided can be considered as TSmarT family handbook for programming and using devices. 2 TSmarT User Manual

11 2 System overview Given the scalability and multi-tasking properties provided by TSmarT family, the best way to describe the platform is from hardware and software s perspective. The first one will define the technical features, footprint and cost. On the other hand, the second one will provide the tools, based on open source software, which will enable an abstraction layer to the underlying hardware. In addition to the architecture overview, this section provides the basic guidance needed to start working with TSmarT devices. For further information about this development environment, please refer to section Hardware architecture TSmarT platform is a modular, multi-technology, RF design tool that enables fast and simple development of wireless monitoring, remote control and M2M applications. Figure 2 1 pictures all devices available at TSmarT platform. Figure 2 1. TSmarT hardware components The product family comprises two programmable boards (TSmoTe & TSgaTe) and a set of add-on modules compatible with both of them. Current available add-on modules include ZigBee & Wi-Fi radios, GPRS modems, RFID/NFC readers, GPS modules, RS-485 serial ports and an industrial sensor interface board. TSmarT hardware is truly plug&play; you just have to connect the selected add-on boards for your application to the chosen mother board (TSmoTe & TSgaTe). 3 TSmarT User Manual

12 Table 2 1. Compatibility overview 2.2 Software architecture TSmarT software architecture is based on a layering approach that enables the easy development of user applications based on the TSmarT hardware. It is written in C programming language. Figure 2 2 shows the software structure of TSmarT. Figure 2 2. TSmarT software architecture The TSmarT architecture has three main layers: 1. STM32 layer This layer contains the low level drivers of the microcontroller provided by the STM32F10X manufacturer. These drivers implement the basic functionality of the microcontroller and manage the core and the different peripherals of the microcontroller, such as the UART or the MCU core. 2. FreeRTOS layer FreeRTOS is an open source, real-time, multitasking operating system for embedded software applications. This layer has its own API to develop not only 4 TSmarT User Manual

13 internal layers but also applications. Please read chapter 2.3 for further information on FreeRTOS. 3. TSAPI layer TST has implemented a hardware abstraction layer to facilitate software development of user applications. This layer supports many functions to simplify the management of the underlying hardware. This layer is based on FreeRTOS s mechanisms, e.g. mutex, semaphores, queues and so on. Devices (i.e. virtualization of TSmarT hardware) and communication buses are integrated in a complete multitasking software environment, which simplifies user application programming. An example of an API function available for programmers is shown in Figure 2 3. Figure 2 3. Function to send SMS messages If the user wants to send a SMS using the GRPS modem, this function can be used to implement that functionality. The user only needs to enter the destination phone number and the text that shall be sent. Users can find further documentation about TSAPI at website. To develop a complete TSmarT application, users must code their own applications. This is done by creating the application layer and then linking it with TSAPI and FreeRTOS layers. Just three steps are necessary for doing so: 1. Include the TSmarT header tsmart.h in the main file. This header includes all needed headers to work with TSmarT architecture. 2. Fill in the init() function with the requested hardware resources (i.e. initialize devices required by the application), demanded software needs (e.g. create task, mutex, queues ) and the desired debug level. 3. Program your own tasks. Thanks to the different communication protocols (Modbus, FTP, TCP/IP, ZigBee, Digimesh, , Wi-Fi, RS-485, USB), peripherals (UART, I2C, SPI, DIOs, AIs) and devices (GPRS, NFC, GPS, XBee) supported by the TSmarT family, users can develop almost any kind of application. TSmarT is able to mix different technologies in the same application, giving a wide variety of possible applications. For example, some customers may use TSmarT with NFC, GPRS and FTP functionality to manage hospital logistics, but others can take advantage of GPS and Modbus to avoid collisions in mining applications, or even some harbors could use ZigBee technology to perform lighting control, etc 5 TSmarT User Manual

14 Figure 2 4. Code structure 2.3 Real-Time Operating System FreeRTOS FreeRTOS is a real-time, open source, multitasking operating system for embedded systems. It was designed to be simple, portable and concise. It is written in C with only a few assembler functions. FreeRTOS works with a priority system proving flexibility to the design of applications. It was chosen to be supporting TSmarT family due to its main advantages for M2M devices: It is open source, so it is free, but user applications can remain confidential. It is widely used at industrial applications, supporting a large number of users. There are specialized companies offering profesional support for developing under FreeRTOS. It is a real time OS. It supports multitasking. 6 TSmarT User Manual

15 Figure 2 5. FreeRTOS mechanisms The main standard features of FreeRTOS are: Scheduling policy o Pre-emptive. The highest available task runs always. Tasks of identical priority share CPU time (fully pre-emptive with round robin time slicing). o Cooperative: Context switches only occur if a task blocks, or explicitly calls the task YIELD(). Figure 2 6. FreeRTOS multitasking support Co-routines (light weight tasks that utilize very little RAM). Queues Semaphores Mutex Wide range of ports and examples Users can manage application tasks, creating, blocking, deleting and setting their priorities. Each created task requires a task control block (TCB) and a stack to be allocated from the heap. In addition, FreeRTOS is able to manage the memory selecting different kinds of heaps, TSmarT architecture forces FreeRTOS to use heap 2 kind. This type of heap allocates memory and allows memory to be freed. 7 TSmarT User Manual

16 Figure 2 7. FreeRTOS heap structure FreeRTOS provides different mechanisms to manage tasks, e.g. queues to communicate between tasks, mutex to synchronize, delays to sleep tasks, locate/delocate memory to request for dynamic memory, etc More information on FreeRTOS can be read on chapter 6.2 or at Integrated Development Environment The development environment for TSmarT consists of several open source software tools merged in a single integrated development environment (IDE). In this environment, users can manage all the processes to program, compile and load their applications to the selected target board (TSgaTe or TSmoTe). Figure 2 8. TSmarT toolchain 8 TSmarT User Manual

17 The IDE is composed by the following modules: the main interface with the end user is Eclipse, a well known programming interface. It is customized for programming TSmarT devices by adding GDB as debugger and OpenOCD to establish the link with the hardware device (via JTAG). Each module is further explained below: Codesourcery: It is a free distribution of the GNU toolchain with support for several families of microcontrollers. It includes C/C++ compilers, assembler, linkers, standard libraries and the debugger. TSmarT uses this module to compile TSmarT applications generating three files in the well-known cross-compilation process: Filename.map - Reports about used memory. Filename.bin - Binary file to load. Filename.axf - Binary with debug information. OpenOCD: It provides an interface for programming and debugging embedded systems, i.e. an interface between the GDB debugger and the JTAG programmer (TST recommends a JTAG manufactered by ST Microelectronics, which is provided with the TSkiT development kit). OpenOCD provides a communication link between the JTAG and the TSmoTe or TSgaTe using the TCP/IP protocol. GDB: It is a debugger provided by the Codesourcery toolchain. This tool uses OpenOCD commands to operate in a lower level with the TSmarT platform. It allows the user to stop the execution using breakpoints, move between code lines, jump to a selected line, check the state of the variables, program the internal flash memory and so on. Eclipse: It is a free and open source software IDE prepared to be used with many different programming languages for software development projects. The main features of this software are: Text editor with code styles. Version controller: CSV, SVN. Can be adapted to several programming languages and can integrate different tools: compilers, debuggers 9 TSmarT User Manual

18 To develop applications for TSmarT devices, Eclipse must be able to work in C/C++. In addition, Eclipse will be the basis of the TSmarT environment. The complete software development kit (SDK) can be downloaded from 10 TSmarT User Manual

19 3 Getting Started This section is oriented to be a quick reference guide for programmers who just need the basic instructions to start working with TSmarT devices. It contains a brief introduction to the development kit, the basic hardware connectivity, and instructions how to install the programming environment and run a sample application. 3.1 TSkiT development kit The TSkiT development kit contains the essentials that you need to design your own wireless microprocessor-based system, and includes a complete ANSI C software development environment. The main boards are the TSgaTe and the TSmoTe. Both boards are based on a 32-bit low-power microcontroller with an ARM Cortex-M3 core. This development kit also contains add-on modules supporting several wireless technologies, e.g. ZigBee, Wi-Fi, NFC, GPRS, GPS, etc Scope of supply The TSkiT includes: 1 TSgaTe 2 TSmoTe Figure 3 1. TSkiT development kit 3 XBee radios Digimesh/ or ZigBee or WiFi with onboard chip antenna 1 debug board Optional: o o o 1 GSM/GPRS modem (with antenna) 1 RFID/NFC reader 1 GPS module with chip antenna 11 TSmarT User Manual

20 1 JTAG programmer/debugger 2 USB power supplies 5V 1A 1 Jack power supply 5V 2A Debug Board This board facilitates the first contact with the hardware and software of TSmarT platform. The board includes 3 GPIOs (dio0a, dio1a, dio7) with a button and a LED associated to each one of them, i.e. there are 3 buttons (P2, P3, P4) and 3 LEDs (LD5, LD6, LD7). The GPIOs can be set per software by the user to act as an input (i.e. buttons that generate events for the microcontroller) or an output (LED lights on/off). With the onboard APDS-9301 light sensor users can read real sensor values through the I2C interface. Figure 3 2. Debug Board The Debug board has 2 UARTs and a USB interface to connect with a hyperterminal software on a PC. With the P1 button, users can select the UART channel to be sniffed. The selected line is automatically directed to the USB port to be printed on screen at the hyperterminal on the PC: UART A RX line (when selected, LED LD1 is turned on) UART A TX line (when selected, LED LD2 is turned on) UART B RX line (when selected, LED LD3 is turned on) UART B TX line (when selected, LED LD4 is turned on) Figure 3 3. Debug Board Pinout shows the correspondence between pinout and the 3 configurable digital I/Os as buttons (P2, P3, P4) or LEDs (LD5, LD6, LD7). 12 TSmarT User Manual

21 Figure 3 3. Debug Board Pinout There are also two jumpers (JP1 and JP2) as shown in Figure 3 4. Debug Board Jumpers to enable or disable sending data from the hyperterminal to the microcontroller using UART A (jumper JP1) or UART B (jumper JP2), always through the respective UART_RX line (Pin8 or Pin18). 3.2 Hardware connections Figure 3 4. Debug Board Jumpers Figure 3 5. TSmarT mother boards TSgaTe (left) & TSmoTe (right) shows the most important connectors to start working with the TSmarT hardware. 13 TSmarT User Manual

22 Figure 3 5. TSmarT mother boards TSgaTe (left) & TSmoTe (right) Before start working directly with these boards, it is recommended to begin using the TSkiT development kit to get familiar with the TSmarT platform. The first step to manage the TSmarT platform is to connect properly the hardware connections: 1- Connect the Debug board on the J2 socket for TSmoTe or J7 socket for TSgaTe board. 2- Connect the JTAG device. 3- Turn the power on plugging the provided power adapter (either USB or jack connector) to the main outlet. 3.3 Install software toolchain The IDE toolchain is available for free download at TSmarT API website: The instructions for installing the toolchain can be summarized as follows: 1- Download the SDK32.zip (32-bit) or SDK64.zip (64-bit) file. 2- Extract the files. 3- Execute the installer file. 4- Install the drivers for both FTDI and for the JTAG interfaces. 5- Import the TSmarT libraries. 6- Configure Eclipse to work. All these steps are described in detail at the online quick start guide: 14 TSmarT User Manual

23 3.4 Run a sample program Users can run a simple application following the few steps described at Source codes for the following examples are available at * ai_read * \carriots carriots_2g carriots_wifi * \cellular_2g cellular_2g_ftp_send cellular_2g_ftp_receive cellular_2g_sms cellular_2g_tcp_client cellular_2g_tcp_server * \cumulocity cumulocity_nfc_wifi_xbee cumulocity_2g cumulocity_wifi * \debug_board db_dio db_i2c db_uart * dio_read * dled * \freertos freertos_advance freertos_basic freertos_timer * \i2c i2c * \i2c\i2c_master_slave i2c_master i2c_slave * int_flash * \modbus modbus_master_rtu modbus_slave_rtu * \msal msal_current msal_voltage msal_digital * \nfc nfc_read nfc_write * pwr * \rs485 rs485_receiver 15 TSmarT User Manual

24 rs485_sender * rtc * sdcard * spi * timer * uart * watchdog * \wifi tcp_client tcp_client_server tcp_server * \xbee802 xbee802_receiver xbee802_sender * \xbeedm xbeedm_receiver xbeedm_sender * \xbeewifi xbeewifi_receiver xbeewifi_sender * \xbeezb xbeezb_receiver xbeezb_sender * \xively xively_2g xively_wifi To execute any example application the user should follow the steps described below: 1- Compile for the selected board (TSmoTe or TSgaTe). 2- Open connection with the selected board (TSmoTe or TSgaTe). 3- Flash the binary file created into the flash memory. 4- Press the play button in the debug view of Eclipse. 5- Debug the application or simply run it. To do these steps users shall use the Eclipse environment. No additional programs are required. To know more about this process, please check 16 TSmarT User Manual

25 4 Hardware This chapter is oriented to provide the full technical specification for all hardware elements composing the TSmarT family. It is structured in two main sections: Sections 4.1 and 4.2 include the full specification of the two programmable devices, namely TSgaTe and TSmoTe. These boards are the core of TSmarT family. They both include the basic computational and communication features needed for sustaining M2M applications. Their technical specifications are described in the respective sections, paying special attention to the building blocks included and the pinout. Section 4.3 is in charge of providing the full definition of all possible add-on boards that can be attached to the previous ones in order to enhance connectivity features. 4.1 TSgaTe The TSgaTe is a powerful communication platform that enables fast and simple development of M2M solutions, wireless monitoring and remote control applications. Available TST libraries allow easy and quick development of software applications in ANSI C language that take full advantage of the add-on modules. Figure 4 1. TSgaTe 17 TSmarT User Manual

26 TSgaTe device is based on a powerful, low-power 32-bit microcontroller which runs the FreeRTOS real time operating system. Via the Ethernet port or through one of the available add-on modules, the TSgaTe usually acts as a gateway between the TSmoTe devices and software applications in remote servers or PCs. There are multiple add-on modules available for the TSgaTe, supporting different wireless technologies: ZigBee, Wi-Fi, GPRS, RFID/NFC, GPS, etc. Moreover, it is included an onboard temperature sensor. At software level the TSgaTe includes Wiznet s TCP/IP and Modbus stacks, as well as drivers for add-on modules. The software runs on top of the real-time multitask operating system. Besides, due to its modular design, it is possible to combine different wireless and/or wired technologies just choosing the corresponding add-on module. Moreover, programming applications using these modules is extremely simple with TST software libraries. The TSgate integrates the STM32F103RG low-power 32-bit microcontroller developed by STMicroelectronics. The STM32F103RG incorporates the high-performance ARM Cortex -M3 32-bit RISC core operating at a 72 MHz frequency, high-speed embedded memories, and an extensive range of enhanced I/Os and peripherals connected to three APB buses. Besides offers 12-bit ADCs, timers, plus 16-bit PWM timers as well as standard and advanced communication interfaces: I 2 Cs, SPIs, I 2 Ss, SDIO, USARTs, UARTs, USB, Ethernet 10/100 and CAN buses. A comprehensive set of power-saving mode allows the design of low-power applications. These features make the STM32F103RG connectivity microcontroller suitable for a wide range of applications such as motor drives and application control, medical and handheld equipment, industrial applications, PLCs, inverters, printers, and scanners, alarm systems, video intercom, HVAC and home audio equipment. More information available on manufacturer s datasheet. The TSgaTe microcontroller incorporates 96 KB internal RAM and 1024 Kbytes internal Flash memory. Additionally the TSgaTe includes a microsd card slot, supporting the file system up to 32 GB cards. All these building blocks described can be seen in Figure TSmarT User Manual

27 TSgaTe Xbee Compatible DMA PERIPHERALS I2C JTAG Interface usd Slot 2 x SPI RTC SPI ADC TIM Internal Flash Internal Flash CORE 32 BIT CPU RMII UART NVIC PWR Up to 44x CMOS level IO 3 x UART EXT INT STM32F 103XXXX WDG 1 x I2C 6 x ADC 1 x USB Temperature Ethernet 10/100 Base T Figure 4 2. TSgaTe building blocks Pinout This section provides the specification for all connectors included in the TSgaTe board. Their location can be shown in Figure 4 1. For each connector, a figure is provided regarding its layout in the board and a table matching each pin with its location, function and MCU used. 19 TSmarT User Manual

28 J2 connector Figure 4 3. TSgaTe J2 connector Table 4 1. TSgaTe J2 connector pinout Pin # Pin function Pin MCU Pin # Pin function Pin MCU 1 ai0a, dio0a PC3 12 dio6, SPI2 MISO, UART3 RTS PB14 2 ai1a, dio1a PC2 13 dio7, SPI2 MOSI PB15 3 ai2a, dio2a PC1 14 dio8 PC7 4 ai3a, dio3a PC0 15 dio9 PC8 5 ai0, dio0 PB0 16 dio10 PC VDC NC 17 dio11 PA8 7 ai1, dio1 PB1 18 dio12, UART1 TX PA9 8 dio2, UART3 TX, I2C2 SCL PB10 19 dio13, UART1 RX PA10 9 dio3, UART3 RX, I2C2 SDA PB11 20 dio14, I2C1 SDA PB7 10 dio4, SPI2 NSS PB12 21 dio15, I2C1 SCL PB6 11 dio5, SPI2 SCK, UART3 CTS PB13 22 GND NC 20 TSmarT User Manual

29 M1 connector Figure 4 4. TSgaTe M1 connector Table 4 2. TSgaTe M1 connector pinout Pin # Pin function Pin MCU Pin # Pin function Pin MCU VDC NC 11 NC NC 2 tsmart_uart2 Rx, dio6x PA3 12 tsmart_uart2 CTS, dio3x PA0 3 tsmart_uart2 Tx, dio7x PA2 13 NC PC12 4 NC NC 14 NC NC 5 Xbee_Reset, RS485_Dir, dio1x 15 NC NC 6 NC NC 16 tsmart_uart2 RTS, dio5x PA1 7 NC NC 17 NC NC 8 NC NC 18 NC NC 9 Xbee_Sleep_RQ, dio2x PC10 19 NC NC 10 GND NC 20 NC NC JT1 connector 21 TSmarT User Manual

30 Figure 4 5. TSgaTe JT1 connector Table 4 3. TSgaTe JT1 connector pinout Pin # Pin function Pin MCU Pin # Pin function Pin MCU 1 GND NC 5 TDO PB3 2 TMS PA13 6 ntrst PB4 3 TCK PA14 7 nsrst NRST 4 TDI PA VDC NC Technical characteristics Finally, this section presents in a single table all previously mentioned technical characteristics. Table 4 4. TSgaTe technical characteristics Pin # Alternative function Electrical Input voltage Internal voltage Current CPU on VDC 3.3 VDC 40mA Current MCU stand-by 23µA Coin cell CR1025 Mechanical & Environmental Dimensions Connectors 70x52mm 22 pins female slot for expansopn modules Doble row female slot for expansion modules Micro USB 8 pin JTAG connector 22 TSmarT User Manual

31 Environmental Operation temperature Storage temperature Certificates -20ºC / +70ºC -40ºC / +85ºC CE MCU Microcontroller Clock Flash RAM SD card Serial interfaces I/O Wi-Fi Ethernet STM 32-bit ARM Cortex-M3 core 72 MHz 1MB 96KB Slot for microsd up to 2GB 3 UART, 2 I2C, 1 SPI Up to 6 analog inputs, Up to 20 digital IOs b/g (ceramic or external antenna) 100 MB Add-on modules RFID/NFC, Zigbee, Wi-fi, IEEE , GPRS/3G, GPS, RS-485, Industrial range sensors and upcoming Embedded Software Stacks OS API TCP/IP, HTTP, Modbus FreeRTOS Yes, available at api.tst-sistemas.es 4.2 TSmoTe The TSmoTe is an embedded system designed to enable fast and simple development of wireless monitoring applications, remote control and M2M solutions. It is based on a powerful, low-power 32-bit microcontroller with an ARM Cortex-M3 core. Sensors, actuators and other measuring devices can be connected to the TSmoTe over I/Os and serial ports. There are multiple add-on modules available for the TSmoTe supporting different wireless technologies: ZigBee, Wi-Fi, GPRS, RFID/NFC, GPS, etc. Moreover, it is included an onboard temperature sensor. 23 TSmarT User Manual

32 Figure 4 6. TSmoTe At software level the TSmoTe includes the Modbus stack and the drivers for the addon modules. The software runs on top of the real-time multitasking operating system FreeRTOS. Due to its modular design, it is possible to combine different wireless or/and wired technologies just choosing the corresponding add-on modules. Programming applications that use those modules is extremely simple with TST software libraries (please visit api.tst-sistemas.es). The TSmoTe integrates the low-power 32-bit microcontroller STM32F103RG developed by STMicroelectronics. The STM32F103RG incorporates the high-performance ARM Cortex -M3 32-bit RISC core operating at a 72 MHz frequency, high-speed embedded memories, and an extensive range of enhanced I/Os and peripherals connected to two APB buses. The STM32F103RG also offers 12-bit ADCs, general-purpose 16-bit timers plus PWM timers, 12-bit D/A converters, as well as standard and advanced communication interfaces: I 2 Cs, SPIs, I 2 Ss, SDIO, USARTs, UARTs, USB and CAN bus. A comprehensive set of power-saving mode allows the design of low-power applications. These features make the STM32F103RG high-density performance microcontroller suitable for a wide range of applications such as motor drives, application control, medical and handheld equipment, PC and gaming peripherals, GPS platforms, industrial applications, PLCs, inverters, printers, scanners, alarm systems and video intercom. More information available on manufacturer s datasheet. The TSmoTe microcontroller incorporates 96 KB internal RAM and 1 MB internal Flash memory. Additionally the TSmoTe includes a microsd card slot supporting a file system up to 32GB cards. All the information regarding building blocks included at TSmoTe board is summarized in Figure TSmarT User Manual

33 TSmoTe Xbee Compatible RTC PERIPHERALS DMA I2C JTAG Interface usd Slot SPI ADC TIM Internal Flash Internal Flash 32 BIT CPU UART NVIC PWR Up to 20x CMOS level IO 1 x SPI EXT INT STM32F 103XXXX WDG 3 x UART 2 x I2C 1 x USB Temperature 6 x ADC Figure 4 7. TSmoTe building blocks 25 TSmarT User Manual

34 4.2.1 Pinout This section provides the specification for all connectors included in the TSmoTe board. Their location can be shown in Figure 4 6. For each connector, a figure is provided regarding its layout in the board and a table matching each pin with its location, function CORE and MCU used. J2 connector Figure 4 8. TSmoTe J2 connector Table 4 5. TSmoTe J2 connector pinout Pin # Pin function Pin MCU Pin # Pin function Pin MCU 1 ai0a, dio0a PC3 12 dio6, SPI2 MISO, UART3 RTS PB14 2 ai1a, dio1a PC2 13 dio7, SPI2 MOSI PB15 3 ai2a, dio2a PC1 14 dio8 PC7 4 ai3a, dio3a PC0 15 dio9 PC8 5 ai0, dio0 PB0 16 dio10 PC VDC NC 17 dio11 PA8 7 ai1, dio1 PB1 18 dio12, UART1 TX PA9 8 dio2, UART3 TX, I2C2 SCL PB10 19 dio13, UART1 RX PA10 9 dio3, UART3 RX, I2C2 SDA PB11 20 dio14, I2C1 SDA PB7 10 dio4, SPI2 NSS PB12 21 dio15, I2C1 SCL PB6 11 dio5, SPI2 SCK, UART3 CTS PB13 22 GND NC 26 TSmarT User Manual

35 M1 connector Figure 4 9. TSmoTe M1 connector Table 4 6. TSmoTe M1 connector pinout Pin # Pin function Pin MCU Pin # Pin function Pin MCU VDC NC 11 NC NC 2 tsmart_uart2 Rx, dio6x PA3 12 tsmart_uart2 CTS, dio3x PA0 3 tsmart_uart2 Tx, dio7x PA2 13 Xbee_On_Sleep, dio4x PC12 4 NC NC 14 NC NC 5 Xbee_Reset, RS485_Dir, dio1x 15 NC NC 6 NC NC 16 tsmart_uart2 RTS, dio5x PA1 7 NC NC 17 NC NC 8 NC NC 18 NC NC 9 Xbee_Sleep_RQ, dio2x PC10 19 NC NC 10 GND NC 20 NC NC 27 TSmarT User Manual

36 JT1 connector Figure TSmoTe JT1 connector Table 4 7. TSmoTe JT1 connector pinout Pin # Pin function Pin MCU Pin # Pin function Pin MCU 1 GND NC 5 TDO PB3 2 TMS PA13 6 ntrst PB4 3 TCK PA14 7 nsrst NRST 4 TDI PA VDC NC Technical characteristics Finally, this section presents in a single table all previously mentioned technical characteristics. Table 4 8. TSmoTe technical characteristics Pin # Alternative function Electrical Input voltage Internal voltage Current CPU on VDC 3.3 VDC 40mA Current MCU stand-by 23µA Coin cell CR1225 Mechanical & Environmental Dimensions Connectors 70x52mm 22 pin 2.54mm pitch for add-on modules 2x10 pin 2mm pitch socket 28 TSmarT User Manual

37 USB mini DF3 3 pin 2mm pitch 8 pin 1.27mm pitch JTAG Operation temperature Storage temperature Certificates -20ºC / +70ºC -40ºC / +85ºC CE MCU Microcontroller Clock Flash RAM SD card Serial interfaces I/O STM 32-bit ARM Cortex-M3 core 8 MHz 1MB 96KB microsd up to 2GB 2 UART, 2 I2C, 1 SPI Up to 6 analog inputs, Up to 20 digital IOs Add-on modules RFID/NFC, Zigbee, Wi-fi, IEEE , GPRS/3G, GPS, RS-485, Industrial range sensors and upcoming Embedded Software Stacks OS API TCP/IP, HTTP, Modbus FreeRTOS Yes, available at api.tst-sistemas.es 4.3 Add-on boards TSmarT main boards offer the programming capabilities, while the add-on boards offer the communication standards. They cover three main areas: Extended communication, by the use of either licensed (GPRS modem, section 4.3.1) or unlicensed bands (ZigBee and Wi-Fi modules, sections 4.3.8, and 0). Positioning features withthe GPS module (section 0) Attaching external sensors, by enabling easy to use digital and analog inputs and outputs (section 4.3.4). 29 TSmarT User Manual

38 4.3.1 GPRS modem The GPRS module is one of the most important components that can be connected to the TSmoTe or TSgaTe, as it guarantees long range connectivity and Internet access. With respect to other cellular modems, the GPRS add-on board is distinguished by its low-power consumption, small size and full Internet connectivity with native support of FTP and TCP/UDP protocols. The modem is also able of sending and receiving s and SMS messages. The GPRS modem can be used worldwide thanks to its quad band support (850/900/1800/1900 MHz). It can be attached to class 10 GSM and GPRS networks. The modem enables a fast and simple development of M2M applications. Software libraries (TSMART_CELLULAR_2G_) provided by TST offer a simple way to use the GPRS modem. In addition, developers also have the option to communicate directly with the modem via AT commands over a serial port Pinout Figure GPRS modem As in previous sections, the pinout is provided by showing a figure with the physical layout and a table matching each pin with its functionality. J1 connector 30 TSmarT User Manual

39 Figure GPRS modem J1 connector Table 4 9. GPRS J1 connector pinout table Pin # Pin function Pin # Pin function 1 NC 12 GPRS UART RTS 2 NC 13 NC 3 NC 14 GPRS RING INDICATOR 4 NC 15 GPRS POWER ON/OFF 5 NC 16 NC 6 NC 17 NC 7 NC 18 NC 8 GPRS UART RX 19 NC 9 GPRS UART TX 20 NC 10 GPRS DEVICE RESET 21 NC 11 GPRS UART CTS 22 GND 31 TSmarT User Manual

40 Table 4 10 GPRS J2 connector pinout table Pin # Pin function 1 4.2V DC In 2 GND Datasheet All previously mentioned technical characteristics are summarized in Table Table GPRS modem technical characteristics Technical Characteristics GPRS module Electrical Supply voltage Transmitting current VDC 1.6 A peak Sleep current 400 µa Stand-by current 1.9 ma (calls reception available) Mechanical Size Connectors 52 x 43 mm 22 pins female socket U.FL antenna connector 2 pin 2.54mm pitch for power supply 2-pin microphone connector 2-pin speaker connector Radio parameters Frequency bands Supported standards Output power Baudrate 850/900/1800/1900 MHz GSM, GPRS EDGE (MCS-9) 2W at 850/900 MHz, 1W at 1800/1900 MHz Up to 237 kbps download, 237 kbps upload Embedded software Supported services Communications FTP, TCP, HTTP, UDP, , SMS TST software library AT commands Enviromental Operating temperature Storage temperature Certifications -40ºC / +85ºC -40ºC / +85ºC CE, RoHS, R&TTE, RoHS, GCF-CC, FCC, PTCRB, China RTE, ICASA, Anatel, ATEX 32 TSmarT User Manual

41 4.3.2 NFC/RFID reader/writer The NFC/RFID module is a device supporting several operating modes, as, for example, reader/writer roles, card emulation mode and peer-to-peer applications. This module supports MIFARE, FeliCa, ISO/IEC 14443A&B and NFC (MIFARE Ultralight, MIFARE DESfire, Jewel, FeliCa and NFC smartphones) tags and cards. It can be used to implement multiple applications, as for instance access control, logistic solutions, mobile payments and P2P applications with smartphones among others. Figure RFID/NFC reader By means of a printed antenna on the PCB for MHz communication, the typical range obtained is approximately 5 cm. Data exchange with the TSmoTe/TSgaTe takes place over a serial port with baud rates up to 424 kbps. Using the API provided (TSMART_NFC_) by TST, software developers can access the functionality provided by the NFC/RFID module. In case it is needed, programmers can establish communication with the NFC/RFID module using native commands over a serial interface Pinout As in previous sections, the pinout is provided by showing a figure with the physical layout and a table matching each pin with its functionality. P1 connector 33 TSmarT User Manual

42 Figure RFID/NFC reader connector Table RFID/NFC reader pinout table Pin # Pin function Pin # Pin function 1 NC 12 NC 2 NC 13 NC 3 NC 14 NC 4 NFC DEVICE RESET 15 NC 5 NC 16 NC VDC In 17 NC 7 NC 18 NFC UART RX 8 NC 19 NFC UART TX 9 NC 20 NC 10 NC 21 NC 11 NC 22 GND 34 TSmarT User Manual

43 Datasheet All previously mentioned technical characteristics are summarized in Table Table RFID/NFC reader technical characteristics Technical Characteristics Electrical Supply voltage RF current Sleep current Mechanical Size Connectors Radio parameters Operating frequency Range Serial baudrate Supported protocols Reader/Writer mode Card emulation mode P2P mode Embedded software Communications Enviromental Operating temperature Storage temperature Humidity Certifications NFC/RFID module VDC 70 ma 12 ua 72 x 70 mm 22 pins female socket MHz 80 mm Up to 424 kbps ISO/IEC 14443A&B, MIFARE, FeliCa, NFC ISO 14443A, MIFARE ISO/IEC (active and passive) TST software library Native commands over UART -30ºC / +85ºC -55ºC / +150ºC 5-95% RH CE GPS module The GPS module features a very high sensitivity that allows satellite signal reception under extreme conditions where other GPS receivers fail. In a cold start with only-148 dbm received power the GPS module is able to capture its coordinates, and in navigation mode -165 dbm strength signal is enough for it to operate. 35 TSmarT User Manual

44 Figure GPS module The low-power module requires just 75 mw power in order to operate properly, a feature that makes it suitable for battery operated mobile applications. The GPS module captures up to 10 fixes per second, enabling its use in extremely high dynamics applications. This GPS device offers also a high time synchronization of 1 µsec and geographic precission of +/- 1.8 meters. It is very simple to use and program the GPS module with the software libraries provided (TSMART_GPS_)by TST Pinout As in previous sections, the pinout is provided by showing a figure with the physical layout and a table matching each pin with its functionality. P1 connector 36 TSmarT User Manual

45 Figure GPS module connector Table GPS module pinout table Pin # Pin function Pin # Pin function 1 NC 12 NC 2 NC 13 NC 3 MODULE STAND BY 14 NC 4 RESET 15 NC 5 NC 16 NC VDC In 17 NC 7 NC 18 NC 8 ANTENNA SELECTION PIN 19 GPS UART TX 9 NC 20 GPS UART RX 10 DEVICE POWER ON 21 NC 11 NC 22 GND 37 TSmarT User Manual

46 Datasheet All previously mentioned technical characteristics are summarized in Table Table GPS module technical characteristics Technical Characteristics Electrical Supply voltage Internal voltage Navigating current Sleep current Mechanical Size Connectors Times Cold start Hot start GPS parameters Sensitivity Maximum rate Position precision Speed precision Time precision Frequency Embedded software Communications Enviromental Operating temperature Storage temperature Humidity Certifications GPS module VDC 2.8 VDC 25 ma + 15mA LNA 5 ua from backup battery 52 x 43 mm 22 pins female socket U.FL connector for external antenna 35s 1s -165 dbm tracking, -148 dbm navigating - 15dBm (LNA) 10 Hz 3 m horizontal, 5 m vertical 0,1 m/sec 50ns RMS 1575 MHz TST software library Native commands over UART -30ºC / +85ºC -55ºC / +150ºC 5-95% RH CE Industrial Sensors Adapter The industrial sensor adapter is an add-on module oriented to ease the connection of industrial sensors to TSmarT devices. Any commercial sensor with analog 4-20 ma and/or 0-10V outputs can be adapted via this interface. There are four available analog inputs for 4 to 20 ma sensors, four analog inputs from 0 to 10 volts sensors and two CMOS 3.3V logic level digital inputs/outputs. Software libraries provided (TSMART_MSAL_) by TST offer a simple way to use the Industrial sensors interface board. 38 TSmarT User Manual

47 Figure Industrial sensors interface board Pinout As in previous sections, the pinout is provided by showing a figure with the physical layout and a table matching each pin with its functionality. P1 connector Figure Industrial sensors interface board P1 connector 39 TSmarT User Manual

48 Table Industrial sensors interface board P1 pinout table Pin # Pin function Pin # Pin function 1 V1 Voltage ADC In 12 NC 2 V1 Voltage ADC In 13 Digital 2 In 3 A2 Current ADC In 14 NC 4 A1 Current ADC In 15 NC 5 Enable device 16 NC VDC In 17 NC 7 Digital 1 In 18 Current Channel Selection 1 8 NC 19 Current Channel Selection 2 9 NC 20 Voltage Channel Selection 1 10 NC 21 Voltage Channel Selection 2 11 NC 22 GND External sensor connectors Figure Industrial sensors interface board external sensor connectors 40 TSmarT User Manual

49 Table Industrial sensors interface board external connector pinout table Pin # Pin function Pin # Pin function P2 CONNECTOR 1 GND 5 GND mA Current Channel A1 In mA Current Channel A2 In 1 3 GND 7 GND mA Current Channel A1 In mA Current Channel A2 In 2 P3 CONNECTOR 1 GND 5 GND V Voltage Channel V1 In V Voltage Channel V2 In 1 3 GND 7 GND V Voltage Channel V1 In V Voltage Channel V2 In 2 P4 CONNECTOR 1 GND 2 Digital 1 In P5 CONNECTOR 1 GND 2 Digital 2 In Serial Board The Serial Board allows connecting the PORT-A and PORT-B UARTs from the TSmarT platform to external device through RS-232, RS-485 or USB serial interfaces by switching the appropriated levers on S1 and S2 switches to the ON position. The leds on the board will indicate the selected bus on each UART. Notice that only one serial interface should be selected on each UART at the same time, and the same serial interface should not be selected on both UARTs. Moreover, other expansion boards from the TSmarT platform may use PORTA or PORTB as well, so that, all switch levers on such used ports have to be switched off. It is very simple to use Serial Board module with the software libraries provided (TSMART_UART_ [USB and RS232] or TSMART_RS485_ [RS485] ) by TST 41 TSmarT User Manual

50 Figure Serial Board Pinout Figure J1 Expansion connector Figure Serial Board J1 connector pinout 42 TSmarT User Manual

51 Table Serial Board J1 pinout table Pin # Pin function Pin # Pin function 1 NC 12 NC 2 NC 13 NC 3 NC 14 NC 4 CONTROL_485_A 15 NC 5 NC 16 CONTROL_485_B VDC In 17 NC 7 NC 18 PORTA_Tx 8 PORTB_Rx 19 PORTB_Rx 9 PORTB_Tx 20 NC 10 NC 21 NC 11 NC 22 GND RS-232 serial adapter The RS-232 serial adapter is configured as DCE. It is also possible to use it as DTE adding a null modem cable or adapter. Figure RS-232 J4 Serial adapter 43 TSmarT User Manual

52 Table RS-232 J4 DB9 female connector pinout Pin # Pin function Pin # Pin function 1 NC 6 NC 2 RS-232 Tx 7 NC 3 RS-232 Rx 8 NC 4 NC 9 NC 5 GND RS-485 serial adapter The RS-485 serial adapter works in half-duplex configuration and includes a 120 ohms resistor which can be used in order to reduce noise interferences between the ines. Connect it only in case of having high noise in long lines just shunting the jumper J5. Figure RS-485 Serial adapter 44 TSmarT User Manual

53 Table RS-485 J3 connector pinout Pin # Pin function Pin # Pin function 1 GND 3 B(-) 2 A(+) Table RS-485 J5 connector function J5 SHORT OPEN Function 120R connected 120R not connected USB serial adapter The USB serial adapter is configured as device and it has to be connected to a host. Please, find the driver for the CP210X VCP in the following link: Figure mini USB Serial adapter 45 TSmarT User Manual

54 Datasheet All Technical characteristics are summarized in Table 4 22 Table Serial adapter board technical characteristics Technical Characteristics Electrical Supply voltage Internal voltage RS-232 supply current RS-485 supply current USB supply current Mechanical Size Connectors Baudrates RS-232 RS-485 USB GPS module VDC 3.3 VDC 300uA 2mA 17mA 52 x 49 mm 22 pins female socket D-SUB 9 pos female socket 5.08mm 3 way terminal block 26-14AWG Mini USB type B female connector 300Kbps (Min) 10Mbps (Max) 2 Mbps (Max) Communications TST software libraries Enviromental Operating temperature Storage temperature Humidity Certifications -30ºC / +85ºC -55ºC / +150ºC 5-95% RH CE Wi-fi Module The Wi-Fi module allows connection to b / g making it possible to exchange data at speeds of 54Mbps or faster. In combination with TST API, it allows Wi-Fi connectivity of the TSmoTe modules, extending its possibilities to wireless data networks. The board is based on the new module of Texas Instruments CC3000. Software libraries provided (TSMART_WIFI_) by TST offer a simple way to use the Wi-fi Module. 46 TSmarT User Manual

55 Pinout Figure Wi-fi Module As in previous sections, the pinout is provided by showing a figure with the physical layout and a table matching each pin with its functionality. Figure Wi-fi Module J1 connector pinout 47 TSmarT User Manual

56 Table Wi-fi Module J1 pinout table Pin # Pin function Pin # Pin function 1 NC 12 WL_SDO 2 NC 13 WL_SDI 3 NC 14 PWR_ON 4 NC 15 NC 5 NC 16 NC VDC In 17 NC 7 WL_IRQ 18 NC 8 NC 19 NC 9 NC 20 NC 10 WL_CS 21 NC 11 WL_SCK 22 GND Datasheet All previously mentioned technical characteristics are summarized in Table 4 26 Table Wi-fi Module technical characteristics Technical Characteristics Electrical Supply voltage Internal voltage Tx current Rx current Sleep current Mechanical Size Connectors Operating frecuencies Data rates Tx Power 1Mbps Tx Power 54Mbps Sensitivity 1Mbps Sensitivity 54Mbps Enviromental Operating temperature GPS module VDC 3.3 VDC 260mA peak 103mA 2uA 24 x 43 mm 22 pins female connector to TSmoTe / TSgaTe U.FL connector for external antenna 1 54 Mbps 18.3 dbm 14 dbm dbm -75 dbm -20ºC / +70ºC 48 TSmarT User Manual

57 Storage temperature Certifications -40ºC / +85ºC CE, RoHS ZigBee radio The TSmarT ZigBee module uses XBee Series 2 radio module from Digi. XBee Series 2 OEM RF Modules were engineered to operate within the ZigBee protocol and support the unique needs of low-cost, low-power wireless sensor networks. These modules require minimal powering and provide reliable delivery of data between remote devices. Modules operate within the unlicensed ISM 2.4 GHz frequency band. It is possible to find the software libraries needed in order to control the ZigBee module at TSmarT API [TSMART_XBEE_ZB_]. Figure ZigBee radio module Digimesh / IEEE radio TSmarT platform also supports IEEE RF networking through XBee [TSMART_XBEE_802_] and DigiMesh modules from Digi [TSMART_XBEE_DM_]. Figure Digimesh / IEEE radio module The XBee DigiMesh 2.4 embedded RF modules utilize the peer-to-peer DigiMesh protocol in 2.4 GHz for global deployments. This innovative mesh protocol offers users 49 TSmarT User Manual

58 added network stability through self-healing, self-discovery, and dense network operation. With support for sleeping routers, DigiMesh is ideal for power sensitive applications relying upon batteries or power harvesting technology for power. The XBee OEM RF modules are embedded solutions providing wireless endpoint connectivity to devices. These modules use the IEEE networking protocol for fast point-to-multipoint or peer-to-peer networking. They are designed for high-throughput applications requiring low latency and predictable communication timing. It is very simple to use and program the and DigiMesh modules with the software libraries provided by TST Wi-Fi radio The Wi-Fi module for the TSmarT platform is based on the XBee Wi-Fi embedded RF module, which provides simple serial to IEEE connectivity. By bridging the lowpower/low-cost requirements of wireless device networking with the proven infrastructure of , the XBee Wi-Fi creates new wireless opportunities for energy management, process and factory automation, wireless sensor networks, intelligent asset management and more. Focused on the rigorous requirements of these wireless device networks, the XBee Wi-Fi gives developers IP-to-the-device flexibility. Figure Wi-Fi radio module Using the API provided [TSMART_XBEE_WIFI_] by TST, software developers can access the functionality provided by the Wi-Fi radio module RF below 1 GHz The 868 MHz Xbee module is long-range embedded RF module providing end-point device connectivity for European applications. Supporting RF line-of-sight distances up to 80 km, these modules are ideal for challenging wireless environments where RF penetration and transmission distance are critical to the application. 50 TSmarT User Manual

59 Figure MHz radio module Using the API provided [TSMART_XBEE_868_] by TST, software developers can access the functionality provided radio module. 51 TSmarT User Manual

60 5 Software Once all hardware modules available within the TSmarT family have been introduced, it is time to explain how these modules are programmed. This section provides a full overview of the development environment needed to program TSmarT devices (application structure in section 5.1, FreeRTOS basics in section 5.2, API information at 5.3 and the toolchain description in section 5.4), added to a step-by-step guide about how to program M2M application in nodes (section 5.5). 5.1 Application structure TSmarT software architecture enables the easy creation of embedded wireless applications, just basic programming knowledge is required. The structure is shown in Figure 5 1. Structure of TSmarT applications. Figure 5 1. Structure of TSmarT applications An application is linked to TSmarT architecture using the provided API. An application is made up of three parts, as it can be seen in Figure 5 2. Code structure for TSmarT applications 52 TSmarT User Manual

61 Figure 5 2. Code structure for TSmarT applications 1- Headers: They are.h files. These files contain the declaration of the functions that programmers will use in their programs. It is mission critical to include the tsmart.h header. This header includes everything needed to work with TSmarT architecture, e.g. drivers, boards, devices and standard libraries. Other libraries (e.g. math.h) can also be included here. Figure 5 3. Application headers 2- Init() function. This function is created during the initialization process. This process is an automatic initialization of the microcontroller, and simply requires a small configuration of the peripherals that will be used by the microcontroller. The initialization process consists on several steps: 1. When the program is loaded in the internal flash memory, the enter point to execute code is ResetISR() function. This function initializes every variable of the.bss section to zero and loads the.data section to the SRAM. In addition, it defines the entry point to the application code using the internal main() function. 2. The main() function performs a very basic hardware initialization and creates the internal init task. This basic initialization sets the microcontroller system, initializes both the embedded flash interface and the PLL, and updates the SystemCoreClock variable. In addition, it configures and enables the usage 53 TSmarT User Manual

62 fault and bus fault priorities. The internal init task is created before starting the scheduler and must be the only task being executed during the initialization process. It is created with the highest system priority. 3. The init task calls the init() function, enables the interrupts and finally deletes itself, freeing the resources allocated. Once this process is finished, the programmer tasks are running. Therefore the init() function is the first thing that the programmer must fill in so as to use TSmarT architecture. It initializes the specific hardware application resources (GPRS, GPS, AI, DIO, Modbus, TCP/IP, etc ) and the software application resources (queues, mutex, tasks ) demanded by the user application. The proper way to fill in this function is to initialize first all hardware resources needed, and then do the same with the software resources. It is mandatory for this function to return TSMART_PASS when everything is ok or TSMART_FAIL when an error is detected. It is common in TSmarT architecture to use these define sentences: TSMART_PASS takes the value 0 TSMART_FAIL takes the value -1 When using the init() function, users cannot take advantage most of TSAPI functionalities, as interrupts are not enabled yet. Just functions used to initialize and set peripherals can be executed at this time, such as TSMART_GPRS_Init (), TSMART_I2C_Init () or TSMART_XBEE_DM_Init (). If the programmer executes inside the init() function any other function apart from the initialization functions of TSAPI, an exception will be thrown. Heap size for applications is set to 24,000 bytes. This size cannot be modified. For this reason, it is important for users to manage and monitor the stack size used. 3 - Application task. Each task created in the init() function is developed in this part. Tasks contain the functionality of the application, for example sending a SMS to a specific mobile phone number or reading a NFC card to process the NFC data. Programmers can use this area to implement the functionality of their application. 5.2 FreeRTOS FreeRTOS is a real-time, open source operating system for embedded systems under active development since It supports many different architectures and compiler toolchains. It is designed to be small, simple and easy to use. FreeRTOS's main job is to run tasks. Most of FreeRTOS's code involves prioritizing, scheduling, and running user-defined tasks. FreeRTOS defines several types of data to be used in a software development project. The mapping of those data types with the ones supported by ANSI C can be seen in Table 5 1. FreeRTOS data types Note: FreeRTOS is written in C for this reason users can avoid to use these types and use the standard ANSI C types. 54 TSmarT User Manual

63 Table 5 1. FreeRTOS data types FreeRTOS ANSI C portchar Char portfloat Float portdouble Double portlong Long portshort Short portstack_type unsigned long portbase_type Long State machines FreeRTOS supports multitasking offering the possibility to run multiple tasks. There are 2 possible states for each task: Running. In this state the code of the task is being executed by the microcontroller. Only one task can be in this state at a certain time. The scheduler can move a task to Not Running state for several reasons, e.g. by priority, by blocking (FreeRTOS higher priority function was invoked, as, for instance, vtaskdelay ()) or by suspending. Not running. This state includes all tasks that are not currently running. It comprises 3 possible internal states. o Suspended. Tasks in this state are not available for the scheduler. Tasks are only changed to this state using the vtasksuspend() function. The way out of this state will be calling to the vtaskresume() function. o Ready. Tasks that are not blocked or suspended and are able to run, but have to wait for executing its code. For example, there is another task with higher priority being executed. o Blocked. In this state there are tasks waiting for an event. Tasks can enter this state due to temporal (waiting for a period of time, e.g. 1 sec) or to synchronization events (e.g. wait for data to arrive on a queue). It s possible to block a task with both types, for example wait for data during a specific time on a queue. All these states as well as their possible interactions and changes can be seen in Figure 5 4. State machine for applications in FreeRTOS 55 TSmarT User Manual

64 5.2.2 Tasks Figure 5 4. State machine for applications in FreeRTOS There must be always at least one task in the running state. If the user task is blocked, FreeRTOS will provide an IDLE task. This task is automatically created when the scheduler is called; this process with TSmarT architecture is transparent for the programmer. FreeRTOS scheduler has a scheme called fixed priority preemptive scheduling because each task is assigned a priority that is not altered by the kernel itself (only tasks can change priorities) and because a task entering the Ready state or having its priority altered will always pre-empt the Running state if the tasks in the Running state have lower priority. FreeRTOS can also operate with a co-operative scheduling, but this option is not supported by TSmarT architecture. Programmers shall carefully assign adequate priorities for each task. FreeRTOS has 15 priority levels, being 1 the lowest and 15 the highest. 56 TSmarT User Manual

65 There are several functions available to manage tasks. The most important functions dealing with this job are the following ones: xtaskcreate(). Creates a new task and adds it to the list of tasks that are ready to run. It sets the priority and allocates the needed stack for the task. xtaskdelete (). Removes a task from RTOS management kernel. The task being deleted will be removed from ready, blocked, suspended and event lists. vtaskdelay (). Delays a task for a given number of ticks (X). It is possible to evaluate the timeout in milliseconds (Y) using porttick_rate_ms definition. The rule will be: vtaskdelayuntil (). Delays a task until a specified time. vtasksuspend (). Suspends any task. When a task is suspended, it will never get any microcontroller processing time again, no matter what its priority is. vtaskresume (). Resumes a suspended task Queues There are two options to communicate independent tasks; variables or queues. It is not recommended to use variables to communicate tasks because problems can arise if the access to the variable is not protected enough. The most effective way to communicate tasks is to use a queue. A queue can hold a finite number of data and it operates like a FIFO, i.e. data is written at the end (tail) of the queue and removed from the front (head) of the queue. Figure 5 5. Queues The main functions to manage queues are the following ones: xqueuecreate(). This function creates a queue. It needs to known how many elements will the queue hold and the elements size. The function returns a queue handler. vqueuedelete(). This function removes a queue of the system, freezing its resources. xqueuesend(). This function sends data to a queue. xqueuereceive(). This function reads data from the queue. Once the data has been read, it is removed from the queue Semaphores and mutex FreeRTOS supports also synchronization mechanisms as mutex or semaphores. A binary semaphore can be used to unblock a task each time a particular event occurs. Taking and giving a semaphore are concepts that have several different meanings depending on their use case. In classic semaphore terminology taking a semaphore is 57 TSmarT User Manual

66 equivalent to a P() operation and giving a semaphore is equivalent to a V() operation. A mutex is a special type of binary semaphore that is used to control the access to a resource that is shared between two or more tasks. The main functions that FreeRTOS offers to manage semaphores and mutex are the following one: vsemaphorecreatebinary(). This function creates a semaphore. vsemaphoredelete(). This function deletes a semaphore, including mutex type semaphores. xsemaphoretake(). This function obtains a semaphore. To use this function the semaphore or mutex must have been created previously. xsemaphoregive(). This function releases a semaphore. The semaphore or mutex has been created and obtained previously. xsemaphorecreatemutex(). This function creates a mutex. FreeRTOS provides mechanisms to protect critical sections, as taskenter_critical() and taskexit_critical(). Additionally FreeRTOS also offers an API for software timers. A software timer allows a function to be executed at a set time in the future. This timer has a 10 ms resolution because it is the minimum period defined for FreeRTOS in TSmarT architecture. The kernel of FreeRTOS has to dynamically allocate RAM each time a task, queue or semaphore is created. For this reason FreeRTOS provides its own pvportmalloc() and vportfree() functions to allocate and free memory. It is not recommended to use them because eventually programmers may not be able to obtain a single contiguous memory area due to fragmentation. FreeRTOS comes with three example implementation of both functions. TSmarT only uses one of them, matching with the heap type 2. Heap 2 uses a simple array dimensioned to 24,000 Bytes. This array is statically declared. For further information about FreeRTOS, please visit API The API developed by TST (a.k.a. TSAPI) offers many functions to program the TSmarT platform simplifying the management of the underlying hardware Coding rules All functions in the TSAPI are sharing the same naming system: TSMART_<DEVICE>_<Functionality> (tsmart_<device>_t *tsmart_<device>, <type> TSMART_<DEVICE>_parameter1, <type> TSMART_<DEVICE>_parameter2); Function name: TSMART_<DEVICE>_<Functionality>. Every function in TSmarT consists of 3 parts; it begins with the name TSmarT followed by the device name and a short description to explain the functionality offered by the function, e.g. TSMART_GPRS_SendSms () is a function to send a SMS using the GPRS modem. Function parameters: Type: tsmart_<device>_[<name>]_t. All data types in TSAPI follow the same coding rule; they begin with the word tsmart followed by the device 58 TSmarT User Manual

67 and a short explanation about its use, e.g. tsmart_gprs_config_t is a type to configure the GPRS modem. Almost all functions have a software handler to link it to the hardware module and to store relevant information like task handlers or queue handlers. This function handler should not be modified by the programmer, but sometimes it is interesting to check or read it to look for error codes. These function handlers are automatically initialized by the TSmarT architecture. An example of a function handler is pictured in Figure 5 6. GPRS function handler Figure 5 6. GPRS function handler All function parameters in the TSAPI are sharing the same naming system; TSMART_<DEVICE>_<parameter_name>, e.g: TSMART_GPRS_phone Return codes It is very common to have the same return codes in API functions; TSMART_PASS or TSMART_FAIL. There are a few functions that can return a special fault code. These codes have specific meaning to help programmers to debug their applications (it is possible to check the meaning of these codes reading the documentation at Initialization and configuration functions To program TSmarT devices using TSAPI, the first function that programmers must execute is TSMART_<DEVICE>_Init() function. This function initializes all hardware and software resources needed to manage the devices (GPRS, NFC, GPS, etc ) or peripherals (UART, I2C, SPI, DIO, AI ). The init functions have 2 main parameters: device s handler and configuration structure. This structure holds relevant parameters for the device as, for example, the baud rate. Some devices need to be preconfigured in order to be used. TST recommends to use TSMART_<DEVICE>_InitStruct() function to initialize all parameters required in TSMART_<DEVICE>_Config() function. An example of configuration is given below this line: int8_t TSMART_<DEVICE>_Config (tsmart_<device>_t *TSMART_<DEVICE>, tsmart_<device>_config_device_t *TSMART_<DEVICE>_config_device); This kind of function sets the parameters for the selected device, e.g. APN for the GPRS or PAN ID for ZigBee modules. 59 TSmarT User Manual

68 5.3.4 Other functions API documentation includes a plethora of predefined example functions that programmers may use as references for developing their own solutions. They cover all communication possibilities using not only the main but also the add-on boards: Figure 5 7. Example of API function If programmers want to send a SMS message using the GRPS modem, they can use this function. Programmers just need to enter the destination phone number and the text that shall be sent. Programmers can find documentation about TSAPI at website. 5.4 Toolchain The programming environment for TSmarT architecture is made up of several tools integrated under a single IDE. Each tool standalone is not very useful itself, but all of them together build a really powerful toolchain to develop software for embedded applications. This environment is organized as shown in Figure 5 8. TST software toolchain 60 TSmarT User Manual

69 Figure 5 8. TST software toolchain The environment is based on Eclipse, which is a free and open source IDE for programmers ( The environment supplied by TST has integrated the free GDB and compiler from the Codesourcery toolchain, counts on OpenOCD to communicate with the embedded platforms, and a JTAG hardware to make the conversion of the signals. All tools together provide a wonderful and unique integrated development environment to program applications for TSmarT platform. Programmers can download the environment for TSmarT (64-bit and 32-bit versions, please see Figure 5-9) at TSmarT website: 61 TSmarT User Manual

70 5.4.1 Eclipse Figure 5 9. Download SDK Once installed, it is time to begin using the IDE. The main page of Eclipse, just after initializing it, is shown in Figure In the picture, the main buttons are indentified: TSmarT project: It includes the TSmarT architecture. Compile button: It compiles any application. GDB: Used to load any application into the board. It also stops and resumes the microcontroller. OpenOCD: It establishes a link with the TSmoTe or TSgaTe. Change view: Programmers can change the view (debugger/develop view) to make the development process more comfortable. Eclipse can be adapted to work with C/C++ languages; the necessary plug-in (Eclipse CDT) is automatically installed in the TSmarT software environment. 62 TSmarT User Manual

71 5.4.2 Codesourcery Compiler Figure Main window for Eclipse Before debugging the application, users must perform a cross-compile process. This process is done using Codesourcery, the compiler defined in Eclipse. It generates three files: Filename.bin - Binary file to load. Filename.axf - Binary with debug information. Filename.map - Reports about used memory. To learn more about Codesourcery, please visit OpenOCD Once programmers have finished the cross-compilation process, the next step is to load the program (the binary file created in the previous step) into the flash memory of the microcontroller using OpenOCD, which provides an interface for programming and debugging embedded systems. OpenOCD establishes a communication link between the JTAG and the TSmoTe or TSgaTe using a TCP/IP protocol. This module has a configuration file for the boards and several parameters that TST has integrated automatically into the TSmarT environment. The flashing process is done automatically by the toolchain supplied by TST, programmers just have to press the proper button for the TSmoTe or TSgaTe boards on Eclipse IDE. To learn more about the OpenOCD, please visit 63 TSmarT User Manual

72 5.4.4 GDB Debugger A GDB tool from Codesourcery is provided in order to debug TSmarT applications. Once the program has been recorded into the flash memory with OpenOCD, programmers can stop, resume and start the execution of the program in the microcontroler. It is also possible to set break points to stop the program execution and to check the state of the variables. Figure 5-11 shows the main buttons in the debugger view that programmers should know to debug applications in TSmarT, namely play (for beginning the debugging process), pause (stop the process without cancelling it), stop (cancelling the debugging process), step into ( to step into the next method call at the currently executing line of code), step over ( to step over the next method call, without entering it, at the currently executing line of code) and step return ( to return from a method which has been stepped into) buttons. Figure Debugger options In addition to breakpoints, this debugger allows to move between code lines or jump to a selected line, as explained in Figure Figure Jump to a line of code Users can check variables too in the debug view. By clicking at variables label it is possible to know their current state. This information it is very worthy when a 64 TSmarT User Manual

73 programmer does not known what is happening in the application (in case of exceptions or other unknown bugs). Figure 5-13 shows where this label is and what kind of information users can see. Figure Check variable status To know more about the process of how to compile and flash the application into the boards, please visit the website This link explains in detail the steps needed in order to make a compilation and load the application in the flash memory of the microcontroller. 5.5 Application Example This section describes how to program, compile and install an application step by step to provide a complete view of the programming process using TSmarT platform. The example consists of four tasks; two of them switching a LED on/off using queues, and the other two to control other LED using an interruption generated by a button. 65 TSmarT User Manual

74 5.5.1 Folder structure Figure Example application The folder hierarchy provided for this example includes not only the application but also general purpose directories. TSmarT architecture has several folders: FreeRTOS. This folder includes the FreeRTOS library Include. This folder contains the configuration for TSmarT devices. STM32. Contains the low level drivers. Templates. Includes a template for applications. Third_Party. This folder contains third party libraries, such as TCP/IP, Modbus, FTP and file system. TS_XXXX. These folders (TS_Devices, TS_Board, TS_Utils and TS_Drivers) keep the libraries for the TSAPI. tsmart_examples: This folder contains a lot of examples for TSmarT Preparing the application It is recommended to use a template in order to start programming any application for TSmarT architecture. Programmers can find this template at templates folder. 66 TSmarT User Manual

75 Figure Folder structure An application is composed by main 2 folders and several files: 1. Folder Include: It stores the headers of the application. 2. Folder Src: It contains the sources files. The files included are the following ones: App_defs: This file includes several definitions for the application naming (programmers can change the name of the application). There are also several definitions about the Modbus stack. Using these defines, programmers can enable or disable the different libraries for the functionalities of the Modbus stack: o Gateway o RTU master o RTU slave Link_STM32F10X_<TYPE _MICROCONTROLER>.ld: TST provides a linker for its applications. This linker has enough information to load the application binary file into the TSgaTe or TSmoTe board. Programmers only need to know that a linker is necessary to flash the program into the flash memory. Makefile: The makefile provides all necessary links to the libraries and application files (module.mk) to build the binary file in the cross-compile process. This file will be unique for all applications in TSmarT architecture. Module.mk: It contains the application files to compile. Programmers shall fill this file with the name of their application files. 67 TSmarT User Manual

76 Makefile.local: Makefile.local contains references to Figure Definitions file the paths where the TSmarT and codesourcery directories are located in the user PC. This file is automatically created during the installation process of the IDE Initialize and configure your application. Once programmers know how TSmarT structure is organized, it is the moment to start programming the application. For this purpose the programmer may copy the app folder of the templates folder in the root TSmarT folder (this is not a mandatory rule since the application can be in any location in your PC, but is very comfortable to program having them all together). Programmers can rename their application, for example ex_app. (do not forget to fill the application files to define the name and the characteristics). Figure Folder and file structure for example application At src folder, there is a template of main.c file. This file contains the template for any application in TSmarT architecture. If programmers open the file, the init() function shall be filled in by them, configuring the necessary hardware and software resources. For the current example application, it is necessary to initialize the following hardware and software resources: Hardware resources: o 3 DIOs (2 for the LEDs and the third one for the button). Software resources: o 2 queues to exchange values between tasks o 1 mutex o 4 tasks 68 TSmarT User Manual

77 The queues and the mutex shall be declared as global variables to share them between tasks. 69 TSmarT User Manual /* Global variables */ xsemaphorehandle task_mutex; xqueuehandle task1_queue; xqueuehandle task2_queue; To fill in the init() function, the programmer must set the resources as follow: Enable debug modes to start/stop the program execution. Configure the DIOs for the LEDs and for the button in a proper way: - DIOs (LED): Open-Drain and not IRQ will be used. - Button: Input pull-up and IRQ by falling edge. Queues just need one element of one byte (uint8_t). Tasks set its stack size to 128 bytes and the priorities are set as: - task1: ---> 6/15 - task2: ---> 6/15 - task3: ---> 7/15

78 - task4: ---> 9/15 Setting these priorities ensures the example s adequate performance. Then the init() function is filled in as follow: int32_t init() { tsmart_dio_config_t dio_config; portbase_type xreturn; /* ************************************************************************* */ /* Debug Mode */ /* ************************************************************************* */ /* Uncomment for Debug */ TSMART_SYSTEM_All_Debug(); /* ************************************************************************* */ /* Initialize resources */ /* ************************************************************************* */ /* LED1 - DIO */ dio_config.irq_mode = TSMART_DIO_IRQ_NULL; dio_config.mode = TSMART_DIO_OD; TSMART_DIO_Init(&tsmart_dio0a, &dio_config); /* LED2 - DIO */ dio_config.irq_mode = TSMART_DIO_IRQ_NULL; dio_config.mode = TSMART_DIO_OD; TSMART_DIO_Init(&tsmart_dio1a, &dio_config); /* Button */ dio_config.irq_mode = TSMART_DIO_IRQ_FALLING; dio_config.mode = TSMART_DIO_IPU; TSMART_DIO_Init(&tsmart_dio7, &dio_config); /* ************************************************************************* */ /* Application task */ /* ************************************************************************* */ /* Create task1 queue */ task1_queue = xqueuecreate(1, sizeof(uint8_t)); if (task1_queue == NULL) { return TSMART_FAIL; } /* Create task2 queue */ task2_queue = xqueuecreate(1, sizeof(uint8_t)); if (task2_queue == NULL) { return TSMART_FAIL; } /* Create mutex */ led_mutex = xsemaphorecreatemutex(); if(led_mutex == NULL){ return TSMART_FAIL; } /* Create task 1 */ xreturn = xtaskcreate(vtask1, "TASK1", 128, NULL, 6, NULL); if (xreturn!= pdpass) { return TSMART_FAIL; } /* Create task 2 */ xreturn = xtaskcreate(vtask2, "TASK2", 128, NULL, 6, NULL); if (xreturn!= pdpass) { return TSMART_FAIL; } /* Create task3 */ xreturn = xtaskcreate(vtask3, "TASK3", 128, NULL, 7, NULL); if (xreturn!= pdpass) { return TSMART_FAIL; } /* Create task4 */ xreturn = xtaskcreate(vtask4, "TASK4", 128, NULL, 9, NULL); if (xreturn!= pdpass) { return TSMART_FAIL; } } /* Everything OK */ return TSMART_PASS; 70 TSmarT User Manual