Category Archives: howto

Arduino YUN – how to get older system images

On Arduino.cc  You can always find and download most recent Arduino YUN system image (firmware).  What to do, if You need older one?

Arduino YUNOlder firmware for Arduino YUN

First, You need to know which firmware You need. Browse all release notes on  GitHub. Knowing which one You need, insert revision number into link replacing XXX:

https://downloads.arduino.cc/openwrtyun/1/YunSysupgradeImage_vXXX.zip

So, if You need 1.4.2 link for download is:

https://downloads.arduino.cc/openwrtyun/1/YunSysupgradeImage_v1.4.2.zip

And for Release 1.3:

https://downloads.arduino.cc/openwrtyun/1/YunSysupgradeImage_v1.3.zip

 

Debug sketch on Arduino Zero Pro with GDB and OpenOCD

Arduino is simple platform but empowers it’s users to do fantastic projects. People with experience in writing software for bigger computers can get strange feeling when they have no access to debugger. Debugger is tool for tracing program execution – You can examine/modify variables, going through code step by step and many more. In other words it let’s You know why program does not behave as expected. It is very useful tool, especially when You have to deal with more complex programs. But Arduino does not have such tool, only debugging method is to write messages via Serial class.

Arduino Zero Pro for rescue

We have Arduino Zero Pro in our offer. This board has 32-bit ARM Cortex-M0 processor. New feature is interface for debugging sketches on board. You can do it with JTAG/SWD adapter, or just connecting board to PROGRAMMING USB port. This article will show You how to access debugger feature with free and open tools.

Debug in progress

Debug in progress

 

How to start?

Test were done with computer running Linux, but all required software is bundled with Arduino IDE, so this tutorial should work also on Windows and MacOS without any significant changes.

Arduino ORG

It is important to note, that we will need Arduino IDE from Arduino.org not from Arduino.cc. At this moment (Apr/May 2015) only IDE on Arduino.org has support for Arduino Zero Pro.

We need to download and install Arduino IDE 1.7.3 or newer. Next step is to increase number of messages given by IDE during sketch compilation. Open preferences (Ctrl+,) and near  Show verbose option during mark compilation.

For our first debug target we will use Blink. Open it  (menu Files/Examples/01. Basic/Blink), connect Arduino Zero to computer using PROGRAMMING port, in IDE select also Arduino Zero Pro (Programming) and upload sketch to board (Ctrl+U).

OpenOCD

ARM consortium has agreed on communication standard for Cortex-M0 processors. It is called CMSIS (more details about – link) and there is open software supporting this standard.

Let me introduce You – OpenOCD. OpenOCD binary files are bundled with Arduino IDE and You don’t have to install anything more.

Starting OpenOCD

Having our Blink sketch on board, we go to directory where is Arduino IDE and we start OpenOCD using this command:

./hardware/tools/OpenOCD-0.9.0-dev-arduino/bin/openocd -s hardware/tools/OpenOCD-0.9.0-dev-arduino/share/openocd/scripts/ -f hardware/arduino/samd/variants/arduino_zero/openocd_scripts/arduino_zero.cfg

Argument after -s defines folder where are configuration files for OpenOCD, and after -f switch there is configuration file defining Arduino Zero Pro capabilities.Result for running this command should be similar to this:

Open On-Chip Debugger 0.9.0-dev-g1deebff (2015-02-06-13:06)
Licensed under GNU GPL v2
For bug reports, read
    http://openocd.sourceforge.net/doc/doxygen/bugs.html
Info : only one transport option; autoselect 'cmsis-dap'
adapter speed: 500 kHz
adapter_nsrst_delay: 100
cortex_m reset_config sysresetreq
Info : CMSIS-DAP: SWD  Supported
Info : CMSIS-DAP: JTAG Supported
Info : CMSIS-DAP: Interface Initialised (SWD)
Info : CMSIS-DAP: FW Version = 01.1F.0118
Info : SWCLK/TCK = 1 SWDIO/TMS = 1 TDI = 1 TDO = 1 nTRST = 0 nRESET = 1
Info : DAP_SWJ Sequence (reset: 50+ '1' followed by 0)
Info : CMSIS-DAP: Interface ready
Info : clock speed 500 kHz
Info : IDCODE 0x0bc11477
Info : at91samd21g18.cpu: hardware has 4 breakpoints, 2 watchpoints

GDB

OpenOCD is ready to work. It listens on ports  4444 and 3333. On first port there is telnet server and second one hosts GDB server.

GDB is open source software for debugging programs. It is also bundled with Arduino IDE. It is important to have GDB with support for ARM architecture, so use binaries attached to Arduino IDE.

To proceed we need file with compiled program in  ELF format and with included informations required to properly debug code. Such file is prepared by Arduino IDE during compilation and is stored in temporary directory. To know where this file is we compile Blink again, this time without uploading to board. Just press Ctrl+R and examine output in IDE console window. In one of last lines You will see path and filename with .elf extension. See by Yourself, but note that console window is scrolled to the right, to see this file path:

Where to find ELF file location in Arduino IDE

Where to find ELF file location in Arduino IDE

 

We are ready to run GDB. In folder with Arduino IDE issue command:

./hardware/tools/gcc-arm-none-eabi-4.8.3-2014q1/bin/arm-none-eabi-gdb -d examples/01.Basics/Blink/

Folder given after -d switch is place where GDB can find source files for our program. This is required by GDB to display it later to You when You will step through Your program. After issuing this command You should see GDB command line:

