API referencestd/embedded

std/embedded/chip/atmega328p

Public declarations, types, methods, and source contracts for std/embedded/chip/atmega328p.

On this page

Library guide · API index and notation

This page is generated from the bundled library in this checkout. Signatures and adjacent source comments are reproduced below; the linked guide explains usage, storage, failures, and platform support.

import "std/embedded/chip/atmega328p"

Names used in signatures

Unqualified names denote this package’s types (including other source files in the same package), language built-ins, or generic parameters such as T. Qualified names use the import aliases below. These aliases belong to the library source; import a dependency yourself to use its alias in your program.

Alias Package Source file
hal std/embedded/hal atmega328p.dodo
io std/io atmega328p.dodo
mmio core/mmio atmega328p.dodo
serial std/embedded/hal/serial atmega328p.dodo

PIN_COUNT

Constant · Source

pub const PIN_COUNT: u32 = 20

PD0

Constant · Source

pub const PD0: u32 = 0

PD1

Constant · Source

pub const PD1: u32 = 1

PD2

Constant · Source

pub const PD2: u32 = 2

PD3

Constant · Source

pub const PD3: u32 = 3

PD4

Constant · Source

pub const PD4: u32 = 4

PD5

Constant · Source

pub const PD5: u32 = 5

PD6

Constant · Source

pub const PD6: u32 = 6

PD7

Constant · Source

pub const PD7: u32 = 7

PB0

Constant · Source

pub const PB0: u32 = 8

PB1

Constant · Source

pub const PB1: u32 = 9

PB2

Constant · Source

pub const PB2: u32 = 10

PB3

Constant · Source

pub const PB3: u32 = 11

PB4

Constant · Source

pub const PB4: u32 = 12

PB5

Constant · Source

pub const PB5: u32 = 13

PC0

Constant · Source

pub const PC0: u32 = 14

PC1

Constant · Source

pub const PC1: u32 = 15

PC2

Constant · Source

pub const PC2: u32 = 16

PC3

Constant · Source

pub const PC3: u32 = 17

PC4

Constant · Source

pub const PC4: u32 = 18

PC5

Constant · Source

pub const PC5: u32 = 19

UART_RX_PIN

Constant · Source

Fixed functions of pins.

pub const UART_RX_PIN: u32 = PD0

UART_TX_PIN

Constant · Source

pub const UART_TX_PIN: u32 = PD1

I2C_SDA_PIN

Constant · Source

pub const I2C_SDA_PIN: u32 = PC4

I2C_SCL_PIN

Constant · Source

pub const I2C_SCL_PIN: u32 = PC5

SPI_SELECT_PIN

Constant · Source

pub const SPI_SELECT_PIN: u32 = PB2

SPI_TX_PIN

Constant · Source

pub const SPI_TX_PIN: u32 = PB3

SPI_RX_PIN

Constant · Source

pub const SPI_RX_PIN: u32 = PB4

SPI_CLOCK_PIN

Constant · Source

pub const SPI_CLOCK_PIN: u32 = PB5

EEPROM_BYTES

Constant · Source

The EEPROM’s size, and the erase block it reports to the Flash protocol: four blocks of the 256 bytes std/embedded/storage needs at least.

pub const EEPROM_BYTES: u32 = 1024

EEPROM_BLOCK

Constant · Source

pub const EEPROM_BLOCK: u32 = 256

ANALOG_MAX

Constant · Source

The analog-to-digital converter’s 10-bit range.

pub const ANALOG_MAX: u16 = 1023

Config

Struct · Source

What the circuit board decides. Board packages pass theirs to take.

pub struct Config {
    // The CPU clock in hertz, from the crystal or resonator: 16 MHz on the
    // Arduino Uno. 1, 2, 4, 8 and 16 MHz are supported, for the
    // microsecond time base.
    pub cpu_hz: u32
}

Peripherals

Struct · Source

The chip’s peripherals, from take.

pub struct Peripherals {
    pub pins: Pins
    pub timer: Timer
    pub watchdog: Watchdog
    pub eeprom: Eeprom
}

take

Function · Source

Start the time base and return the peripherals. A second call returns Error.Busy, so no two owners exist; an unsupported clock returns Error.InvalidInput.

pub fn take(config: Config) -> Peripherals!hal.Error

reset_flags

Function · Source

Why the chip last started, from MCUSR at reset: bit 0 power-on, 1 the reset pin, 2 brown-out, 3 the watchdog. Bootloaders such as the Arduino Uno’s clear it before starting the program, so there it reads 0.

pub fn reset_flags() -> u8

restart

Function · Source

Restart the chip through the watchdog: it resets 16 ms later. Does not return. The Arduino Uno’s bootloader starts the program again at once.

pub fn restart()

flash_byte

Function · Source

One byte of program memory at address, such as a panic message.

