Skip to content

Commit 4542643

Browse files
author
danicampora
committed
docs: Update all WiPy docs to reflect the new API.
1 parent fca3308 commit 4542643

28 files changed

Lines changed: 1283 additions & 847 deletions

‎cc3200/mods/modmachine.c‎

Lines changed: 0 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -40,18 +40,13 @@
4040
#include "rom_map.h"
4141
#include "prcm.h"
4242
#include "pyexec.h"
43-
#include "ff.h"
44-
#include "diskio.h"
45-
#include "sflash_diskio.h"
4643
#include "pybuart.h"
4744
#include "pybpin.h"
4845
#include "pybrtc.h"
49-
#include "mpsystick.h"
5046
#include "simplelink.h"
5147
#include "modnetwork.h"
5248
#include "modwlan.h"
5349
#include "moduos.h"
54-
#include "telnet.h"
5550
#include "FreeRTOS.h"
5651
#include "portable.h"
5752
#include "task.h"
@@ -67,7 +62,6 @@
6762
#include "utils.h"
6863
#include "gccollect.h"
6964
#include "mperror.h"
70-
#include "genhdr/mpversion.h"
7165

7266

7367
#ifdef DEBUG

‎cc3200/mods/pybuart.c‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -558,15 +558,15 @@ STATIC mp_obj_t pyb_uart_irq (mp_uint_t n_args, const mp_obj_t *pos_args, mp_map
558558
invalid_args:
559559
nlr_raise(mp_obj_new_exception_msg(&mp_type_ValueError, mpexception_value_invalid_arguments));
560560
}
561-
STATIC MP_DEFINE_CONST_FUN_OBJ_KW(pyb_uart_callback_obj, 1, pyb_uart_irq);
561+
STATIC MP_DEFINE_CONST_FUN_OBJ_KW(pyb_uart_irq_obj, 1, pyb_uart_irq);
562562

