But I hope this crash course will help you get started. And even if you don’t want to create your own libraries, some knowledge is still very useful. Being able to “read” libraries will help you to use them better or to understand error messages if necessary.<\/p>\r\n
In this first part, I explain the basics. The grammar, so to speak. I have deliberately chosen an example that has nothing to do with microcontrollers. In the second part, I will show you how to develop a library for a sensor and what typical issues arise.<\/p>\r\n\n
Libraries – basic terms<\/h2>\n\n
I don’t want to get too deep into general theory, but make sure “we’re speaking the same language”. I will keep this part about the basic concepts short because I want to focus on the practical application. If you think it’s too<\/em> short, do a little googling. There is already so much on the net about this that I can’t offer any added value.<\/p>\r\n\n A library is actually just a collection of program parts that is not executable on its own. The library can contain classes, but it does not have to. For the class, the library is a kind of container in which it is kept – alongside other components, if necessary.<\/p>\r\n The Arduino libraries that are not part of the “basic equipment” are located in the folder “Arduino\/libraries” as subfolders. The subfolders have the name of the library.<\/p>\r\n\n In object-oriented programming (OOP), we think of the world as a collection of objects that are related to each other. Classes are the blueprints for objects, just as circuit diagrams are for circuits, for example. Just as you can create virtually an infinite number of circuits from a circuit diagram, you can create an unlimited number of objects from a class. At least as many as the memory allows you. <\/p>\r\n The objects or the classes are designed in such a way that they reveal only what is necessary to the outside world (principle of encapsulation). Basically, the object properties should only be able to be changed via defined methods. This initially means increased effort, but it pays off later. Who does not know this: You extend a program, which then no longer works because the program parts affect each other unintentionally. Using OOP, these problems can be minimized. <\/p>\r\n In addition to encapsulation, there are other fundamental principles of OOP. Above all, these are inheritance, polymorphism and abstraction. However, I will not go into it any further. Interested parties can look here<\/a>, for example.<\/p>\r\n\n Objects have certain attributes (properties) and methods (functions). An example that is often used to illustrate this is a car:<\/p>\r\n\n Some properties are invariant, such as the model or the color. Other properties, such as speed, are variable and are changed via methods. Methods, on the other hand, do not necessarily have to control a property, such as the “hoot” method here.<\/p>\r\n\n The library folders contain the corresponding header (extension “.h”) and source files (extension “.cpp”). Among other things, the header files contain the class declarations. If necessary, further elements are placed there, such as For simple libraries that contain only a single class, the library, the class, and the header and source files often have the same name.<\/p>\r\n If you are designing a library yourself, make sure that you use individual names. Header files or classes whose names appear twice in the library directory can cause problems. That’s why (almost) all my libraries and classes that I publish on GitHub have my initials “WE” in their names, so you can see that this doesn’t (only \ud83d\ude42 ) serve my ego.<\/p>\r\n\n You can download the CoolCarLib exercise library used in this post from GitHub. Follow this link<\/a>, then click on the “Code” button and select “Download ZIP”. Save the ZIP file in your “Arduino\/libraries” folder and unzip it there. You should then find a folder called “CoolCarLib-main”. You don’t need the ZIP file anymore and can delete it. The easiest way to get to the library example sketches is via File \u2192 Examples \u2192 CoolCarLib-main in the Arduino IDE.<\/p>\r\n\n For the creation and editing of libraries, the Arduino IDE is not particularly well suited as an editor. I recommend the free Notepad++<\/a>. For smaller projects, the program is absolutely sufficient and requires hardly any introduction. <\/p>\r\n\n The first class we are looking at describes a car and is named CoolCarBasic. The car is very minimalistic, having only the following attributes and methods:<\/p>\r\n CoolCarLib contains the two classes CoolCarBasic and CoolCar. The following excerpt of the header file CoolCarLib.h contains a general part and the code of the CoolCarBasic class declaration:<\/p>\r\n\n The content of the header file is framed by:<\/p>\r\n\n The statements beginning with the hash Then follows the class declaration, started with the keyword All functions (methods) and variables (attributes) after The first function of the class is For variable definitions of integers, you should specify the variable type in the notation Now we come to the source file CoolCarLib.cpp. First, here is the code relevant for CoolCarBasic:<\/p>\r\n\n In the first line CoolCarBasic.h is included. The statement seems superfluous because we include the file in the sketches right away. But you can’t do without it – these are the peculiarities of the preprocessor.<\/p>\r\n This is followed by the definitions of the functions previously declared in the header file. What stands out is that all function names are preceded by the class name, separated by the double colon Now we come to the constructor You query the maximum number of passengers with The function And this is what a sketch using CoolCarBasic might look like:<\/p>\r\n\n Line 3 calls the constructor and creates the object Libraries vs. classes<\/h3>\n\n
Objects and object-oriented programming <\/h3>\n\n
Attributes and methods <\/h3>\n\n
![\"Writing](\"https:\/\/wolles-elektronikkiste.de\/wp-content\/uploads\/2022\/11\/car_class_eng_lang-1024x535.png\")
<\/a>Header and source files<\/h3>\n\n
#define<\/code> and #include<\/code> statements or enum definitions. The source files mainly contain the functions.<\/p>\r\nPreparations<\/h2>\n\n
A minimal class – CoolCarBasic<\/h2>\n\n
\r\n
\r\n
\r\n
CoolCarBasic – header file<\/h3>\n\n
#ifndef COOL_CAR_LIB_H_\r\n#define COOL_CAR_LIB_H_\r\n\r\n#include <Arduino.h>\r\n\r\n\/* ############### CoolCarBasic ############### *\/\r\n\r\nclass CoolCarBasic \/\/ Class Declaration\r\n{\r\n public: \r\n CoolCarBasic(uint8_t mP); \/\/ Constructor\r\n \r\n uint8_t getMaxPassengers();\r\n uint16_t getSpeed();\r\n void setSpeed(uint16_t speed);\r\n void hoot();\r\n \r\n protected:\r\n uint8_t maxPassengers;\r\n uint16_t speed;\r\n};\r\n\r\n\/* ################# CoolCar ################ \r\n....\r\n....\r\n....\r\n*\/\r\n\r\n#endif<\/pre>\r\n\nExplanation of the header file<\/h4>\n\n
#ifndef COOL_CAR_LIB_H_ \r\n#define COOL_CAR_LIB_H_ \r\n.......\r\n\r\n#endif<\/pre>\r\n\n
#<\/code> are preprocessor directives. That is, they are not part of the actual code, but determine what is read as code. Only if COOL_CAR_LIB_H_<\/code> has not been defined yet, the code between #ifndef<\/code> (= if not defined) and #endif<\/code> is included. COOL_CAR_LIB_H_<\/code> would be defined then. This prevents the code from being read in twice. <\/p>\r\n#include <Arduino.h><\/code> embeds – not surprisingly – the Arduino library. What is surprising, however, is that<\/em> you have to include Arduino.h at all. If you write a simple sketch, Arduino.h will be included automatically even without this directive. This necessity results from the order in which the program parts are read. If your library is read before the Arduino library, the compiler will stop with an error message when it encounters an Arduino-specific function such as digitalWrite()<\/code> or Serial.print()<\/code>.<\/p>\r\nclass<\/code>. The content of the class declaration is enclosed in curly brackets. It ends with a semicolon. If the semicolon is missing, there are error messages, which unfortunately do not point directly to the cause.<\/p>\r\npublic:<\/code> are publicly accessible. You access them via the object name and the point operator. Everything after protected:<\/code> is available only to the class itself. That means, if you create a CoolCarBasic object with the name myCar, then the statement myCar.setSpeed(50)<\/code> is allowed. myCar.speed = 50<\/code>, on the other hand, would not be allowed. An alternative to protected<\/code> is private<\/code>. The difference is that private functions and variables cannot be accessed in inherited classes. <\/p>\r\nCoolCarBasic(uint8_t);<\/code>. This is the constructor, which we will discuss below.<\/p>\r\n(u)int<\/code>x<\/code><\/em>_t<\/code> . “int” stands for integer, “u” for unsigned and “x” for the size in bits. For example, on an Arduino, a uint16_t<\/code> corresponds to unsigned int<\/code>. However, there are MCUs, such as the ESP32, on which an integer is larger than 16 bits. Therefore, uint16_t<\/code> is a clearer definition. <\/p>\r\n\nCoolCarBasic – source file<\/h3>\n\n
#include <CoolCarLib.h>\r\n\r\n\/* ############### CoolCarBasic ############### *\/\r\n\r\n\/************ Constructor ************\/\r\n\r\nCoolCarBasic::CoolCarBasic(uint8_t mP){\r\n maxPassengers = mP;\r\n speed = 0;\r\n}\r\n\r\n\/********** Public Functions **********\/\r\n\r\nuint8_t CoolCarBasic::getMaxPassengers(){ \r\n return maxPassengers;\r\n}\r\n\r\nuint16_t CoolCarBasic::getSpeed(){ \r\n return speed;\r\n}\r\n\r\nvoid CoolCarBasic::setSpeed(uint16_t sp){ \r\n speed = sp;\r\n}\r\n\r\nvoid CoolCarBasic::hoot(){\r\n Serial.println(\"beep! beep! beep!\");\r\n}\r\n\r\n\/* ################# CoolCar ################ \r\n............\r\n*\/<\/pre>\r\n\nExplanation of the source file <\/h4>\n\n
::<\/code>. This character has the bulky name “scope resolution operator”. CoolCarBasic::xxx()<\/code> means that the function xxx() belongs to the CoolCarBasic class. How else should the compiler know which class to assign the function to!<\/p>\r\nCoolCarBasic::CoolCarBasic(uint8_t){...}<\/code>. The constructor is the function you use to create your objects. As a function, the constructor is special in that it has no return value. However, it is allowed to pass parameters to the constructor. In our example, the constructor gets the maximum number of passengers and assigns it to the maxPassengers private variable. In addition, speed<\/code> is set to the initial value 0. Typically, however, this is something you don’t put in the constructor, but in a init()<\/code> or begin()<\/code> function.<\/p>\r\ngetMaxPassengers()<\/code>. Since maxPassengers is a constant value, there is no setMaxPassengers()<\/code> function. This is different for speed<\/code>. Here we define a get and a set function.<\/p>\r\nhoot()<\/code> is a method that does not change any variable. When it is called, it will trigger a Serial.println()<\/code> instruction. Normally, I would not define the output medium in a class, but only return values – how they are output is decided by the user.<\/p>\r\n\nCoolCarBasic – Usage<\/h3>\n\n
cool_car_basic_test.ino – test sketch<\/h4>\n\n
#include <CoolCarBasic.h>\r\n\r\nCoolCarBasic myCar = CoolCarBasic(7); \/\/ 7 passengers is maximum\r\n\r\nvoid setup() {\r\n Serial.begin(9600);\r\n \/\/delay(200); \/\/ uncomment for ESP32 \/ ESP8266 Boards\r\n \r\n byte passengerLimit = myCar.getMaxPassengers();\r\n unsigned int currentSpeed = myCar.getSpeed();\r\n \r\n Serial.print(\"Max. number of passengers: \");\r\n Serial.println(passengerLimit);\r\n \r\n Serial.print(\"CurrentSpeed [km\/h]: \");\r\n Serial.println(currentSpeed);\r\n \r\n myCar.setSpeed(50);\r\n currentSpeed = myCar.getSpeed();\r\n Serial.print(\"CurrentSpeed [km\/h]: \");\r\n Serial.println(currentSpeed);\r\n \r\n myCar.hoot(); \r\n}\r\n\r\nvoid loop() {}<\/pre>\r\n\nmyCar<\/code>. You can also say: An instance of the CoolCarBasic class is created. In doing so, you pass the value for maxPassengers<\/code> to the object.<\/p>\r\n
![\"Output](\"https:\/\/wolles-elektronikkiste.de\/wp-content\/uploads\/2022\/09\/output_cool_car_basic.png\")
<\/a>![\"Output](\"https:\/\/wolles-elektronikkiste.de\/wp-content\/uploads\/2022\/10\/output_cool_car_example.png\")
<\/a>