My first Raspberry Pi tutorial in C. Christophe Delord

Transcription

1 My first Raspberry Pi tutorial in C Christophe Delord Sunday 22 October 2017

2 2

3 Contents 1 Availability COPYRIGHT This book is now freely available About this book 9 3 Introduction Licenses Source code wiringpi Hardware Software Generic definitions wiringpi library State machines Clock state machine interface Clock state machine implementation Clock example main loop Compilation on a PC Execution on a PC Compilation on a Raspberry Pi Execution on a Raspberry Pi What s next

4 4 CONTENTS 4 Blinking LED Hardware Software Blinking LED state machine interface Blinking LED state machine implementation Blinking LED example main loop Compilation on a PC Execution on a PC Compilation on a Raspberry Pi Execution on a Raspberry Pi What s next PWM output (music generator) Hardware Software Music state machine interface Music state machine implementation Music generator example main loop Compilation on a PC Execution on a PC Compilation on a Raspberry Pi Execution on a Raspberry Pi What s next Light sensor input Hardware Software Light sensor state machine interface Light sensor state machine interface Music state machine Main loop Compilation on a PC

5 CONTENTS Execution on a PC Compilation on a Raspberry Pi Execution on a Raspberry Pi What s next A Appendices 63 A.1 Generic definitions A.1.1 demo.h A.1.2 demo A.2 wiringpi stub A.2.1 wiringpi.h A.2.2 wiringpi.c A.3 STATUS state machine A.3.1 status.h A.3.2 status.c A.4 Clock state machine A.4.1 clock.h A.4.2 clock.c A.5 Blinking LED state machine A.5.1 blink.h A.5.2 blink.c A.6 Music generator state machine A.6.1 music.h A.6.2 music.c A.7 Light sensor state machine A.7.1 light.h A.7.2 light.c A.8 ex1-clock.c: basic state machine demo A.9 ex2-blinkingled.c: blinking LED demo A.10 ex3-pwmoutput.c: music generator demo A.11 ex4-lightsensor.c: light sensor demo

6 6 CONTENTS

