2019 Supervisers: Eric Chabert, edition Eric Conte Computing session 2 Implementing a C++ class PixelWriter Abstract: The goal of this computing session is to write step-by-step a complete and operational C++ class. The class content is described by a UML (Unified Modeling Language) diagram. The class implementation must be tested in a main program. The class to implement is called PixelWriter and must allow the user to display on the 8x8 LEDs text messages. For this purpose, it is required to take profit from the class SenseHat and the header file font.h. Pedagogical goals: C++ language • Writing new classes from UML diagrams. • Instantiating objects from classes and initializing them. • Reading and adapting an existing piece of code. • Improving the robutness of the code in order to prevent ab- normal termination or unexpected actions. Collaboration work • Respecting a given set of programming rules and conventions. • Generating automatically the reference documentation rela- ted to the code with Doxygen. Compiling/linking • Creating an executable file from a simple source file. • Compiling and linking via a script a project made up of se- veral source files. Requirements: • Concept of class in C++, including constructors, destructor, mutators, accessors, ... • Some particular C++ points: I/O access, arrays, pointers/references, algorithms. 1 / 14 Contents I Development environment 3 1 Foreword 4 2 The Raspberry framework 5 2.1 Checking the hardware connections . .5 2.2 Booting the Raspberry . .6 2.3 Opening a Linux console . .6 2.4 Setting the environment . .6 II The class PixelWriter 7 3 First implementation of the class 8 3.1 Specifications . .8 3.2 Tasks to do . .8 4 Enriching the functionalities of the class 8 5 Enriching the structure of the class 9 III Generation of the class reference documentation 11 6 Generating documentation from C++ sources 12 6.1 First words about the Doxygen package . 12 6.2 Standard doxygen configuration file . 12 6.3 Adding graphics in the reference documentation . 13 6.4 Launching Doxygen ................................. 13 6.5 Work to do . 14 2 / 14 Part I Development environment 3 / 14 1 Foreword Computing sessions belong to the educational program of the ESIPAP (European School in Instrumentation for Particle and Astroparticle Physics). Their goal is to teach the secrets of C++ programming through practical work in the context of high energy physics. The session is designed to be pedagogical. It is advised to read this document section-by-section. Indeed, except the Physics context, each section of the document is a milestone allowing to acquire computing skills and to validate them. The sections related to C++ programming are ranked in terms of complexity. In order to facilitate the reading of this document and to measure his progress, the student must fill up the dedicated roadmap which includes a check-list and empty fields for personal report. In the document, some graphical tags are used for highlighting some particular points. The list of tags and their description are given below. The student is invited to perform a pratical work by writing a piece of code following some instructions. Analyzing or interpreting task is requested and the re- sults must be reported in the roadmap. Some additional information is provided for exten- ding the main explanations. It is devoted to curious students. A piece of advice is given to help the student in his task. 4 / 14 2 The Raspberry framework The present computing session must be performed on a specific setup based on a single-board machine, the Raspberry Pi 3 Model B+ released in 2018, and an add-on board containing several sensors, the Sense Hat board. The user will find below all the instructions for handling this particular framework and being ready to develop code. 2.1 Checking the hardware connections The Raspberry board needs to be linked to other peripheral devices for running properly. Photography 1 show the different items of the setup: Figure 1: Connections of the Raspberry board Please check the connections between the Raspberry board and: • the screen via a HDMI cable, • the mouse via a USB cable, • the keyboard via a USB cable, • the internet network via an Ethernet cable, • the power supply cable, • the Sense Hat board via the Ribbon cable. Finally check that a micro SD card is also inserted in the Raspberry board. 5 / 14 2.2 Booting the Raspberry For switching on the Raspberry board, the user has just to plug the power supply. The OS (Operator System) contained in the SD card will be executed and an initialization screen must be displayed at the screen. During this phase of initialization, the pixels of the Sense Hat board show rainbow colors. If you do not managed to have the booting sequence described previously, please warn the supervisors. 2.3 Opening a Linux console The OS (Operator System) is a Linux distribution called Raspbian which is very similar to Debian in the PC world. According to the Figure 2, you can open a new console by clicking on the fourth icon from the left of the task bar. It is the perfect environment for developing with Raspberry. All required packages have been a priori installed by the supervisors. Figure 2: The task bar of a Raspbian session If you notice that when you type with your keyboard it displays wrong letters (AZERTY/Q- WERTY issue), you should configure your keyboard by clicking on the last icon on the right (English, US or French flag) of the task bar. 2.4 Setting the environment To load the work environment, you can issue the command below at the shell prompt. bash$source /home/pi/tools/setup.sh If the system is properly installed, the version of each tool to study should be displayed at the screen like below. If you have an error, please call the supervisors. ---------------------------------------------- ESIPAP environment ---------------------------------------------- - GNU g++ version 4.9.1 - ROOT version 6.06/00 - Geant4 version 10.2.0 ---------------------------------------------- Good luck in your computing session!!! 6 / 14 Part II The class PixelWriter 7 / 14 3 First implementation of the class In this section, a class called PixelWriter, corresponding to the files called PixelWriter.h and PixelWriter.cpp, must be written. This class must be able to display any sentence with 8x8 LEDs of the Sense Hat board. 3.1 Specifications Here are enumerated the functionalities of the class PixelWriter. • The class must contain a pointer to an object of type SenseHat called device . We assume that the user instantiate an object of type SenseHat in the main program and the class PixelWriter has a pointer to this object. • The class must contain also two data members for the color: one for the text forecolor and one for the background backcolor . • Two constructors will be implemented for this class: one constructor with no argument where the data members are set to arbitrary values and a second constructor which allows us to initialize all data members. • The function SetDevice, SetForecolor, SetBackcolor allow to initialize the device , forecolor and backcolor data member. • The function Clear allows to clear the LEDs i.e. setting all LEDs to color black. • The function DisplayPattern takes in argument a 8x8 array of bool type and displays it to the LEDs. 2 prototypes must be implemented: one where the array is in C-format and the another one where the array is a std::vector. The UML diagram corresponding to the class PixelWriter is supplied below. 3.2 Tasks to do • Implement this first version of class PixelWriter according to the UML diagram. • Test the class definition by instantiating an object and by performing some operations. • Adapt the script mymake for building this project. 4 Enriching the functionalities of the class The goal is to add 2 additional functions to the UML diagram: • DisplayCharacter which takes in argument a character which must be displayed at the screen with the good colors. For that, the developer needs to download the file font.h from the ESIPAP indico and analyze it for understanding how to use it. 8 / 14 Figure 3: UML diagram of the class PixelWriter • DisplaySentence which takes in argument a std::string containing a sentence to dis- play with the LEDs. • Implement the function DisplayCharacter • Implement the function DisplaySentence 5 Enriching the structure of the class We would like to improve the structure of the class. These improvements are not crucial for the next developments. Their goal is totally pedagogical. 9 / 14 • Add a copy constructor to the class. • Associate the reserved word const to the appropriated functions. • Overload the operator << to display the data member va- lues when std::cout is applied directly to instance of this class. • Overload the operator [>> to display a std::string on the LEDs. 10 / 14 Part III Generation of the class reference documentation 11 / 14 6 Generating documentation from C++ sources Annotation and comments inside the code is very useful for the understanding. In order to increase the documentation level, it is also possible to generate automatically reference docu- mentation by reading the syntax and the annotations of the code. Whereas some documentation generators such as Javadoc are specific to one programming language, the Doxygen program has the advantage to be used for plenty languages. 6.1 First words about the Doxygen package Doxygen can read not only C++ language but also Java Python, Fortran, PHP and others. The formats of the generated documentation are mainly HTML and LaTex (PDF or PS after Latex compilation). It can cross reference documentation and code, so that the reader of a document can easily refer to the documentation. The package can be downloaded from the official website (www.doxygen.org).