GNU gdb (GNU Tools for ARM Embedded Processors (Arduino build)) 7.6.0.20140228-cvs
Copyright (C) 2013 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later 
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.  Type "show copying"
and "show warranty" for details.
This GDB was configured as "--host=x86_64-linux-gnu --target=arm-none-eabi".
For bug reporting instructions, please see:
.
(gdb) 

In this article I show You only basic steps to get debugger features, for more detailed info about how to use GDB dig by Yourself. In future we may prepare more detailed info about GBD.

First we have tell GDB where to find file with program and debug information:

(gdb) file /tmp/build4557814640826011475.tmp/Blink.cpp.elf
Reading symbols from /tmp/build4557814640826011475.tmp/Blink.cpp.elf...done.
(gdb) 

Command file is used to supply path and filename to program, just insert here path copied from Arduino IDE few steps earlier.

Now we need to inform GDB where it can find our live program:

(gdb) target remote localhost:3333
Remote debugging using localhost:3333
0x00000000 in ?? ()
(gdb) 

Now we can take control over program execution, examine this GDB session output:

(gdb) monitor reset halt
target state: halted
target halted due to debug-request, current mode: Thread 
xPSR: 0x21000000 pc: 0x000028b8 msp: 0x20002c08
(gdb) monitor reset init
target state: halted
target halted due to debug-request, current mode: Thread 
xPSR: 0x21000000 pc: 0x000028b8 msp: 0x20002c08
(gdb) l loop
19    // initialize digital pin 13 as an output.
20    pinMode(13, OUTPUT);
21  }
22  
23  // the loop function runs over and over again forever
24  void loop() {
25    digitalWrite(13, HIGH);   // turn the LED on (HIGH is the voltage level)
26    delay(1000);              // wait for a second
27    digitalWrite(13, LOW);    // turn the LED off by making the voltage LOW
28    delay(1000);              // wait for a second
(gdb) b 25
Breakpoint 1 at 0x4120: file Blink.ino, line 25.
(gdb) cont
Continuing.
Note: automatically using hardware breakpoints for read-only addresses.

Breakpoint 1, loop () at Blink.ino:25
25    digitalWrite(13, HIGH);   // turn the LED on (HIGH is the voltage level)
(gdb) c
Continuing.

Breakpoint 1, loop () at Blink.ino:25
25    digitalWrite(13, HIGH);   // turn the LED on (HIGH is the voltage level)
(gdb) 

Command monitor reset halt sends to our board processor instruction to stop sketch execution, now LED on Arduino stops blinking. monitor reset init resets Arduino CPU to empty state, and it becomes ready to start over.

l loop display loop function code (that is reason why we need tell GDB where are source files). Command b 25 sets breakpoint in line 25 of current source file. cont resumes program execution (well, actually it starts from beginning since we have issued  monitor reset init ). This is reason why after cont, program gets to line 25 and before LED is lit execution is halted. Next c commands allow to run code until it returns to line 25 .

What’s next?

This is simple example to illustrate new possibilities Arduino Zero Pro opens before You. People familiar with GDB are ready now to order Arduino Zero Pro  and start exploring new ways to debug sketches. Others can see on this short video, debugging on Zero Pro is quite easy.

But, since GDB is working nothing does stop us from using some graphical interface for GDB, list of such tools is quite long. We have used DDD (this time You have to install it by Yourself)

DDD during debug session with Arduino Zero Pro

DDD during debug session with Arduino Zero Pro

To use it with Arduino You have to tell DDD where is proper GDB:

ddd --debugger "hardware/tools/gcc-arm-none-eabi-4.8.3-2014q1/bin/arm-none-eabi-gdb -d examples/01.Basics/Blink/"

nRF24L01+ wireless modem

There are many options how to connect Your Arduinos wireless. One of options available is – nRF24L01+. It costs only 6zł (1.5 EUR) per node and it allows you to connect many devices without using a single wire. nRF24L01 uses radio waves (in 2.4 GHz band) to contact with other modules.

nrf24L01+ module

nrf24L01+ module

Modem works on 2.4GHz frequency and has 100m range (at best). You can communicate with different baud rates: 250 kbps, 1 or 2 Mbps. High baud rate allows users even to send video material in 720p resolution (very similar to Youtube). During operation modem uses less power that single LED. During receive power consumption is around 12mA and during transmission 11mA. According to datasheet users can set automatic power saving modes. During this states module consume only 320 µA (when data is waiting for transmission), 26 µA (when there is nothing to send), 0.9 µA (in shutdown).

nRF can operate on voltages between 1.9 and 3.6V. The input pins tolerate the 5V logic, so without any problems this module can be connected to the most popular development boards like Arduino. You don’t have to use any logic level converters when connecting this module to Arduino working in 5V logic. Most models of Arduino (UNO, Mega, Leonardo and more) are working with this logic levels.

Operating bandwidth is divided on 125 channels (separate frequencies). Thanks to this, you can create a network of 125 independently working modems in one place. Every channels has its own address. Well, to be honest it can have up to 6 addresses. This addresses are numbers and they represent specific device connected to network which will receive data. Length of the address can be from 3 to 5 bytes. This gives us the addresses from 24 to 40 bits. With the lowest value of the address it is 17 million combinations. Longer address value can be used as 5 letter names (5 chars at 8 bits give us 40 bits in total).

nRF24L01 automatically creates data packets. You are only sending what you want to the specified address. Modem creates a data packet, which is protected from errors with a CRC. When there’s a problem with sending packet, device automatically will try to send it one more time. If sending is successful, receiving module automatically sends a confirmation to the transmitting module.

nRF24L01 uses SPI interface to communicate with the MCU. It uses 5 wires.

Pinout

nRF24L01 module is being sold on breakout board with build in antenna. The pcb only requires a connection with the development board or MCU. Size of the whole module is very small (1.55×2.9cm). From the bottom you can see two rows of communication pins.

nrf24l01+ pinout

nrf24l01+ pinout

As it was written before, module communicates with the controller via SPI interface.

Signals:

  • VCC – power – from 1.9 up to 3.3 V
  • GND – ground
  • MOSI – SPI serial data input
  • MISO – SPI serial data output
  • SCK – SPI clock
  • CSN – low state on this pin indicates that with this module the controller wants to communicate.
  • CE – signal activating receiving and transmitting. In receive mode, the high state indicates that he wants to receive. In transmit mode, pulse sends one packet of data.
  • IRQ – interrupt output. It does a low state pulse when data is waiting to receive, or when the data was properly sent.

 

P4A – PHP for Arduino part 2

In the previous post we’ve finished with reading files from SD card. Now we have to pass them through our PHP :) and send the results to the client. To make whole process more simple, we’re assuming each of the files is known to us. This means, we’re registering every file (URL) with addCommand. How it should work? The idea is to keep our functions in the sketch code, whose results should be put into selected places of HTML code. In other words, we want to have HTML file with such a code snippet:

