3.3. drivers — Device drivers

This module contains device drivers.

The following classes are defined:

Simba documentation: drivers


class drivers.Pin(device, mode)

Create a pin object with given device and mode. The device is selected among the pins available in the board module. mode must be either INPUT or OUTPUT.

>>> led = Pin(board.PIN_LED, Pin.OUTPUT)
>>> led.write(1)
>>> led.toggle()

Simba documentation: drivers/pin

read()

Read the current pin value and return it as an integer. Returns 0 if the pin is low and 1 if the pin is high.

write(value)

Write the logic level value to the pin. value must be an object that can be converted to an integer. The value is either 0 or 1, where 0 is low and 1 is high.

toggle()

Toggle the pin output value (high/low).

set_mode(mode)

Set the pin mode to given mode mode. The mode must be either INPUT or OUTPUT.

INPUT

Input pin mode.

OUTPUT

Output pin mode.

class drivers.Exti(device, trigger, channel=None, data=None, callback=None)

Create an object handling interrupts on given device. trigger may be a combination of RISING, FALLING or BOTH. When an interrupt occurs given callback is called from interrupt context and data is written to given event or queue channel channel.

Event channel example.

>>> event = Event()
>>> exti = Exti(board.EXTI_D3, Exti.FALLING, event, 0x1)
>>> exti.start()
>>> event.read(0x1)        # Wait for an interrupt to occur.
>>> exti.stop()

Queue channel example.

>>> queue = Queue()
>>> exti = Exti(board.EXTI_D4, Exti.RISING, queue, b'1')
>>> exti.start()
>>> queue.read(1)        # Wait for an interrupt to occur.
b'1'
>>> exti.stop()

Simba documentation: drivers/exti

start()

Start the interrupt handler.

stop()

Stop the interrupt handler.

RISING

Trigger an interrupt on rising edges.

FALLING

Trigger an interrupt on falling edges.

BOTH

Trigger an interrupt on both rising and falling edges.

class drivers.Adc(device, pin_device, reference, sampling_rate)

Instansiate an Adc object with given device and pin_device devices. reference is the voltage reference and sampling_rate is the sampling frequency.

Here is an example of how to create a ADC driver object and convert an analog signal level to three digital samples with a sampling rate of 1 kHz.

>>> a0 = Adc(board.PIN_ADC0, board.PIN_A0, Adc.REFERENCE_VCC, 1000)
>>> a0.convert(3)
b'\x00\x01\x00\x02\x00\x03'
>>> array.array('h', a0.convert(3))
array('h', [1, 2, 3])

The equivalent asynchronous example.

>>> a0 = Adc(board.PIN_ADC0, board.PIN_A0, Adc.REFERENCE_VCC, 1000)
>>> a0.async_convert(3)
>>> array.array('h', a0.async_wait())
array('h', [1, 2, 3])

Simba documentation: drivers/adc

convert(number_of_samples)

Start a synchronous convertion of an analog signal to digital samples. This is equivalent to async_convert() + async_wait(), but in a single function call. Returns a bytes object where each sample is 2 bytes.

async_convert(number_of_samples)

Start an asynchronous convertion of analog signal to digital samples. Call async_wait() to wait for the convertion to complete.

async_wait()

Wait for an asynchronous convertion started with async_convert() to complete. Returns a bytes object where each sample is 2 bytes.

REFERENCE_VCC

Use VCC as reference.

class drivers.Dac(devices, sampling_rate)

Instansiate a Dac object. devices is either a list of DAC pin devices or a single DAC pin device. The DAC pin devices can be found in the board module, often named PIN_DAC0 and PIN_DAC1.

Here is an example of how to create a DAC driver and convert digital samples to an analog signal.

>>> dac = Dac(board.PIN_DAC0)
>>> dac.convert(b'\x01\x02\x03\x04')

Simba documentation: drivers/dac

convert(samples)

Start a synchronous convertion of digital samples to an analog signal. This function returns when all samples have been converted.

async_convert(samples)

