Programming Arduino Uno (ATmega386P) in assembly

_1_intro.md

There are a few different sources online that describe the ways that you can program Arduino Uno/ATmega328P in assembly, and in the last couple of days I've had to switch through most of them just to get the basic setup and initial programs working. This is an attempt to aggregate all those sources in a centralized document, with two simple example programs.

Requirements

There are two major options for the task (of which I'm aware of), and the setup I've settled on is accidental in retrospect¹. But you might research on your own the alternative setup based around the AVR Libc project.

For the setup I use you need: avrdude and avra. Do note that I'm using a Linux box, and in case you're on another operating system you'll be on your own with the setup/configuration of these tools.

Optional (but must read)

When connected via USB my Uno would have it's serial interface mapped to /dev/ttyACM0. Because I wanted a more intuitive device name (and the fact that it took me some time to find out what device name it had in the first name), I wrote an udev rule to map my Uno board to /dev/arduino-uno.

$ cat /etc/udev/rules.d/10-arduino.rules
KERNEL=="ttyACM0", SYMLINK+="arduino-uno", OWNER="mhitza"

If you do the symlink, be sure to also include the OWNER directive; otherwise every time you upload the new program to your Uno you will have to call avrdude with sudo.

NOTE If you skipped this step, be sure to replace any occurence of /dev/arduino-uno with /dev/ttyACM0, and prefix all avrdude calls with sudo in the followup Makefile.

Also you'll see a reference to picocom (program used for serial communication with the board) in the Makefile I use, and it should work but I haven't tested it yet.

A simple Makefile

NOTE There is already a popular Makefile project for Arduino, however that one relies on the AVR Libc project. And as with other "prepackaged" solutions, like oh-my-zsh, I prefer to start from a small base. I find it easier to understand and maintain.

The makefile is available towards the end of the page.

Given a program named blink.asm

• make (or make blink.hex) - compile it to a hex file
• make program=blink upload - upload the program to your Arduino board. If you didn't run the previous step manually it will also compile the program for you
• make monitor - monitor serial data

Where do the names come from?

When reading other example assembly code online you will find references to named constants that are not built into the assembler. Those usually come from m328Pdef.inc. From where you download that file doesn't really matter, since basically everyone is carrying a copy around with them; or so it seems.²

I personally use it as a learning reference, and I would recommend you copy only the definitions you need in your program until you get familiar with the names. That's the way I approach it, as you'll see in my example programs.

The project for the sample code

Project rendered on 123d.circuits.io

Three LEDs and a simple switch. With each press on the switch the LEDs turn on (from left to right), one by one, and once the red LED is reached further presses will turn off the LEDs in reverse order until we reach the initial state. Rinse and repeat.

Two implementations will be shown, the first one is the way most people - I think - would write the implementation (in terms on reacting to button presses, not necessary how they'd toggle the LEDs) (assuming they don't know about interrupts yet), and the second version will use an interrupt instead of "polling" the pin for voltage (state) changes.

References

NOTE the assembler manual is for AVRASM32.exe, not avra. However avra is a compatible assembler, with just a few extra features

NOTE if you see online references to avrasm2, you have to know that piece of software is different from AVRASM32.exe and avra. And avra is highly unlikely to be able to compile code written for that assembler.

You need to keep these references close by when programming AVR in assembly:

• Atmel AVR 8-bit Instruction Set - Atmel Corporation
• AVR Assembler Guide

---

1. Initially I started with avr-as, but the helpfull stackoverflow answers I've found pointed to avra and as soon as I was able to write a simple program I didn't look back. jump to reference
2. Maybe it could matter where you download it from. Some dastardly individual might provide that file in an altered format where the mappings wouldn't be correct and you'd write to the wrong memory bits and spend hours/days debugging the assembly code. jump to reference

_2_intermission_assembly.md

While mentioned in the previous document that you should download the assembly instruction set manual, for the following examples I'd like to detail the instructions I will use (so that you can follow along the code examples).

• jmp label or rjmp label - jump to a label
• sbi memory_location, bit_position - set bit immediate¹
• cbi memory_location, bit_position - clear bit immediate
• clr register - clear register
• sbis memory_location, bit_position - skip branch immediate (bit) set²
• sbic memory_location, bit_position - skip branch immediate (bit) clear
• tst register - test register for zero or negative number, if true, the Z flag is set³
• brne label - branch not equal
• ldi register, byte_value - load data immediate
• reti - return from interrupt
• out memory_location, register - write a register to a memory location
• lds register, data_space - load from data space (register, I/O memory, SRAM) into register
• ori register, byte_value - bitwise OR immediate
• sts register, data_space - store to data space from register
• sei - enable interrupts
• in register, memory_location - read memory location into register

---

1. Immediate here means that a value (bit_position/byte_value) can be specified directly for the operation. jump to reference
2. With skip branch instructions, when the comparison turns out to be true the followup instruction is skipped. Most of the time that followup instruction would be a jmp. jump to reference
3. There are a couple of instructions that work on implicit values inside the SREG registry. For example the Z flag is bit 1 in that register. tst is one of the many instructions that sets that value, while the brne/breq instructions are two example instructions that make use of the Z bit value. jump to reference

blink.asm

; Copyright 2015 Marius Ghita
;
; Licensed under the Apache License, Version 2.0 (the "License");
; you may not use this file except in compliance with the License.
; You may obtain a copy of the License at
;
;     http://www.apache.org/licenses/LICENSE-2.0
;
; Unless required by applicable law or agreed to in writing, software
; distributed under the License is distributed on an "AS IS" BASIS,
; WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
; See the License for the specific language governing permissions and
; limitations under the License.


; Everything after a semicolon is a comment

; We specify the Atmel microprocessor. The Uno uses ATmega328P,
; older versions might use ATmega328 
.device ATmega328P

; These are all constant definitions taken from m328Pdef.inc
; and we will go in more detail of what they are, when they
; are used
.equ PORTB = 0x05
.equ PORTD = 0x0b
.equ PIND  = 0x09
.equ DDRB  = 0x04
.equ DDRD  = 0x0a

; At ORiGin 0x0000 we "hook" in our call to our programm main
; we do not write our program here, as of why, we will go over
; that later
.org 0x0000
    jmp main

; DDR* are used just for specifing what will be an input
; pin, and what will be an output pin.
main:
    ; DDRB maps over pins 8-13.
    ; We set[1] pin 10 and 12 (starting DDRB pin is 8):
    ;  - 8 + 2 = 10
    ;  - 8 + 4 = 12
    ; [1] Set means we assign the bit value to 1 = output
    sbi DDRB, 2
    sbi DDRB, 4
    ; DDRD maps over pins 0-7
    ; We set pin 5: 0 + 5 = 5
    sbi DDRD, 5
    
    ; DDRD maps over pins 0-7
    ; We clear the 2nd bit: 0 + 2 = 2
    ; Clear means we assign the bit value to 0 = input
    cbi DDRD, 2
    ; just set register r20 to 0
    clr r20

; tight loops polling pin information to see when either
; there's voltage (bit set - check_press_loop) on pin 2,
; or not (bit clear - check_release_loop)
check_press_loop:
    ; if input on pin 2, skip next instruction
    sbis PIND, 2
    rjmp check_press_loop  ; this is the one we will skip
    rjmp toggle_leds
check_release_loop:
    ; if input on pin 2, loop once more
    ; if clear pin 2, switch to button press check loop
    sbic PIND, 2
    rjmp check_release_loop
    rjmp check_press_loop

toggle_leds:
    tst r20
    brne off_pins
    sbis PORTB, 4
    rjmp set_pin_12 ; if pin 12 is not on, set it
    sbis PORTB, 2
    rjmp set_pin_10 ; if pin 10 is not on, set it
    sbis PORTD, 5
    rjmp set_pin_5 ; if pin 5 is not on, set it
all_on:
    ; once it falls through and we set 1 to r20 the first check
    ; in toggle_leads should make sense
    ldi r20, 1
    rjmp check_release_loop
off_pins:
    sbic PORTD, 5
    rjmp off_pin_5
    sbic PORTB, 2
    rjmp off_pin_10
    sbic PORTB, 4
    rjmp off_pin_12
all_off:
    ; now we go back to our initial state and the whole program loops
    ldi r20, 0
    rjmp check_release_loop

; We use PORT* to write to a pin configured as output (in our main)
; As with DDR*:
;   - PORTB maps over pins 8-13 (just like DDRB)
;   - PORTD maps over pins 0-7 (just like DDRD)
set_pin_12:
    sbi PORTB, 4
    rjmp check_release_loop
off_pin_12:
    cbi PORTB, 4
    rjmp all_off

set_pin_10:
    sbi PORTB, 2
    rjmp check_release_loop
off_pin_10:
    cbi PORTB, 2
    rjmp check_release_loop

set_pin_5:
    sbi PORTD, 5
    rjmp all_on
off_pin_5:
    cbi PORTD, 5
    rjmp check_release_loop

; NOTE a program must never terminate. If you're not processing something
; in a loop like this program did, you can just add an infinite loop at 
; the end, like
;
; loop:
;      rjmp loop

blink_interrupt.asm

; Copyright 2015 Marius Ghita
;
; Licensed under the Apache License, Version 2.0 (the "License");
; you may not use this file except in compliance with the License.
; You may obtain a copy of the License at
;
;     http://www.apache.org/licenses/LICENSE-2.0
;
; Unless required by applicable law or agreed to in writing, software
; distributed under the License is distributed on an "AS IS" BASIS,
; WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
; See the License for the specific language governing permissions and
; limitations under the License.

.device ATmega328P
.equ SREG = 0x3f
.equ RAMEND = 0x08ff
.equ SPL = 0x3d
.equ SPH = 0x3e
.equ EICRA = 0x69
.equ EIMSK = 0x1d
.equ DDRB  = 0x04
.equ DDRD  = 0x0a
.equ PORTB = 0x05
.equ PORTD = 0x0b

.org 0x0000
    jmp reset
    
; memory location for interrupt 0 (PIN 2)
.org 0x0002
    jmp pushed_button

; The code here is mostly similar to the one written in the previous example
; The only major difference is that the jumps back to the main loop have been
; replaced with reti calls, since this is a interrupt handler
pushed_button:
    tst r20
    brne off_pins
    sbis PORTB, 4
    rjmp set_pin_12
    sbis PORTB, 2
    rjmp set_pin_10
    sbis PORTD, 5
    rjmp set_pin_5
    all_on:
        ldi r20, 1
        reti
    off_pins:
        sbic PORTD, 5
        rjmp off_pin_5
        sbic PORTB, 2
        rjmp off_pin_10
        sbic PORTB, 4
        rjmp off_pin_12
    all_off:
        ldi r20, 0
        reti
    set_pin_12:
        sbi PORTB, 4
        reti
    off_pin_12:
        cbi PORTB, 4
        rjmp all_off

    set_pin_10:
        sbi PORTB, 2
        reti
    off_pin_10:
        cbi PORTB, 2
        reti

    set_pin_5:
        sbi PORTD, 5
        rjmp all_on
    off_pin_5:
        cbi PORTD, 5
        reti

reset:
    sbi DDRB, 2
    sbi DDRB, 4
    sbi DDRD, 5

    ; The stack is used by the MCU to store the return address from the interrupt handler 
    ; and we have to manually initialize the stack; by writting
    ; the SPL (stack pointer low) and SPH (stack pointer high) memory
    ; locations with the RAMEND information we know for our device
    ldi r16, LOW(RAMEND)
    out SPL, r16
    ldi r16, HIGH(RAMEND)
    out SPH, r16

    ; load in register r17 EICRA (External Interrupt Control Register) and
    ; set the bit 1, which means our interrupt handler is called when there's
    ; a low to high voltage change on our PIN2
    lds r17, EICRA
    ori r17, 0b00000010
    sts EICRA, r17

    ; we enable our INT0 (PIN2) by setting bit 0 on EIMSK (bit 1 would be used
    ; if we wanted to use INT1 (PIN3) instead
    in r18, EIMSK
    ori r18, 0b00000001
    out EIMSK, r18

    sei ; enable interrupt handler

; since programs can't terminate, and our logic is done in the interrupt handler
; we do an infinite loop. Alternatively you can research the sleep instruction
; and use that here as well, that way power usage will be small and the MCU will
; awake itself when the interrupt is triggered
main: rjmp main

Makefile

%.hex: %.asm
	avra -fI $<
	rm *.eep.hex *.obj *.cof

all: $(patsubst %.asm,%.hex,$(wildcard *.asm))

upload: ${program}.hex
	avrdude -c arduino -p m328p -P /dev/arduino-uno -b 115200 -U flash:w:$<

monitor:
	picocom --send-cmd "ascii_xfr -s -v -l10" --nolock /dev/arduino-uno

.PHONY: all upload monitor

z_end.md

You are encouraged to implement the simple Arduino project presented, download the files (there's a download button at the top) and build the project. If you're unfamiliar with the resistor values from the attached image, here's the handy cheat sheet I'm using.

Taken from the "Arduino Projects Book", licensed under CreativeCommons BY-NC-SA 3.0

---

Except where otherwise noted, this work is licensed under a Creative Commons Attribution 4.0 International License.

Hi! I added links to references in the different files (like the [1] goes to the reference and jump to reference goes back to the text) with a bit of html in my fork : it would be useful if you merged these changes in your own gist [1].

@lapingenieur I took in your changes in spirit, but "markdownified it" back a bit, dropped square brackets on the backreferences, and switched to superscripts for references. If you haven't tried it already, I highly recommend Vimwiki or any other markdown vim plugin, the first two changes just made it a better reading experience in vim 🔥

Thanks, and I hope you got some use out of this document.

I thought we couldn't write markdown on lines containing html, it always broke what I did. Is there something to do or am I just stupid 😂 ?

Yes, this gist is so useful, thank you really much !