<p>
Sensor 1 reading: MAGIC1<br/>
Sensor 2 reading: MAGIC2<br/>
</p>

Our parser’s goal is to replace MAGIC1 and MAGIC2 with values returned by the functions from the sketch.

It’s best to begin from the magic!

How to write a code in HTML so to tell our parser to substitute it with another text. For simplification we’ll assume the following pattern: #{X} will be substituted with the value returned from appropriate functioni. X is an one-character mnemonic denoting the function we want to invoke. The functions must have a specified definition and mustn’t receive any parameters. Why? Receiving arguments will make the parser unnecessarily complicated and we rather don’t need it now. We’ve already chosen the method of writing entries to HTML code. Now, a question arises, how to pass the returned value from our function? We’re assuming the example function must have the following definition:

void timeReport(char *buf) { itoa(millis()/1000, buf, 10); };

It doesn’t return any values (void), but receives a pointer to a text buffer. In that buffer it has to put its result, and after that, the result will be put in a proper place in the HTML code. The function must take care of the buffer in order not to overload it. Its length is declared in P4A_MAX_FUNCTION_RESPONSE_LENGTH. As you can see, the function above returns the number of seconds elapsed from turning on or resetting the Arduino. How to parse a file? Thanks to our “magic” marker it’s quite easy. We’re reading the file by one character. If we come across ‘#’ character, then we’re reading the next character and checking, if it’s ‘{‘. If does, we have the marker sequence. Until we come across ‘#’, all the characters are sent to the buffer, which will be eventually sent to the web browser. If the next character after ‘#’ isn’t the opening bracket (‘{‘), then both characters (‘#’ and the following) are sent to browser. In case the next character is a bracket, then we’re reading the next character – it’s our mnemonic! After that, a function is invoked, according to the mnemonic, and the result is sent to the web browser. Afterwards, we’re reading the file until the closing bracket (‘}’), then continuing scanning for the next ‘#’. Now it only remains for us to assign functions to mnemonics. For this, we’ll be using

Array of pointers to functions

Let’s talk about slightly more complex topic – pointers to functions. Basically, after compilation, a function is an address at which its code is located along with a contract describing what kind of data is passed to the function and how values are returned from it. If the contract (list of parameters and returned value) is the same for many functions, such a functions can be stored in a form of pointer and kept in an array. Then we are able to call such functions by using the pointer, without a need to know its name. This is what will be serving us as a mechanism translating mnemonics to called functions. Now we know why all of our functions must have the same interface/contract (as we already assigned, it will be void, regarding returned data type and char * as an argument) – thanks to this we are able to keep them in a single array with single-lettered index. But, starting from the beginning:

void (*_fcts['z'-'a'])(char *);

We’re defining an array of pointers to functions. The leading “void” denotes type of data returned by the function, that in brackets means what arguments is expected by the function. Inside is the declaration of an array. It’s name 'z'-'a' can appear strange to you, but in this context the characters are treated as numbers by the compiler. So, from ‘z’ code we’re subtracting ‘a’ code. The difference is the letter count. Thanks to it we have an array which is able to store one pointer for each small letter in Latin alphabet (or rather in ASCII charset). If we have any letter code, it’s enough to subtract the letter code from it and we’ll get the index from the array. Let’s look:

				if (_fcts[c[0]-'a'] == NULL) {
					bufferedSend(server,"n/a");
					continue;
				} else {
					//Call function from table
					_fcts[ c[0]-'a'](buf);
					//Write response to client
					bufferedSend( server, buf );
				}

c[0] contains a character of our mnemonic. If the array don’t have any value (i.e. NULL value) at c[0] - 'a' index, then in HTML code n/a is put – that’s our method of indicating wrong mnemonics. 'a' has a value of 97 in ASCII. If our mnemonic is also 'a' 97-97 = 0, so it’s the first element of the array. If the mnemonic is 'b', then 'b'-'a' = 98 – 97 = 1 so the second element of the array. It would be useful to know if the mnemonic is in range, otherwise we could try to call a function with a random address (when the array index is out of range, RAM memory out of the array will be read and the processor will try to interpret a value at this address as an address of a function to invoke – easy way to crash the program). In the code above you can also see, how to call a function from the array:

_fcts[ c[0]-'a'](buf);

