Masaryk University Faculty of Informatics Graphical Debugger of GPIO Pins Bachelor’s Thesis Miloslav Žežulka Brno, Spring 2018 This is where a copy of the official signed thesis assignment and a copy ofthe Statement of an Author is located in the printed version of the document. Declaration Hereby I declare that this paper is my original authorial work, which I have worked out on my own. All sources, references, and literature used or excerpted during elaboration of this work are properly cited and listed in complete reference to the due source. Miloslav Žežulka Advisor: Mgr. Marek Grác, Ph.D. i Acknowledgements I would like to thank my advisor Mgr. Marek Grác, Ph.D. for his valuable feedback and comments regarding the thesis. I would also like to thank my technical advisor Ing. Pavel Macík who guided me throughout the whole work. iii Abstract The main aim of this thesis is to implement a graphical debugger for single-board computers (SBC) using a library called Bulldog. The first section of this work describes hardware interfaces typically present on SBCs with the emphasis on Raspberry Pi. The main part of the thesis is dedicated to the debugger itself, including a graphical demonstra- tion of its functionality. The result is a graphical debugger capable of communicating with devices from the Raspberry Pi family. During the implementation of the debugger, we also discover that the library itself required some major modifications. The application is based on the client-server model. Given the underlying library picked for the debugger, the application is written in Java and is publicly released via GitHub as an open source project. iv Keywords single-board computer, Bulldog, GPIO, I2C, SPI, Raspberry Pi, BCM2835, Java, JNI v Contents 1 Introduction 1 2 State of the art 3 2.1 RPi.GPIO ...........................3 2.2 BCM2835 ...........................3 2.3 GPIO utility from WiringPi .................3 2.4 i2cdetect, i2cget, i2cset ....................4 3 Bulldog Library 5 3.1 JNI ...............................6 4 Functions of GPIO Pins 9 4.1 Digital I/O ..........................9 4.1.1 Analog vs. digital signal . .9 4.1.2 Accessing GPIO pins . 10 4.1.3 Interrupts . 16 4.2 I2C ............................... 16 4.2.1 Protocol definition . 17 4.2.2 I2C data transmission - semantics . 17 4.3 SPI .............................. 19 4.3.1 SPI data transmission . 21 4.4 Other interfaces ........................ 23 4.4.1 PWM . 23 4.4.2 UART . 23 4.4.3 PCM . 24 5 Raspberry Pi 25 5.1 Raspberry Pi as a single board computer ........... 25 5.2 Uses .............................. 25 5.3 Raspbian ........................... 25 5.4 Accessing peripherals ..................... 26 6 Debugger 29 6.1 Use cases of the debugger ................... 30 6.2 Protocol ............................ 31 6.2.1 Details of the protocol implementation . 31 vii 6.2.2 Agent . 32 6.2.3 Client . 33 6.3 Libraries and frameworks used ................ 33 6.4 Networking .......................... 34 6.4.1 Java NIO . 34 6.5 Usage ............................. 36 6.5.1 Initial state of the debugger . 36 6.5.2 Connecting to a device . 38 6.5.3 Disconnecting from a device . 40 6.5.4 Digital I/O request . 40 6.5.5 Interrupts . 42 6.5.6 I2C request . 43 6.5.7 SPI request . 44 6.5.8 Agent . 45 6.5.9 Testing mode . 46 7 Conclusion 47 7.1 Possible improvements .................... 47 7.1.1 Bulldog . 47 7.1.2 Debugger . 48 7.1.3 Testing . 49 A JNI 55 B Sequence diagram of the debugger 59 C Archive 61 viii List of Figures 2.1 Output of gpio readall 4 3.1 JNI Architecture 7 4.1 Signal sampling 10 4.2 Sysfs tree 11 4.3 GPIO pin sysfs structure 12 4.4 I2C timing diagram 17 4.5 I2C protocol diagram 18 4.6 Regular SPI connection 20 4.7 Daisy-chained SPI bus 21 4.8 Schema of SPI data transmission 22 5.1 raspi-config tool 26 5.2 Binary data in procfs 27 6.1 Use case diagram 30 6.2 Blocking and nonblocking I/O 35 6.3 Debugger initial state 36 6.4 The client connected to Raspberry Pi 38 6.5 netstat command 39 6.6 Digital I/O usage 40 6.7 Interrupts in debugger 42 6.8 Prefilled I2C request form 43 6.9 I2C request form 44 6.10 SPI request form 45 6.11 Agent logger output 46 ix 1 Introduction Single-board computer (SBC) is a fully functional computer embedded on a single board. In comparison with a personal computer, SBC is a computer with all the necessary components (microprocessor, mem- ory, I/O) already present on the board. Furthermore, SBCs usually do not rely on expansion slots for peripheral functions or expansion [33]. By integrating all the components on one board, a smaller overall system can be obtained compared to a conventional PC. This also brings us to one of the most distinguishing characteristics of such com- puters. SBC is usually a very specialized piece of hardware designed and optimized for its one and only purpose. In the past few years, however, SBCs designed for general purpose are becoming increasingly popular1. In the context of this thesis, we will exclusively focus on this SBC type. General purpose SBCs are used as educational tools, development systems, demonstrations and in many other ways. When developing software or hardware for such devices, it is beneficial to have a debug- ging tool which is capable of reading or writing various information from the board, in the most convenient way possible. We will refer to such tool as a graphical debugger. This graphical debugger should be user-friendly2 since it is possible that users might come into contact with an SBC device for their first time. More specifically, the graphical debugger presented in this thesis represents a tool which is capable of providing the user with com- plex information about various hardware components and interfaces present on SBC. It is possible to read and write values on GPIO pins and listen for interrupts on them. Other interfaces available for de- bugging should be at least I2C and SPI3. In general, the debugger retrieves information using general purpose input/output interface, GPIO. This information is then graphically presented to the user. 1. An exhaustive list of such devices can be found in [9] 2. By user-friendly we especially mean the ability to use the debugger without long preparation beforehand. In the ideal implementation, the debugger should be able to run straight out of the box. 3. Both of these interfaces are described in more detail in the chapter "Functions of GPIO Pins". 1 1. Introduction The goal of my thesis was to implement such debugger using the Bulldog library [7]. This library was not fully functional. One of my other goals was also to look into Bulldog and improve it. The Bulldog library specializes in SBCs which use ARM processors (ARM SBC, ASBC). At the time of writing this thesis, Bulldog can communicate with Raspberry Pi, CubieBoard, and BeagleBoneBlack. Debugger implementation mainly focuses on Raspberry Pi with the potential for extending it for the other two SBCs supported by Bulldog. The debugger consists of two modules: client with graphical user interface and agent. The client is run on the machine from which the device is controlled and monitored over the network. The agent is deployed on the target device. The client can connect to multiple devices at once, whereas the agent is designed for communicating with one client only. The implementation language is Java because this is the primary language used in Bulldog. The resulting outcome of this project is a pair of JAR archives together with a manual describing how to deploy and use the application. This manual is one of the parts of this thesis. 2 2 State of the art Despite Raspberry Pi being powerful enough to run graphical appli- cations, most of the tools used for debugging are only available via a command-line interface. One of the reasons is compatibility with older Raspberry Pi releases which do not have powerful enough hard- ware to run graphics-based software. List of the most commonly used tools follows. 2.1 RPi.GPIO Python library for controlling digital I/O features of pins. What is more, RPi.GPIO [32] can also be used for writing scripts which test other functions available on pins1. However, this library only provides limited functionality when compared to others on this list. 2.2 BCM2835 Named after the chip Raspberry Pi has got embedded in its processor, this library written in C directly accesses chip registers. This makes BCM2835 [8] very powerful2. The BCM2835 library is recommended for more advanced users as it assumes deeper understanding of the interfaces. 2.3 GPIO utility from WiringPi WiringPi [18] is a pin-based GPIO access library written in C for the BCM2835 chip used in Raspberry Pi3. Apart from the library itself, WiringPi also provides a separate program which in textual form displays information about all avail- 1. Pin capabilities are determined by general purpose input output (GPIO) which itself is discussed in the chapter "Functions of GPIO Pins". 2. Other tools access GPIO functionality indirectly via sysfs which is in detail discussed in the section "Sysfs" of the chapter "Functions of GPIO Pins". 3. Since the initial release of this library in May 2013, it has been extended to also work on newer chips and supports alternative pin functions. 3 2. State of the art able pins. This is very useful when searching for various types of pin addresses (as shown in the illustration below).