Start an asynchronous convertion of digital samples to an analog signal. This function only blocks if the hardware is not ready to convert more samples. Call async_wait() to wait for an asynchronous convertion to finish.

async_wait()

Wait for an ongoing asynchronous convertion to finish.

class drivers.Spi(device, slave_select, mode=MODE_MASTER, speed=SPEED_250KBPS, polarity=0, phase=0)

Create a Spi object. Select the SPI device with device and slave select pin with slave_select. mode in one of MODE_MASTER and MODE_SLAVE. speed is only used by the master. polarity is the bus idle logic level. phase controls if sampling are done on falling or rising clock edges.

Here is an example of how to create a SPI driver and write 4 bytes to the slave.

>>> spi = Spi(board.SPI_0, board.PIN_D3)
>>> spi.start()
>>> spi.select()
>>> spi.write(b'\x01\x02\x03\x04')
>>> spi.deselect()
>>> spi.stop()

Simba documentation: drivers/spi

start()

Configures the SPI hardware with the settings of this object.

stop()

Deconfigures the SPI hardware if given driver currently ownes the bus.

take_bus()

In multi master application the driver must take ownership of the SPI bus before performing data transfers. Will re-configure the SPI hardware if configured by another driver.

give_bus()

In multi master application the driver must give ownership of the SPI bus to let other masters take it.

select()

Select the slave by asserting the slave select pin.

deselect()

Deselect the slave by de-asserting the slave select pin.

transfer(write_buffer[, size])

Simultaniuos read/write operation over the SPI bus. Writes data from write_buffer to the bus. The size argument can be used to transfer fewer bytes than the size of write_buffer. Returns the read data as a bytes object.

The number of read and written bytes are always equal for a transfer.

transfer_into(read_buffer, write_buffer[, size])

Same as transfer(), but the read data is written to read_buffer.

read(size)

Read size bytes from the SPI bus. Returns the read data as a bytes object.

read_into(buffer[, size])

Same as read(), but the read data is written to buffer.

write(buffer[, size])

Write size bytes from buffer to the SPI bus. Writes all data in buffer if size is not given.

MODE_MASTER

SPI master mode.

MODE_SLAVE

SPI slave mode.

SPEED_8MBPS
SPEED_4MBPS
SPEED_2MBPS
SPEED_1MBPS
SPEED_500KBPS
SPEED_250KBPS
SPEED_125KBPS

SPI bus speed. Only used if the driver is configured as master.

class drivers.Can(device, speed=SPEED_500KBPS)

Create a Can object. Select CAN device and speed with device and speed.

Here is an example of how to create a CAN driver, write a frame and then read a frame.

>>> can = Can(board.CAN_0)
>>> can.start()
>>> can.write(0x123, b'\x01\x02')
>>> can.read()
(id=0x32, data=b'\x34\x35\x36', flags=0)
>>> can.stop()

Simba documentation: drivers/can

start()

Starts the CAN device.

stop()

Stops the CAN device.

read()

Read a frame from the CAN bus and return it as a named tuple with three items; id, data and flags. id is the frame id as an integer. flags contains information about the frame format, and possibly additional information in the future. data is a bytes object of up to 8 bytes of read frame data.

write(id, data[, flags])

Write a frame with given id and data to the CAN bus. id is an integer and data is a bytes object of up to 8 bytes. Set FLAGS_EXTENDED_FRAME in flags to write an extended frame (29 bits frame id), otherwise a standard frame is written.

SPEED_500KBPS

CAN bus speed.

FLAGS_EXTENDED_FRAME

Extended frame flag. A 29 bits frame id will be sent/received.

class drivers.I2C(device, baudrate=BAUDRATE_100KBPS, address=-1)

Create an I2C object. Select the I2C device with device. The bus baudrate baudrate is one of BAUDRATE_1MBPS, BAUDRATE_400KBPS and BAUDRATE_100KBPS. address is the slave address when this driver is a slave (only master is suported in the current version of the driver).