pub fn flash_byte(address: u16) -> u8

Pins

Struct · Source

The GPIO pins and the peripherals on them. Each pin and peripheral is handed out once until released; a second claim returns Error.Busy, and a pin number from PIN_COUNT on returns Error.InvalidInput.

pub struct Pins {

}

Pins.output

Function · Source

A push-pull output, low until set. Claims the pin.

pub fn output(&mut self, number: u32) -> Pin!hal.Error

Pins.input

Function · Source

An input without pull-up, for a line another device drives.

pub fn input(&mut self, number: u32) -> Pin!hal.Error

Pins.input_pull_up

Function · Source

An input with the internal pull-up (20 to 50 kOhm), for a button to ground: high while released.

pub fn input_pull_up(&mut self, number: u32) -> Pin!hal.Error

Pins.release

Function · Source

Give back a pin: it becomes an input without pull-up.

pub fn release(&mut self, pin: Pin)

Pins.uart

Function · Source

The serial port (USART0) on tx (PD1) and rx (PD0), or transmit only with rx none, at baud, 8 data bits, no parity, 1 stop bit. InvalidInput for other pins, or a baud rate the clock cannot make within 2.5 %.

pub fn uart(&mut self, tx: u32, rx: Option<u32>, baud: u32) -> Serial!hal.Error

Pins.release_uart

Function · Source

pub fn release_uart(&mut self, port: Serial)

Pins.i2c

Function · Source

The I2C bus (TWI) on sda (PC4) and scl (PC5), as controller, at up to frequency_hz (100 kHz or 400 kHz usually). The internal pull-ups are on; most modules add their own. InvalidInput for other pins or a frequency the clock cannot divide down to.

pub fn i2c(&mut self, sda: u32, scl: u32, frequency_hz: u32) -> I2c!hal.Error

Pins.release_i2c

Function · Source

pub fn release_i2c(&mut self, bus: I2c)

Pins.spi

Function · Source

The SPI bus as controller on clock (PB5), tx (PB3) and rx (PB4, or none to leave it free), in mode, at the fastest rate up to frequency_hz: the clock divided by 2, 4, … 128. PB2, the controller’s select input, must stay an output while the bus runs; the bus claims it too, and select() hands it out as the chip select of one device. InvalidInput for other pins or a frequency below the clock / 128.

pub fn spi(&mut self, clock: u32, tx: u32, rx: Option<u32>, mode: hal.SpiMode, frequency_hz: u32) -> Spi!hal.Error

Pins.release_spi

Function · Source

pub fn release_spi(&mut self, bus: Spi)

Pins.pwm

Function · Source

A PWM output on pin at about frequency_hz. Timer 1 serves PB1 and PB2 at any frequency from 1 Hz up, with up to 16-bit resolution; both share one frequency, so the second must ask for the same. Timer 2 serves PD3 and PB3 at the nearest of its seven fixed frequencies (62.5 kHz down to 61 Hz at 16 MHz), with 8-bit resolution, again shared. PD5 and PD6 run on the time base’s Timer 0, at its 976 Hz whatever frequency_hz is. InvalidInput for another pin, a frequency of 0, or Timer 1 at a frequency its other output does not use.

pub fn pwm(&mut self, pin: u32, frequency_hz: u32) -> Pwm!hal.Error

Pins.release_pwm

Function · Source

pub fn release_pwm(&mut self, output: Pwm)

Pins.analog

Function · Source

An analog input on PC0 to PC5 (A0 to A5): 0 at ground to ANALOG_MAX at the supply voltage (AVCC, 5 V on the Uno). Disables the pin’s digital input buffer, which saves power. InvalidInput for another pin.

pub fn analog(&mut self, pin: u32) -> Analog!hal.Error

Pins.temperature

Function · Source

The temperature sensor, an analog input against the internal 1.1 V reference: about 352 at 25 C, rising 1.28 per degree; millicelsius converts a reading. Busy if it is out already.

pub fn temperature(&mut self) -> Analog!hal.Error

Pins.release_analog

Function · Source

pub fn release_analog(&mut self, input: Analog)

Pin

Struct · Source

One GPIO pin, from Pins.output or Pins.input. Implements the hal OutputPin and InputPin protocols.

pub struct Pin: hal.OutputPin + hal.InputPin {
    // Private implementation fields omitted.
}

Pin.set_high

Function · Source

pub fn set_high(&mut self)

Pin.set_low

Function · Source

pub fn set_low(&mut self)

Pin.toggle

Function · Source

Writing a one to PIN toggles the output in one step.

pub fn toggle(&mut self)

Pin.is_high

Function · Source

pub fn is_high(&self) -> bool

Pin.set_as_output

Function · Source

Drive the pin at its output level, for a line that changes direction.

pub fn set_as_output(&mut self)

Pin.set_as_input

Function · Source