We’re using status variable for file analysis. It indicates the status of the parser. It can be:

  • P4A_PARSE_REGULAR – searching for ‘#’
  • P4A_PARSE_HASH – waiting for the opening bracket (‘{‘)
  • P4A_PARSE_COMMAND – searching for mnemonic

Thanks to the status it’s easier to control, what our parser is doing. According to current status and next letter we can make decision, what to to afterwards. For the interested ones, here is whole parseP4A program code:


//Reads HTML file, parses looking for our macro and sends back to client
int parseP4A( char * filename, WebServer &server ) {
	//simple status
	short int STATUS = P4A_PARSE_REGULAR;
	char c[2];
	c[1] = 0;

	//buffer to hold response from functions - there is no boundary checking, so
	//function has to not overwrite data
  char buf[P4A_MAX_FUNCTION_RESPONSE_LENGTH];

  if (! file.open(&root, filename, O_READ)) {
		return -1;
  }
  while ((file.read(c,1) ) > 0) {
		if (STATUS == P4A_PARSE_REGULAR && c[0] == '#')
		{
			//hash was found we need to inspect next character
			STATUS = P4A_PARSE_HASH;
			continue;
		}

		if (STATUS == P4A_PARSE_HASH) {
			if (c[0] == '{') {
				//go to command mode
				STATUS = P4A_PARSE_COMMAND;
				continue;
			} else {
				//fallback to regular mode, but first send pending hash
				STATUS = P4A_PARSE_REGULAR;
				bufferedSend(server, "#");
			}

		}

		if (STATUS == P4A_PARSE_COMMAND) {
			if(c[0] == '}') {
				STATUS = P4A_PARSE_REGULAR;
				continue;
			};
		  if (c[0] >= 'a' && c[0] <='z') {
				//Command found
				if (_fcts[c[0]-'a'] == NULL) {
					bufferedSend(server,"n/a");
					continue;
				} else {
					//Call function from table
					_fcts[ c[0]-'a'](buf);
					//Write response to client
					bufferedSend( server, buf );
				}
			}

		}

		if (STATUS == P4A_PARSE_REGULAR)
			bufferedSend(server, c);
  }

  //force buffer flushing
  flushBuffer(server);
	file.close();
  return 0;
}

P4A – PHP for Arduino in action

Let’s assume we want to make a nice virtual barometer, but showing real air pressure. We’ll take advantage of BMP085 – it’s a breakout board for pressure and temperature sensor made by SparkFun. We’re going to have the following result:

Virtual barometer's appearance

Virtual barometer's appearance

The hand should point to value read from the sensor and the foretasted weather symbol should change according to air pressure changes. How do we get on with that, when, as it was said in the previous part, WWW server on Arduino is not a best idea (loading many files – pictures(!) simultaneously)? So, if everything is going to be available from the web, why don’t we make the static elements also available from there? These elements are: the barometer’s dial, hand image and weather symbols. On Arduino, on SD card, there’s a HTML file. In the sketch we’re writing a function calling the parser for this file:

void index(WebServer &server, WebServer::ConnectionType type, char *, bool){
  server.httpSuccess();
  if (!parseP4A("BARO.HTM", server)) {
		Serial.println("P4A: -1");
	}
};

parseP4A is a function parsing a given file and sending the result using Webdiuno object. It only remains to register our function as the default command:

webserver.setDefaultCommand(&index);

The HTML itself uses JavaScript and canvas object to draw the dial. This is done by draw function, receiving pressure in hectopascals as an argument. When the site is ready (this means, has been loaded), we’re calling draw function by onload attribute and the pressure is passed by our P4A:

<body onload="draw(#{p});"

p mnemonic has to be assigned with a proper function. In the sketch, in setup, we’re setting a function for p:

 _fcts['p'-'a'] = pressureReport;

And the pressureReport itself looks like:

void pressureReport(char *buf) {
	bmp085_read_temperature_and_pressure (&temperature, &pressure);
	itoa(pressure/100.0, buf, 10);
	Serial.print ("temp & press: ");
	Serial.print (temperature/10.0);
	Serial.print(" ");
	Serial.println (pressure/100.0);

};

Serial is used for checking, if the values are according to our expectations and there isn’t any impact on the barometer’s operation. bmp085_read_temperature_and_pressure it’s a BMP085 handling function, taken from a finnish blog. The whole code is available for download here. It’s a sketch powering our server plus HTML file and graphics. The dial, graphics and HTML/JS code was made bySprae.

Installation

Download, unpack in sketchbook. Content of html subdirectory has to be put into the main catalog on SD card, then insert the card into the shield. Correct the sketch by specifying proper MAC and IP address. After opening the main site in our browser, we should see the barometer, supposing we have BMP085 ;)

Some annotations at the end

The code is beta version :) It means it worked for me, during the tests I performed and maybe there’s some bugs (and probably that’s true) I haven’t ever imagined :) The code needs to be rearranged, e.g. functions related to buffered output should be moved to Webdiuno code. I’m planning to make it and submit all the changes to Webduino developers. Maybe some of them will be included in the library. I’m curious of your opinion. Does something like P4A have any sense and could it be useful?

P4A – PHP for Arduino part 1

If you already know Arduino stuff a bit, maybe you want to connect it with a network somehow. It could be some network-enabled home automation solution or a set of sensors sending data to a database. So, here comes the Ethernet Shield to help you.

First, a bit of history. Initially, the Ethernet Shield was compatible with the small Arduino. Why not with Mega? It’s because for communication with W5100 IC, a heart of the shield, SPI protocol is used. In Arduino Mega SPI occupies a different set of digital outputs (not 10, 11, 12 and 13). Of course, there’s a workaround for this – wiring the shield up with cables.