Here is an example of how to create a I2C obeject and scan the bus to find conected devices.

>>> i2c = I2C(0)
>>> i2c.start()
>>> i2c.scan()
[87, 104]
>>> i2c.stop()

Simba documentation: drivers/i2c

start()

Start the I2C driver. Configures the hardware.

stop()

Stop the I2C driver. Resets the hardware.

read(address, size)

Read size bytes from slave with address address.

read_into(address, buffer[, size])

Read len(buffer) bytes from slave with address address into buffer. Give the argument size to read fewer bytes than len(buffer).

write(address, buffer[, size])

Write the buffer buffer to slave with address address.

scan()

Scan the bus and return a list of all found slave addresses.

BAUDRATE_1MBPS
BAUDRATE_400KBPS
BAUDRATE_100KBPS

I2C bus baudrate. Only used if the driver is configured as master.

class drivers.I2CSoft(scl, sda, baudrate=50000, max_clock_stretching_sleep_us=1000000, clock_stretching_sleep_us=10000)

Create an I2CSoft object. Select the I2C SCL and SDA pins with scl and sda. The bus baudrate is selected using the baudrate argument. max_clock_stretching_sleep_us and clock_stretching_sleep_us are timing configuration parameters.

Here is an example of how to create a I2CSoft obeject and scan the bus to find conected devices.

>>> i2c = I2CSoft(board.PIN_D3, board.PIN_D4)
>>> i2c.start()
>>> i2c.scan()
[87, 104]
>>> i2c.stop()

Simba documentation: drivers/i2c_soft

start()

Start the I2C soft driver. Configures the hardware.

stop()

Stop the I2C soft driver. Resets the hardware.

read(address, size)

Read size bytes from slave with address address.

read_into(address, buffer[, size])

Read len(buffer) bytes from slave with address address into buffer. Give the argument size to read fewer bytes than len(buffer).

write(address, buffer[, size])

Write the buffer buffer to slave with address address.

scan()

Scan the bus and return a list of all found slave addresses.

class drivers.Owi(pin_device)

Create an Owi object with pin_device as the One Wire bus pin.

Here is an example of how to use the Owi class.

>>> owi = Owi(board.PIN_D3)
>>> owi.reset()
>>> owi.search()
2
>>> owi.get_devices()
[b'12345678', b'abcdefgh']
>>> owi.read(b'12345678', 3)
b'\x00\x01\x02'
>>> owi.write(b'12345678', b'\x00')
1

Simba documentation: drivers/owi

reset()

Send reset on One Wire bus.

search()

Search for devices on the One Wire bus. The device id of all found devices are stored and returned by get_devices().

get_devices()

Returns a list of all devices found in the latest call to search().

read(device_id, size)

Read size bytes from device with id device_id.

write(device_id, buffer[, size])

Write buffer buffer to device with id device_id. Give size to write fewer bytes than the buffer size.

class drivers.Ds18b20(owi)

Create a Ds18b20 object.

Here is an example of how to use the Ds18b20 class.

>>> owi = Owi(board.PIN_D3)
>>> owi.search()
>>> ds18b20 = Ds18b20(owi)
>>> ds18b20.get_devices()
[b'(2345678']
>>> ds18b20.convert()
>>> ds18b20.get_temperature(b'(2345678')
20.5

Simba documentation: drivers/ds18b20

convert()

Start temperature convertion on all sensors. A convertion takes about one second to finish.

get_devices()

Returns a list of all DS18B20 devices found by the latest call to Owi.search().

get_temperature(device_id)

Get the temperature for given device identity. Reads the latest converted sample for the device with id device_id. Call convert() before calling this function to get the current temperature.

class drivers.Sd(spi)

Create a Sd object with given SPI driver.

Here is an example of how to create a SD and read the CID.

>>> sd = Sd(spi)
>>> sd.start()
>>> print(sd.read_cid())
(mid=2, oid=b'TM', pnm=b'SA04G', prv=22, psn=-681299654, mdt=60416, crc=107)
>>> sd.stop()

