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) andrx(PD0), or transmit only with rxnone, atbaud, 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) andscl(PC5), as controller, at up tofrequency_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) andrx(PB4, or none to leave it free), inmode, at the fastest rate up tofrequency_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, andselect()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
pinat aboutfrequency_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 whateverfrequency_hzis. 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;
millicelsiusconverts 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
deselectbefore 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 unlessfeedis 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.
readandupdateare 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
offsetwithbytes, 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:
checkandfilemust 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.