That involves the older shields. The ones which are currently sold by Nettigo are compatible both with small Arduinos (UNO, Duemilanove) and Mega (with ATmega1280 and ATmega2560 microcontrollers). How to recognize such a shield? If there’s a microSD slot – it’s the newer version.

Ethernet Shield with microSD slot

Ethernet Shield with microSD slot

 

 

W5100 – the IC powering Ethernet Shield is a chip made by Korean-based WIZnet. The difference between it and other Ethernet controllers is TCP/IP stack implementation. In W5100, the stack is implemented directly in the chip. What it means for an ordinary user? The communication library uses less RAM and occupies less space on flash memory in compare to chips with no TCP/IP stack.

How to take advantage of Ethernet Shield?

There’s plenty of examples on the Internet, how to make websites displaying data from Arduino. However, if you have any bigger experience with Arduino programming, you probably know that every single text string, even the one defined in the program code, needs some amount of space in RAM memory. And, of course, there always lacks of RAM memory.

Let’s check out the official example from the Arduino Tutorial. Code:

 client.println("HTTP/1.1 200 OK");
 client.println("Content-Type: text/html");
 client.println();

It will take 40 bytes of RAM (15 chars in HTTP… + trailing zero and 23 in Conte… + trailing zero). It’s simple to imagine, how important it is when we have only 2kB to use. The HTML website shouldn’t be too complex.
Fortunately, there’s a soution – storing the strings in Flash memory. It can lower the usage of RAM memory, but sometimes by adding some code. Accessing strings defined in this way is possible only with a special macro and the compiler wouldn’t let us to use this macro in function char * as a parameter. What’s more, any change in the HTML code forces us to recompile whole sketch and upload it to Arduino.

Wait, the Ethernet Shield has a microSD slot, hasn’t it? Couldn’t we take advantage of it somehow? So, it’s possible, but requires a bit of work.

First – the Ethernet Shield has to be configured for work in a network – this means setting the MAC and IP addresses. This can be done like that:

byte mac[] = { 0xDE, 0xAD, 0xBE, 0xEF, 0xFE, 0xED };
byte ip[] = { 192,168,1, 177 };

Ethernet.begin(mac, ip);

MAC address is given on a sticker on the back side of the shield. IP address depends on the network’s configuration. The sequence Ethernet.begin will work only in a local network, this means, when all of the IP addresses belong to the same subnet. If the shield should connect with hosts from other networks (either when operating as a client or as a server) you must specify one more parameter – an array containing 4 numbers – the IP address of default gateway (Yours router IP address). More on the Ethernet Library reference page.

Most of the blocks are ready. The Ethernet library found in Arduino IDE is not the best solution. It simplifies creating, for example, TCP server, but the HTTP server is a few steps away. Thus, the Webduino will be very useful. It’s a HTTP server based on the Ethernet library, so we have most of work done.

Normally, we would download it from there and unpack to sketchbook/libraries, but now we are going to modify Webduino a little, the final version will be available at the end of this mini tutorial, so for now, you needn’t to install anything.

Webduino – how to begin?

At first – we have to know that with this:

void addCommand(const char *verb, Command *cmd);

we are able to register any function invoked every time when a URL matches verb. Example:

webserver.addCommand("blob.htm", &blob);

If the URL begins with blob.htm, then the function blob will be invoked. The function has to receive parameters according to the definition in Command:

typedef void Command(WebServer &server, ConnectionType type,

                       char *url_tail, bool tail_complete);

server is a WebServer object, for which the method was invoked, type – type of request (INVALID, GET, HEAD, POST), url_tail the remaining part of matched URL address (after blob.htm). If the URL has to be truncated because of too small Webduino buffer, the last parameter tail_complete will have false value.

OK, but it’s not very convenient to register every single function, especially when we want to use data from SD card, which we don’t know. Now, setFailureCommand will be useful to register in our code a function invoked, when none of the functions defined with addCommand was invoked.

Now, it only remains to check if url_tail is a name of a file located on the SD card (because any matching didn’t occur, url_tail contains full URL address including first character ‘/’). If the file doesn’t exist, we’re displaying HTTP 404 error, if does – sending it to the client.

How to read a file from SD card?

Like with HTTP server, we don’t have to do everything by ourselves. A good help will be a tutorial prepared by Limor Fried – a.k.a. LadyAda. She utilizes the SdFatLib library, supporting FAT16 i FAT32 file systems (commonly found on SD and SDHC cards).

Initialization code and file handling was basically taken from the tutorial. I will describe here the fetchSD function, registered by setFailureCommand. Its objective is to find a file on the card and send it to web browser:

P(CT_PNG) = "image/png\n";
P(CT_JPG) = "image/jpeg\n";
P(CT_HTML) = "text/html\n";
P(CT_CSS) = "text/css\n";
P(CT_PLAIN) = "text/plain\n";
P(CT) = "Content-type: ";
P(OK) = "HTTP/1.0 200 OK\n";
void fetchSD(WebServer &server, WebServer::ConnectionType type, char *urltail, bool){
	char buf[32];
	int16_t  readed;

	++urltail;
	char *dot_index; //Where dot is located
	if (! file.open(&root, urltail, O_READ)) {
		//Real 404
		webserver.httpNotFound();
  } else {
	if (dot_index = strstr(urltail, ".")) {
		++dot_index;
		server.printP(OK);
		server.printP(CT);
		if (!strcmp(dot_index, "htm")) {
				server.printP(CT_HTML);

		} else if (!strcmp(dot_index, "css")) {
				server.printP(CT_CSS);

		} else if (!strcmp(dot_index, "jpg")) {
				server.printP(CT_JPG);

		} else {
				server.printP(CT_PLAIN);
		}
		server.print(CRLF);
	}
	readed = file.read(buf,30);
	while( readed > 0) {
		buf[readed] = 0;
		bufferedSend(server,buf,readed);
		readed = file.read(buf,30);
	}
	flushBuffer(server);
	file.close();
	}
}