563563
STATIC const mp_map_elem_t pyb_uart_locals_dict_table[] = {
564564
// instance methods
565565
{ MP_OBJ_NEW_QSTR(MP_QSTR_init), (mp_obj_t)&pyb_uart_init_obj },
566566
{ MP_OBJ_NEW_QSTR(MP_QSTR_deinit), (mp_obj_t)&pyb_uart_deinit_obj },
567567
{ MP_OBJ_NEW_QSTR(MP_QSTR_any), (mp_obj_t)&pyb_uart_any_obj },
568568
{ MP_OBJ_NEW_QSTR(MP_QSTR_sendbreak), (mp_obj_t)&pyb_uart_sendbreak_obj },
569-
{ MP_OBJ_NEW_QSTR(MP_QSTR_irq), (mp_obj_t)&pyb_uart_callback_obj },
569+
{ MP_OBJ_NEW_QSTR(MP_QSTR_irq), (mp_obj_t)&pyb_uart_irq_obj },
570570

571571
/// \method read([nbytes])
572572
{ MP_OBJ_NEW_QSTR(MP_QSTR_read), (mp_obj_t)&mp_stream_read_obj },

‎docs/conf.py‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -300,6 +300,11 @@
300300

301301
# Append the other ports' specific folders/files to the exclude pattern
302302
exclude_patterns.extend([port + '*' for port in ports if port != micropy_port])
303+
# Exclude pyb module if the port is the WiPy
304+
if micropy_port == 'wipy':
305+
exclude_patterns.append('library/pyb*')
306+
else: # exclude machine
307+
exclude_patterns.append('library/machine*')
303308

304309
# Specify a custom master document based on the port name
305310
master_doc = micropy_port + '_' + 'index'

‎docs/library/index.rst‎

Lines changed: 5 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -74,23 +74,21 @@ it will fallback to loading the built-in ``ujson`` module.
7474

7575
Libraries specific to the pyboard
7676
---------------------------------
77-
77+
7878
The following libraries are specific to the pyboard.
79-
79+
8080
.. toctree::
8181
:maxdepth: 2
82-
82+
8383
pyb.rst
8484
network.rst
8585

8686
.. only:: port_wipy
8787

8888
.. toctree::
8989
:maxdepth: 1
90-
90+
9191
ubinascii.rst
92-
uhashlib.rst
93-
uheapq.rst
9492
ujson.rst
9593
ure.rst
9694
usocket.rst
@@ -105,7 +103,7 @@ it will fallback to loading the built-in ``ujson`` module.
105103
.. toctree::
106104
:maxdepth: 2
107105

108-
pyb.rst
106+
machine.rst
109107
network.rst
110108

111109

‎docs/library/machine.ADC.rst‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
.. _machine.ADC:
2+
3+
class ADC -- analog to digital conversion
4+
=========================================
5+
6+
Usage::
7+
8+
import machine
9+
10+
adc = machine.ADC() # create an ADC object
11+
apin = adc.channel(pin='GP3') # create an analog pin on GP3
12+
val = apin() # read an analog value
13+
14+
Constructors
15+
------------
16+
17+
.. class:: machine.ADC(id=0, \*, bits=12)
18+
19+
Create an ADC object associated with the given pin.
20+
This allows you to then read analog values on that pin.
21+
For more info check the `pinout and alternate functions
22+
table. <https://raw.githubusercontent.com/wipy/wipy/master/docs/PinOUT.png>`_
23+
24+
.. warning::
25+
26+
ADC pin input range is 0-1.4V (being 1.8V the absolute maximum that it
27+
can withstand). When GP2, GP3, GP4 or GP5 are remapped to the
28+
ADC block, 1.8 V is the maximum. If these pins are used in digital mode,
29+
then the maximum allowed input is 3.6V.
30+
31+
Methods
32+
-------
33+
34+
.. method:: adc.channel(id, \*, pin)
35+
36+
Create an analog pin. If only channel ID is given, the correct pin will
37+
be selected. Alternatively, only the pin can be passed and the correct
38+
channel will be selected. Examples::
39+
40+
# all of these are equivalent and enable ADC channel 1 on GP3
41+
apin = adc.channel(1)
42+
apin = adc.channel(pin='GP3')
43+
apin = adc.channel(id=1, pin='GP3')
44+
45+
.. method:: adc.init()
46+
47+
Enable the ADC block.
48+
49+
.. method:: adc.deinit()
50+
51+
Disable the ADC block.
52+
53+
class ADCChannel --- read analog values from internal or external sources
54+
=========================================================================
55+
56+
ADC channels can be connected to internal points of the MCU or to GPIO pins.
57+
ADC channels are created using the ADC.channel method.
58+
59+
.. method:: adcchannel()
60+
61+
Fast method to read the channel value.
62+
63+
.. method:: adcchannel.value()
64+
65+
Read the channel value.
66+
67+
.. method:: adcchannel.init()
68+
69+
Re-init (and effectively enable) the ADC channel.
70+
71+
.. method:: adcchannel.deinit()
72+
73+
Disable the ADC channel.

docs/library/pyb.HeartBeat.rst renamed to docs/library/machine.HeartBeat.rst

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
.. _pyb.HeartBeat:
1+
.. _machine.HeartBeat:
22

33
class HeartBeat -- heart beat LED
44
=================================
@@ -11,14 +11,14 @@ can be used to control the light intesity of the heart beat LED.
1111

1212
Example usage::
1313

14-
hb = pyb.HeartBeat()
14+
hb = machine.HeartBeat()
1515
hb.disable() # disable the heart beat
1616
hb.enable() # enable the heart beat
1717

1818
Constructors
1919
------------
2020

21-
.. class:: pyb.HeartBeat()
21+
.. class:: machine.HeartBeat()
2222

2323
Create a HeartBeat object.
2424

@@ -35,12 +35,13 @@ Methods
3535

3636
Example::
3737
38-
import pyb
38+
from machine import HeartBeat
39+
from machine import Pin
3940
4041
# disable the heart beat
41-
pyb.HeartBeat().disable()
42-
# get the GP25 pin object
43-
hbl = pyb.Pin('GP25')
42+
HeartBeat().disable()
43+
# init GP25 as output
44+
led = Pin('GP25', mode=Pin.OUT)
4445
# toggle the led
45-
hbl.toggle()
46+
led.toggle()
4647
...

‎docs/library/machine.I2C.rst‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
.. _machine.I2C:
2+
3+
class I2C -- a two-wire serial protocol
4+
=======================================
5+
6+
I2C is a two-wire protocol for communicating between devices. At the physical
7+
level it consists of 2 wires: SCL and SDA, the clock and data lines respectively.
8+
9+
I2C objects are created attached to a specific bus. They can be initialised
10+
when created, or initialised later on.
11+
12+
.. only:: port_wipy
13+
14+
Example::
15+
16+
from machine import I2C
17+
18+
i2c = I2C(0) # create on bus 0
19+
i2c = I2C(0, I2C.MASTER) # create and init as a master
20+
i2c.init(I2C.MASTER, baudrate=20000) # init as a master
21+
i2c.deinit() # turn off the peripheral
22+
23+
Printing the i2c object gives you information about its configuration.
24+
25+
.. only:: port_wipy
26+
27+
A master must specify the recipient's address::
28+
29+
i2c.init(I2C.MASTER)
30+
i2c.writeto(0x42, '123') # send 3 bytes to slave with address 0x42
31+
i2c.writeto(addr=0x42, b'456') # keyword for address
32+
33+
Master also has other methods::
34+
35+
i2c.scan() # scan for slaves on the bus, returning
36+
# a list of valid addresses
37+
i2c.readfrom_mem(0x42, 2, 3) # read 3 bytes from memory of slave 0x42,
38+
# starting at address 2 in the slave
39+
i2c.writeto_mem(0x42, 2, 'abc') # write 'abc' (3 bytes) to memory of slave 0x42
40+
# starting at address 2 in the slave, timeout after 1 second
41+
42+
Constructors
43+
------------
44+
45+
.. only:: port_wipy
46+
47+
.. class:: machine.I2C(bus, ...)
48+
49+
Construct an I2C object on the given bus. `bus` can only be 0.
50+
If the bus is not given, the default one will be selected (0).
51+
52+
Methods
53+
-------
54+
55+
.. method:: i2c.deinit()
56+
57+
Turn off the I2C bus.
58+
59+
.. only:: port_wipy
60+
61+
.. method:: i2c.init(mode, \*, baudrate=100000, pins=(SDA, SCL))
62+
63+
Initialise the I2C bus with the given parameters:
64+
65+
- ``mode`` must be ``I2C.MASTER``
66+
- ``baudrate`` is the SCL clock rate
67+
- ``pins`` is an optional tuple with the pins to assign to the I2C bus.
68+
69+
.. method:: i2c.readfrom(addr, nbytes)
70+
71+
Read ``nbytes`` from the slave specified by ``addr``.
72+
Returns a ``bytes`` object with the data read.
73+
74+
.. method:: i2c.readfrom_into(addr, buf)
75+
76+
Read into ``buf`` from the slave specified by ``addr``.
77+
Returns the number of bytes read.
78+
79+
.. method:: i2c.writeto(addr, buf, \*, stop=True)
80+
81+
Write ``buf`` to the slave specified by ``addr``. Set ``stop`` to ``False``
82+
if the transfer should be continued.
83+
Returns the number of bytes written.
84+
85+
.. method:: i2c.readfrom_mem(addr, memaddr, nbytes, \*, addrsize=8)
86+
87+
Read ``nbytes`` from the slave specified by ``addr`` starting from the memory
88+
address specified by ``memaddr``.
89+
Param ``addrsize`` specifies the address size in bits.
90+
Returns a ``bytes`` object with the data read.
91+
92+
.. method:: i2c.readfrom_mem_into(addr, memaddr, buf, \*, addrsize=8)
93+
94+
Read into ``buf`` from the slave specified by ``addr`` starting from the memory
95+
address specified by ``memaddr``.
96+
Param ``addrsize`` specifies the address size in bits.
97+
Returns the number of bytes read.
98+
99+
.. method:: i2c.writeto_mem(addr, memaddr, buf, \*, addrsize=8)
100+
101+
Write ``buf`` to the slave specified by ``addr`` starting from the
102+
memory address specified by ``memaddr``. Param ``addrsize`` specifies the
103+
address size in bits.
104+
Set ``stop`` to ``False`` if the transfer should be continued.
105+
Returns the number of bytes written.
106+
107+
.. method:: i2c.scan()
108+
109+
Scan all I2C addresses from 0x01 to 0x7f and return a list of those that respond.
110+
Only valid when in master mode.
111+
112+
Constants
113+
---------
114+
115+
.. data:: I2C.MASTER
116+
117+
for initialising the bus to master mode

0 commit comments

Comments
 (0)