Stop driving the pin; is_high reads it.

pub fn set_as_input(&mut self)

Pin.set_pull_up

Function · Source

The internal pull-up of an input pin (the PORT bit while it is an input).

pub fn set_pull_up(&mut self, on: bool)

Pin.number

Function · Source

The pin’s number, as given to Pins.

pub fn number(&self) -> u32

Timer

Struct · Source

Microseconds since take, from Timer 0, which ticks every 64 cycles (4 us at 16 MHz), and busy-waiting delays. Implements the hal Delay and Counter protocols.

pub struct Timer: hal.Delay + hal.Counter {
    // Private implementation fields omitted.
}

Timer.now_us

Function · Source

Microseconds since take(), in steps of 64 cycles.

pub fn now_us(&self) -> u64

Timer.delay_us

Function · Source

Busy-wait microseconds, counting cycles, so it also works with interrupts masked; interrupt handlers that run meanwhile lengthen it.

pub fn delay_us(&mut self, microseconds: u32)

Timer.delay_ms

Function · Source

pub fn delay_ms(&mut self, milliseconds: u32)

Serial

Struct · Source

The serial port, USART0, from Pins.uart. Implements std/io’s Reader and Writer and the serial Port and PollPort protocols, so std/fmt writes to it. Received bytes wait in the runtime’s 32-byte buffer until read; bytes arriving while it is full are dropped and reported as Overrun on the next read.

pub struct Serial: serial.Port + serial.PollPort {
    // Private implementation fields omitted.
}

Serial.baud

Function · Source

pub fn baud(&self) -> u32

Serial.set_crlf

Function · Source

Send each “\n” as “\r\n”, as terminals expect.

pub fn set_crlf(&mut self, on: bool)

Serial.write

Function · Source

Send all of bytes, waiting for room.

pub fn write(&mut self, bytes: &[u8]) -> usize!io.Error

Serial.poll_write

Function · Source

Queue what the transmitter has room for: one byte (a “\n” with CR LF on, once there is room for its “\r”).

pub fn poll_write(&mut self, bytes: &[u8]) -> io.Poll!io.Error

Serial.flush

Function · Source

Wait until every byte written has left, stop bit included.

pub fn flush(&mut self) -> void!io.Error

Serial.poll_flush

Function · Source

pub fn poll_flush(&mut self) -> bool!io.Error

Serial.read

Function · Source

Wait for the first byte, then return what has arrived, up to buffer.len. Errors with io.ErrorKind.Other, code the error bits, after bytes were lost or garbled (0x01 dropped from a full buffer, 0x04 parity, 0x08 overrun, 0x10 framing); the next read continues after them. InvalidInput on a transmit-only port.

pub fn read(&mut self, buffer: &mut[u8]) -> usize!io.Error

Serial.poll_read

Function · Source

Return what has arrived, up to buffer.len, without waiting.

pub fn poll_read(&mut self, buffer: &mut[u8]) -> io.Poll!io.Error

I2c

Struct · Source

The I2C bus as controller, from Pins.i2c. Implements hal.I2c. Each operation waits for the bus with a time limit, so a stuck bus reports Timeout instead of hanging.

pub struct I2c: hal.I2c {
    // Private implementation fields omitted.
}

I2c.frequency_hz

Function · Source

The SCL frequency the divider gives.

pub fn frequency_hz(&self) -> u32

I2c.write

Function · Source

pub fn write(&mut self, address: u8, bytes: &[u8]) -> void!hal.Error

I2c.read

Function · Source

pub fn read(&mut self, address: u8, buffer: &mut[u8]) -> void!hal.Error

I2c.write_read

Function · Source

pub fn write_read(&mut self, address: u8, bytes: &[u8], buffer: &mut[u8]) -> void!hal.Error

Spi

Struct · Source

The SPI bus as controller, from Pins.spi. Implements hal.Spi; pair it with an output pin as chip select (hal.SpiDevice), PB2 included.

pub struct Spi: hal.Spi {
    // Private implementation fields omitted.
}

Spi.frequency_hz

Function · Source

The clock rate the divider gives.

pub fn frequency_hz(&self) -> u32

Spi.select

Function · Source

PB2, which the bus keeps as an output, as an output pin for a device’s chip select. Give it back with deselect before releasing the bus.

pub fn select(&mut self) -> Pin

Spi.deselect

Function · Source

pub fn deselect(&mut self, pin: Pin)

Spi.transfer

Function · Source

pub fn transfer(&mut self, bytes: &mut[u8]) -> void!hal.Error

Spi.write

Function · Source

pub fn write(&mut self, bytes: &[u8]) -> void!hal.Error

Pwm

Struct · Source

A PWM output, from Pins.pwm. Implements hal.PwmOutput.

pub struct Pwm: hal.PwmOutput {
    // Private implementation fields omitted.
}

