October 29, 2013

Register access to the GPIOs of the Beaglebone via memory mapping

On the Beaglebone Black, Linux abstracts the GPIO pins as files: To control a given pin, you can write to certain files. For example, if you want to turn off the blue LED on the far side of the board, navigate via command line to /sys/class/leds/beaglebone:green:usr0. The trigger file in this directory controls the behaviour of the LED. By default, it is set to heartbeat.The command

echo none > trigger

turns the LED off, whereas

echo default-on > trigger

turns it on. You can find more information at many places, for example here.
However, this method is fairly slow and -at least for me - somewhat unsatisfying since you do not see at all what is going on at the hardware level. The achievable toggle speed of a GPIO pin via the Linux file method is something like 5 kHZ, which is painfully slow. To achieve higher speeds and work closer to the hardware, we can use memory mapping and directly access the GPIO registers. For the following sample program, you should connect a LED to Pin 28 on GPIO board 1, which is pin 12 on Header 9. Make sure not to connect the LED directly - use a transistor instead; the GPIO pins can only supply 4 mA. Also make sure that the usr0-LED is off as explained above. The program will first blink the LED at pin 28 and the usr0 LED 5 times; then it turns pin 28 into an input which is polled once per second for 20 seconds, and the usr0-LED is switched on and off accordingly.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
#include <unistd.h>
#include <fcntl.h>
#include <sys/mman.h>
#include <iostream>
#define OE_ADDR 0x134
#define GPIO_DATAOUT 0x13C
#define GPIO_DATAIN 0x138
#define GPIO0_ADDR 0x44E07000
#define GPIO1_ADDR 0x4804C000
#define GPIO2_ADDR 0x481AC000
#define GPIO3_ADDR 0x481AF000
using namespace std;

int main(){
    int fd = open("/dev/mem",O_RDWR | O_SYNC);
    ulong* pinconf1 =  (ulong*) mmap(NULL, 0x1000, PROT_READ | PROT_WRITE, MAP_SHARED, fd, GPIO1_ADDR);
    pinconf1[OE_ADDR/4] &= (0xFFFFFFFF ^ (1 << 28));
    for(int i = 0 ; i < 5; i++){
     pinconf1[GPIO_DATAOUT/4]  |= (1 << 28);
     pinconf1[GPIO_DATAOUT/4]  ^= (1 << 21);
     sleep(1);
     pinconf1[GPIO_DATAOUT/4]  ^= (1 << 28);
     pinconf1[GPIO_DATAOUT/4]  |= (1 << 21);
     sleep(1);
    }
    pinconf1[GPIO_DATAOUT/4]  &= (0xFFFFFFFF ^ ((1 << 21) | (1 << 28)));
    pinconf1[OE_ADDR/4] |= ( 1 << 28);
    for(int i = 0; i < 20; i++){
     cout << pinconf1[GPIO_DATAIN/4]  << endl;
     if(pinconf1[GPIO_DATAIN/4] & (1  << 28)){
      cout << "on" <<endl;
      pinconf1[GPIO_DATAOUT/4]  |= (1 << 21);
     }
     else{
      cout << "off" <<endl;
      pinconf1[GPIO_DATAOUT/4] &= (0xFFFFFFFF ^ (1 << 21));
     }
     sleep(1);
    }
    pinconf1[GPIO_DATAOUT/4]  ^= (1 << 21);
    return 0;
}
Now, what precisely does this program do? The magic numbers appearing in the defines are the memory addresses of the registers controlling the GPIO pins, so we have a look into the technical reference manual of the AM335x-processor used in the Beaglebone Black, which happens to be a 4600 pages document. In Chapter 2, Memory Map, you find a long list with the memory addresses of the various registers controlling the behaviour of the processor. Scrolling down a few pages, you find the register address of GPIO1 is 0x4804C000, which we defined to be GPIO1_ADDR in oyr program. In my version of the reference manual, you find GPIO1 on page 211, but that may change in future versions of the reference manual.

So the registers at and directly after the address 0x4804C000 control the behaviour of the pins of GPIO1. This alone is not yet helpful, so we turn to chapter 25, General Purpose Input/Output, for more details. In the GPIO registers subsection, we find the addresses and descriptions of the various registers. The addresses given there are relative to the beginning of the GPIO1 registers, respectively the beginning of the GPIO0 and GPIO2 registers. For example, the GPIO_OE register has a relative address of 0x134, so the GPIO_OE register for GPIO1 will be at 0x4804C000+0x134 = 0x4804C134. Going back to the memory map in chapter 2 of the reference manual, we find that the GPIO0 registers start at 0x44E07000, so the GPIO_OE for GPIO0 will be at 0x44E07134, and similarly for GPIO2.

The GPIO_OE register is the register controlling whether a pin is an input or output. It is a 32bit register whose k-th bit corresponds to pin k of GPIO1. If this bit is 1 (as it is by default), the pin is an input; if it is zero, the pin is an output. The GPIO_DATAIN register is for reading the value of an input pin: If pin k is an input, its k-th bit is 0 if pin k is low and 1 if it is high. If pin k is an output, GPIO_DATAOUT is for setting the pin: Writing a 0 to bit k sets pin k low, writing 1 sets it high. Alternatively, you can use the GPIO_CLEARDATAOUT and GPIO_SETDATAOUT registers: writing a 1 to bit k clears respectively sets pin k.

