simplified example & added readme

README.md

@@ -1,2 +1,46 @@
-# avr-c-boilerplate
-Basic boilerplate for programming AVR (arduino) in C.
+# AVR C Builerplate
+
+This is a basic boilerplate for programming AVRs in C.
+
+The project aims to make programming Arduinos in C fun by
+providing support for basic functionality like GPIO and USART,
+so you can start developing without having the datasheet open
+all the time.
+
+It is intended for **ATmega328P** (the chip in Arduinos),
+but can be easily adapted to other parts.
+
+## Requirements
+
+Before you can start coding, you need to install a few software packages:
+
+- `avrdude` - the flash tool
+- `avr-gcc` - compiler
+- `avr-libc` - libc implementation for AVR
+- `avr-binutils` - utils for manipulating AVR binaries
+- `make` - to run the Makefile
+
+There's a good chance you already have `make`, the rest should be in your
+distribution's repos.
+
+If you're on Arch:
+
+```
+# pacman -S base-devel avr-gcc avr-binutils avr-libc avrdude
+```
+
+If you're on Mac, you should be able to pull the software with *brew*.
+
+## Getting started
+
+The provided main.c is a good starting point - it contains some simple demo code.
+
+You can compile it with `make` and flash with `make flash`.
+
+If you add a new C file to the project, add an entry for it's `.o` (object file,
+created by the compiler before linking) to the `OBJS` list in the Makefile.
+
+Similarly, if you add a new folder with header files, add it to `INCL_DIRS`.
+
+The Makefile should take care of everything for you, this is the only modification
+you should have to do.

lib/usart.h

@@ -14,6 +14,22 @@
 #include <stdbool.h>
 #include <stdint.h>
 
+
+/* USART BAUD RATE REGISTER values at 16 MHz */
+enum {
+	BAUD_9600 = 103,
+	BAUD_14400 = 68,
+	BAUD_19200 = 51,
+	BAUD_28800 = 34,
+	BAUD_38400 = 25,
+	BAUD_57600 = 16,
+	BAUD_76800 = 12,
+	BAUD_115200 = 8,
+	BAUD_250k = 3,
+	BAUD_500k = 1,
+	BAUD_1M = 0,
+};
+
 /** Init UART with a UBRR value */
 void usart_init(uint16_t ubrr);
 

main.c

@@ -10,7 +10,6 @@
 #include "lib/iopins.h"
 #include "lib/usart.h"
 
-void main() __attribute__ ((noreturn));
 
 // Pins
 #define LED 13
@@ -19,6 +18,7 @@ void main() __attribute__ ((noreturn));
 // UART receive handler
 ISR(USART_RX_vect)
 {
+	// "ECHO" function:
 	uint8_t b = usart_rx();
 	usart_tx(b); // send back
 }
@@ -26,7 +26,7 @@ ISR(USART_RX_vect)
 
 void main()
 {
-	usart_init(8); // set usart @ 115200 (8 is a UBRR value)
+	usart_init(BAUD_9600);
 	usart_rx_isr_enable(true); // enable RX interrupt handler
 
 	// configure pins
@@ -36,17 +36,9 @@ void main()
 	sei();
 
 	while (1) {
-		// This string is in the program memory
-		// PSTR is a special macro that puts it there.
-		// That means it does not waste ram space, but
-		// needs special treatment when being read.
-		// (avr-gcc is a bit dumb in this)
-		usart_puts_P( PSTR("Hello World\r\n") ); // Print a string to USART
+		usart_puts("Hello World!\r\n");
 
-		// This one is copied to RAM before being printed = bad.
-		usart_puts("Wastin' RAM!\r\n");
-
-		pin_toggle(13);
+		pin_toggle(13); // blink the LED
 
 		_delay_ms(500);
 	}