At the very beginning we have a few constants stored in Flash memory.

P(CT_PNG) = "image/png\n";

P macro is a part of Webduino and serves for storing strings in Flash and not in RAM. And the constants are names of various content types, so called MIME types. What’s going on? The browser don’t know what data is going to be sent by the server. It finds it out from Content-Type header, which will be described after a while.

Next, we’re getting rid of the slash: ++urltail;, after that we’re trying to open a file on SD card – in case of failure – displaying HTTP 404 (Not Found) error:

	if (! file.open(&root, urltail, O_READ)) {
		//Real 404
		webserver.httpNotFound();
  } else {

and in case of success, we will try to read it in else and send it to the client.

Now some annotations. First of all – SdFatLib only supports short filenames in 8.3 format. If you use longer names (which FAT32 allows), you must remember that the name visible for SdFatLib is different than the one you see in file manager. When you create index.html file (four characters in the extension), the name for SdFatLib would be ind~1.htm. Even after renaming it to index.htm, the catalog entry will be still in extended form. You have to delete the file and create it again with a new name in 8.3 format.

The second annotation – for obvious reasons we won’t worry about the subdirectories. We’re supposing all of files are in the root directory. Maybe in further versions I will add some support for more complex directory trees.

OK, let’s go back to the code fetchSD. If we succeeded to open the file, we’ll search for a dot in its name and check if the rest (after the dot) matches any of the known extensions. This is because it’s not enough to send the data itself to the client. A header with a proper Content-Type must be sent. Otherwise, the data could be interpreted wrong by the browser.

Speaking of it – how an response from a web server should look like. It’s divided into two parts. The first are so called headers. Web browsers treats everything at the beginning as headers, until it find a blank line (the lines are separated by CR LF). The rest is the answer itself. It depends on the headers, how it will be interpreted. The server can help web browsers by setting headers describing the type of data:

Content-type: text/html

Before the colon there is a name of the header (in this case, Content-Type) and after, its value. Here are used so called MIME types. For example image/png for PNG image, image/jpg for JPG and text/html for HTML.

An obligatory header is status – tells, if a client’s request was handled or an error or redirection occurred. HTTP/1.0 200 OK means everything is OK. At the first place is the protocol and its version (HTTP, version 1.0), next the 200 code – which means everything was done properly. Other frequently used codes are 404 – content not found, 301 and 302 – redirections.

Knowing that, we’ll try to recognize the file extension and send appropriate header:

	if (dot_index = strstr(urltail, ".")) {
		++dot_index;
		server.printP(OK);
		server.printP(CT);
		if (!strcmp(dot_index, "htm")) {
				server.printP(CT_HTML);

		} else if (!strcmp(dot_index, "css")) {
				server.printP(CT_CSS);

		} else if (!strcmp(dot_index, "jpg")) {
				server.printP(CT_JPG);

		} else {
				server.printP(CT_PLAIN);
		}
		server.print(CRLF);

Functions with big P at the end don’t expect char *, but const prog_uchar *, which is data type strings stored in flash.

Now we have already the HTTP header (ended with a blank line server.print(CRLF)), so it’s time to send data:

	readed = file.read(buf,30);
	while( readed > 0) {
		buf[readed] = 0;
		bufferedSend(server,buf,readed);
		readed = file.read(buf,30);
	}
	flushBuffer(server);
	file.close();

We’re reading by 30 bytes, sending to client through a function which buffers sent data. What for? If we use the simplest method and send data by one byte, then every single character will be in a separate TCP packet . Very (really, very) ineffective solution. Simply server.write sends the data instantly. We could read file by bigger chunks and send them directly to client. Ability to read file by one char and send response in bigger chunks will be used in second part of this tutorial.

For that reason I wrote bufferedSend function, receiving WWW server object, pointer to data buffer and size of the buffer as it’s parameters. Why don’t use functions returning the size of a string, like strlen? Because it will work only with text data. When the data is binary (like images), the a character denoting end of the text string could appear in legal data stream.

In C and C++ the end of a text string is 0 (not the digit 0, but a byte with value of 0). If in our data stream zeros could appear, all the functions provided by the standard library would be useless.

For that reason we need to define the amount of the data sent to the buffer.

Basically, that’s all. We already have WWW server sending data from SD card.

Does it have any sense?

After a couple of tests with more complex websites (not only one HTML file, but some CSSes and images) you will realize that this solution has certain limits. Arduino is single-threaded, so every element from our site is downloaded separately – we need to finish sending first file before sending another. This means, from the user’s point of view, the site loads slowly if we need to fetch HTML, some CSS, images.

So, how can this be useful? Arduino can present data collected with sensors in more friendly form if the limit of RAM memory could be bypassed. Keeping HTML code on SD card we are bypassing it. But how to put data collected by Arduino sensors to HTML page on SD?

We need something that will allow us to inject data to HTML between ‘reading’ and sending’. Something like:

PHP for Arduino

OK, it’s a bit exaggerated :) We need something more like templates not full PHP, but at it’s beginning PHP also wasn’t a miracle :)

How to make such a parser (and full sketch code) – in the next part. Stay tuned.

Arduino SMS and not only