Now we know which registers we have to control, but how can we actually control them? We use memory mapping to get a pointer which points to the beginning of GPIO1. This is achieved in the lines

int fd = open("/dev/mem",O_RDWR | O_SYNC);
ulong* pinconf1 = (ulong*) mmap(NULL, 0x1000, PROT_READ | PROT_WRITE, MAP_SHARED, fd, GPIO1_ADDR);

This "maps the memory" at the physical location GPIO1_ADDR to the pointer pinconf1; we make it a pointer to ulong since a long happens to be 32bit on the Beaglebone and the registers are 32 bit. Note that the offset addresses of the various registers are in bytes, not in registers: This is why we have to divide by 4 later on in the code  since an ulong is 4 byte. For all practical purposes, pinconf1 is now a pointer pointing to the address GPIO1_ADDR; however, a "normal" pointer can only point to the memory allocated to the process, so we have to use memory mapping. The NULL argument to mmap specifies that Linux is free to put the memory map wherver it wants in the memory of the process; PROT_READ | PROT_WRITE specify that we can both read and write to the memoryand map_shared says that we actually access the underlying memory and not only the map in the memory of the process when we write to the memory map. The file /dev/mem we pass via the variable fd happens to be the place where Linux abstracts the phzsical memory as a file. The GPIO1_ADDR specifies where the memory map starts and the number 0x1000 = 4096 specifies its length - in this case, we map the 4 kB following 0x4804c000. If you consult the technical reference manual again, you will see that the GPIO registers for each GPIO board total 4kB, so we have precisely mapped all the registers for GPIO1.

The program is hopefully fairly self-explanatory now: pinconf1[OE_ADDR/4] is the memory at address 0x4804c000 (where our mmap begins) + 0x134 (the offset of OE). Remember that we have to divide by 4 since pinconf1 is an ulong pointer and the offsets are in bytes. Now pinconf1[OE_ADDR/4] &= (0xFFFFFFFF ^ (1 << 28)) sets pin 28 of GPIO1 to be an output and all other to inputs. Then pinconf1[GPIO_DATAOUT/4] |= (1 << 28) sets pin 28 to high. The register pinconf1[GPIO_DATAIN/4] stores the input values of the various pins; we read bit 28 from this register, which means reading the input of pin 28, and process the result accordingly.
All in all, this is a much neater and faster way to access the GPIO pins of the Beaglebone. Be aware, however, that not all pins can be accessed directly; some of the pins are by default reserved for non-GPIO stuff and have to be enabled via the device tree, which is a story for another day.

October 9, 2013

Building your own Infrared-controlled car, Part 1: Receiving infrared signals


Well, technically not a car, but a tracked vehicle. Here you can see it in action:

Now, why do I write about this? After all, you can easily build such a car purely from Lego parts! That is true. However, later on - when this vehicle is upgraded to something you could call a robot - I want to connect my own little computer and some sensors, and this is not really possible with pure Lego parts.

First, we need a remote. We could build our own, but the result would be rather clumsy, so we use an existing remote. I use the Lego IR remote, but in principle you could use your TV remote - which, of course, would not only control the car, but also still control your TV...

Before we can use the remote, we have to read out the infrared protocol used - we have to know what the remote sends when we press, say, button 1 on the remote. You might luck out and find a complete instruction set online for your remote, but this is no sure thing, and the work needed for the readout is basically the same work we have to do anyway to receive infrared signals at all, so it comes basically for free.

The infrared LED in the remote has two states: It is either plain off, or it will flash at a high frequency, typically 38 kHZ. It will flash for some time, then it is off for some time, then it will flash again. The message we want to send is either encoded into the time it flashes before turning off again, or - more commonly - into the time between two sets of flashes. The point of the flashing is that a 38 kHz flashing signal is much less likely to be of natural origin compared to non-flashing infrared light, which makes receiving less error-prone.

The most convenient way for receiving the signal is using a receiver IC like the TSOP312xx. There are several different ones, depending on the carrier frequency: The 31238 is for 38 kHz, the 31236 for 36 kHz and so on. The 38 kHz frequency is the most common one, and the TSOP31238 should also work for 36 kHZ remotes, with somewhat decreased range.

The TSOP has three pins, two of which are for the power supply. The third is for the output of the demodulated signal: If the IC sees the remote flashing, it will pull the output pin low; otherwise, it is high. On the output pin, we hence do not see the carrier frequency at all, which makes reading the signal much easier.

Now we can connect the TSOP to some microcontroller and measure when the output line goes low. I will use an Arduino since it is easy to connect to a PC. A bare AVR can also easily receive the signal, but getting the data onto your PC is more difficult. The setup looks as follows:

Not much to see here: The orange output line goes to pin 2 on the Arduino, which is the pin for the external interrupt 0, the other two wires are ground and 5 volt. You should check the exact wiring in the data sheet of your receiver - it may be different, and a wrong wiring will probably destroy the receiver. Also, you might want to add a capacitator over ground and 5 volt, but it works for me without. Whenever the output line goes low, the interrupt routine saves the time passed since the last interrupt or (in case of the Arduino code) just the time in microseconds since startup.

Below you find the sourcecode in plain C and for the Arduino; but you should be careful with the Arduino code: the interrupt routine has lots of overhead, and this seems to be the outer limit of what is achievable in this way - I crashed it a few times when the program had a longer interrupt routine, so this approach is probably out for use on the car since there the Arduino has to do other stuff as well.

The source-code in Arduino-speak:

volatile unsigned long timevalues[150];
volatile int i = 0;
int finished = 0;
void setup(){
   attachInterrupt(0, external, FALLING); 
   Serial.begin(9600); 
   Serial.println("starting program");
}
void loop(){

  if(finished == 0){
 if(i > 140){
   finished = 1;
   for(int j = 1; j < 140; j++){
  Serial.println(timevalues[j]-timevalues[j-1]);
     
       }
    
 }
  
  
}
}
void external(){
  //if(timecounter > 1){
    timevalues[i] = micros();
    i++;
 //} 

}
and in AVR-GCC:
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
#define F_CPU 16000000UL
#include <avr/io.h>
#include <util/delay.h>
#include <avr/interrupt.h>

#define BAUDRATE 9600
#define BAUD_PRESCALLER (((F_CPU / (BAUDRATE * 16UL))) - 1)

//Declaration of our functions
void USART_init(void);
void USART_send( unsigned char data);





volatile int i = 0;
volatile int timecounter = 0;
uint8_t finished = 0;
volatile uint8_t timevalues[150];

int main(void){
 USART_init();        //Call the USART initialization code
 EICRA = (1 << ISC01); //interrupt on falling edge
 EIMSK = (1 << INT0); //enable INT0-interrupt
 TCCR0A = (1 << WGM01); //clear timer on compare match
 
 TCCR0B = (1 << CS01) | ( 1 << CS00); //prescaler 64
 OCR0A = 16; //one timer interrupt every 16 ticks of the clock, which here means every 64 microseconds
 TIMSK0 |= (1 << OCIE0A); //turn timer interrupt A on
 sei();
 while(1){        //Infinite loop
 if(finished == 0){
  if(i > 100){
   cli();
   finished = 1;
   for(int j = 0; j < 100; j++){
    USART_send(timevalues[j]);
    
   }
   
  }
 }
 
 
}

return 0;
}

ISR(INT0_vect){
 if(timecounter > 1){
 timevalues[i] = timecounter;
 i++;
 timecounter = 0;
 } 
}

ISR(TIMER0_COMPA_vect){
 timecounter++;
} 


void USART_init(void){
 
 UBRR0H = (uint8_t)(BAUD_PRESCALLER>>8);
 UBRR0L = (uint8_t)(BAUD_PRESCALLER);
 UCSR0B = (1<<RXEN0)|(1<<TXEN0);
 UCSR0C = (3<<UCSZ00);
}

void USART_send( unsigned char data){
 
 while(!(UCSR0A & (1<<UDRE0)));
 UDR0 = data;
 
}
The principle is the same both times: Wait for 100 received signals and then send the time intervals over UART. The output of the Arduino program is the time in microseconds between flashes; the output of the C-code (for which you will need a serial terminal, for example Realterm) is in 64 microseconds, i.e. a "10" means roughly 640 microseconds. The precision is still sufficient, and it saves memory and processor cycles.

Part of the output when I press 1 on my TV remote for the Arduino code is

13464 1124 1156 1100 1124 1156 1100 2240 1156 2216 2244 2240 2244 2244 2244 1152 2216 2244 1152 1128 1128 1100 1152 1100 1128 1152 2216 2248 2240 2240 2244 2244 2244 40312 11208 96448 11208 96452 11208 96452 11208 96448 11208 96452 11208 96452 11208 96452 11208 96448 11212 96448 11208 96452 11208 96452 11208 96452 11208 96452 11208 96448 11208 96452 11208 96452 11208 96452 11208 96452 11208 96452 11208 96448 11212

It uses the NEC protocol, and you will find all the numbers above also in the linked document. We start with a pause of 13 ms, signifying the beginning of the transmission. Then we send the code 00000010111111011000000001111111 - a 0 for the short pause of 1.1 ms, a 1 for the long break of 2.2 ms. Then the remote starts a "continue" pattern, which is also described in the link: This signifies the receiver that the button keeps getting pressed.

I have a blog


Finally, I managed to get my own blog.

I intend to blog about my microcontroller and robotic projects. Why do I do this? I hope that some people will find my future posts useful and/or interesting, and I would like to have write-ups of my own projects anyway - and this blog will hopefully act as a source of motivation for actually creating these write-ups.

My current project is a Robot made from Lego, a microcontroller, and a Beaglebone Black respectively a Raspberry Pi computer for some basic image processing. The first step will be making the electronics for an infrared-controlled vehicle. This could be done purely with Lego parts; however, we later on want to steer everything via a computer, and hence will need to interface a computer into the circuit.