Pwm.max_duty

Function · Source

pub fn max_duty(&self) -> u16

Pwm.set_duty

Function · Source

Fast PWM is high for compare + 1 of every max + 1 counts, and constantly high with compare at max; 0 disconnects the output, which holds the pin low.

pub fn set_duty(&mut self, duty: u16) -> void!hal.Error

Pwm.pin

Function · Source

pub fn pin(&self) -> u32

Analog

Struct · Source

An analog input, from Pins.analog or Pins.temperature. Implements hal.AnalogInput. A conversion takes 13 converter clocks, 104 us at 16 MHz.

pub struct Analog: hal.AnalogInput {
    // Private implementation fields omitted.
}

Analog.max_value

Function · Source

pub fn max_value(&self) -> u16

Analog.read

Function · Source

Convert once. After a switch to another reference, the capacitor on AREF (100 nF on the Uno) takes milliseconds to charge or discharge, so conversions are discarded for about 20 ms first, with interrupts enabled between them.

pub fn read(&mut self) -> u16!hal.Error

Analog.pin

Function · Source

pub fn pin(&self) -> u32

millicelsius

Function · Source

The temperature in thousandths of a degree Celsius that a reading of the temperature sensor shows, from the datasheet’s typical values (269 at -40 C, 352 at 25 C, 480 at 125 C: 1.28 per degree). Chips differ by up to about 10 degrees; calibrate with an offset of your own where that matters.

pub fn millicelsius(value: u16) -> i32

Watchdog

Struct · Source

The watchdog: stopped until start, it then resets the chip unless feed is called within the timeout. Implements hal.Watchdog.

pub struct Watchdog: hal.Watchdog {
    // Private implementation fields omitted.
}

Watchdog.max_timeout_ms

Function · Source

The longest timeout, 8 s.

pub fn max_timeout_ms(&self) -> u32

Watchdog.start

Function · Source

Start (or restart) with the longest of the watchdog’s timeouts, 16, 32 or 64 ms, 0.125 to 8 s in powers of two, that does not exceed timeout_ms. InvalidInput below 16 ms or above max_timeout_ms().

pub fn start(&mut self, timeout_ms: u32) -> void!hal.Error

Watchdog.feed

Function · Source

pub fn feed(&mut self)

Watchdog.stop

Function · Source

pub fn stop(&mut self)

Watchdog.reset_reason

Function · Source

Whether the watchdog reset the chip last time, from the reset flags. The Arduino Uno’s bootloader clears them, so there it reads Other.

pub fn reset_reason(&self) -> hal.ResetReason

Eeprom

Struct · Source

The 1 KiB EEPROM, which keeps its bytes without power for about 100,000 writes each. read and update are the usual way to keep settings:

saved: [4]u8 = [0u8; 4] b.eeprom.read(0, &mut saved)! b.eeprom.update(0, &saved)!

It also implements hal.Flash, with EEPROM_BLOCK-byte erase blocks and single-byte writes, for drivers written against that protocol; std/embedded/storage’s key-value store takes more flash than the ATmega328P has. A byte takes 3.4 ms to erase and write, 1.8 ms for each alone.

pub struct Eeprom: hal.Flash {

}

Eeprom.capacity

Function · Source

pub fn capacity(&self) -> u32

Eeprom.erase_size

Function · Source

pub fn erase_size(&self) -> u32

Eeprom.write_size

Function · Source

pub fn write_size(&self) -> u32

Eeprom.read

Function · Source

pub fn read(&mut self, offset: u32, buffer: &mut[u8]) -> void!hal.Error

Eeprom.erase

Function · Source

Set the range to 0xFF, skipping bytes that already are.

pub fn erase(&mut self, offset: u32, length: u32) -> void!hal.Error

Eeprom.write

Function · Source

Program bytes, which clears bits only, as the Flash protocol writes to erased bytes.

pub fn write(&mut self, offset: u32, bytes: &[u8]) -> void!hal.Error

Eeprom.update

Function · Source

Replace the bytes at offset with bytes, whatever they held, erasing and writing only the bytes that change: the usual way to keep a setting.

pub fn update(&mut self, offset: u32, bytes: &[u8]) -> void!hal.Error

report_panic

Function · Source

Write a failed check, as the compiler passes it to the panic hook, to the serial port if it is open, and wait until it is out:

dodo: arithmetic overflow check failed at /home/me/blink/main.dodo:12:5

the line a desktop program prints. Only the first call reports. SAFETY: check and file must be the hook’s NUL-terminated strings, which the compiler places in program memory, and the caller must halt or reset afterwards, as this takes over the serial port.

pub unsafe fn report_panic(check: *const u8, file: *const u8, line: u32, column: u32)

Requires an unsafe context. Follow the source safety preconditions and the linked guide before calling this API.

Search every guide, reference page, and API declaration.