GSM module for Arduino lets you convert it into a cell phone :) Well, somewhere about a cell phone.

Arduino with GSM module (a makeshift power supply in the background)

Arduino with GSM module (a makeshift power supply in the background)

Let’s start from the beginning. First, we need the the module and a valid SIM card. The first issue – power. The GSM module is quite demanding in this regard. Not every USB port provides enough power to feed an Arduino with GSM module. As a result, the communication breaks up immediately afer entering PIN code. In this case you will need an additional power supply. How to – more on that later.

Testing the module

GSM module can work in two serial comunication modes. It “talks” with Arduino or a computer connected to Arduino’s USB port. The first is used during normal operating, the second can be used for testing. To choose the second mode you should follow these steps:

  1. remove the ATMega from Arduino (Arduino will be used only as power supply, we will be utilizing also the USB/Serial converter)
  2. set operating mode jumpers to USB gateway
  3. insert SIM card
  4. connect Arduino to computer
  5. press ON/OFF button on module and hold it for two seconds
  6. start the terminal software (gtkterm), choose serial port (parameters: 115200 8,N,1, line ending – CR (not CR+LF)) and write AT commands in UPPERCASE
    • AT – the answer expected is “OK” – this means the connection has been estabilished
    • AT+CPIN=”ABCD” – where ABCD is the PIN code of SIM card inserted – we should get “OK” if it’s correct or “+CME ERROR 16” if not
    • the module starts to search for GSM network – if it will be returning “OK” for “AT” command in the next few seconds, means the USB port succeeded to power the device. In case of a failure, begin to prepare additional power supply
    • if it’s working we can try some commands:
      • AT+COPS? – returns the name of GSM provider
      • AT+CPBR=# – returns an entry from address book (# is a number)
      • AT*PSCPOF – turns the module off
      • ATD##########; – call the number # (of course, a conversation is impossible, for now)
      • ATH – ends the call
    • sending a SMS – follow these steps:
      • AT+CSCA? – download the SMS center number
      • AT+CMGF=1 – SMS sending mode – 1 is tezt
      • AT+CMGS=”#######” – target number
      • after AT+CMGS begin to enter the message content in a single line and end with character 0x1A (hex code)
      • wait for the SMS ;)

Full AT command list for Sagem HiLO modem is here.

GSM module has a microphone input and speaker output, so it’s able to act as regular cell phone :)

Power feeding

There is a jumper specifying power source. When set in “5V” position, Arduino is used for powering the module. By choosing “ext” we are able to power it from external power supply. The manufacturer reccomends a 12V, 2A supply. When using a supply with current efficiency lower than 2A, a 220 μF capacitor should be added. I tested whole device feeding Arduino from USB port and GSM module from 12/0.5A power supply with 200 μF capacitor and 5V voltage regulator (L7805).

1 - power socket and power source jumper, 2 - communication mode jumper

1 - power socket and power source jumper, 2 - communication mode jumper

Controlling it from Arduino

When serial mode communication jumper is set to Arduino, the module can be connected to Arduino serial port and controlled by commands sent from Arduino (using Serial.println). An example code:

int led = 13;
int onModulePin = 2;        // the pin to switch on the module (without press on button)
int timesToSend = 1;        // Numbers of SMS to send
int count = 0;

void switchModule(){

  digitalWrite(onModulePin,HIGH);
  delay(2000);
  digitalWrite(onModulePin,LOW);

}

void setup(){

  pinMode(led, OUTPUT);
  pinMode(onModulePin, OUTPUT);
  Serial.begin(115200);               // the GPRS baud rate
  switchModule();                    // swith the module ON

  for (int i=0;i<5;i++){
    delay(5000);
  }
   Serial.println("AT+CMGF=1");         // set the SMS mode to text
}

void loop(){

  while (count < timesToSend){
    delay(1500);

    Serial.print("AT+CMGS=");               // send the SMS the number
    Serial.print(34,BYTE);                  // send the " char
    Serial.print("*********");              // send the number change ********* by the actual number
    Serial.println(34,BYTE);                // send the " char
    delay(1500);
    Serial.print("Arduino SMS...");     // the SMS body
    delay(500);
    Serial.println(0x1A,BYTE);                // end of message command 1A (hex)
    delay(5000);
    count++;
  }

  if (count == timesToSend){
    Serial.println("AT*PSCPOF");             // switch the module off
    count++;
  }

}

Finally – as you can see, this module has a weird shape. Well, it fits perfectly to another shield – GPS :)

Arduino with GSM and GPS shields

Arduino with GSM and GPS shields

But about it later.

Programming the Arduino Pro Mini with USB Mini

Everyone, who has been making a project based on Arduino probably wanted the board to be smaller than the basic unit.

A variety of smaller, but compatible with Arduino, boards have been developed. One of them is SparkFun’s Arduino Pro Mini. Currently, it has ATmega328 onboard and its dimensions are 33 mm x 18 mm. It’s available in two versions. The first runs on lowered (3,3V) supply voltage, sacrificing clock frequency (up to 8 MHz). The latter version is a copy of an ordinary Arduino – works with 5V supply and the maximum frequency is 16 MHz.

If the board is so small, then what’s lacking? So, there is no USB/Serial converter (however, it lowers the price also). Because of that we need an additional device for programming it – USB/Serial TTL converter.

One of USB/Serial converters in Nettigo’s offer is Arduino Mini USB. Wiring it up and programming could cause some problems, so, here is a small HOWTO:

Manual programming

