From 9487b80666ead95b0143c9372b72774af8ebf950 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Tue, 7 Jun 2016 02:07:08 +0300 Subject: docs/library/network: wipy: Fix literal block indentation. --- docs/library/network.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'docs/library') diff --git a/docs/library/network.rst b/docs/library/network.rst index fe4eaa7525..b183ef9a4b 100644 --- a/docs/library/network.rst +++ b/docs/library/network.rst @@ -41,11 +41,11 @@ For example:: Example:: - import network - server = network.Server() - server.deinit() # disable the server - # enable the server again with new settings - server.init(login=('user', 'password'), timeout=600) + import network + server = network.Server() + server.deinit() # disable the server + # enable the server again with new settings + server.init(login=('user', 'password'), timeout=600) Constructors ------------ -- cgit v1.2.3 From 753a965363474231540cc74ffd5b30f7b394e5f6 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Tue, 7 Jun 2016 02:40:05 +0300 Subject: docs/esp.socket: Remove unused file. --- docs/library/esp.socket.rst | 82 --------------------------------------------- 1 file changed, 82 deletions(-) delete mode 100644 docs/library/esp.socket.rst (limited to 'docs/library') diff --git a/docs/library/esp.socket.rst b/docs/library/esp.socket.rst deleted file mode 100644 index 4f5234a154..0000000000 --- a/docs/library/esp.socket.rst +++ /dev/null @@ -1,82 +0,0 @@ -class socket -- network socket -============================== - -``socket`` is an object that represents a network socket. Example usage:: - - socket = esp.socket() - socket.onrecv(print) - socket.connect(('207.58.139.247', 80)) - socket.send('GET /testwifi/index.html HTTP/1.0\r\n\r\n') - -Constructors ------------- - -.. class:: esp.socket() - - Create and return a socket object. - - -TCP Methods ------------ - -.. method:: socket.connect(addr) - - Connect to the adress and port specified in the ``addr`` tuple. - -.. method:: socket.close() - - Close the connection. - -.. method:: socket.accept() - - Accept a single connection from the connection queue. - -.. method:: socket.listen(backlog) - - Start listening for incoming connections. - - Note: Only one socket can be listening for connections at a time. - -.. method:: socket.bind(addr) - - Bind the socket to the address and port specified by the ``addr`` tuple. - -.. method:: socket.send(buf) - - Send the bytes from ``buf``. - -.. method:: socket.recv() - - Receive and return bytes from the socket. - - -UDP Methods ------------ - -.. method:: socket.sendto(data, addr) - - Placeholder for UDP support, not implemented yet. - -.. method:: socket.recvfrom(addr) - - Placeholder for UDP support, not implemented yet. - - -Callback Setter Methods ------------------------ - -.. method:: onconnect(lambda):: - - When connection is established, call the callback ``lambda``. - -.. method:: onrecv(lambda):: - - When data is received, call the callback ``lambda``. - -.. method:: onsent(lamda):: - - What data is finished sending, call the callback ``lambda``. - -.. method:: ondisconnect(lambda):: - - Call the callback ``lambda`` when the connection is closed. -- cgit v1.2.3 From 9b18811951a8a9fff712b300fb481a16c8e61ac4 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Tue, 7 Jun 2016 08:53:54 +0300 Subject: docs/ure: Typo fix. --- docs/library/ure.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/library') diff --git a/docs/library/ure.rst b/docs/library/ure.rst index f20dff6f39..ee360bcc47 100644 --- a/docs/library/ure.rst +++ b/docs/library/ure.rst @@ -32,7 +32,7 @@ Supported operators are: ``'+?'`` -Counted repetitions (``{m,n}``), more advanced assertions, names groups, +Counted repetitions (``{m,n}``), more advanced assertions, named groups, etc. are not supported. -- cgit v1.2.3 From 6e2fa5237db911b2c8f898c5a2fef2fe56626b93 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Tue, 7 Jun 2016 17:41:21 +0300 Subject: docs/usocket: There must be empty line after .only:: . --- docs/library/usocket.rst | 1 + 1 file changed, 1 insertion(+) (limited to 'docs/library') diff --git a/docs/library/usocket.rst b/docs/library/usocket.rst index d31e4d2fc9..9d1d569df4 100644 --- a/docs/library/usocket.rst +++ b/docs/library/usocket.rst @@ -74,6 +74,7 @@ Constants .. data:: socket.IPPROTO_UDP .. data:: socket.IPPROTO_TCP .. only:: port_wipy + .. data:: socket.IPPROTO_SEC protocol numbers -- cgit v1.2.3 From 2c5fc681c809e6bf871a463f1b20e433a338c4f6 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Tue, 7 Jun 2016 17:49:00 +0300 Subject: docs/library/machine.Pin: Mention GPIO and cross-link .value() function. --- docs/library/machine.Pin.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'docs/library') diff --git a/docs/library/machine.Pin.rst b/docs/library/machine.Pin.rst index a2e97c87c2..053c6e79b3 100644 --- a/docs/library/machine.Pin.rst +++ b/docs/library/machine.Pin.rst @@ -3,7 +3,8 @@ class Pin -- control I/O pins ============================= -A pin is the basic object to control I/O pins. It has methods to set +A pin is the basic object to control I/O pins (also known as GPIO - +general-purpose input/output). It has methods to set the mode of the pin (input, output, etc) and methods to get and set the digital logic level. For analog control of a pin, see the ADC class. @@ -132,7 +133,7 @@ Methods .. method:: pin([value]) Pin objects are callable. The call method provides a (fast) shortcut to set and get the value of the pin. - See **pin.value** for more details. + See :func:`pin.value` for more details. .. method:: pin.alt_list() -- cgit v1.2.3 From c8b7628094528cb8b68de499165db5bfb0b1264b Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Wed, 8 Jun 2016 00:46:27 +0300 Subject: docs/machine.*: Add "currentmodule:: machine" directive. Makes sure that classes described in these separate files are properly designated as belonging to "machine" module in indexes. --- docs/library/machine.ADC.rst | 1 + docs/library/machine.I2C.rst | 1 + docs/library/machine.Pin.rst | 1 + docs/library/machine.RTC.rst | 1 + docs/library/machine.SD.rst | 1 + docs/library/machine.SPI.rst | 1 + docs/library/machine.Timer.rst | 1 + docs/library/machine.UART.rst | 1 + docs/library/machine.WDT.rst | 1 + 9 files changed, 9 insertions(+) (limited to 'docs/library') diff --git a/docs/library/machine.ADC.rst b/docs/library/machine.ADC.rst index 309d070b1b..ef545f35f3 100644 --- a/docs/library/machine.ADC.rst +++ b/docs/library/machine.ADC.rst @@ -1,3 +1,4 @@ +.. currentmodule:: machine .. _machine.ADC: class ADC -- analog to digital conversion diff --git a/docs/library/machine.I2C.rst b/docs/library/machine.I2C.rst index a7e90ca39b..c83c436ad9 100644 --- a/docs/library/machine.I2C.rst +++ b/docs/library/machine.I2C.rst @@ -1,3 +1,4 @@ +.. currentmodule:: machine .. _machine.I2C: class I2C -- a two-wire serial protocol diff --git a/docs/library/machine.Pin.rst b/docs/library/machine.Pin.rst index 053c6e79b3..2d3385b065 100644 --- a/docs/library/machine.Pin.rst +++ b/docs/library/machine.Pin.rst @@ -1,3 +1,4 @@ +.. currentmodule:: machine .. _machine.Pin: class Pin -- control I/O pins diff --git a/docs/library/machine.RTC.rst b/docs/library/machine.RTC.rst index c69e4781a2..684f31aa0f 100644 --- a/docs/library/machine.RTC.rst +++ b/docs/library/machine.RTC.rst @@ -1,3 +1,4 @@ +.. currentmodule:: machine .. _machine.RTC: class RTC -- real time clock diff --git a/docs/library/machine.SD.rst b/docs/library/machine.SD.rst index da60121d07..d1a3b4e358 100644 --- a/docs/library/machine.SD.rst +++ b/docs/library/machine.SD.rst @@ -1,3 +1,4 @@ +.. currentmodule:: machine .. _machine.SD: class SD -- secure digital memory card diff --git a/docs/library/machine.SPI.rst b/docs/library/machine.SPI.rst index eddd62dbdc..285cd37b4b 100644 --- a/docs/library/machine.SPI.rst +++ b/docs/library/machine.SPI.rst @@ -1,3 +1,4 @@ +.. currentmodule:: machine .. _machine.SPI: class SPI -- a master-driven serial protocol diff --git a/docs/library/machine.Timer.rst b/docs/library/machine.Timer.rst index daf63c9b93..8bb9a36600 100644 --- a/docs/library/machine.Timer.rst +++ b/docs/library/machine.Timer.rst @@ -1,3 +1,4 @@ +.. currentmodule:: machine .. _machine.Timer: class Timer -- control internal timers diff --git a/docs/library/machine.UART.rst b/docs/library/machine.UART.rst index 7399b9b6e9..5552b9dd72 100644 --- a/docs/library/machine.UART.rst +++ b/docs/library/machine.UART.rst @@ -1,3 +1,4 @@ +.. currentmodule:: machine .. _machine.UART: class UART -- duplex serial communication bus diff --git a/docs/library/machine.WDT.rst b/docs/library/machine.WDT.rst index dca74f70f6..10e6af0e14 100644 --- a/docs/library/machine.WDT.rst +++ b/docs/library/machine.WDT.rst @@ -1,3 +1,4 @@ +.. currentmodule:: machine .. _machine.WDT: class WDT -- watchdog timer -- cgit v1.2.3 From 0a4cc24b2e8e7ceafb4e2cbe640c9f5dce655a70 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Wed, 8 Jun 2016 00:57:41 +0300 Subject: docs/pyb.*: Add "currentmodule:: pyb" directive. Makes sure that classes described in these separate files are properly designated as belonging to "pyb" module in indexes. --- docs/library/pyb.ADC.rst | 1 + docs/library/pyb.Accel.rst | 2 ++ docs/library/pyb.CAN.rst | 2 ++ docs/library/pyb.DAC.rst | 1 + docs/library/pyb.ExtInt.rst | 1 + docs/library/pyb.I2C.rst | 1 + docs/library/pyb.LCD.rst | 2 ++ docs/library/pyb.LED.rst | 1 + docs/library/pyb.Pin.rst | 1 + docs/library/pyb.RTC.rst | 1 + docs/library/pyb.SPI.rst | 1 + docs/library/pyb.Servo.rst | 1 + docs/library/pyb.Switch.rst | 2 ++ docs/library/pyb.Timer.rst | 1 + docs/library/pyb.UART.rst | 1 + docs/library/pyb.USB_VCP.rst | 2 ++ 16 files changed, 21 insertions(+) (limited to 'docs/library') diff --git a/docs/library/pyb.ADC.rst b/docs/library/pyb.ADC.rst index 30957c4c1a..e75efae7b5 100644 --- a/docs/library/pyb.ADC.rst +++ b/docs/library/pyb.ADC.rst @@ -1,3 +1,4 @@ +.. currentmodule:: pyb .. _pyb.ADC: class ADC -- analog to digital conversion diff --git a/docs/library/pyb.Accel.rst b/docs/library/pyb.Accel.rst index fd96ec35f9..53e410dfb9 100644 --- a/docs/library/pyb.Accel.rst +++ b/docs/library/pyb.Accel.rst @@ -1,3 +1,5 @@ +.. currentmodule:: pyb + class Accel -- accelerometer control ==================================== diff --git a/docs/library/pyb.CAN.rst b/docs/library/pyb.CAN.rst index e5d2b9acb1..efa2f19d50 100644 --- a/docs/library/pyb.CAN.rst +++ b/docs/library/pyb.CAN.rst @@ -1,3 +1,5 @@ +.. currentmodule:: pyb + class CAN -- controller area network communication bus ====================================================== diff --git a/docs/library/pyb.DAC.rst b/docs/library/pyb.DAC.rst index 7b5b1a6821..02c85fdd1b 100644 --- a/docs/library/pyb.DAC.rst +++ b/docs/library/pyb.DAC.rst @@ -1,3 +1,4 @@ +.. currentmodule:: pyb .. _pyb.DAC: class DAC -- digital to analog conversion diff --git a/docs/library/pyb.ExtInt.rst b/docs/library/pyb.ExtInt.rst index 61023ebb38..8344a14c2e 100644 --- a/docs/library/pyb.ExtInt.rst +++ b/docs/library/pyb.ExtInt.rst @@ -1,3 +1,4 @@ +.. currentmodule:: pyb .. _pyb.ExtInt: class ExtInt -- configure I/O pins to interrupt on external events diff --git a/docs/library/pyb.I2C.rst b/docs/library/pyb.I2C.rst index 9d17bb0559..d8eb8655c6 100644 --- a/docs/library/pyb.I2C.rst +++ b/docs/library/pyb.I2C.rst @@ -1,3 +1,4 @@ +.. currentmodule:: pyb .. _pyb.I2C: class I2C -- a two-wire serial protocol diff --git a/docs/library/pyb.LCD.rst b/docs/library/pyb.LCD.rst index 7555b6fb09..06fe35589d 100644 --- a/docs/library/pyb.LCD.rst +++ b/docs/library/pyb.LCD.rst @@ -1,3 +1,5 @@ +.. currentmodule:: pyb + class LCD -- LCD control for the LCD touch-sensor pyskin ======================================================== diff --git a/docs/library/pyb.LED.rst b/docs/library/pyb.LED.rst index aeeb75b8f1..fd997e40f7 100644 --- a/docs/library/pyb.LED.rst +++ b/docs/library/pyb.LED.rst @@ -1,3 +1,4 @@ +.. currentmodule:: pyb .. _pyb.LED: class LED -- LED object diff --git a/docs/library/pyb.Pin.rst b/docs/library/pyb.Pin.rst index 30440f5025..65ae601bed 100644 --- a/docs/library/pyb.Pin.rst +++ b/docs/library/pyb.Pin.rst @@ -1,3 +1,4 @@ +.. currentmodule:: pyb .. _pyb.Pin: class Pin -- control I/O pins diff --git a/docs/library/pyb.RTC.rst b/docs/library/pyb.RTC.rst index 51b17deccf..19401b9823 100644 --- a/docs/library/pyb.RTC.rst +++ b/docs/library/pyb.RTC.rst @@ -1,3 +1,4 @@ +.. currentmodule:: pyb .. _pyb.RTC: class RTC -- real time clock diff --git a/docs/library/pyb.SPI.rst b/docs/library/pyb.SPI.rst index b17c804d70..0b5546513b 100644 --- a/docs/library/pyb.SPI.rst +++ b/docs/library/pyb.SPI.rst @@ -1,3 +1,4 @@ +.. currentmodule:: pyb .. _pyb.SPI: class SPI -- a master-driven serial protocol diff --git a/docs/library/pyb.Servo.rst b/docs/library/pyb.Servo.rst index cea31fd28e..da117c8076 100644 --- a/docs/library/pyb.Servo.rst +++ b/docs/library/pyb.Servo.rst @@ -1,3 +1,4 @@ +.. currentmodule:: pyb .. _pyb.Servo: class Servo -- 3-wire hobby servo driver diff --git a/docs/library/pyb.Switch.rst b/docs/library/pyb.Switch.rst index daaed19420..a9aef4e2ec 100644 --- a/docs/library/pyb.Switch.rst +++ b/docs/library/pyb.Switch.rst @@ -1,3 +1,5 @@ +.. currentmodule:: pyb + class Switch -- switch object ============================= diff --git a/docs/library/pyb.Timer.rst b/docs/library/pyb.Timer.rst index d2a299bd29..a709e11bf7 100644 --- a/docs/library/pyb.Timer.rst +++ b/docs/library/pyb.Timer.rst @@ -1,3 +1,4 @@ +.. currentmodule:: pyb .. _pyb.Timer: class Timer -- control internal timers diff --git a/docs/library/pyb.UART.rst b/docs/library/pyb.UART.rst index 536b6f467d..3aa07b7356 100644 --- a/docs/library/pyb.UART.rst +++ b/docs/library/pyb.UART.rst @@ -1,3 +1,4 @@ +.. currentmodule:: pyb .. _pyb.UART: class UART -- duplex serial communication bus diff --git a/docs/library/pyb.USB_VCP.rst b/docs/library/pyb.USB_VCP.rst index cc4dbe5903..6a77f1eae3 100644 --- a/docs/library/pyb.USB_VCP.rst +++ b/docs/library/pyb.USB_VCP.rst @@ -1,3 +1,5 @@ +.. currentmodule:: pyb + class USB_VCP -- USB virtual comm port ====================================== -- cgit v1.2.3 From 0a4361ca671d4fc2b69543c2e7f787ae21467a67 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Wed, 8 Jun 2016 01:13:59 +0300 Subject: docs/machine.Pin: Remove explicit target. With currentmodule:: support, all targets should be generated properly by Sphinx. --- docs/library/machine.Pin.rst | 1 - 1 file changed, 1 deletion(-) (limited to 'docs/library') diff --git a/docs/library/machine.Pin.rst b/docs/library/machine.Pin.rst index 2d3385b065..773d9ed0d7 100644 --- a/docs/library/machine.Pin.rst +++ b/docs/library/machine.Pin.rst @@ -1,5 +1,4 @@ .. currentmodule:: machine -.. _machine.Pin: class Pin -- control I/O pins ============================= -- cgit v1.2.3 From 93968bd6fb15d1d49e0c2e4a2d412250cc653057 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Wed, 8 Jun 2016 01:32:16 +0300 Subject: docs/machine.UART: Cleanup pyboard section. --- docs/library/machine.UART.rst | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) (limited to 'docs/library') diff --git a/docs/library/machine.UART.rst b/docs/library/machine.UART.rst index 5552b9dd72..81e75e1ea3 100644 --- a/docs/library/machine.UART.rst +++ b/docs/library/machine.UART.rst @@ -37,7 +37,7 @@ using the standard stream methods:: uart.readinto(buf) # read and store into the given buffer uart.write('abc') # write the 3 characters -.. only:: port_machineoard +.. only:: port_pyboard Individual characters can be read/written using:: @@ -48,9 +48,6 @@ using the standard stream methods:: uart.any() # returns True if any characters waiting - *Note:* The stream functions ``read``, ``write``, etc. are new in MicroPython v1.3.4. - Earlier versions use ``uart.send`` and ``uart.recv``. - .. only:: port_wipy To check if there is anything to be read, use:: -- cgit v1.2.3 From 7d7243f44c68c5c1bfeba160a1650174c744722f Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Wed, 8 Jun 2016 01:33:49 +0300 Subject: docs/machine.*: Use proper class case in method headers. Class designator will be used as is in indexes, so must match actual class name. --- docs/library/machine.ADC.rst | 6 +++--- docs/library/machine.I2C.rst | 28 ++++++++++++++-------------- docs/library/machine.Pin.rst | 26 +++++++++++++------------- docs/library/machine.RTC.rst | 14 +++++++------- docs/library/machine.SD.rst | 4 ++-- docs/library/machine.SPI.rst | 12 ++++++------ docs/library/machine.Timer.rst | 6 +++--- docs/library/machine.UART.rst | 20 ++++++++++---------- 8 files changed, 58 insertions(+), 58 deletions(-) (limited to 'docs/library') diff --git a/docs/library/machine.ADC.rst b/docs/library/machine.ADC.rst index ef545f35f3..11381e98b0 100644 --- a/docs/library/machine.ADC.rst +++ b/docs/library/machine.ADC.rst @@ -32,7 +32,7 @@ Constructors Methods ------- -.. method:: adc.channel(id, \*, pin) +.. method:: ADC.channel(id, \*, pin) Create an analog pin. If only channel ID is given, the correct pin will be selected. Alternatively, only the pin can be passed and the correct @@ -43,11 +43,11 @@ Methods apin = adc.channel(pin='GP3') apin = adc.channel(id=1, pin='GP3') -.. method:: adc.init() +.. method:: ADC.init() Enable the ADC block. -.. method:: adc.deinit() +.. method:: ADC.deinit() Disable the ADC block. diff --git a/docs/library/machine.I2C.rst b/docs/library/machine.I2C.rst index c83c436ad9..2f020f6d47 100644 --- a/docs/library/machine.I2C.rst +++ b/docs/library/machine.I2C.rst @@ -62,7 +62,7 @@ General Methods .. only:: port_wipy - .. method:: i2c.init(mode, \*, baudrate=100000, pins=(SDA, SCL)) + .. method:: I2C.init(mode, \*, baudrate=100000, pins=(SDA, SCL)) Initialise the I2C bus with the given parameters: @@ -72,7 +72,7 @@ General Methods .. only:: port_esp8266 - .. method:: i2c.init(scl, sda, \*, freq=400000) + .. method:: I2C.init(scl, sda, \*, freq=400000) Initialise the I2C bus with the given arguments: @@ -80,13 +80,13 @@ General Methods - `sda` is a pin object for the SDA line - `freq` is the SCL clock rate -.. method:: i2c.deinit() +.. method:: I2C.deinit() Turn off the I2C bus. Availability: WiPy. -.. method:: i2c.scan() +.. method:: I2C.scan() Scan all I2C addresses between 0x08 and 0x77 inclusive and return a list of those that respond. A device responds if it pulls the SDA line low after @@ -101,19 +101,19 @@ The following methods implement the primitive I2C master bus operations and can be combined to make any I2C transaction. They are provided if you need more control over the bus, otherwise the standard methods (see below) can be used. -.. method:: i2c.start() +.. method:: I2C.start() Send a start bit on the bus (SDA transitions to low while SCL is high). Availability: ESP8266. -.. method:: i2c.stop() +.. method:: I2C.stop() Send a stop bit on the bus (SDA transitions to high while SCL is high). Availability: ESP8266. -.. method:: i2c.readinto(buf) +.. method:: I2C.readinto(buf) Reads bytes from the bus and stores them into `buf`. The number of bytes read is the length of `buf`. An ACK will be sent on the bus after @@ -122,7 +122,7 @@ control over the bus, otherwise the standard methods (see below) can be used. Availability: ESP8266. -.. method:: i2c.write(buf) +.. method:: I2C.write(buf) Write all the bytes from `buf` to the bus. Checks that an ACK is received after each byte and raises an OSError if not. @@ -135,12 +135,12 @@ Standard bus operations The following methods implement the standard I2C master read and write operations that target a given slave device. -.. method:: i2c.readfrom(addr, nbytes) +.. method:: I2C.readfrom(addr, nbytes) Read `nbytes` from the slave specified by `addr`. Returns a `bytes` object with the data read. -.. method:: i2c.readfrom_into(addr, buf) +.. method:: I2C.readfrom_into(addr, buf) Read into `buf` from the slave specified by `addr`. The number of bytes read will be the length of `buf`. @@ -148,7 +148,7 @@ operations that target a given slave device. On WiPy the return value is the number of bytes read. Otherwise the return value is `None`. -.. method:: i2c.writeto(addr, buf, \*, stop=True) +.. method:: I2C.writeto(addr, buf, \*, stop=True) Write the bytes from `buf` to the slave specified by `addr`. @@ -167,7 +167,7 @@ from and written to. In this case there are two addresses associated with an I2C transaction: the slave address and the memory address. The following methods are convenience functions to communicate with such devices. -.. method:: i2c.readfrom_mem(addr, memaddr, nbytes, \*, addrsize=8) +.. method:: I2C.readfrom_mem(addr, memaddr, nbytes, \*, addrsize=8) Read `nbytes` from the slave specified by `addr` starting from the memory address specified by `memaddr`. @@ -175,7 +175,7 @@ methods are convenience functions to communicate with such devices. this argument is not recognised and the address size is always 8 bits). Returns a `bytes` object with the data read. -.. method:: i2c.readfrom_mem_into(addr, memaddr, buf, \*, addrsize=8) +.. method:: I2C.readfrom_mem_into(addr, memaddr, buf, \*, addrsize=8) Read into `buf` from the slave specified by `addr` starting from the memory address specified by `memaddr`. The number of bytes read is the @@ -186,7 +186,7 @@ methods are convenience functions to communicate with such devices. On WiPy the return value is the number of bytes read. Otherwise the return value is `None`. -.. method:: i2c.writeto_mem(addr, memaddr, buf, \*, addrsize=8) +.. method:: I2C.writeto_mem(addr, memaddr, buf, \*, addrsize=8) Write `buf` to the slave specified by `addr` starting from the memory address specified by `memaddr`. diff --git a/docs/library/machine.Pin.rst b/docs/library/machine.Pin.rst index 773d9ed0d7..f672abe30b 100644 --- a/docs/library/machine.Pin.rst +++ b/docs/library/machine.Pin.rst @@ -61,14 +61,14 @@ Constructors .. class:: machine.Pin(id, ...) Create a new Pin object associated with the id. If additional arguments are given, - they are used to initialise the pin. See :meth:`pin.init`. + they are used to initialise the pin. See :meth:`Pin.init`. Methods ------- .. only:: port_wipy - .. method:: pin.init(mode, pull, \*, drive, alt) + .. method:: Pin.init(mode, pull, \*, drive, alt) Initialise the pin: @@ -98,13 +98,13 @@ Methods Returns: ``None``. - .. method:: pin.id() + .. method:: Pin.id() Get the pin id. .. only:: port_esp8266 - .. method:: pin.init(mode, pull=None, \*, value) + .. method:: Pin.init(mode, pull=None, \*, value) Initialise the pin: @@ -121,7 +121,7 @@ Methods - if `value` is given then it is the output value to set the pin if it is in output mode. -.. method:: pin.value([value]) +.. method:: Pin.value([value]) Get or set the digital logic level of the pin: @@ -133,9 +133,9 @@ Methods .. method:: pin([value]) Pin objects are callable. The call method provides a (fast) shortcut to set and get the value of the pin. - See :func:`pin.value` for more details. + See :func:`Pin.value` for more details. -.. method:: pin.alt_list() +.. method:: Pin.alt_list() Returns a list of the alternate functions supported by the pin. List items are a tuple of the form: ``('ALT_FUN_NAME', ALT_FUN_INDEX)`` @@ -144,23 +144,23 @@ Methods .. only:: port_wipy - .. method:: pin.toggle() + .. method:: Pin.toggle() Toggle the value of the pin. - .. method:: pin.mode([mode]) + .. method:: Pin.mode([mode]) Get or set the pin mode. - .. method:: pin.pull([pull]) + .. method:: Pin.pull([pull]) Get or set the pin pull. - .. method:: pin.drive([drive]) + .. method:: Pin.drive([drive]) Get or set the pin drive strength. - .. method:: pin.irq(\*, trigger, priority=1, handler=None, wake=None) + .. method:: Pin.irq(\*, trigger, priority=1, handler=None, wake=None) Create a callback to be triggered when the input level at the pin changes. @@ -194,7 +194,7 @@ Methods .. only:: port_esp8266 - .. method:: pin.irq(\*, trigger, handler=None) + .. method:: Pin.irq(\*, trigger, handler=None) Create a callback to be triggered when the input level at the pin changes. diff --git a/docs/library/machine.RTC.rst b/docs/library/machine.RTC.rst index 684f31aa0f..219ca273d0 100644 --- a/docs/library/machine.RTC.rst +++ b/docs/library/machine.RTC.rst @@ -24,35 +24,35 @@ Constructors Methods ------- -.. method:: rtc.init(datetime) +.. method:: RTC.init(datetime) Initialise the RTC. Datetime is a tuple of the form: ``(year, month, day[, hour[, minute[, second[, microsecond[, tzinfo]]]]])`` -.. method:: rtc.now() +.. method:: RTC.now() Get get the current datetime tuple. -.. method:: rtc.deinit() +.. method:: RTC.deinit() Resets the RTC to the time of January 1, 2015 and starts running it again. -.. method:: rtc.alarm(id, time, /*, repeat=False) +.. method:: RTC.alarm(id, time, /*, repeat=False) Set the RTC alarm. Time might be either a milllisecond value to program the alarm to current time + time_in_ms in the future, or a datetimetuple. If the time passed is in milliseconds, repeat can be set to ``True`` to make the alarm periodic. -.. method:: rtc.alarm_left(alarm_id=0) +.. method:: RTC.alarm_left(alarm_id=0) Get the number of milliseconds left before the alarm expires. -.. method:: rtc.cancel(alarm_id=0) +.. method:: RTC.cancel(alarm_id=0) Cancel a running alarm. -.. method:: rtc.irq(\*, trigger, handler=None, wake=machine.IDLE) +.. method:: RTC.irq(\*, trigger, handler=None, wake=machine.IDLE) Create an irq object triggered by a real time clock alarm. diff --git a/docs/library/machine.SD.rst b/docs/library/machine.SD.rst index d1a3b4e358..330ef217ae 100644 --- a/docs/library/machine.SD.rst +++ b/docs/library/machine.SD.rst @@ -32,11 +32,11 @@ Constructors Methods ------- -.. method:: sd.init(id=0, pins=('GP10', 'GP11', 'GP15')) +.. method:: SD.init(id=0, pins=('GP10', 'GP11', 'GP15')) Enable the SD card. In order to initalize the card, give it a 3-tuple: ``(clk_pin, cmd_pin, dat0_pin)``. -.. method:: sd.deinit() +.. method:: SD.deinit() Disable the SD card. diff --git a/docs/library/machine.SPI.rst b/docs/library/machine.SPI.rst index 285cd37b4b..8e66660768 100644 --- a/docs/library/machine.SPI.rst +++ b/docs/library/machine.SPI.rst @@ -35,7 +35,7 @@ Constructors Methods ------- -.. method:: spi.init(mode, baudrate=1000000, \*, polarity=0, phase=0, bits=8, firstbit=SPI.MSB, pins=(CLK, MOSI, MISO)) +.. method:: SPI.init(mode, baudrate=1000000, \*, polarity=0, phase=0, bits=8, firstbit=SPI.MSB, pins=(CLK, MOSI, MISO)) Initialise the SPI bus with the given parameters: @@ -48,27 +48,27 @@ Methods - ``firstbit`` can be ``SPI.MSB`` only. - ``pins`` is an optional tupple with the pins to assign to the SPI bus. -.. method:: spi.deinit() +.. method:: SPI.deinit() Turn off the SPI bus. -.. method:: spi.write(buf) +.. method:: SPI.write(buf) Write the data contained in ``buf``. Returns the number of bytes written. -.. method:: spi.read(nbytes, *, write=0x00) +.. method:: SPI.read(nbytes, *, write=0x00) Read the ``nbytes`` while writing the data specified by ``write``. Return the number of bytes read. -.. method:: spi.readinto(buf, *, write=0x00) +.. method:: SPI.readinto(buf, *, write=0x00) Read into the buffer specified by ``buf`` while writing the data specified by ``write``. Return the number of bytes read. -.. method:: spi.write_readinto(write_buf, read_buf) +.. method:: SPI.write_readinto(write_buf, read_buf) Write from ``write_buf`` and read into ``read_buf``. Both buffers must have the same length. diff --git a/docs/library/machine.Timer.rst b/docs/library/machine.Timer.rst index 8bb9a36600..0e596588eb 100644 --- a/docs/library/machine.Timer.rst +++ b/docs/library/machine.Timer.rst @@ -72,7 +72,7 @@ Methods .. only:: port_wipy - .. method:: timer.init(mode, \*, width=16) + .. method:: Timer.init(mode, \*, width=16) Initialise the timer. Example:: @@ -93,14 +93,14 @@ Methods (or large periods), 32-bit timers should be used. 32-bit mode is only available for ``ONE_SHOT`` AND ``PERIODIC`` modes. -.. method:: timer.deinit() +.. method:: Timer.deinit() Deinitialises the timer. Disables all channels and associated IRQs. Stops the timer, and disables the timer peripheral. .. only:: port_wipy - .. method:: timer.channel(channel, \**, freq, period, polarity=Timer.POSITIVE, duty_cycle=0) + .. method:: Timer.channel(channel, \**, freq, period, polarity=Timer.POSITIVE, duty_cycle=0) If only a channel identifier passed, then a previously initialized channel object is returned (or ``None`` if there is no previous channel). diff --git a/docs/library/machine.UART.rst b/docs/library/machine.UART.rst index 81e75e1ea3..594a11dce9 100644 --- a/docs/library/machine.UART.rst +++ b/docs/library/machine.UART.rst @@ -70,7 +70,7 @@ Methods .. only:: port_wipy - .. method:: uart.init(baudrate=9600, bits=8, parity=None, stop=1, \*, pins=(TX, RX, RTS, CTS)) + .. method:: UART.init(baudrate=9600, bits=8, parity=None, stop=1, \*, pins=(TX, RX, RTS, CTS)) Initialise the UART bus with the given parameters: @@ -86,28 +86,28 @@ Methods .. only:: not port_esp8266 - .. method:: uart.deinit() + .. method:: UART.deinit() Turn off the UART bus. - .. method:: uart.any() + .. method:: UART.any() Return the number of characters available for reading. -.. method:: uart.read([nbytes]) +.. method:: UART.read([nbytes]) Read characters. If ``nbytes`` is specified then read at most that many bytes. Return value: a bytes object containing the bytes read in. Returns ``None`` on timeout. -.. method:: uart.readall() +.. method:: UART.readall() Read as much data as possible. Return value: a bytes object or ``None`` on timeout. -.. method:: uart.readinto(buf[, nbytes]) +.. method:: UART.readinto(buf[, nbytes]) Read bytes into the ``buf``. If ``nbytes`` is specified then read at most that many bytes. Otherwise, read at most ``len(buf)`` bytes. @@ -115,13 +115,13 @@ Methods Return value: number of bytes read and stored into ``buf`` or ``None`` on timeout. -.. method:: uart.readline() +.. method:: UART.readline() Read a line, ending in a newline character. Return value: the line read or ``None`` on timeout. -.. method:: uart.write(buf) +.. method:: UART.write(buf) Write the buffer of bytes to the bus. @@ -129,7 +129,7 @@ Methods .. only:: not port_esp8266 - .. method:: uart.sendbreak() + .. method:: UART.sendbreak() Send a break condition on the bus. This drives the bus low for a duration of 13 bits. @@ -137,7 +137,7 @@ Methods .. only:: port_wipy - .. method:: uart.irq(trigger, priority=1, handler=None, wake=machine.IDLE) + .. method:: UART.irq(trigger, priority=1, handler=None, wake=machine.IDLE) Create a callback to be triggered when data is received on the UART. -- cgit v1.2.3 From bba77a2d0166918aeba8c6b8e9d8a4c3f6a8c4dd Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Wed, 8 Jun 2016 01:37:03 +0300 Subject: docs/machine.Pin: Add class designator to all constants. This makes rendered docs to not provide incorrect information and consistent with how it's down for other machine classes. --- docs/library/machine.Pin.rst | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) (limited to 'docs/library') diff --git a/docs/library/machine.Pin.rst b/docs/library/machine.Pin.rst index f672abe30b..6d6fb860d3 100644 --- a/docs/library/machine.Pin.rst +++ b/docs/library/machine.Pin.rst @@ -228,28 +228,28 @@ Constants The following constants are used to configure the pin objects. Note that not all constants are available on all ports. -.. data:: IN - OUT - OPEN_DRAIN - ALT - ALT_OPEN_DRAIN +.. data:: Pin.IN + Pin.OUT + Pin.OPEN_DRAIN + Pin.ALT + Pin.ALT_OPEN_DRAIN Selects the pin mode. -.. data:: PULL_UP - PULL_DOWN +.. data:: Pin.PULL_UP + Pin.PULL_DOWN Selects the whether there is a pull up/down resistor. -.. data:: LOW_POWER - MED_POWER - HIGH_POWER +.. data:: Pin.LOW_POWER + Pin.MED_POWER + Pin.HIGH_POWER Selects the pin drive strength. -.. data:: IRQ_FALLING - IRQ_RISING - IRQ_LOW_LEVEL - IRQ_HIGH_LEVEL +.. data:: Pin.IRQ_FALLING + Pin.IRQ_RISING + Pin.IRQ_LOW_LEVEL + Pin.IRQ_HIGH_LEVEL Selects the IRQ trigger type. -- cgit v1.2.3 From 8171995ee9145922d86b9130e4084466ad8c9f0e Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Wed, 8 Jun 2016 15:49:30 +0300 Subject: docs/pyb.CAN: Mark CAN.initfilterbanks() as classmethod explicitly. --- docs/library/pyb.CAN.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/library') diff --git a/docs/library/pyb.CAN.rst b/docs/library/pyb.CAN.rst index efa2f19d50..7d7dfabd8e 100644 --- a/docs/library/pyb.CAN.rst +++ b/docs/library/pyb.CAN.rst @@ -36,7 +36,7 @@ Constructors Class Methods ------------- -.. method:: CAN.initfilterbanks(nr) +.. classmethod:: CAN.initfilterbanks(nr) Reset and disable all filter banks and assign how many banks should be available for CAN(1). -- cgit v1.2.3 From 0d8c22b122cf044e9bbb561d84ef614150a176e5 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Wed, 8 Jun 2016 15:57:46 +0300 Subject: docs/pyb.Pin: af_list() is a normal method, not a class method. --- docs/library/pyb.Pin.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'docs/library') diff --git a/docs/library/pyb.Pin.rst b/docs/library/pyb.Pin.rst index 65ae601bed..c5e91e0b16 100644 --- a/docs/library/pyb.Pin.rst +++ b/docs/library/pyb.Pin.rst @@ -85,11 +85,7 @@ Constructors Class methods ------------- - - .. method:: Pin.af_list() - - Returns an array of alternate functions available for this pin. - + .. method:: Pin.debug([state]) Get or set the debugging state (``True`` or ``False`` for on or off). @@ -179,6 +175,10 @@ Methods Get the pin port. + .. method:: Pin.af_list() + + Returns an array of alternate functions available for this pin. + .. method:: pin.pull() Returns the currently configured pull of the pin. The integer returned -- cgit v1.2.3 From 585aafc27eb7fa8fe660e3eeaa29bf8d7ab99213 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Wed, 8 Jun 2016 16:00:12 +0300 Subject: docs/pyb.ExtInt,pyb.Pin: Mark up class methods as such. --- docs/library/pyb.ExtInt.rst | 2 +- docs/library/pyb.Pin.rst | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/library') diff --git a/docs/library/pyb.ExtInt.rst b/docs/library/pyb.ExtInt.rst index 8344a14c2e..89db62e464 100644 --- a/docs/library/pyb.ExtInt.rst +++ b/docs/library/pyb.ExtInt.rst @@ -72,7 +72,7 @@ Constructors Class methods ------------- -.. method:: ExtInt.regs() +.. classmethod:: ExtInt.regs() Dump the values of the EXTI registers. diff --git a/docs/library/pyb.Pin.rst b/docs/library/pyb.Pin.rst index c5e91e0b16..50d52eff34 100644 --- a/docs/library/pyb.Pin.rst +++ b/docs/library/pyb.Pin.rst @@ -86,15 +86,15 @@ Constructors Class methods ------------- - .. method:: Pin.debug([state]) + .. classmethod:: Pin.debug([state]) Get or set the debugging state (``True`` or ``False`` for on or off). - .. method:: Pin.dict([dict]) + .. classmethod:: Pin.dict([dict]) Get or set the pin mapper dictionary. - .. method:: Pin.mapper([fun]) + .. classmethod:: Pin.mapper([fun]) Get or set the pin mapper function. -- cgit v1.2.3 From a384a5313013d8ffda4db0e509cf798a080b3526 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Wed, 8 Jun 2016 16:21:28 +0300 Subject: docs/pyb.*: Use proper class case in method headers. Class designator will be used as is in indexes, so must match actual class name. --- docs/library/pyb.ADC.rst | 4 ++-- docs/library/pyb.Accel.rst | 10 +++++----- docs/library/pyb.CAN.rst | 16 ++++++++-------- docs/library/pyb.DAC.rst | 12 ++++++------ docs/library/pyb.ExtInt.rst | 8 ++++---- docs/library/pyb.I2C.rst | 16 ++++++++-------- docs/library/pyb.LCD.rst | 18 +++++++++--------- docs/library/pyb.LED.rst | 8 ++++---- docs/library/pyb.Pin.rst | 22 +++++++++++----------- docs/library/pyb.RTC.rst | 8 ++++---- docs/library/pyb.SPI.rst | 10 +++++----- docs/library/pyb.Servo.rst | 8 ++++---- docs/library/pyb.Switch.rst | 7 ++++--- docs/library/pyb.Timer.rst | 18 +++++++++--------- docs/library/pyb.UART.rst | 26 +++++++++++++------------- docs/library/pyb.USB_VCP.rst | 24 ++++++++++++------------ 16 files changed, 108 insertions(+), 107 deletions(-) (limited to 'docs/library') diff --git a/docs/library/pyb.ADC.rst b/docs/library/pyb.ADC.rst index e75efae7b5..2ffd4e16f5 100644 --- a/docs/library/pyb.ADC.rst +++ b/docs/library/pyb.ADC.rst @@ -36,12 +36,12 @@ Methods .. only:: port_pyboard - .. method:: adc.read() + .. method:: ADC.read() Read the value on the analog pin and return it. The returned value will be between 0 and 4095. - .. method:: adc.read_timed(buf, timer) + .. method:: ADC.read_timed(buf, timer) Read analog values into ``buf`` at a rate set by the ``timer`` object. diff --git a/docs/library/pyb.Accel.rst b/docs/library/pyb.Accel.rst index 53e410dfb9..2ae357fe70 100644 --- a/docs/library/pyb.Accel.rst +++ b/docs/library/pyb.Accel.rst @@ -22,7 +22,7 @@ Constructors Methods ------- -.. method:: accel.filtered_xyz() +.. method:: Accel.filtered_xyz() Get a 3-tuple of filtered x, y and z values. @@ -31,18 +31,18 @@ Methods with the sample from the current call. Returned values are therefore 4 times the size of what they would be from the raw x(), y() and z() calls. -.. method:: accel.tilt() +.. method:: Accel.tilt() Get the tilt register. -.. method:: accel.x() +.. method:: Accel.x() Get the x-axis value. -.. method:: accel.y() +.. method:: Accel.y() Get the y-axis value. -.. method:: accel.z() +.. method:: Accel.z() Get the z-axis value. diff --git a/docs/library/pyb.CAN.rst b/docs/library/pyb.CAN.rst index 7d7dfabd8e..9e71f12b06 100644 --- a/docs/library/pyb.CAN.rst +++ b/docs/library/pyb.CAN.rst @@ -48,7 +48,7 @@ Class Methods Methods ------- -.. method:: can.init(mode, extframe=False, prescaler=100, \*, sjw=1, bs1=6, bs2=8) +.. method:: CAN.init(mode, extframe=False, prescaler=100, \*, sjw=1, bs1=6, bs2=8) Initialise the CAN bus with the given parameters: @@ -80,11 +80,11 @@ Methods See page 680 of the STM32F405 datasheet for more details. -.. method:: can.deinit() +.. method:: CAN.deinit() Turn off the CAN bus. -.. method:: can.setfilter(bank, mode, fifo, params, \*, rtr) +.. method:: CAN.setfilter(bank, mode, fifo, params, \*, rtr) Configure a filter bank: @@ -126,17 +126,17 @@ Methods |CAN.MASK32 |1 | +-----------+----------------------+ -.. method:: can.clearfilter(bank) +.. method:: CAN.clearfilter(bank) Clear and disables a filter bank: - ``bank`` is the filter bank that is to be cleared. -.. method:: can.any(fifo) +.. method:: CAN.any(fifo) Return ``True`` if any message waiting on the FIFO, else ``False``. -.. method:: can.recv(fifo, \*, timeout=5000) +.. method:: CAN.recv(fifo, \*, timeout=5000) Receive data on the bus: @@ -150,7 +150,7 @@ Methods - The FMI (Filter Match Index) value. - An array containing the data. -.. method:: can.send(data, id, \*, timeout=0, rtr=False) +.. method:: CAN.send(data, id, \*, timeout=0, rtr=False) Send a message on the bus: @@ -170,7 +170,7 @@ Methods Return value: ``None``. -.. method:: can.rxcallback(fifo, fun) +.. method:: CAN.rxcallback(fifo, fun) Register a function to be called when a message is accepted into a empty fifo: diff --git a/docs/library/pyb.DAC.rst b/docs/library/pyb.DAC.rst index 02c85fdd1b..4b9651e27e 100644 --- a/docs/library/pyb.DAC.rst +++ b/docs/library/pyb.DAC.rst @@ -63,32 +63,32 @@ Constructors Methods ------- -.. method:: dac.init(bits=8) +.. method:: DAC.init(bits=8) Reinitialise the DAC. ``bits`` can be 8 or 12. -.. method:: dac.deinit() +.. method:: DAC.deinit() De-initialise the DAC making its pin available for other uses. -.. method:: dac.noise(freq) +.. method:: DAC.noise(freq) Generate a pseudo-random noise signal. A new random sample is written to the DAC output at the given frequency. -.. method:: dac.triangle(freq) +.. method:: DAC.triangle(freq) Generate a triangle wave. The value on the DAC output changes at the given frequency, and the frequence of the repeating triangle wave itself is 2048 times smaller. -.. method:: dac.write(value) +.. method:: DAC.write(value) Direct access to the DAC output. The minimum value is 0. The maximum value is 2\*\*``bits``-1, where ``bits`` is set when creating the DAC object or by using the ``init`` method. -.. method:: dac.write_timed(data, freq, \*, mode=DAC.NORMAL) +.. method:: DAC.write_timed(data, freq, \*, mode=DAC.NORMAL) Initiates a burst of RAM to DAC using a DMA transfer. The input data is treated as an array of bytes in 8-bit mode, and diff --git a/docs/library/pyb.ExtInt.rst b/docs/library/pyb.ExtInt.rst index 89db62e464..d8f4d92bb8 100644 --- a/docs/library/pyb.ExtInt.rst +++ b/docs/library/pyb.ExtInt.rst @@ -80,20 +80,20 @@ Class methods Methods ------- -.. method:: extint.disable() +.. method:: ExtInt.disable() Disable the interrupt associated with the ExtInt object. This could be useful for debouncing. -.. method:: extint.enable() +.. method:: ExtInt.enable() Enable a disabled interrupt. -.. method:: extint.line() +.. method:: ExtInt.line() Return the line number that the pin is mapped to. -.. method:: extint.swint() +.. method:: ExtInt.swint() Trigger the callback from software. diff --git a/docs/library/pyb.I2C.rst b/docs/library/pyb.I2C.rst index d8eb8655c6..210b4ccf21 100644 --- a/docs/library/pyb.I2C.rst +++ b/docs/library/pyb.I2C.rst @@ -86,13 +86,13 @@ Constructors Methods ------- -.. method:: i2c.deinit() +.. method:: I2C.deinit() Turn off the I2C bus. .. only:: port_pyboard - .. method:: i2c.init(mode, \*, addr=0x12, baudrate=400000, gencall=False) + .. method:: I2C.init(mode, \*, addr=0x12, baudrate=400000, gencall=False) Initialise the I2C bus with the given parameters: @@ -101,11 +101,11 @@ Methods - ``baudrate`` is the SCL clock rate (only sensible for a master) - ``gencall`` is whether to support general call mode - .. method:: i2c.is_ready(addr) + .. method:: I2C.is_ready(addr) Check if an I2C device responds to the given address. Only valid when in master mode. - .. method:: i2c.mem_read(data, addr, memaddr, \*, timeout=5000, addr_size=8) + .. method:: I2C.mem_read(data, addr, memaddr, \*, timeout=5000, addr_size=8) Read from the memory of an I2C device: @@ -118,7 +118,7 @@ Methods Returns the read data. This is only valid in master mode. - .. method:: i2c.mem_write(data, addr, memaddr, \*, timeout=5000, addr_size=8) + .. method:: I2C.mem_write(data, addr, memaddr, \*, timeout=5000, addr_size=8) Write to the memory of an I2C device: @@ -131,7 +131,7 @@ Methods Returns ``None``. This is only valid in master mode. - .. method:: i2c.recv(recv, addr=0x00, \*, timeout=5000) + .. method:: I2C.recv(recv, addr=0x00, \*, timeout=5000) Receive data on the bus: @@ -143,7 +143,7 @@ Methods Return value: if ``recv`` is an integer then a new buffer of the bytes received, otherwise the same buffer that was passed in to ``recv``. - .. method:: i2c.send(send, addr=0x00, \*, timeout=5000) + .. method:: I2C.send(send, addr=0x00, \*, timeout=5000) Send data on the bus: @@ -153,7 +153,7 @@ Methods Return value: ``None``. -.. method:: i2c.scan() +.. method:: I2C.scan() Scan all I2C addresses from 0x01 to 0x7f and return a list of those that respond. Only valid when in master mode. diff --git a/docs/library/pyb.LCD.rst b/docs/library/pyb.LCD.rst index 06fe35589d..83cf890b63 100644 --- a/docs/library/pyb.LCD.rst +++ b/docs/library/pyb.LCD.rst @@ -49,48 +49,48 @@ Constructors Methods ------- -.. method:: lcd.command(instr_data, buf) +.. method:: LCD.command(instr_data, buf) Send an arbitrary command to the LCD. Pass 0 for ``instr_data`` to send an instruction, otherwise pass 1 to send data. ``buf`` is a buffer with the instructions/data to send. -.. method:: lcd.contrast(value) +.. method:: LCD.contrast(value) Set the contrast of the LCD. Valid values are between 0 and 47. -.. method:: lcd.fill(colour) +.. method:: LCD.fill(colour) Fill the screen with the given colour (0 or 1 for white or black). This method writes to the hidden buffer. Use ``show()`` to show the buffer. -.. method:: lcd.get(x, y) +.. method:: LCD.get(x, y) Get the pixel at the position ``(x, y)``. Returns 0 or 1. This method reads from the visible buffer. -.. method:: lcd.light(value) +.. method:: LCD.light(value) Turn the backlight on/off. True or 1 turns it on, False or 0 turns it off. -.. method:: lcd.pixel(x, y, colour) +.. method:: LCD.pixel(x, y, colour) Set the pixel at ``(x, y)`` to the given colour (0 or 1). This method writes to the hidden buffer. Use ``show()`` to show the buffer. -.. method:: lcd.show() +.. method:: LCD.show() Show the hidden buffer on the screen. -.. method:: lcd.text(str, x, y, colour) +.. method:: LCD.text(str, x, y, colour) Draw the given text to the position ``(x, y)`` using the given colour (0 or 1). This method writes to the hidden buffer. Use ``show()`` to show the buffer. -.. method:: lcd.write(str) +.. method:: LCD.write(str) Write the string ``str`` to the screen. It will appear immediately. diff --git a/docs/library/pyb.LED.rst b/docs/library/pyb.LED.rst index fd997e40f7..1ab73a69c9 100644 --- a/docs/library/pyb.LED.rst +++ b/docs/library/pyb.LED.rst @@ -20,7 +20,7 @@ Constructors Methods ------- -.. method:: led.intensity([value]) +.. method:: LED.intensity([value]) Get or set the LED intensity. Intensity ranges between 0 (off) and 255 (full on). If no argument is given, return the LED intensity. @@ -32,15 +32,15 @@ Methods relevant LED is set to a value between 1 and 254. Otherwise the timers are free for general purpose use. -.. method:: led.off() +.. method:: LED.off() Turn the LED off. -.. method:: led.on() +.. method:: LED.on() Turn the LED on, to maximum intensity. -.. method:: led.toggle() +.. method:: LED.toggle() Toggle the LED between on (maximum intensity) and off. If the LED is at non-zero intensity then it is considered "on" and toggle will turn it off. diff --git a/docs/library/pyb.Pin.rst b/docs/library/pyb.Pin.rst index 50d52eff34..30ffccdbd4 100644 --- a/docs/library/pyb.Pin.rst +++ b/docs/library/pyb.Pin.rst @@ -104,7 +104,7 @@ Methods .. only:: port_pyboard - .. method:: pin.init(mode, pull=Pin.PULL_NONE, af=-1) + .. method:: Pin.init(mode, pull=Pin.PULL_NONE, af=-1) Initialise the pin: @@ -128,7 +128,7 @@ Methods Returns: ``None``. -.. method:: pin.value([value]) +.. method:: Pin.value([value]) Get or set the digital logic level of the pin: @@ -139,39 +139,39 @@ Methods .. only:: port_pyboard - .. method:: pin.__str__() + .. method:: Pin.__str__() Return a string describing the pin object. - .. method:: pin.af() + .. method:: Pin.af() Returns the currently configured alternate-function of the pin. The integer returned will match one of the allowed constants for the af argument to the init function. - .. method:: pin.gpio() + .. method:: Pin.gpio() Returns the base address of the GPIO block associated with this pin. - .. method:: pin.mode() + .. method:: Pin.mode() Returns the currently configured mode of the pin. The integer returned will match one of the allowed constants for the mode argument to the init function. - .. method:: pin.name() + .. method:: Pin.name() Get the pin name. - .. method:: pin.names() + .. method:: Pin.names() Returns the cpu and board names for this pin. - .. method:: pin.pin() + .. method:: Pin.pin() Get the pin number. - .. method:: pin.port() + .. method:: Pin.port() Get the pin port. @@ -179,7 +179,7 @@ Methods Returns an array of alternate functions available for this pin. -.. method:: pin.pull() +.. method:: Pin.pull() Returns the currently configured pull of the pin. The integer returned will match one of the allowed constants for the pull argument to the init diff --git a/docs/library/pyb.RTC.rst b/docs/library/pyb.RTC.rst index 19401b9823..383ddf20c2 100644 --- a/docs/library/pyb.RTC.rst +++ b/docs/library/pyb.RTC.rst @@ -25,7 +25,7 @@ Constructors Methods ------- -.. method:: rtc.datetime([datetimetuple]) +.. method:: RTC.datetime([datetimetuple]) Get or set the date and time of the RTC. @@ -45,7 +45,7 @@ Methods .. only:: port_pyboard - .. method:: rtc.wakeup(timeout, callback=None) + .. method:: RTC.wakeup(timeout, callback=None) Set the RTC wakeup timer to trigger repeatedly at every ``timeout`` milliseconds. This trigger can wake the pyboard from both the sleep @@ -56,7 +56,7 @@ Methods If ``callback`` is given then it is executed at every trigger of the wakeup timer. ``callback`` must take exactly one argument. - .. method:: rtc.info() + .. method:: RTC.info() Get information about the startup time and reset source. @@ -65,7 +65,7 @@ Methods - Bit 0x10000 is set if a power-on reset occurred. - Bit 0x20000 is set if an external reset occurred - .. method:: rtc.calibration(cal) + .. method:: RTC.calibration(cal) Get or set RTC calibration. diff --git a/docs/library/pyb.SPI.rst b/docs/library/pyb.SPI.rst index 0b5546513b..54ecc65b6d 100644 --- a/docs/library/pyb.SPI.rst +++ b/docs/library/pyb.SPI.rst @@ -51,13 +51,13 @@ Constructors Methods ------- -.. method:: spi.deinit() +.. method:: SPI.deinit() Turn off the SPI bus. .. only:: port_pyboard - .. method:: spi.init(mode, baudrate=328125, \*, prescaler, polarity=1, phase=0, bits=8, firstbit=SPI.MSB, ti=False, crc=None) + .. method:: SPI.init(mode, baudrate=328125, \*, prescaler, polarity=1, phase=0, bits=8, firstbit=SPI.MSB, ti=False, crc=None) Initialise the SPI bus with the given parameters: @@ -83,7 +83,7 @@ Methods .. only:: port_pyboard - .. method:: spi.recv(recv, \*, timeout=5000) + .. method:: SPI.recv(recv, \*, timeout=5000) Receive data on the bus: @@ -94,7 +94,7 @@ Methods Return value: if ``recv`` is an integer then a new buffer of the bytes received, otherwise the same buffer that was passed in to ``recv``. - .. method:: spi.send(send, \*, timeout=5000) + .. method:: SPI.send(send, \*, timeout=5000) Send data on the bus: @@ -103,7 +103,7 @@ Methods Return value: ``None``. - .. method:: spi.send_recv(send, recv=None, \*, timeout=5000) + .. method:: SPI.send_recv(send, recv=None, \*, timeout=5000) Send and receive data on the bus at the same time: diff --git a/docs/library/pyb.Servo.rst b/docs/library/pyb.Servo.rst index da117c8076..b3ce71d11a 100644 --- a/docs/library/pyb.Servo.rst +++ b/docs/library/pyb.Servo.rst @@ -38,7 +38,7 @@ Constructors Methods ------- -.. method:: servo.angle([angle, time=0]) +.. method:: Servo.angle([angle, time=0]) If no arguments are given, this function returns the current angle. @@ -49,7 +49,7 @@ Methods angle. If omitted, then the servo moves as quickly as possible to its new position. -.. method:: servo.speed([speed, time=0]) +.. method:: Servo.speed([speed, time=0]) If no arguments are given, this function returns the current speed. @@ -59,14 +59,14 @@ Methods - ``time`` is the number of milliseconds to take to get to the specified speed. If omitted, then the servo accelerates as quickly as possible. -.. method:: servo.pulse_width([value]) +.. method:: Servo.pulse_width([value]) If no arguments are given, this function returns the current raw pulse-width value. If an argument is given, this function sets the raw pulse-width value. -.. method:: servo.calibration([pulse_min, pulse_max, pulse_centre, [pulse_angle_90, pulse_speed_100]]) +.. method:: Servo.calibration([pulse_min, pulse_max, pulse_centre, [pulse_angle_90, pulse_speed_100]]) If no arguments are given, this function returns the current calibration data, as a 5-tuple. diff --git a/docs/library/pyb.Switch.rst b/docs/library/pyb.Switch.rst index a9aef4e2ec..bc62b6eee9 100644 --- a/docs/library/pyb.Switch.rst +++ b/docs/library/pyb.Switch.rst @@ -29,11 +29,12 @@ Constructors Methods ------- -.. method:: switch() +.. method:: Switch.__call__() - Return the switch state: ``True`` if pressed down, ``False`` otherwise. + Call switch object directly to get its state: ``True`` if pressed down, + ``False`` otherwise. -.. method:: switch.callback(fun) +.. method:: Switch.callback(fun) Register the given function to be called when the switch is pressed down. If ``fun`` is ``None``, then it disables the callback. diff --git a/docs/library/pyb.Timer.rst b/docs/library/pyb.Timer.rst index a709e11bf7..ffb092caa3 100644 --- a/docs/library/pyb.Timer.rst +++ b/docs/library/pyb.Timer.rst @@ -68,7 +68,7 @@ Methods .. only:: port_pyboard - .. method:: timer.init(\*, freq, prescaler, period) + .. method:: Timer.init(\*, freq, prescaler, period) Initialise the timer. Initialisation must be either by frequency (in Hz) or by prescaler and period:: @@ -115,7 +115,7 @@ Methods You must either specify freq or both of period and prescaler. -.. method:: timer.deinit() +.. method:: Timer.deinit() Deinitialises the timer. @@ -128,7 +128,7 @@ Methods .. only:: port_pyboard - .. method:: timer.callback(fun) + .. method:: Timer.callback(fun) Set the function to be called when the timer triggers. ``fun`` is passed 1 argument, the timer object. @@ -136,7 +136,7 @@ Methods .. only:: port_pyboard - .. method:: timer.channel(channel, mode, ...) + .. method:: Timer.channel(channel, mode, ...) If only a channel number is passed, then a previously initialized channel object is returned (or ``None`` if there is no previous channel). @@ -212,27 +212,27 @@ Methods .. only:: port_pyboard - .. method:: timer.counter([value]) + .. method:: Timer.counter([value]) Get or set the timer counter. .. only:: port_pyboard - .. method:: timer.freq([value]) + .. method:: Timer.freq([value]) Get or set the frequency for the timer (changes prescaler and period if set). .. only:: port_pyboard - .. method:: timer.period([value]) + .. method:: Timer.period([value]) Get or set the period of the timer. - .. method:: timer.prescaler([value]) + .. method:: Timer.prescaler([value]) Get or set the prescaler for the timer. - .. method:: timer.source_freq() + .. method:: Timer.source_freq() Get the frequency of the source of the timer. diff --git a/docs/library/pyb.UART.rst b/docs/library/pyb.UART.rst index 3aa07b7356..4a692469f8 100644 --- a/docs/library/pyb.UART.rst +++ b/docs/library/pyb.UART.rst @@ -77,7 +77,7 @@ Methods .. only:: port_pyboard - .. method:: uart.init(baudrate, bits=8, parity=None, stop=1, \*, timeout=1000, flow=0, timeout_char=0, read_buf_len=64) + .. method:: UART.init(baudrate, bits=8, parity=None, stop=1, \*, timeout=1000, flow=0, timeout_char=0, read_buf_len=64) Initialise the UART bus with the given parameters: @@ -101,22 +101,22 @@ Methods *Note:* with parity=None, only 8 and 9 bits are supported. With parity enabled, only 7 and 8 bits are supported. -.. method:: uart.deinit() +.. method:: UART.deinit() Turn off the UART bus. .. only:: port_pyboard - .. method:: uart.any() + .. method:: UART.any() Returns the number of bytes waiting (may be 0). - .. method:: uart.writechar(char) + .. method:: UART.writechar(char) Write a single character on the bus. ``char`` is an integer to write. Return value: ``None``. See note below if CTS flow control is used. -.. method:: uart.read([nbytes]) +.. method:: UART.read([nbytes]) Read characters. If ``nbytes`` is specified then read at most that many bytes. If ``nbytes`` are available in the buffer, returns immediately, otherwise returns @@ -130,19 +130,19 @@ Methods Return value: a bytes object containing the bytes read in. Returns ``None`` on timeout. -.. method:: uart.readall() +.. method:: UART.readall() Read as much data as possible. Returns after the timeout has elapsed. Return value: a bytes object or ``None`` if timeout prevents any data being read. -.. method:: uart.readchar() +.. method:: UART.readchar() Receive a single character on the bus. Return value: The character read, as an integer. Returns -1 on timeout. -.. method:: uart.readinto(buf[, nbytes]) +.. method:: UART.readinto(buf[, nbytes]) Read bytes into the ``buf``. If ``nbytes`` is specified then read at most that many bytes. Otherwise, read at most ``len(buf)`` bytes. @@ -150,7 +150,7 @@ Methods Return value: number of bytes read and stored into ``buf`` or ``None`` on timeout. -.. method:: uart.readline() +.. method:: UART.readline() Read a line, ending in a newline character. If such a line exists, return is immediate. If the timeout elapses, all available data is returned regardless @@ -158,7 +158,7 @@ Methods Return value: the line read or ``None`` on timeout if no data is available. -.. method:: uart.write(buf) +.. method:: UART.write(buf) .. only:: port_pyboard @@ -170,7 +170,7 @@ Methods Return value: number of bytes written. If a timeout occurs and no bytes were written returns ``None``. -.. method:: uart.sendbreak() +.. method:: UART.sendbreak() Send a break condition on the bus. This drives the bus low for a duration of 13 bits. @@ -215,14 +215,14 @@ Flow Control If CTS flow control is enabled the write behaviour is as follows: - If the Pyboard's ``uart.write(buf)`` method is called, transmission will stall for + If the Pyboard's ``UART.write(buf)`` method is called, transmission will stall for any periods when ``nCTS`` is ``False``. This will result in a timeout if the entire buffer was not transmitted in the timeout period. The method returns the number of bytes written, enabling the user to write the remainder of the data if required. In the event of a timeout, a character will remain in the UART pending ``nCTS``. The number of bytes composing this character will be included in the return value. - If ``uart.writechar()`` is called when ``nCTS`` is ``False`` the method will time + If ``UART.writechar()`` is called when ``nCTS`` is ``False`` the method will time out unless the target asserts ``nCTS`` in time. If it times out ``OSError 116`` will be raised. The character will be transmitted as soon as the target asserts ``nCTS``. diff --git a/docs/library/pyb.USB_VCP.rst b/docs/library/pyb.USB_VCP.rst index 6a77f1eae3..4e34af2586 100644 --- a/docs/library/pyb.USB_VCP.rst +++ b/docs/library/pyb.USB_VCP.rst @@ -19,7 +19,7 @@ Constructors Methods ------- -.. method:: usb_vcp.setinterrupt(chr) +.. method:: USB_VCP.setinterrupt(chr) Set the character which interrupts running Python code. This is set to 3 (CTRL-C) by default, and when a CTRL-C character is received over @@ -28,20 +28,20 @@ Methods Set to -1 to disable this interrupt feature. This is useful when you want to send raw bytes over the USB VCP port. -.. method:: usb_vcp.isconnected() +.. method:: USB_VCP.isconnected() Return ``True`` if USB is connected as a serial device, else ``False``. -.. method:: usb_vcp.any() +.. method:: USB_VCP.any() Return ``True`` if any characters waiting, else ``False``. -.. method:: usb_vcp.close() +.. method:: USB_VCP.close() This method does nothing. It exists so the USB_VCP object can act as a file. -.. method:: usb_vcp.read([nbytes]) +.. method:: USB_VCP.read([nbytes]) Read at most ``nbytes`` from the serial device and return them as a bytes object. If ``nbytes`` is not specified then the method acts as @@ -49,12 +49,12 @@ Methods so if no pending data available, this method will return immediately with ``None`` value. -.. method:: usb_vcp.readall() +.. method:: USB_VCP.readall() Read all available bytes from the serial device and return them as a bytes object, or ``None`` if no pending data available. -.. method:: usb_vcp.readinto(buf, [maxlen]) +.. method:: USB_VCP.readinto(buf, [maxlen]) Read bytes from the serial device and store them into ``buf``, which should be a buffer-like object. At most ``len(buf)`` bytes are read. @@ -64,14 +64,14 @@ Methods Returns the number of bytes read and stored into ``buf`` or ``None`` if no pending data available. -.. method:: usb_vcp.readline() +.. method:: USB_VCP.readline() Read a whole line from the serial device. Returns a bytes object containing the data, including the trailing newline character or ``None`` if no pending data available. -.. method:: usb_vcp.readlines() +.. method:: USB_VCP.readlines() Read as much data as possible from the serial device, breaking it into lines. @@ -79,13 +79,13 @@ Methods Returns a list of bytes objects, each object being one of the lines. Each line will include the newline character. -.. method:: usb_vcp.write(buf) +.. method:: USB_VCP.write(buf) Write the bytes from ``buf`` to the serial device. Returns the number of bytes written. -.. method:: usb_vcp.recv(data, \*, timeout=5000) +.. method:: USB_VCP.recv(data, \*, timeout=5000) Receive data on the bus: @@ -96,7 +96,7 @@ Methods Return value: if ``data`` is an integer then a new buffer of the bytes received, otherwise the number of bytes read into ``data`` is returned. -.. method:: usb_vcp.send(data, \*, timeout=5000) +.. method:: USB_VCP.send(data, \*, timeout=5000) Send data over the USB VCP: -- cgit v1.2.3 From f1eb672d887e8d71504b9dcfd397e340b556afb3 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Wed, 8 Jun 2016 16:36:22 +0300 Subject: docs/pyb.Pin: Sort .af() and .af_list() methods together. --- docs/library/pyb.Pin.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/library') diff --git a/docs/library/pyb.Pin.rst b/docs/library/pyb.Pin.rst index 30ffccdbd4..154217ebb7 100644 --- a/docs/library/pyb.Pin.rst +++ b/docs/library/pyb.Pin.rst @@ -148,6 +148,10 @@ Methods Returns the currently configured alternate-function of the pin. The integer returned will match one of the allowed constants for the af argument to the init function. + + .. method:: Pin.af_list() + + Returns an array of alternate functions available for this pin. .. method:: Pin.gpio() @@ -174,10 +178,6 @@ Methods .. method:: Pin.port() Get the pin port. - - .. method:: Pin.af_list() - - Returns an array of alternate functions available for this pin. .. method:: Pin.pull() -- cgit v1.2.3 From 0cec4e9bb8357e80d8b14ee9f5cf67cb3d5dc194 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Thu, 9 Jun 2016 00:24:52 +0300 Subject: docs/builtins: Enumerate all builtin functions implemented. Based on unix version. No descriptions so far. --- docs/library/builtins.rst | 127 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 127 insertions(+) create mode 100644 docs/library/builtins.rst (limited to 'docs/library') diff --git a/docs/library/builtins.rst b/docs/library/builtins.rst new file mode 100644 index 0000000000..d99eadce3e --- /dev/null +++ b/docs/library/builtins.rst @@ -0,0 +1,127 @@ +Builtin Functions +================= + +All builtin functions are described here. They are alse available via +``builtins`` module. + +.. function:: abs() + +.. function:: all() + +.. function:: any() + +.. function:: bin() + +.. class:: bool() + +.. class:: bytearray() + +.. class:: bytes() + +.. function:: callable() + +.. function:: chr() + +.. function:: classmethod() + +.. function:: compile() + +.. class:: complex() + +.. class:: dict() + +.. function:: dir() + +.. function:: divmod() + +.. function:: enumerate() + +.. function:: eval() + +.. function:: exec() + +.. function:: filter() + +.. class:: float() + +.. class:: frozenset() + +.. function:: getattr() + +.. function:: globals() + +.. function:: hasattr() + +.. function:: hash() + +.. function:: hex() + +.. function:: id() + +.. function:: input() + +.. class:: int() + +.. function:: isinstance() + +.. function:: issubclass() + +.. function:: iter() + +.. function:: len() + +.. class:: list() + +.. function:: locals() + +.. function:: map() + +.. function:: max() + +.. class:: memoryview() + +.. function:: min() + +.. function:: next() + +.. class:: object() + +.. function:: oct() + +.. function:: open() + +.. function:: ord() + +.. function:: pow() + +.. function:: print() + +.. function:: property() + +.. function:: range() + +.. function:: repr() + +.. function:: reversed() + +.. function:: round() + +.. class:: set() + +.. function:: setattr() + +.. function:: sorted() + +.. function:: staticmethod() + +.. class:: str() + +.. function:: sum() + +.. function:: super() + +.. class:: tuple() + +.. function:: type() + +.. function:: zip() -- cgit v1.2.3 From 1d3b903eb56ebacf7efe0f7859f56b12c58dfd94 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Thu, 9 Jun 2016 00:26:44 +0300 Subject: docs/library/index: Add builtins.rst. --- docs/library/index.rst | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs/library') diff --git a/docs/library/index.rst b/docs/library/index.rst index e3d6e31575..9a105697b7 100644 --- a/docs/library/index.rst +++ b/docs/library/index.rst @@ -51,6 +51,7 @@ library. .. toctree:: :maxdepth: 1 + builtins.rst cmath.rst gc.rst math.rst @@ -74,6 +75,7 @@ library. .. toctree:: :maxdepth: 1 + builtins.rst cmath.rst gc.rst math.rst @@ -97,6 +99,7 @@ library. .. toctree:: :maxdepth: 1 + builtins.rst gc.rst select.rst sys.rst @@ -113,6 +116,7 @@ library. .. toctree:: :maxdepth: 1 + builtins.rst gc.rst math.rst sys.rst -- cgit v1.2.3 From a0c296f6d515b0a18306213cf64d9580875448f6 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Thu, 9 Jun 2016 02:58:15 +0300 Subject: docs/machine.Pin: Disambiguate object call method. --- docs/library/machine.Pin.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/library') diff --git a/docs/library/machine.Pin.rst b/docs/library/machine.Pin.rst index 6d6fb860d3..21e5323d5b 100644 --- a/docs/library/machine.Pin.rst +++ b/docs/library/machine.Pin.rst @@ -130,7 +130,7 @@ Methods anything that converts to a boolean. If it converts to ``True``, the pin is set high, otherwise it is set low. -.. method:: pin([value]) +.. method:: Pin.__call__([value]) Pin objects are callable. The call method provides a (fast) shortcut to set and get the value of the pin. See :func:`Pin.value` for more details. -- cgit v1.2.3 From 79b40d11276b2b70b2eaa2fe0cac4d3d830c19e4 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Thu, 9 Jun 2016 03:03:53 +0300 Subject: docs/machine*: Remove explicit targets and "machine." prefixes on classes. With currentmodule:: set properly, none are needed. Extra "machine." prefix produces wrong indexing data. --- docs/library/machine.ADC.rst | 3 +-- docs/library/machine.I2C.rst | 5 ++--- docs/library/machine.Pin.rst | 2 +- docs/library/machine.RTC.rst | 3 +-- docs/library/machine.SD.rst | 3 +-- docs/library/machine.SPI.rst | 3 +-- docs/library/machine.Timer.rst | 3 +-- docs/library/machine.UART.rst | 3 +-- docs/library/machine.WDT.rst | 3 +-- 9 files changed, 10 insertions(+), 18 deletions(-) (limited to 'docs/library') diff --git a/docs/library/machine.ADC.rst b/docs/library/machine.ADC.rst index 11381e98b0..2752878ff3 100644 --- a/docs/library/machine.ADC.rst +++ b/docs/library/machine.ADC.rst @@ -1,5 +1,4 @@ .. currentmodule:: machine -.. _machine.ADC: class ADC -- analog to digital conversion ========================================= @@ -15,7 +14,7 @@ Usage:: Constructors ------------ -.. class:: machine.ADC(id=0, \*, bits=12) +.. class:: ADC(id=0, \*, bits=12) Create an ADC object associated with the given pin. This allows you to then read analog values on that pin. diff --git a/docs/library/machine.I2C.rst b/docs/library/machine.I2C.rst index 2f020f6d47..b3bfa68f07 100644 --- a/docs/library/machine.I2C.rst +++ b/docs/library/machine.I2C.rst @@ -1,5 +1,4 @@ .. currentmodule:: machine -.. _machine.I2C: class I2C -- a two-wire serial protocol ======================================= @@ -45,14 +44,14 @@ Constructors .. only:: port_wipy - .. class:: machine.I2C(bus, ...) + .. class:: I2C(bus, ...) Construct an I2C object on the given bus. `bus` can only be 0. If the bus is not given, the default one will be selected (0). .. only:: port_esp8266 - .. class:: machine.I2C(scl, sda, \*, freq=400000) + .. class:: I2C(scl, sda, \*, freq=400000) Construct and return a new I2C object. See the init method below for a description of the arguments. diff --git a/docs/library/machine.Pin.rst b/docs/library/machine.Pin.rst index 21e5323d5b..fdada2f383 100644 --- a/docs/library/machine.Pin.rst +++ b/docs/library/machine.Pin.rst @@ -58,7 +58,7 @@ Usage Model: Constructors ------------ -.. class:: machine.Pin(id, ...) +.. class:: Pin(id, ...) Create a new Pin object associated with the id. If additional arguments are given, they are used to initialise the pin. See :meth:`Pin.init`. diff --git a/docs/library/machine.RTC.rst b/docs/library/machine.RTC.rst index 219ca273d0..b6e98e9d1f 100644 --- a/docs/library/machine.RTC.rst +++ b/docs/library/machine.RTC.rst @@ -1,5 +1,4 @@ .. currentmodule:: machine -.. _machine.RTC: class RTC -- real time clock ============================ @@ -17,7 +16,7 @@ Example usage:: Constructors ------------ -.. class:: machine.RTC(id=0, ...) +.. class:: RTC(id=0, ...) Create an RTC object. See init for parameters of initialization. diff --git a/docs/library/machine.SD.rst b/docs/library/machine.SD.rst index 330ef217ae..21c28aa200 100644 --- a/docs/library/machine.SD.rst +++ b/docs/library/machine.SD.rst @@ -1,5 +1,4 @@ .. currentmodule:: machine -.. _machine.SD: class SD -- secure digital memory card ====================================== @@ -25,7 +24,7 @@ Example usage:: Constructors ------------ -.. class:: machine.SD(id,... ) +.. class:: SD(id,... ) Create a SD card object. See ``init()`` for parameters if initialization. diff --git a/docs/library/machine.SPI.rst b/docs/library/machine.SPI.rst index 8e66660768..f3c95181dc 100644 --- a/docs/library/machine.SPI.rst +++ b/docs/library/machine.SPI.rst @@ -1,5 +1,4 @@ .. currentmodule:: machine -.. _machine.SPI: class SPI -- a master-driven serial protocol ============================================ @@ -24,7 +23,7 @@ Constructors .. only:: port_wipy - .. class:: machine.SPI(id, ...) + .. class:: SPI(id, ...) Construct an SPI object on the given bus. ``id`` can be only 0. With no additional parameters, the SPI object is created but not diff --git a/docs/library/machine.Timer.rst b/docs/library/machine.Timer.rst index 0e596588eb..344d1ea86e 100644 --- a/docs/library/machine.Timer.rst +++ b/docs/library/machine.Timer.rst @@ -1,5 +1,4 @@ .. currentmodule:: machine -.. _machine.Timer: class Timer -- control internal timers ====================================== @@ -60,7 +59,7 @@ class Timer -- control internal timers Constructors ------------ -.. class:: machine.Timer(id, ...) +.. class:: Timer(id, ...) .. only:: port_wipy diff --git a/docs/library/machine.UART.rst b/docs/library/machine.UART.rst index 594a11dce9..27a8801900 100644 --- a/docs/library/machine.UART.rst +++ b/docs/library/machine.UART.rst @@ -1,5 +1,4 @@ .. currentmodule:: machine -.. _machine.UART: class UART -- duplex serial communication bus ============================================= @@ -59,7 +58,7 @@ Constructors .. only:: port_wipy - .. class:: machine.UART(bus, ...) + .. class:: UART(bus, ...) Construct a UART object on the given bus. ``bus`` can be 0 or 1. If the bus is not given, the default one will be selected (0) or the selection diff --git a/docs/library/machine.WDT.rst b/docs/library/machine.WDT.rst index 10e6af0e14..d7c801356e 100644 --- a/docs/library/machine.WDT.rst +++ b/docs/library/machine.WDT.rst @@ -1,5 +1,4 @@ .. currentmodule:: machine -.. _machine.WDT: class WDT -- watchdog timer =========================== @@ -18,7 +17,7 @@ Example usage:: Constructors ------------ -.. class:: machine.WDT(id=0, timeout=5000) +.. class:: WDT(id=0, timeout=5000) Create a WDT object and start it. The timeout must be given in seconds and the minimum value that is accepted is 1 second. Once it is running the timeout -- cgit v1.2.3 From 343b5c1081331c2c06bda7d7add67da44ae47fea Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Thu, 9 Jun 2016 05:02:55 +0300 Subject: docs/uctypes: Improve documentation. Seealso and Limitations sectiosn added, better formatting and grammar. --- docs/library/uctypes.rst | 166 ++++++++++++++++++++++++++++------------------- 1 file changed, 99 insertions(+), 67 deletions(-) (limited to 'docs/library') diff --git a/docs/library/uctypes.rst b/docs/library/uctypes.rst index 9a7f85edcd..630a3a36fb 100644 --- a/docs/library/uctypes.rst +++ b/docs/library/uctypes.rst @@ -1,97 +1,106 @@ -:mod:`uctypes` -- access C structures -===================================== +:mod:`uctypes` -- access binary data in a structured way +======================================================== .. module:: uctypes - :synopsis: access C structures + :synopsis: access binary data in a structured way This module implements "foreign data interface" for MicroPython. The idea -behind it is similar to CPython's ``ctypes`` modules, but actual API is -different, streamlined and optimized for small size. +behind it is similar to CPython's ``ctypes`` modules, but the actual API is +different, streamlined and optimized for small size. The basic idea of the +module is to define data structure layout with about the same power as the +C language allows, and the access it using familiar dot-syntax to reference +sub-fields. + +.. seealso:: + + Module :mod:`ustruct` + Standard Python way to access binary data structures (doesn't scale + well to large and complex structures). Defining structure layout ------------------------- Structure layout is defined by a "descriptor" - a Python dictionary which encodes field names as keys and other properties required to access them as -an associated values. Currently, uctypes requires explicit specification of -offsets for each field. Offset are given in bytes from structure start. +associated values. Currently, uctypes requires explicit specification of +offsets for each field. Offset are given in bytes from a structure start. Following are encoding examples for various field types: - Scalar types:: +* Scalar types:: "field_name": uctypes.UINT32 | 0 - in other words, value is scalar type identifier ORed with field offset - (in bytes) from the start of the structure. + in other words, value is scalar type identifier ORed with field offset + (in bytes) from the start of the structure. - Recursive structures:: +* Recursive structures:: "sub": (2, { "b0": uctypes.UINT8 | 0, "b1": uctypes.UINT8 | 1, }) - i.e. value is a 2-tuple, first element of which is offset, and second is - a structure descriptor dictionary (note: offsets in recursive descriptors - are relative to a structure it defines). + i.e. value is a 2-tuple, first element of which is offset, and second is + a structure descriptor dictionary (note: offsets in recursive descriptors + are relative to a structure it defines). - Arrays of primitive types:: +* Arrays of primitive types:: "arr": (uctypes.ARRAY | 0, uctypes.UINT8 | 2), - i.e. value is a 2-tuple, first element of which is ARRAY flag ORed - with offset, and second is scalar element type ORed number of elements - in array. + i.e. value is a 2-tuple, first element of which is ARRAY flag ORed + with offset, and second is scalar element type ORed number of elements + in array. - Arrays of aggregate types:: +* Arrays of aggregate types:: "arr2": (uctypes.ARRAY | 0, 2, {"b": uctypes.UINT8 | 0}), - i.e. value is a 3-tuple, first element of which is ARRAY flag ORed - with offset, second is a number of elements in array, and third is - descriptor of element type. + i.e. value is a 3-tuple, first element of which is ARRAY flag ORed + with offset, second is a number of elements in array, and third is + descriptor of element type. - Pointer to a primitive type:: +* Pointer to a primitive type:: "ptr": (uctypes.PTR | 0, uctypes.UINT8), - i.e. value is a 2-tuple, first element of which is PTR flag ORed - with offset, and second is scalar element type. + i.e. value is a 2-tuple, first element of which is PTR flag ORed + with offset, and second is scalar element type. - Pointer to aggregate type:: +* Pointer to an aggregate type:: "ptr2": (uctypes.PTR | 0, {"b": uctypes.UINT8 | 0}), - i.e. value is a 2-tuple, first element of which is PTR flag ORed - with offset, second is descriptor of type pointed to. + i.e. value is a 2-tuple, first element of which is PTR flag ORed + with offset, second is descriptor of type pointed to. - Bitfields:: +* Bitfields:: "bitf0": uctypes.BFUINT16 | 0 | 0 << uctypes.BF_POS | 8 << uctypes.BF_LEN, - i.e. value is type of scalar value containing given bitfield (typenames are - similar to scalar types, but prefixes with "BF"), ORed with offset for - scalar value containing the bitfield, and further ORed with values for - bit offset and bit length of the bitfield within scalar value, shifted by - BF_POS and BF_LEN positions, respectively. Bitfield position is counted - from the least significant bit, and is the number of right-most bit of a - field (in other words, it's a number of bits a scalar needs to be shifted - right to extra the bitfield). - - In the example above, first UINT16 value will be extracted at offset 0 - (this detail may be important when accessing hardware registers, where - particular access size and alignment are required), and then bitfield - whose rightmost bit is least-significant bit of this UINT16, and length - is 8 bits, will be extracted - effectively, this will access - least-significant byte of UINT16. - - Note that bitfield operations are independent of target byte endianness, - in particular, example above will access least-significant byte of UINT16 - in both little- and big-endian structures. But it depends on the least - significant bit being numbered 0. Some targets may use different - numbering in their native ABI, but ``uctypes`` always uses normalized - numbering described above. + i.e. value is type of scalar value containing given bitfield (typenames are + similar to scalar types, but prefixes with "BF"), ORed with offset for + scalar value containing the bitfield, and further ORed with values for + bit offset and bit length of the bitfield within scalar value, shifted by + BF_POS and BF_LEN positions, respectively. Bitfield position is counted + from the least significant bit, and is the number of right-most bit of a + field (in other words, it's a number of bits a scalar needs to be shifted + right to extra the bitfield). + + In the example above, first UINT16 value will be extracted at offset 0 + (this detail may be important when accessing hardware registers, where + particular access size and alignment are required), and then bitfield + whose rightmost bit is least-significant bit of this UINT16, and length + is 8 bits, will be extracted - effectively, this will access + least-significant byte of UINT16. + + Note that bitfield operations are independent of target byte endianness, + in particular, example above will access least-significant byte of UINT16 + in both little- and big-endian structures. But it depends on the least + significant bit being numbered 0. Some targets may use different + numbering in their native ABI, but ``uctypes`` always uses normalized + numbering described above. Module contents --------------- @@ -103,17 +112,18 @@ Module contents .. data:: LITTLE_ENDIAN - Little-endian packed structure. (Packed means that every field occupies - exactly as many bytes as defined in the descriptor, i.e. alignment is 1). + Layout type for a little-endian packed structure. (Packed means that every + field occupies exactly as many bytes as defined in the descriptor, i.e. + the alignment is 1). .. data:: BIG_ENDIAN - Big-endian packed structure. + Layour type for a big-endian packed structure. .. data:: NATIVE - Native structure - with data endianness and alignment conforming to - the ABI of the system on which MicroPython runs. + Layout type for a native structure - with data endianness and alignment + conforming to the ABI of the system on which MicroPython runs. .. function:: sizeof(struct) @@ -145,33 +155,55 @@ Structure descriptors and instantiating structure objects Given a structure descriptor dictionary and its layout type, you can instantiate a specific structure instance at a given memory address -using uctypes.struct() constructor. Memory address usually comes from +using :class:`uctypes.struct()` constructor. Memory address usually comes from following sources: * Predefined address, when accessing hardware registers on a baremetal system. Lookup these addresses in datasheet for a particular MCU/SoC. -* As return value from a call to some FFI (Foreign Function Interface) +* As a return value from a call to some FFI (Foreign Function Interface) function. -* From uctypes.addressof(), when you want to pass arguments to FFI +* From uctypes.addressof(), when you want to pass arguments to an FFI function, or alternatively, to access some data for I/O (for example, - data read from file or network socket). + data read from a file or network socket). Structure objects ----------------- Structure objects allow accessing individual fields using standard dot -notation: ``my_struct.field1``. If a field is of scalar type, getting -it will produce primitive value (Python integer or float) corresponding -to value contained in a field. Scalar field can also be assigned to. +notation: ``my_struct.substruct1.field1``. If a field is of scalar type, +getting it will produce a primitive value (Python integer or float) +corresponding to the value contained in a field. A scalar field can also +be assigned to. If a field is an array, its individual elements can be accessed with -standard subscript operator - both read and assigned to. +the standard subscript operator ``[]`` - both read and assigned to. If a field is a pointer, it can be dereferenced using ``[0]`` syntax (corresponding to C ``*`` operator, though ``[0]`` works in C too). -Subscripting pointer with other integer values but 0 are supported too, +Subscripting a pointer with other integer values but 0 are supported too, with the same semantics as in C. Summing up, accessing structure fields generally follows C syntax, -except for pointer derefence, you need to use ``[0]`` operator instead -of ``*``. +except for pointer derefence, when you need to use ``[0]`` operator +instead of ``*``. + +Limitations +----------- + +Accessing non-scalar fields leads to allocation of intermediate objects +to represent them. This means that special care should be taken to +layout a structure which needs to be accessed when memory allocation +is disabled (e.g. from an interrupt). The recommendations are: + +* Avoid nested structures. For example, instead of + ``mcu_registers.peripheral_a.register1``, define separate layout + descriptors for each peripheral, to be accessed as + ``peripheral_a.register1``. +* Avoid other non-scalar data, like array. For example, instead of + ``peripheral_a.register[0]`` use ``peripheral_a.register0``. + +Note that these recommendations will lead to decreased readability +and conciseness of layouts, so they should be used only if the need +to access structure fields without allocation is anticipated (it's +even possible to define 2 parallel layouts - one for normal usage, +and a restricted one to use when memory allocation is prohibited). -- cgit v1.2.3 From 9de5eb278d4bb7834c1abf15ddefdf4c85b29465 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Fri, 10 Jun 2016 23:06:56 +0300 Subject: docs/sys: Detailed description of print_exception() diff from traceback module. --- docs/library/sys.rst | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) (limited to 'docs/library') diff --git a/docs/library/sys.rst b/docs/library/sys.rst index b5a9138c07..ebde2b191c 100644 --- a/docs/library/sys.rst +++ b/docs/library/sys.rst @@ -21,7 +21,12 @@ Functions .. admonition:: Difference to CPython :class: attention - This function appears in the ``traceback`` module in CPython. + This is simplified version of a function which appears in the + ``traceback`` module in CPython. Unlike ``traceback.print_exception()``, + this function takes just exception value instead of exception type, + exception value, and traceback object; `file` argument should be + positional; further arguments are not support. Compliant + ``traceback`` module can be found in micropython-lib. Constants --------- -- cgit v1.2.3 From 617e033e2fe2315c66873bdd44d5bc963a3f0e0f Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Sat, 18 Jun 2016 19:05:12 +0300 Subject: docs/select: Add an article. --- docs/library/select.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/library') diff --git a/docs/library/select.rst b/docs/library/select.rst index c24f010e6b..8dcd4080f1 100644 --- a/docs/library/select.rst +++ b/docs/library/select.rst @@ -61,7 +61,7 @@ Methods list of (``obj``, ``event``, ...) tuples, ``event`` element specifies which events happened with a stream and is a combination of `select.POLL*` constants described above. There may be other elements in tuple, depending - on platform and version, so don't assume that its size is 2. In case of + on a platform and version, so don't assume that its size is 2. In case of timeout, an empty list is returned. Timeout is in milliseconds. -- cgit v1.2.3 From 2b6dcdd3e451787d47fba7666ed5f4a2877f9338 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Sat, 18 Jun 2016 19:05:50 +0300 Subject: docs/sys: print_exception: Fixes/clarifications. --- docs/library/sys.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/library') diff --git a/docs/library/sys.rst b/docs/library/sys.rst index ebde2b191c..1d7579754f 100644 --- a/docs/library/sys.rst +++ b/docs/library/sys.rst @@ -25,7 +25,7 @@ Functions ``traceback`` module in CPython. Unlike ``traceback.print_exception()``, this function takes just exception value instead of exception type, exception value, and traceback object; `file` argument should be - positional; further arguments are not support. Compliant + positional; further arguments are not supported. CPython-compatible ``traceback`` module can be found in micropython-lib. Constants -- cgit v1.2.3 From 047ac2044dc48fa34aa2092b88867082987bfe94 Mon Sep 17 00:00:00 2001 From: Martin Müller Date: Sat, 25 Jun 2016 16:50:26 +0200 Subject: docs/library: Fix typo in docs for usocket.listen(). --- docs/library/usocket.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/library') diff --git a/docs/library/usocket.rst b/docs/library/usocket.rst index 9d1d569df4..9b279e5ba7 100644 --- a/docs/library/usocket.rst +++ b/docs/library/usocket.rst @@ -101,7 +101,7 @@ Methods Enable a server to accept connections. If backlog is specified, it must be at least 0 (if it's lower, it will be set to 0); and specifies the number of unaccepted connections - tha the system will allow before refusing new connections. If not specified, a default + that the system will allow before refusing new connections. If not specified, a default reasonable value is chosen. .. method:: socket.accept() -- cgit v1.2.3