Simba documentation: drivers/sd

start()

Configures the SD card driver. This resets the SD card and performs the initialization sequence.

stop()

Deconfigures the SD card driver.

read_cid()

Read card CID register and return it. The CID contains card identification information such as Manufacturer ID, Product name, Product serial number and Manufacturing date.

The return value is an object with 7 attributes:

  • mid - manufacturer ID
  • oid - OEM/Application ID
  • pnm - Product name
  • prv - Product revision
  • psn - Product serial number
  • mdt - Manufacturing date
  • crc - CRC7 checksum
read_csd()

Read card CSD register and return it. The CSD contains that provides information regarding access to the card’s contents.

The return value is an object with 29 attributes for version 1 cards and 24 attributes for version 2 cards:

  • ...
read_block(block)

Read given block from SD card and returns it as a bytes object.

read_block_into(block, buffer)

Same as read_block(), but the read data is written to buffer.

write_block(block, buffer)

Write buffer to given block.

class drivers.esp_wifi

This class is a singleton and can not be instanciated. It configures the Espressif WiFi stack.

An example of how to connect to a WiFi network:

>>> esp_wifi.set_op_mode(esp_wifi.OP_MODE_STATION)
>>> esp_wifi.station_init('ssid', 'password')
>>> esp_wifi.station_connect()
>>> esp_wifi.station_get_status()
'got-ip'
>>> esp_wifi.station_get_ip_info()
(address='192.168.0.5', netmask='255.255.255.0', gateway='192.168.0.1')

An example of how to setup a SoftAP:

>>> esp_wifi.set_op_mode(esp_wifi.OP_MODE_SOFTAP)
>>> esp_wifi.softap_init('ssid', 'password')
>>> esp_wifi.softap_get_ip_info()
(address='192.168.4.1', netmask='255.255.255.0', gateway='192.168.4.1')

Simba documentation: drivers/esp_wifi

set_op_mode(mode)

Set the WiFi operating mode to mode. mode is one of OP_MODE_STATION, OP_MODE_SOFTAP, OP_MODE_STATION_SOFTAP.

get_op_mode()

Returns the current WiFi operating mode.

set_phy_mode(mode)

Set the WiFi physical mode (802.11b/g/n) to one of PHY_MODE_11B, PHY_MODE_11G and PHY_MODE_11N.

get_phy_mode()

Returns the physical mode (802.11b/g/n).

softap_init(ssid, password)

Initialize the WiFi SoftAP interface with given ssid and password.

softap_set_ip_info(info)

Set the ip address, netmask and gateway of the WiFi SoftAP. The info object info is a three items tuple of address, netmask and gateway strings in IPv4 format.

softap_get_ip_info()

Returns a three items tuple of the SoftAP ip address, netmask and gateway.

softap_get_number_of_connected_stations()

Returns the number of stations connected to the SoftAP.

softap_get_station_info()

Returns the information of stations connected to the SoftAP, including MAC and IP addresses.

softap_dhcp_server_start()

Enable the SoftAP DHCP server.

softap_dhcp_server_stop()

Disable the SoftAP DHCP server. The DHCP server is enabled by default.

softap_dhcp_server_status()

Returns the SoftAP DHCP server status.

station_init(ssid, password[, info])

Initialize the WiFi station.

station_connect()

Connect the WiFi station to the Access Point (AP). This function returns before a connection has been established. Call station_get_status() periodically until it retuns got-ip to ensure the WiFi station has been assigned an IP the the WiFi Access Point DHCP server.

station_disconnect()

Disconnect the WiFi station from the AP.

station_set_ip_info(info)

Set the ip address, netmask and gateway of the WiFi station. The info object info is a three items tuple of address, netmask and gateway strings in IPv4 format.

station_get_ip_info()

Returns the station ip address, netmask and gateway.

station_set_reconnect_policy(policy)

Set whether the station will reconnect to the AP after disconnection. Set policy to True to automatically reconnect and False otherwise.