After resetting the device, Arduino bootloader is active for about a second. It waits for data on Serial and, if some binary data is present – transmission will be stored in Flash memory and started. Therefore, the simplest way is to connect Arduino Mini USB and Pro Mini like the following:

  • Connect USB Mini and Pro Mini grounds (GND z GND)
  • Supply voltage from USB Mini (+5V) to Vcc on Pro Mini
  • RX from USB Mini to RX1 on Pro Mini
  • TX from USB Mini to TX0 on Pro Mini

The outputs on USB Mini are unlabelled, so here is a pinout schematic (USB socket is at the left of this picture):

USB Mini pinout

USB Mini pinout

In practice, it looks like this:

Manual reset circuit

Manual reset circuit

A sketch needs to be compiled at first (the icon with a triangle) and compiled after that. In order to do it, press the reset button on Arduino Pro Mini and the upload button in Arduino IDE simultaneously (before that, choose the proper board in Tools/Board menu). TX i RX on USB Mini will start blinking and the sketch should be on Pro Mini after a while.

Automatic Reset or Software Reset

Since a long time ago, a regular Arduino can be easily programmed by clicking Upload in the IDE with no need for resetting it manually. In the case of Mini boards, often placed in difficult spots, this method is much better.

To accomplish it, we only have to connect USB Mini’s RTS output to any of RST inputs on Pro Mini:

Automatic (program) Arduino Pro Mini reset

Automatic (program) Arduino Pro Mini reset

I’ve used Bus Pirate probes here, because I hadn’t any pin headers soldered. From now on the programming only requires clicking Upload in Arduino IDE.

Remember the colours – a game

The following article is based on this entry on Newton’s blog (in Polish). All the pictures, program code and the video clip came from there.

This project’s goal was to use as many parts from the Arduino Starter Kit, as possible. So, what is this project exactly? As the title itself suggests, it’s a game, whose object is to remember a colour sequence and recreate it. At the very beginning the sequence consists of 3 colours only, hovever, the difficulty level increases – an extra colour is added each time. Every colour has a different tone assigned. This tone is emitted from a buzzer when the corresponding colour is displayed, so the game involves two senses, both sight and hearing. User interface consists of: RGB LED diode displaying the colours, 8 red LED diodes arranged in a row to display which colour in turn we are setting and two microswitch type buttons. By pushing both in the same time we are starting the game, the left button chooses the colour, the right – accepts. There are two more LED diodes, indicating whether we have recreated the sequence properly (left LED), or not (right LED).

Whole device mounted on a breadboard looks like the following:

Device mounted on a breadboard

You can see (and hear) how it works on this video clip. Hereunder is the circuit schematic made in Fritzing:

Circuit schematic

Circuit schematic

All the resistors used are 220Ω and the IC in the centre of the breadboard is 74HC595 shift register, which allows to drive eight LEDs using only three Arduino digital pins. This was described in “Shifted LEDs” article.

When everything is connected, we should take care of the code. At the beginning we must declare where we have connected what (to which input/output). The following code is responsible of it:

int latchPin = 8, clockPin = 12, dataPin = 3; //shift register
byte data = 0; //register data

int led8 = 7, led9 = 6; //additional LEDs
int ledR = 11, ledG = 10, ledB = 9; //LED RGB
int buttonLeft = 5, buttonRight = 4; //buttons
int speakerPin = 13; //buzzer

Here comes the initialization part – setting pin as input/output, turning internal pull-up resistors on and so on:

void setup()
{
  Serial.begin(57600);
  for(int i=3;i<=13;i++) // setting all the pins
    pinMode(i, OUTPUT); // from 3 to 13 as outputs
  pinMode(buttonLeft, INPUT); // setting the button pins
  pinMode(buttonRight, INPUT); // as inputs

  digitalWrite(buttonLeft, HIGH); // turning internal pull-up
  digitalWrite(buttonRight, HIGH); // resistors on
  randomSeed(analogRead(0)); // initializing the pseudorandom number generator
  // with the value read from analog input no. 0 
  // - each time it's different
  clearLeds();
}

If you are wondering what stands for such a strange notation:

 a ? b : c

here is the explanation.

The main loop of our program looks like the following:

void loop()
{
  effect();
  clearLeds();
  if(waitForButton() == 3)
    return;

  for(int j=3;j<=8;j++)
    if(!playLevel(7, j))
      return;
}

Consecutively: at the beginning, effect() function turns on visual and light effects, clearLeds turns all the LEDs off. After that, unless the user pushes both buttons at the same time, what will cause a reset, playLevel function starts successive levels of the game, increasing the second parameter (number of the lights to remember) by 1. The first parameter denotes the total number of colours (from 0 to 7). Of course, we can lower it, but then the game will become too easy. It’s better to add another colours using setColor function (changing parameters in setRGB) and upgrade it. Then, we can put the total number of colours (remember – the numeration starts from 0!) as the first parameter of playLevel function to make the game more difficult and hence – more addicting ;).

The whole program code with comments is available here. I think it’s clear enough and doesn’t require any additional explanations.

Self-made Arduino shield – making a PCB

Sooner or later, everyone bitten by Arduino bug would want to make his own extension. At the beginning Proto Shield may be sufficient.

When we have a working prototype, we might want to convert it into a series model, so PCB board will be needed.

PCB

Time for self-made PCB CC by http://www.flickr.com/photos/odinhg/

On Arduino Forum there is a link to a very nice tutorial, how to make our own PCB board, especially for Arduino shields.

Aaron Eiche, author of the article is a member of DorkbotPDX group, which makes orders for PCBs and everyone can order with them the price is quite attractive – $5 for square inch of a double sided board + $15 for shipment (worldwide). It must be ordered in multiples of 3.