Skip to content

Commit 34f01c2

Browse files
dpgeorgedpgeorge
committed
stmhal: Add some documentation to I2C, SPI and USART modules.
1 parent 0ae21a8 commit 34f01c2

3 files changed

Lines changed: 82 additions & 0 deletions

File tree

‎stmhal/i2c.c‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,51 @@
1414
#include "bufhelper.h"
1515
#include "i2c.h"
1616

17+
// Usage model:
18+
//
19+
// I2C objects are created attached to a specific bus. They can be initialised
20+
// when created, or initialised later on:
21+
//
22+
// from pyb import I2C
23+
//
24+
// i2c = I2C(1) # create on bus 1
25+
// i2c = I2C(1, I2C.MASTER) # create and init as a master
26+
// i2c.deinit() # turn off the peripheral
27+
// i2c.init(I2C.MASTER, baudrate=20000) # init as a master
28+
// i2c.init(I2C.SLAVE, addr=0x42) # init as a slave with given address
29+
//
30+
// Printing the i2c object gives you information about its configuration.
31+
//
32+
// Basic methods for slave are send and recv:
33+
//
34+
// i2c.send('abc') # send 3 bytes
35+
// i2c.send(0x42) # send a single byte, given by the number
36+
// data = i2c.recv(3) # receive 3 bytes
37+
//
38+
// To receive inplace, first create a bytearray:
39+
//
40+
// data = bytearray(3) # create a buffer
41+
// i2c.recv(data) # receive 3 bytes, writing them into data
42+
//
43+
// You can specify a timeout (in ms):
44+
//
45+
// i2c.send(b'123', timeout=2000) # timout after 2 seconds
46+
//
47+
// A master must specify the recipient's address:
48+
//
49+
// i2c.init(I2C.MASTER)
50+
// i2c.send('123', 0x42) # send 3 bytes to slave with address 0x42
51+
// i2c.send(b'456', addr=0x42) # keyword for address
52+
//
53+
// Master also has other methods:
54+
//
55+
// i2c.is_ready(0x42) # check if slave 0x42 is ready
56+
// i2c.scan() # scan for slaves on the bus, returning
57+
// # a list of valid addresses
58+
// i2c.mem_read(3, 0x42, 2) # read 3 bytes from memory of slave 0x42,
59+
// # starting at address 2 in the slave
60+
// i2c.mem_write('abc', 0x42, 2, timeout=1000)
61+
1762
#define PYB_I2C_MASTER (0)
1863
#define PYB_I2C_SLAVE (1)
1964

‎stmhal/spi.c‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,25 @@
1414
#include "bufhelper.h"
1515
#include "spi.h"
1616

17+
// Usage model:
18+
//
19+
// See usage model of I2C in i2c.c. SPI is very similar. Main difference is
20+
// parameters to init the SPI bus:
21+
//
22+
// from pyb import SPI
23+
// spi = SPI(1, SPI.MASTER, baudrate=600000, polarity=1, phase=1, crc=0x7)
24+
//
25+
// Only required parameter is mode, SPI.MASTER or SPI.SLAVE. Polarity can be
26+
// 0 or 1, and is the level the idle clock line sits at. Phase can be 1 or 2
27+
// for number of edges. Crc can be None for no CRC, or a polynomial specifier.
28+
//
29+
// Additional method for SPI:
30+
//
31+
// data = spi.send_recv(b'1234') # send 4 bytes and receive 4 bytes
32+
// buf = bytearray(4)
33+
// spi.send_recv(b'1234', buf) # send 4 bytes and receive 4 into buf
34+
// spi.send_recv(buf, buf) # send/recv 4 bytes from/to buf
35+
1736
#if MICROPY_HW_ENABLE_SPI1
1837
SPI_HandleTypeDef SPIHandle1 = {.Instance = NULL};
1938
#endif
@@ -384,6 +403,9 @@ STATIC mp_obj_t pyb_spi_send_recv(uint n_args, const mp_obj_t *args, mp_map_t *k
384403
} else {
385404
// recv argument given
386405
mp_get_buffer_raise(vals[1].u_obj, &bufinfo_recv, MP_BUFFER_WRITE);
406+
if (bufinfo_recv.len != bufinfo_send.len) {
407+
nlr_raise(mp_obj_new_exception_msg(&mp_type_ValueError, "recv must be same length as send"));
408+
}
387409
o_ret = MP_OBJ_NULL;
388410
}
389411
}

‎stmhal/usart.c‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,21 @@
1212
#include "bufhelper.h"
1313
#include "usart.h"
1414

15+
// Usage model:
16+
//
17+
// See usage model of I2C in i2c.c. USART is very similar. Main difference is
18+
// parameters to init the USART bus:
19+
//
20+
// from pyb import USART
21+
// usart = USART(1, 9600) # init with given baudrate
22+
// usart.init(9600, bits=8, stop=1, parity=None) # init with given parameters
23+
//
24+
// Bits can be 8 or 9, stop can be 1 or 2, parity can be None, 0 (even), 1 (odd).
25+
//
26+
// Extra method:
27+
//
28+
// usart.any() # returns True if any characters waiting
29+
1530
struct _pyb_usart_obj_t {
1631
mp_obj_base_t base;
1732
pyb_usart_t usart_id;

0 commit comments

Comments
 (0)