station_get_reconnect_policy()

Check whether the station will reconnect to the AP after disconnection.

station_get_status()

Get the connection status of the WiFi station.

station_dhcp_client_start()

Enable the station DHCP client.

station_dhcp_client_stop()

Disable the station DHCP client.

station_dhcp_client_status()

Get the station DHCP client status.

OP_MODE_NULL
OP_MODE_STATION
OP_MODE_SOFTAP
OP_MODE_STATION_SOFTAP

WiFi operating modes.

PHY_MODE_11B
PHY_MODE_11G
PHY_MODE_11N

WiFi physical modes.

class drivers.Uart(device, baudrate=115200)

Create a Uart object. Select UART device and baudrate with device and baudrate.

Here is an example of how to create a UART driver, write data and then read data.

Instances of this class can be polled by the select module.

>>> uart = Uart(1)
>>> uart.start()
>>> uart.write(b'1234')
>>> uart.read(4)
b'5678'
>>> buf = bytearray(4)
>>> uart.read_into(buf, 3)
3
>>> buf
bytearray(b'901\x00')
>>> uart.stop()

Simba documentation: drivers/uart

start()

Starts the UART device. Configures the hardware.

stop()

Stops the UART device.

read(size)

Read size bytes from the UART. Returns the read data.

read_into(buffer[, size])

Read size bytes from the UART into given buffer buffer. Returns number of bytes read.

write(buffer[, size])

Write data in buffer to the UART. size may be used to send fewer bytes than the size of buffer. Returns number of bytes written.

size()

Returns the number of bytes in the input buffer.

class drivers.Flash(device)

Create a Flash object. Select flash device index with device. It is normally given as 0.

The flash address given to the instance methods is either relative to the flash start address or an absolute physical address in the CPU memory map. This is board dependent and it is not documented anywhere.

Here is an example of how to create a flash driver and use the erase, read and write methods.

>>> flash = Flash(0)
>>> flash.read(0x300000, 4)
b'5678'
>>> flash.erase(0x300000, 4)
>>> flash.write(0x300000, b'1234')
4
>>> buf = bytearray(8)
>>> flash.read_into(0x300000, buf, 4)
4
>>> buf
bytearray(b'1234\x00\x00\x00\x00')

Simba documentation: drivers/flash

read(address, size)

Read size bytes from given address address in the flash. Returns the read data.

read_into(address, buffer[, size])

Read size bytes from given address address in flash into given buffer buffer. Returns number of bytes read.

write(address, buffer[, size])

Write data in buffer to given address address in flash. size may be used to write fewer bytes than the size of buffer. Returns number of bytes written.

erase(address, size)

Erase size bytes in flash starting at given addess address.

class drivers.Ws2812(pin_devices)

Create a Ws2812 object.

Here is an example of how to create a Ws2812 driver and control a LED strip of 30 pixles.

>>> ws2812 = Ws2812(board.PIN_GPIO18)
>>> ws2812.write(30 * b'\xff\x00\x00')

Simba documentation: drivers/ws2812

write(buffer[, number_of_pixels])

Write GRB data from buffer buffer to the LED strip. Writes all data in buffer if size is not given.

class drivers.EepromI2C(i2c, address, size)

Create a I2C EEPROM object. address is the EEPROM I2C address, and size is the EEPROM size in bytes.

Here is an example of how to create an I2C EEPROM obeject and transfer data to and from the EEPROM using it.

>>> i2c = I2C(0)
>>> i2c.start()
>>> eeprom = EepromI2C(i2c, 0x57, 32768)
>>> eeprom.write(0, b'Hello World!')
>>> eeprom.read(0, 12)
b'Hello World!'

Simba documentation: drivers/eeprom_i2c

read(address, size)

Read size bytes from EEPROM address address.

read_into(address, buffer[, size])

Read len(buffer) bytes from EEPROM address address into buffer. Give the argument size to read fewer bytes than len(buffer).

write(address, buffer[, size])

Write the buffer buffer to EEPROM address address.