7 Chapter 1 Availability 1.1 COPYRIGHT This book is copyrighted by Christophe Delord (CDSoft.fr/essays). available at lulu.com: It is PDF version (ISBN ): My first Raspberry Pi tutorial in C Printed version (ISBN ): My first Raspberry Pi tutorial in C 1.2 This book is now freely available This book has been initially published on lulu.com. It is now fully and freely available on HTML version: PDF version: You can download and read this tutorial for free. If you like it, please consider making some donation here ( or buying it on lulu.com to support my work. 7

8 8 CHAPTER 1. AVAILABILITY

9 Chapter 2 About this book This book has been written using some free tools and formats: PP: a general text preprocessor written in Haskell and designed with Pandoc and Markdown in mind. Pandoc: a universal document converter (to produce HTML and PDF versions of the book). Inkscape GIMP GNU Make gcc Debian Raspbian If you are interested by the source code of the book, please contact me at The source code of this book is also a nice example of literate programming with PP: the same source files are used to produce the documentation (in PDF and HTML formats) as well as the source code of the examples that can be compiled for both the Linux simulated platform and the actual Raspberry Pi device. 9

10 10 CHAPTER 2. ABOUT THIS BOOK

11 Chapter 3 Introduction The aim of this tutorial is simply to learn how to program Raspberry Pi 3 GPIOs in C as well as to show how to write clean and efficient C code for the Raspberry Pi. The circuit we are going to realize is quite simple. It provides three functions: 1. The unavoidable blinking LED (aka Raspberry Pi Hello World! project). The purpose of the LED is to indicate that the demo is running. It uses a single output GPIO. 2. A speaker playing some horrible random music. The speaker is driven by a PWM output GPIO. A second LED (called music LED ) is turned on when the frequency is rising and off when the frequency is decreasing. 3. A light sensor is used to switch on and off the music. The music stops when the light level is low to let people sleep! 11

12 12 CHAPTER 3. INTRODUCTION Figure 3.1: Final project The software is based on state machines and written in C. The goal is to provide micro controller low level like software instead of using higher level languages such as Python. C gives better performances and real time characteristics. The reader is assumed to have some basic knowledge on GNU/Linux, bash, gcc Licenses Source code The source code available in this tutorial is copyrighted under the GNU General Public License. Copyright (C) 2016 Christophe Delord This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published

13 3.2. HARDWARE 13 by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PUR- POSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see wiringpi This tutorial uses the wiringpi library. The source code of wiringpi can be found here: /* * wiringpi.h: * Arduino like Wiring library for the Raspberry Pi. * Copyright (c) Gordon Henderson *********************************************************************** * This file is part of wiringpi: * * * wiringpi is free software: you can redistribute it and/or modify * it under the terms of the GNU Lesser General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. * * wiringpi is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public License * along with wiringpi. If not, see < *********************************************************************** */ 3.2 Hardware This demo runs on a Raspberry Pi 3 but I guess it can run on a Raspberry Pi 2 as well. We will also simulate the hardware to debug and run the software on a regular GNU/Linux PC before running it on a real Raspberry Pi.

14 14 CHAPTER 3. INTRODUCTION 3.3 Software This dummy example shows the structure of a classical state machine for embedded softwares. This implementation has a taste of object oriented programmation but with static allocation only (no dynamic object allocation, no polymorphism or inheritance à la C++). All (hard) real time applications must have a clean and deterministic time model. In this tutorial we will define a simple model based on cooperative multitasking. Contrary to preemptive multitasking, cooperative tasks run for some period of time and shall give control back to the sequencer deterministically. Tasks are not arbitrarily interrupted by the sequencer. This model makes it easier to distribute time to tasks and control shared global variables. Each task is a state machine. The state machines are made of a state (a set of values that represent the current state) and a set of functions (or methods) that transform the state. During each time slice, the sequencer calls every state machines once.

15 3.3. SOFTWARE 15 Figure 3.2: Generic software architecture - cooperative multitasking

16 16 CHAPTER 3. INTRODUCTION Generic definitions First we need some generic definitions and tools demo.h /* file: demo.h */ /* */ /* Some global definitions for theses tutorials. */ #ifndef DEMO #define DEMO #include <stdio.h> #include <stdlib.h> /* wiringpi library used to access Raspberry Pi GPIOs */ #include "wiringpi.h" /* Time units (all times are internally in µs) */ #define US * 1 #define MS * 1000 US #define S * 1000 MS /* The base cycle is the period of the sequencer. */ #define CYCLE (10 MS) /* Routines to be defined by the application. */ /* init is called once to initialise the state machines */ extern void init(); /* isalive is called periodically to check if the state machines */ /* are still alive */ extern int isalive(); /* run is called periodically to run one step of every state machines */ extern void run(); /* cleanup is called once when the system is not alive */ extern void cleanup(); /* interrupted is called when an interrupt signal is received. */

17 3.3. SOFTWARE 17 /* interrupt signals are SIGINT, SIGQUIT, SIGABRT and SIGTERM. */ extern void interrupted(); #endif demo.c /* file: demo.h */ /* */ /* Sequencer for the state machines of theses tutorials. */ #include <signal.h> #include <string.h> #include <sys/time.h> #include <unistd.h> #include "demo.h" /* signal_handler is called when a signal is received. It calls */ /* the `interrupted` function defined by the application (which */ /* in turns calls the "interrupted" functions of the state */ /* machines. */ static void signal_handler(int sig) printf("\nsignal received: %s\n", strsignal(sig)); interrupted(); /* timer_handler is called periodically. The period is CYCLE. */ /* The main loop is driven by a timer which is more accurate than */ /* a simple wait. */ /* timer_handler calls: */ /* - `run` to execute one step of every state machines */ /* - `isalive` to check that the system is still alive */ /* - `cleanup` and exits when the system is not alive anymore */ static void timer_handler(int signum) /* run one step */ run(); /* check if the program is still alive */ if (!isalive())

18 18 CHAPTER 3. INTRODUCTION /* stop the program when it is not alive anymore */ cleanup(); exit(exit_success); /* wait for the next cycle */ /* The main function initializes the state machines, */ /* starts a periodic timer to run the state machines */ /* and undefinitely waits for the system to exit. */ int main(void) /* Initialisation of the wiringpi library to access GPIOs */ wiringpisetup(); /* Interruption signal handler */ signal(sigint, signal_handler); signal(sigquit, signal_handler); signal(sigabrt, signal_handler); signal(sigterm, signal_handler); /* Some information about the hardware */ int model, rev, mem, maker, overvolted; piboardid(&model, &rev, &mem, &maker, &overvolted); printf("model = %s\n", pimodelnames[model]); printf("rev = %s\n", pirevisionnames[rev]); printf("mem = %d Mb\n", mem); printf("maker = %s\n", pimakernames[maker]); printf("over volted = %s\n", overvolted? "yes" : "no"); printf("\n"); /* state machine initializations */ init(); /* Install timer_handler as the signal handler for SIGALRM. */ struct sigaction sa; memset (&sa, 0, sizeof (sa)); sa.sa_handler = &timer_handler; sigaction(sigalrm, &sa, NULL); /* Configure the timer to expire after CYCLE µs... */ struct itimerval itimer; itimer.it_value.tv_sec = 0; itimer.it_value.tv_usec = CYCLE; /*... and every CYCLE µs after that. */

19 3.3. SOFTWARE 19 itimer.it_interval.tv_sec = 0; itimer.it_interval.tv_usec = CYCLE; /* Start the timer. */ setitimer (ITIMER_REAL, &itimer, NULL); /* Main loop */ while (1) /* This loop could be used as a background loop */ sleep(1000); return EXIT_SUCCESS; wiringpi library WiringPi is a C library that brings the simplicity of Arduino to the powerful world of Raspberry Pi. To simulate the Raspberry Pi on a GNU/Linux PC, we need to stub this library. I/O functions on a PC will be simulated. Of course on a Raspberry Pi, the real library will be used. The source code of the wiringpi stub is in the appendix wiringpi stub State machines Instead of abusing Linux facilities, we will design software with state machines. This is a clean and deterministic way to describe the behaviour of several tasks (some kind of processes). They are simple and predictable, which is not always the case with general OS. We don t need here the richness of GNU/Linux. We are going to use a cooperative multitasking model instead of a preemptive model. A state machine is a set of functions (methods) that initialize and manage the state of the state machine by interacting with other machines or with the environment. A state is described by a structured type. Each instance of a state machine has its own state in a global variable.

20 20 CHAPTER 3. INTRODUCTION Clock state machine interface This example defines a clock that just counts ticks. Each clock can have its own period. /* file: clock.h */ /* */ /* Clock state machine. Clocks can count execution cycles */ /* and generate rising edges. */ /* A clock is defined by a period and an offset (date of the */ /* first rising edge) in µs. */ #ifndef CLOCK_STATE_MACHINE #define CLOCK_STATE_MACHINE #include "demo.h" /* Clock state */ typedef struct int period_us; /* period of the clock in µs */ int offset_us; /* offset of the clock in µs */ int t; /* time in µs since the start of the period */ int time_us; /* current time in µs */ int ticks; /* number of cycles since the clock started */ CLOCK_t; /* Clock initialisation method */ void CLOCK_init(CLOCK_t *c, int period_us, int offset_us); /* Clock main loop method */ void CLOCK_run(CLOCK_t *c); double CLOCK_time(CLOCK_t *c); /* current time in seconds */ int CLOCK_time_ms(CLOCK_t *c); /* current time in ms */ int CLOCK_time_us(CLOCK_t *c); /* current time in µs */ int CLOCK_edge(CLOCK_t *c); /* is the current cycle a rising edge */ int CLOCK_ticks(CLOCK_t *c); /* number of cycles since the beginning */ double CLOCK_ratio(CLOCK_t *c); /* position within the current cycle */ #endif

21 3.3. SOFTWARE Clock state machine implementation /* file: clock.c */ /* */ /* Clock state machine: implementation (see clock.h) */ #include "clock.h" void CLOCK_init(CLOCK_t *c, int period_us, int offset_us) c->period_us = period_us; c->offset_us = offset_us; c->t = offset_us > 0? period_us - offset_us : 0; c->time_us = 0; c->ticks = 0; void CLOCK_run(CLOCK_t *c) c->ticks++; c->time_us += CYCLE; c->t += CYCLE; if (c->t >= c->period_us) c->t = 0; double CLOCK_time(CLOCK_t *c) return c->time_us/1e6; int CLOCK_time_ms(CLOCK_t *c) return c->time_us/1000; int CLOCK_time_us(CLOCK_t *c) return c->time_us; int CLOCK_edge(CLOCK_t *c) return c->t == 0; int CLOCK_ticks(CLOCK_t *c) return c->ticks; double CLOCK_ratio(CLOCK_t *c) return ((double)c->t) / c->period_us; Clock example main loop The program is made of two main functions: init initializes all the state machines. run runs all the state machines in one cycle

22 22 CHAPTER 3. INTRODUCTION The main function calls init and starts a timer to periodically call run. The function isalive shall return FALSE to stop the execution. In this example, we instantiate two clocks. The first one has a period of 500 ms and the first edge is shifted by 250 ms. The second one has a period of 1 s and no offset. Figure 3.3: Clock example timing /* file: ex1-clock.c */ /* */ /* Clock usage example. */ #include "demo.h" #include "clock.h" /* Clocks are statically allocated "objects" */ CLOCK_t c1, c2; void init() /* Initialisation of the state machines */ CLOCK_init(&c1, 500 MS, 250 MS); CLOCK_init(&c2, 1 S, 0 MS); int isalive() /* Let's run for 5 seconds... */ return CLOCK_time(&c1) < 5.0;

23 3.4. COMPILATION ON A PC 23 void run() /* Some outputs to see that the clocks are running */ int e1 = CLOCK_edge(&c1); int e2 = CLOCK_edge(&c2); if (e1 e2) /* print "CLOCK" in upper case on rising edges */ printf("[%s 1: %7.3f / %9d] [%s 2: %7.3f / %9d]\n", e1? "CLOCK" : "clock", CLOCK_time(&c1), CLOCK_ticks(&c1), e2? "CLOCK" : "clock", CLOCK_time(&c2), CLOCK_ticks(&c2)); /* Execute one step */ CLOCK_run(&c1); CLOCK_run(&c2); void interrupted() void cleanup() 3.4 Compilation on a PC First we are going to test this dummy example on a regular PC. The program can be compiled on GNU/Linux (maybe on Cygwin as well) with gcc using the stubbed wiringpi library: gcc -Wall -Werror \ -o ex1-clock \ ex1-clock.c demo.c clock.c wiringpi.c Some quick explanations about this command line: -Wall reports all warning messages. This is a good practice to fix all warnings. Warnings are sometimes real bugs. Fixing them as early as possible is the best way not to lose time tracking some tricky bugs when testing a software.

24 24 CHAPTER 3. INTRODUCTION -Werror turns warning messages into errors. Warnings will make the compilation fail. Just to be sure not to forget some warnings! -o ex1-clock is the name of the executable. ex1-clock.c is the source of the example. clock.c is the source of the clock state machine. wiringpi.c is the source of the stubbed wiringpi library. demo.c is the source of the sequencer. It also contains the main function. 3.5 Execution on a PC The executable can be run from the command line. ex1-clock will run for 5 seconds, printing a line when a rising edge is detected on one of the clocks (c1 or c2). $./ex1-clock model = Stubbed wiringpi rev = n/a mem = 0 Mb maker = CDSoft.fr over volted = no [clock 1: / 0] [CLOCK 2: / 0] [CLOCK 1: / 25] [clock 2: / 25] [CLOCK 1: / 75] [clock 2: / 75] [clock 1: / 100] [CLOCK 2: / 100] [CLOCK 1: / 125] [clock 2: / 125] [CLOCK 1: / 175] [clock 2: / 175] [clock 1: / 200] [CLOCK 2: / 200] [CLOCK 1: / 225] [clock 2: / 225] [CLOCK 1: / 275] [clock 2: / 275] [clock 1: / 300] [CLOCK 2: / 300] [CLOCK 1: / 325] [clock 2: / 325] [CLOCK 1: / 375] [clock 2: / 375] [clock 1: / 400] [CLOCK 2: / 400] [CLOCK 1: / 425] [clock 2: / 425] [CLOCK 1: / 475] [clock 2: / 475] 3.6 Compilation on a Raspberry Pi A similar command line can be used on a Raspberry Pi (I m using Raspbian). gcc -Wall -Werror \

25 3.7. EXECUTION ON A RASPBERRY PI 25 -o ex1-clock \ ex1-clock.c demo.c clock.c \ -lwiringpi The main difference is that we use the real wiringpi library (-lwiringpi) instead of the stub. 3.7 Execution on a Raspberry Pi This example is not specific to the Raspberry Pi as it doesn t uses any Raspberry Pi input/output. Except from the hardware detection, the program should print the same clock timings. The program uses the real wiringpi library so it requires root privileges. $ sudo./ex1-clock model = Model 2 rev = 1.1 mem = 1024 Mb maker = Sony over volted = yes [clock 1: / 0] [CLOCK 2: / 0] [CLOCK 1: / 25] [clock 2: / 25] [CLOCK 1: / 75] [clock 2: / 75] [clock 1: / 100] [CLOCK 2: / 100] [CLOCK 1: / 125] [clock 2: / 125] [CLOCK 1: / 175] [clock 2: / 175] [clock 1: / 200] [CLOCK 2: / 200] [CLOCK 1: / 225] [clock 2: / 225] [CLOCK 1: / 275] [clock 2: / 275] [clock 1: / 300] [CLOCK 2: / 300] [CLOCK 1: / 325] [clock 2: / 325] [CLOCK 1: / 375] [clock 2: / 375] [clock 1: / 400] [CLOCK 2: / 400] [CLOCK 1: / 425] [clock 2: / 425] [CLOCK 1: / 475] [clock 2: / 475] 3.8 What s next The following chapters will use the same kind of software architecture. Of course we will also see how to use the Inputs/Outputs of the Raspberry Pi to interact with the real world.

26 26 CHAPTER 3. INTRODUCTION Printing messages on a terminal may be some kind of fun... But blinking a LED is way more amusing!

27 Chapter 4 Blinking LED This chapter shows: how to connect a LED to the Raspberry Pi how to write a software in C to turn the LED on and off 4.1 Hardware The electrical wiring for this project is quite simple. Here is what you need: a Raspberry Pi (I have used a Raspberry Pi 3 model) with its power supply a LED a 330 Ohm resistor a breadboard and some wires The LED and the resistor are connected to an output GPIO. 27

28 28 CHAPTER 4. BLINKING LED Figure 4.1: Blinking LED

29 4.1. HARDWARE 29 Figure 4.2: Detailed wiring (blinking LED)

30 30 CHAPTER 4. BLINKING LED 4.2 Software Blinking LED state machine interface For this example we need a state machine that implements a blinking LED. The state machine has two states (the LED can be switched on or off). A clock is embedded to the LED state machine to periodically switch the LED state. To debug this state machine on a regular PC, we use the STATUS state machine that prints some information. This state machine will be used in all the examples in this book. Its source code is in the appendix STATUS state machine Figure 4.3: Blinking LED timing /* file: blink.h */ /* */ /* Blinking LED state machine. The LED is periodically switched */ /* on and off. */ #ifndef BLINK_STATE_MACHINE #define BLINK_STATE_MACHINE #include "demo.h" #include "clock.h" /* Blinking LED state */ typedef struct int pin; /* pin on which the LED is connected */ CLOCK_t clock; /* internal clock of the blinking LED */ enum BLINK_LED_OFF, BLINK_LED_ON, state; /* current LED state */

31 4.2. SOFTWARE 31 int killed; /* kill flag to stop the led */ BLINK_t; /* Blinking LED initialisation method */ void BLINK_init(BLINK_t *q, int pin, int period_in_us); /* The blinking period can be modified */ void BLINK_reschedule(BLINK_t *q, int period_in_us); /* Blinking LED main loop method */ void BLINK_run(BLINK_t *q); /* This method is called to kill the state machine. */ void BLINK_kill(BLINK_t *q); /* The state machine is alive until it is killed. */ int BLINK_isalive(BLINK_t *q); /* Cleanup function (to leave the LED switched off at the end) */ void BLINK_cleanup(BLINK_t *q); #endif Blinking LED state machine implementation /* file: blink.c */ /* */ /* Blinking LED state machine: implementation (see blink.h) */ #include "blink.h" #include "status.h" /* Blinking LED initialisation method */ void BLINK_init(BLINK_t *q, int pin, int period_in_us) q->killed = FALSE; q->pin = pin; CLOCK_init(&q->clock, period_in_us, 0); q->state = BLINK_LED_OFF; pinmode(q->pin, OUTPUT);

32 32 CHAPTER 4. BLINKING LED /* The blinking period can be modified */ void BLINK_reschedule(BLINK_t *q, int period_in_us) q->clock.period_us = period_in_us; /* Blinking LED main loop method */ void BLINK_run(BLINK_t *q) switch (q->state) /* if the LED is off during the first half of the clock */ /* period it must be switched on. */ case BLINK_LED_OFF: if (CLOCK_ratio(&q->clock) < 0.5) q->state = BLINK_LED_ON; digitalwrite(q->pin, HIGH); STATUS_act(HIGH); break; /* if the LED is on during the second half of the clock */ /* period it must be switched off. */ case BLINK_LED_ON: if (CLOCK_ratio(&q->clock) >= 0.5) q->state = BLINK_LED_OFF; digitalwrite(q->pin, LOW); STATUS_act(LOW); break; /* the clock shall also run. */ CLOCK_run(&q->clock); /* This method is called to kill the state machine. */ void BLINK_kill(BLINK_t *q) q->killed = TRUE; /* The state machine is alive until it is killed. */ int BLINK_isalive(BLINK_t *q)

33 4.2. SOFTWARE 33 return!q->killed; /* Cleanup function (to leave the LED switched off at the end) */ void BLINK_cleanup(BLINK_t *q) digitalwrite(q->pin, LOW); Blinking LED example main loop The main program is very similar to the previous example ex2-blinkingled.c /* file: ex2-blinkingled.c */ /* */ /* The famous Raspberry Pi "hello world": Blinking LED example. */ #include "demo.h" #include "status.h" #include "blink.h" #define ACTIVITY_LED 7 /* BCM GPIO 4 */ #define ACTIVITY_PERIOD (1 S) /* The activity LED that eternally blinks to show that the */ /* software is running. */ BLINK_t activity; void init() /* Initialisation of the state machines */ BLINK_init(&activity, ACTIVITY_LED, ACTIVITY_PERIOD); STATUS_init(); int isalive()

34 34 CHAPTER 4. BLINKING LED /* Continue while no interruption signal is received. */ return BLINK_isalive(&activity); void run() BLINK_run(&activity); STATUS_run(); void cleanup() BLINK_cleanup(&activity); STATUS_cleanup(); void interrupted() /* Interruption signal received => stop the demo */ BLINK_kill(&activity); 4.3 Compilation on a PC First we are going to test this demo on a regular PC. The program can be compiled on GNU/Linux with gcc using the stubbed wiringpi library: gcc -Wall -Werror \ -o ex2-blinkingled \ ex2-blinkingled.c demo.c clock.c blink.c wiringpi.c Some quick explanations about this command line: -Wall, -Werror Always the same story. The sooner the errors and warnings are fixed, the better. -o ex2-blinkingled is the name of the executable. ex2-blinkingled.c is the source of the example. clock.c is the source of the clock state machine. It is required by blink.c blink.c is the source of the blinking LED state machine. wiringpi.c is the source of the stubbed wiringpi library. demo.c is the source of the sequencer. It also contains the main function.

35 4.4. EXECUTION ON A PC Execution on a PC The executable can be run from the command line. ex2-blinkingled will run until you kill it (with Ctrl-C for instance). $./ex2-blinkingled model = Stubbed wiringpi rev = n/a mem = 0 Mb maker = CDSoft.fr over volted = no [ACT: HIGH] Signal received: Interrupt 4.5 Compilation on a Raspberry Pi A similar command line can be used on a Raspberry Pi (I m using Raspbian). gcc -Wall -Werror \ -o ex2-blinkingled \ ex2-blinkingled.c demo.c clock.c blink.c \ -lwiringpi The main difference is that we use the real wiringpi library (-lwiringpi) instead of the stub. 4.6 Execution on a Raspberry Pi This example uses a GPIO connected to a LED. While running it you should see the LED blinking once per second. The program uses the real wiringpi library so it requires root privileges. $ sudo./ex2-blinkingled model = Model 2 rev = 1.1 mem = 1024 Mb maker = Sony over volted = yes [ACT: HIGH] Signal received: Interrupt

36 36 CHAPTER 4. BLINKING LED Figure 4.4: Blinking LED 4.7 What s next Now we have a blinking LED showing that the system is running... But it still actually does nothing amazing. The next chapter will add a state machine that composes some nice music (for some definition of nice music). The blinking LED of this chapter will still continue blinking in parallel.

37 Chapter 5 PWM output (music generator) This chapter shows: how to connect a PWM (Pulse Width Modulation) output to a speaker to generate some music how to write a software in C to generate random music 5.1 Hardware The electrical wiring for this project is quite simple. It reuses the blinking LED example. Here is what you need to add to the previous example: an additional LED an additional 330 Ohm resistor a potentiometer a speaker (e.g. PCB Mount Mini Speaker #1898 from Adafruit) The LEDs and resistors are connected to output GPIOs. The speaker is connected to an output PWM GPIO. The potentiometer is used to regulate the volume. The additional LED will be used to kind of visualize the sounds that are being produced. It s turned on when the PWM output frequency is rising. 37

38 38 CHAPTER 5. PWM OUTPUT (MUSIC GENERATOR) Figure 5.1: Blinking LED + PWM output

39 5.1. HARDWARE 39 Figure 5.2: Detailed wiring (blinking LED)

40 40 CHAPTER 5. PWM OUTPUT (MUSIC GENERATOR) 5.2 Software Music state machine interface For this example we need a state machine that generates music. The state machine has several states (play, stop, fade in/out transitions,... ). The music is generated by constantly increasing or decreasing the current frequency (f) until a target frequency (f2) is reached. Then a new frequency is randomly chosen between 110 Hz and 880 Hz. Figure 5.3: Music generator state machine The source code contains some code that will be used in the next chapter to start and stop the music according to a light sensor. This code in not used in this chapter.

41 5.2. SOFTWARE 41 The symbol LIGHTSENSOR must not be defined for the C preprocessor right now. /* file: music.h */ /* */ /* Music state machine. The music is generated on a PWM output. */ #ifndef MUSIC_STATE_MACHINE #define MUSIC_STATE_MACHINE #include "demo.h" #ifdef LIGHTSENSOR #include "light.h" #endif /* Music state */ /* Music generation mode */ typedef enum STOPPED, PLAY, FADEOUT, NIGHT, FADEIN musicmode_t; /* Frequency range used by the random generator */ #define FMIN 110 /* Hz */ #define FMAX 880 /* Hz */ /* Full state machine state */ typedef struct int ticks; /* number of clock ticks */ int fade_slowdown; /* slowdown in fade out/in mode */ int f; /* current frequency */ int f2; /* target frequency */ musicmode_t mode; /* music generation mode */ int led; /* music LED pin number */ int pwm; /* PWM GPIO pin number */ int killed; /* kill flag to stop the music */ #ifdef LIGHTSENSOR LightSensor_t *sensor; /* light sensor state machine */ #endif MUSIC_t; /* Initialisation method */ #ifdef LIGHTSENSOR void MUSIC_init(MUSIC_t *q, int led, int pwm, int fade_slowdown, LightSensor_t *sensor); #else void MUSIC_init(MUSIC_t *q, int led, int pwm, int fade_slowdown);

42 42 CHAPTER 5. PWM OUTPUT (MUSIC GENERATOR) #endif /* The music generator is alive until it is killed. */ int MUSIC_isalive(MUSIC_t *q); /* This metod changes the current music generation mode. */ void MUSIC_mode(MUSIC_t *q, musicmode_t mode); /* This methods kills the music state machine. */ void MUSIC_kill(MUSIC_t *q); /* Computes and eventually plays a different tone at each cycle. */ void MUSIC_run(MUSIC_t *q); /* Stops the music. */ void MUSIC_cleanup(MUSIC_t *q); #endif Music state machine implementation /* file: music.c */ /* */ /* Music state machine: implementation (see music.h) */ #include "music.h" #include "status.h" /* Initialisation method */ #ifdef LIGHTSENSOR void MUSIC_init(MUSIC_t *q, int led, int pwm, int fade_slowdown, LightSensor_t *sensor) #else void MUSIC_init(MUSIC_t *q, int led, int pwm, int fade_slowdown) #endif q->ticks = 0; q->fade_slowdown = fade_slowdown; q->f = 0; q->f2 = 0; q->mode = PLAY; q->led = led;

43 5.2. SOFTWARE 43 q->pwm = pwm; q->killed = FALSE; pinmode(q->led, OUTPUT); pinmode(q->pwm, PWM_OUTPUT); pwmsetmode(pwm_mode_ms); #ifdef LIGHTSENSOR q->sensor = sensor; #endif /* The music generator is alive until it is killed. */ int MUSIC_isalive(MUSIC_t *q) return q->mode!= STOPPED; /* This metod changes the current music generation mode. */ void MUSIC_mode(MUSIC_t *q, musicmode_t mode) q->mode = mode; /* This methods kills the music state machine. */ void MUSIC_kill(MUSIC_t *q) MUSIC_mode(q, FADEOUT); q->killed = TRUE; digitalwrite(q->led, LOW); /* Computes and eventually plays a different tone at each cycle. */ void MUSIC_run(MUSIC_t *q) switch (q->mode) /* Play mode: constantly updates and plays f */ /* until f == f2. */ /* Then choose a new target frequency. */ /* The music may be stopped (Fadeout mode) */ /* when the light is switched off. */ case PLAY: if (q->f!= q->f2) /* continue playing towards the same frequency */ if (q->f < q->f2) q->f++;

44 44 CHAPTER 5. PWM OUTPUT (MUSIC GENERATOR) if (q->f > q->f2) q->f--; else /* find a new tone */ q->f2 = FMIN + random()%(fmax-fmin); digitalwrite(q->led, q->f2 > q->f? HIGH : LOW); #ifdef LIGHTSENSOR if (!LIGHTSENSOR_value(q->sensor)) q->mode = FADEOUT; #endif break; /* Fadeout mode: constantly decreases and plays f */ /* until f == 0. */ /* Then stops the music generation. */ /* The music may be restarted in Fadein */ /* mode if the light is switched on. */ case FADEOUT: if (q->f > 0 && q->ticks%q->fade_slowdown == 0) q->f--; if (q->f <= 0) q->mode = q->killed? STOPPED : NIGHT; digitalwrite(q->led, LOW); #ifdef LIGHTSENSOR if (!q->killed && LIGHTSENSOR_value(q->sensor)) q->mode = FADEIN; #endif break; /* Fadein mode: constantly increases and plays f */ /* while f < f2. */ /* Then starts normal Play mode. */ /* The music may be stopped in Fadeout */ /* mode if the light is switched off. */ case FADEIN: if (q->f < q->f2 && q->ticks%q->fade_slowdown == 0) q->f++; if (q->f >= q->f2) q->mode = PLAY; digitalwrite(q->led, HIGH); #ifdef LIGHTSENSOR if (!LIGHTSENSOR_value(q->sensor)) q->mode = FADEOUT; #endif break; /* Night mode: plays nothing */ /* The music may be restarted in Fadein */ /* mode if the light is switched on. */ case NIGHT: #ifdef LIGHTSENSOR

45 5.2. SOFTWARE 45 if (!q->killed && LIGHTSENSOR_value(q->sensor)) q->mode = FADEIN; #endif break; /* Stop mode: plays nothing */ /* and waits for the sequencer to exit. */ case STOPPED: q->f = 0; break; /* Play the current tone */ pwmtonewrite(q->pwm, q->f); STATUS_music(q->mode, q->f, q->f2); q->ticks++; /* Stops the music. */ void MUSIC_cleanup(MUSIC_t *q) pwmtonewrite(q->pwm, 0); digitalwrite(q->led, LOW); Music generator example main loop The main program is very similar to the previous examples ex3-pwmoutput.c /* file: ex3-pwmoutput.c */ /* */ /* Unpleasant random music generator. */ #include "demo.h" #include "status.h" #include "blink.h"

46 46 CHAPTER 5. PWM OUTPUT (MUSIC GENERATOR) #include "music.h" #define ACTIVITY_LED 7 /* BCM GPIO 4 */ #define MUSIC_LED 0 /* BCM GPIO 0 */ #define MUSIC_PWM 1 /* BCM GPIO 18 */ #define ACTIVITY_PERIOD (1 S) #define FADE_SLOWDOWN 4 /* The activity LED that eternally blinks to show that the */ /* software is running. */ BLINK_t activity; /* The music state machine that generates random music according */ /* to its generation mode. */ MUSIC_t music; void init() /* Initialisation of the state machines */ BLINK_init(&activity, ACTIVITY_LED, ACTIVITY_PERIOD); MUSIC_init(&music, MUSIC_LED, MUSIC_PWM, FADE_SLOWDOWN); STATUS_init(); int isalive() return BLINK_isalive(&activity) && MUSIC_isalive(&music); void run() BLINK_run(&activity); MUSIC_run(&music); STATUS_run(); void cleanup() BLINK_cleanup(&activity); MUSIC_cleanup(&music); STATUS_cleanup(); void interrupted()

47 5.3. COMPILATION ON A PC 47 /* Makes the LED blink faster while the program is stopping. */ BLINK_reschedule(&activity, ACTIVITY_PERIOD/4); /* Also tells the music state machine to stop the music. */ MUSIC_kill(&music); 5.3 Compilation on a PC First we are going to test this demo on a regular PC. The program can be compiled on GNU/Linux with gcc using the stubbed wiringpi library: gcc -Wall -Werror \ -o ex3-pwmoutput \ ex3-pwmoutput.c demo.c clock.c blink.c music.c wiringpi.c Some quick explanations about this command line: -Wall, -Werror Always the same story. The sooner the errors and warnings are fixed, the better. -o ex3-pwmoutput is the name of the executable. ex3-pwmoutput.c is the source of the example. clock.c is the source of the clock state machine. It is required by blink.c blink.c is the source of the blinking LED state machine. music.c is the source of the music generator state machine. wiringpi.c is the source of the stubbed wiringpi library. demo.c is the source of the sequencer. It also contains the main function. 5.4 Execution on a PC The executable can be run from the command line. ex3-pwmoutput will run until you kill it (with Ctrl-C for instance). $./ex3-pwmoutput model = Stubbed wiringpi rev = n/a mem = 0 Mb maker = CDSoft.fr over volted = no [ACT: HIGH] [MUSIC: PLAY / 565 / 839] Of course no sound is played on Linux using the wiringpi stub.

48 48 CHAPTER 5. PWM OUTPUT (MUSIC GENERATOR) 5.5 Compilation on a Raspberry Pi A similar command line can be used on a Raspberry Pi (I m using Raspbian). gcc -Wall -Werror \ -o ex3-pwmoutput \ ex3-pwmoutput.c demo.c clock.c blink.c music.c \ -lwiringpi The main difference is that we use the real wiringpi library (-lwiringpi) instead of the stub. 5.6 Execution on a Raspberry Pi This example uses a GPIO connected to a LED to show if the frequency is rising or falling and another GPIO connected to a speaker. While running it you should see the activity LED blinking once per second, the music LED blinking according to the variation of the frequency and of course hear some unpleasant sound coming from the speaker. The program uses the real wiringpi library so it requires root privileges. $ sudo./ex3-pwmoutput model = Model 2 rev = 1.1 mem = 1024 Mb maker = Sony over volted = yes [ACT: HIGH] [MUSIC: PLAY / 565 / 839]

49 5.7. WHAT S NEXT 49 Figure 5.4: Blinking LED + Music 5.7 What s next Now we produce some sound... But we have no control. The next chapter will add a state machine that detects light and stops the music when the light is low.

50 50 CHAPTER 5. PWM OUTPUT (MUSIC GENERATOR)

51 Chapter 6 Light sensor input This chapter shows: how to connect a light sensor to a discrete input how to write a software in C to stop the music when the light is switched off 6.1 Hardware The electrical wiring for this project is quite simple. It reuses the music generator example. Here is what you need to add to the previous example: a light detector (e.g. ALSPT19 Light Sensor from Adafruit) The LEDs and resistors are connected to output GPIOs. The speaker is connected to an output PWM GPIO. The potentiometer is used to regulate the volume. The additional LED will be used to kind of visualize the sounds that are being produced. It s turned on when the PWM output frequency is rising. The light sensor is connected to an input GPIO. For this demo, the threshold can not be modified. 51

52 52 CHAPTER 6. LIGHT SENSOR INPUT Figure 6.1: Blinking LED + PWM output + Light sensor

53 6.1. HARDWARE 53 Figure 6.2: Detailed wiring (blinking LED)

54 54 CHAPTER 6. LIGHT SENSOR INPUT 6.2 Software Light sensor state machine interface For this example we need a state machine that reads and filters the light sensor values. It s important to filter the light sensor values since they can vary a lot when the light level is near to the sensor threshold. The light level must be stable before being used by the software. A value must be stable for a few cycles before being taken into account. Figure 6.3: Light sensor filtering timing /* file: light.h */ /* */ /* Light sensor state machine. It reads and filters the light */ /* sensor values. */ #ifndef LIGHT_STATE_MACHINE #define LIGHT_STATE_MACHINE #include "demo.h" /* Light state */ typedef struct int pin; /* GPIO pin number of the sensor */ int confirm; /* number of cycles the input is stable */ int value; /* current value acquired on the GPIO */ int confirmedvalue; /* value previously confirmed */ int confirmationperiod; /* number of confirmation cycles */ LightSensor_t; /* Light sensor initialisation */

55 6.2. SOFTWARE 55 void LIGHTSENSOR_init(LightSensor_t *q, int pin, int confirmation_in_us); /* Currently confirmed value */ int LIGHTSENSOR_value(LightSensor_t *q); /* Reads and filters the light sensor value. */ void LIGHTSENSOR_run(LightSensor_t *q); /* The light sensor is considered always alive. */ int LIGHTSENSOR_isalive(LightSensor_t *q); /* Stops the light sensor acquisition. */ void LIGHTSENSOR_cleanup(LightSensor_t *q); #endif Light sensor state machine interface /* file: light.c */ /* */ /* Light sensor state machine: implementation (see light.h) */ #include "light.h" #include "status.h" void LIGHTSENSOR_init(LightSensor_t *q, int pin, int confirmation_in_us) q->pin = pin; q->confirm = 0; q->value = 0; q->confirmationperiod = confirmation_in_us / CYCLE; pinmode(q->pin, INPUT); q->confirmedvalue = q->value = digitalread(q->pin); int LIGHTSENSOR_value(LightSensor_t *q) return q->confirmedvalue; void LIGHTSENSOR_run(LightSensor_t *q)

56 56 CHAPTER 6. LIGHT SENSOR INPUT int value = digitalread(q->pin); if (value == q->value) /* same value than the previous cycle */ q->confirm++; if (q->confirm >= q->confirmationperiod) /* same value for `q->confirmationperiod` cycles */ q->confirmedvalue = value; else /* value not stable => start a new confirmation phase */ q->value = value; q->confirm = 0; STATUS_light(q->value, q->confirmedvalue); int LIGHTSENSOR_isalive(LightSensor_t *q) return TRUE; void LIGHTSENSOR_cleanup(LightSensor_t *q) Music state machine The music state machine described in the previous example is compiled with the LIGHTSENSOR feature. This adds states and transitions to stop and restart the music when the light gets low or high.

57 6.2. SOFTWARE 57 Figure 6.4: Music generator state machine with light sensor Main loop The main program is very similar to the previous examples ex4-lightsensor.c /* file: ex4-lightsensor.c */ /* */ /* Unpleasant random music generator */ /* moderated with a light sensor */ #include "demo.h" #include "status.h"

58 58 CHAPTER 6. LIGHT SENSOR INPUT #include "blink.h" #include "music.h" #include "light.h" #define ACTIVITY_LED 7 /* BCM GPIO 4 */ #define MUSIC_LED 0 /* BCM GPIO 0 */ #define MUSIC_PWM 1 /* BCM GPIO 18 */ #define LIGHT_INPUT 2 /* BCM GPIO 27 */ #define ACTIVITY_PERIOD (1 S) #define LIGHT_CONFIRMATION (100 MS) #define FADE_SLOWDOWN 4 /* The activity LED that eternally blinks to show that */ /* the software is running. */ BLINK_t activity; /* The music state machine that generates random music according */ /* to its generation mode. */ MUSIC_t music; /* The light sensor confirmation state machines. */ LightSensor_t light; void init() /* Initialisation of the state machines */ BLINK_init(&activity, ACTIVITY_LED, ACTIVITY_PERIOD); LIGHTSENSOR_init(&light, LIGHT_INPUT, LIGHT_CONFIRMATION); MUSIC_init(&music, MUSIC_LED, MUSIC_PWM, FADE_SLOWDOWN, &light); STATUS_init(); int isalive() return BLINK_isalive(&activity) && MUSIC_isalive(&music) && LIGHTSENSOR_isalive(&light); void run() BLINK_run(&activity); LIGHTSENSOR_run(&light); MUSIC_run(&music); STATUS_run();

59 6.3. COMPILATION ON A PC 59 void cleanup() BLINK_cleanup(&activity); MUSIC_cleanup(&music); LIGHTSENSOR_cleanup(&light); STATUS_cleanup(); void interrupted() /* Makes the LED blink faster while the program is stopping. */ BLINK_reschedule(&activity, ACTIVITY_PERIOD/4); /* Also tells the music state machine to stop the music. */ MUSIC_kill(&music); 6.3 Compilation on a PC First we are going to test this demo on a regular PC. The program can be compiled on GNU/Linux with gcc using the stubbed wiringpi library: gcc -Wall -Werror \ -DLIGHTSENSOR \ -o ex4-lightsensor \ ex4-lightsensor.c demo.c clock.c blink.c music.c light.c wiringpi.c Some quick explanations about this command line: -Wall, -Werror Always the same story. The sooner the errors and warnings are fixed, the better. -DLIGHTSENSOR activates the light sensor usage in the music generator state machine. -o ex4-lightsensor is the name of the executable. ex4-lightsensor.c is the source of the example. clock.c is the source of the clock state machine. It is required by blink.c blink.c is the source of the blinking LED state machine. music.c is the source of the music generator state machine. light.c is the source of the light sensor state machine. wiringpi.c is the source of the stubbed wiringpi library. demo.c is the source of the sequencer. It also contains the main function.

60 60 CHAPTER 6. LIGHT SENSOR INPUT 6.4 Execution on a PC The executable can be run from the command line. ex4-lightsensor will run until you kill it (with Ctrl-C for instance). $./ex3-pwmoutput model = Stubbed wiringpi rev = n/a mem = 0 Mb maker = CDSoft.fr over volted = no [ACT: HIGH] [LIGHT: 1 / DAY ] [MUSIC: PLAY / 565 / 839] Of course no sound is played on Linux using the wiringpi stub. 6.5 Compilation on a Raspberry Pi A similar command line can be used on a Raspberry Pi (I m using Raspbian). gcc -Wall -Werror \ -DLIGHTSENSOR \ -o ex4-lightsensor \ ex4-lightsensor.c demo.c clock.c blink.c music.c light.c \ -lwiringpi The main difference is that we use the real wiringpi library (-lwiringpi) instead of the stub. 6.6 Execution on a Raspberry Pi This example uses a GPIO connected to a LED to show if the frequency is rising or falling and another GPIO connected to a speaker. The light sensor should detect the light level and the software will stop when the light is switched off. While running it you should see the activity LED blinking once per second, the music LED blinking according to the variation of the frequency and of course hear some unpleasant sound coming from the speaker. Switch the light of the room to stop the music! The program uses the real wiringpi library so it requires root privileges.

61 6.7. WHAT S NEXT 61 $ sudo./ex3-pwmoutput model = Model 2 rev = 1.1 mem = 1024 Mb maker = Sony over volted = yes [ACT: HIGH] [LIGHT: 1 / DAY ] [MUSIC: PLAY / 565 / 839] Figure 6.5: Blinking LED + Music + Light sensor 6.7 What s next Now we produce some sound with some limited control over it... The next step is to use an analog input sensor connected to an I2C input to be able to adjust the detection level. Be patient and wait for the next edition of this tutorial.

62 62 CHAPTER 6. LIGHT SENSOR INPUT

63 Appendix A Appendices A.1 Generic definitions A.1.1 demo.h /* file: demo.h */ /* */ /* Some global definitions for theses tutorials. */ #ifndef DEMO #define DEMO #include <stdio.h> #include <stdlib.h> /* wiringpi library used to access Raspberry Pi GPIOs */ #include "wiringpi.h" /* Time units (all times are internally in µs) */ #define US * 1 #define MS * 1000 US #define S * 1000 MS /* The base cycle is the period of the sequencer. */ #define CYCLE (10 MS) /* Routines to be defined by the application. */ 63

64 64 APPENDIX A. APPENDICES /* init is called once to initialise the state machines */ extern void init(); /* isalive is called periodically to check if the state machines */ /* are still alive */ extern int isalive(); /* run is called periodically to run one step of every state machines */ extern void run(); /* cleanup is called once when the system is not alive */ extern void cleanup(); /* interrupted is called when an interrupt signal is received. */ /* interrupt signals are SIGINT, SIGQUIT, SIGABRT and SIGTERM. */ extern void interrupted(); #endif A.1.2 demo /* file: demo.h */ /* */ /* Sequencer for the state machines of theses tutorials. */ #include <signal.h> #include <string.h> #include <sys/time.h> #include <unistd.h> #include "demo.h" /* signal_handler is called when a signal is received. It calls */ /* the `interrupted` function defined by the application (which */ /* in turns calls the "interrupted" functions of the state */ /* machines. */ static void signal_handler(int sig) printf("\nsignal received: %s\n", strsignal(sig)); interrupted();

65 A.1. GENERIC DEFINITIONS 65 /* timer_handler is called periodically. The period is CYCLE. */ /* The main loop is driven by a timer which is more accurate than */ /* a simple wait. */ /* timer_handler calls: */ /* - `run` to execute one step of every state machines */ /* - `isalive` to check that the system is still alive */ /* - `cleanup` and exits when the system is not alive anymore */ static void timer_handler(int signum) /* run one step */ run(); /* check if the program is still alive */ if (!isalive()) /* stop the program when it is not alive anymore */ cleanup(); exit(exit_success); /* wait for the next cycle */ /* The main function initializes the state machines, */ /* starts a periodic timer to run the state machines */ /* and undefinitely waits for the system to exit. */ int main(void) /* Initialisation of the wiringpi library to access GPIOs */ wiringpisetup(); /* Interruption signal handler */ signal(sigint, signal_handler); signal(sigquit, signal_handler); signal(sigabrt, signal_handler); signal(sigterm, signal_handler); /* Some information about the hardware */ int model, rev, mem, maker, overvolted; piboardid(&model, &rev, &mem, &maker, &overvolted); printf("model = %s\n", pimodelnames[model]); printf("rev = %s\n", pirevisionnames[rev]); printf("mem = %d Mb\n", mem); printf("maker = %s\n", pimakernames[maker]); printf("over volted = %s\n", overvolted? "yes" : "no"); printf("\n");

66 66 APPENDIX A. APPENDICES /* state machine initializations */ init(); /* Install timer_handler as the signal handler for SIGALRM. */ struct sigaction sa; memset (&sa, 0, sizeof (sa)); sa.sa_handler = &timer_handler; sigaction(sigalrm, &sa, NULL); /* Configure the timer to expire after CYCLE µs... */ struct itimerval itimer; itimer.it_value.tv_sec = 0; itimer.it_value.tv_usec = CYCLE; /*... and every CYCLE µs after that. */ itimer.it_interval.tv_sec = 0; itimer.it_interval.tv_usec = CYCLE; /* Start the timer. */ setitimer (ITIMER_REAL, &itimer, NULL); /* Main loop */ while (1) /* This loop could be used as a background loop */ sleep(1000); return EXIT_SUCCESS; A.2 wiringpi stub The wiringpi stub is simply the original wiringpi.h file along with a fake wiringpi.c implementation that simulates some I/O. A.2.1 wiringpi.h /* * wiringpi.h: * Arduino like Wiring library for the Raspberry Pi. * Copyright (c) Gordon Henderson ***********************************************************************