From a79f6676c3381d56f2085bda23cf75ba129db9c6 Mon Sep 17 00:00:00 2001 From: Mike Causer Date: Wed, 21 Dec 2016 13:48:20 +1100 Subject: docs: Fix some minor spelling mistakes. paramter -> parameter send a receive -> send and receive repsonse -> response particualr -> particular constructore -> constructor --- docs/library/machine.SPI.rst | 6 +++--- docs/pyboard/quickref.rst | 2 +- docs/wipy/quickref.rst | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/library/machine.SPI.rst b/docs/library/machine.SPI.rst index dda6314fa..e8a8a2d8c 100644 --- a/docs/library/machine.SPI.rst +++ b/docs/library/machine.SPI.rst @@ -6,7 +6,7 @@ class SPI -- a Serial Peripheral Interface bus protocol (master side) SPI is a synchronous serial protocol that is driven by a master. At the physical level, a bus consists of 3 lines: SCK, MOSI, MISO. Multiple devices can share the same bus. Each device should have a separate, 4th signal, -SS (Slave Select), to select a particualr device on a bus with which +SS (Slave Select), to select a particular device on a bus with which communication takes place. Management of an SS signal should happen in user code (via machine.Pin class). @@ -51,12 +51,12 @@ Methods - ``bits`` is the width in bits of each transfer. Only 8 is guaranteed to be supported by all hardware. - ``firstbit`` can be ``SPI.MSB`` or ``SPI.LSB``. - ``sck``, ``mosi``, ``miso`` are pins (machine.Pin) objects to use for bus signals. For most - hardware SPI blocks (as selected by ``id`` parameter to the constructore), pins are fixed + hardware SPI blocks (as selected by ``id`` parameter to the constructor), pins are fixed and cannot be changed. In some cases, hardware blocks allow 2-3 alternative pin sets for a hardware SPI block. Arbitrary pin assignments are possible only for a bitbanging SPI driver (``id`` = -1). - ``pins`` - WiPy port doesn't ``sck``, ``mosi``, ``miso`` arguments, and instead allows to - specify them as a tuple of ``pins`` paramter. + specify them as a tuple of ``pins`` parameter. .. method:: SPI.deinit() diff --git a/docs/pyboard/quickref.rst b/docs/pyboard/quickref.rst index 5f1a3a6e6..5690dddb0 100644 --- a/docs/pyboard/quickref.rst +++ b/docs/pyboard/quickref.rst @@ -152,7 +152,7 @@ See :ref:`pyb.SPI `. :: spi = SPI(1, SPI.MASTER, baudrate=200000, polarity=1, phase=0) spi.send('hello') spi.recv(5) # receive 5 bytes on the bus - spi.send_recv('hello') # send a receive 5 bytes + spi.send_recv('hello') # send and receive 5 bytes I2C bus ------- diff --git a/docs/wipy/quickref.rst b/docs/wipy/quickref.rst index ac7eec132..7a4ea7f7f 100644 --- a/docs/wipy/quickref.rst +++ b/docs/wipy/quickref.rst @@ -102,7 +102,7 @@ See :ref:`machine.SPI `. :: spi.write('hello') spi.read(5) # receive 5 bytes on the bus rbuf = bytearray(5) - spi.write_readinto('hello', rbuf) # send a receive 5 bytes + spi.write_readinto('hello', rbuf) # send and receive 5 bytes I2C bus ------- -- cgit v1.2.3 From e72e3439086ca16d376d939a60bafa95f7da6748 Mon Sep 17 00:00:00 2001 From: Damien George Date: Mon, 23 Jan 2017 14:37:10 +1100 Subject: docs: Add documentation for lcd160cr module. --- docs/library/index.rst | 1 + docs/library/lcd160cr.rst | 376 ++++++++++++++++++++++++++++++++++++++++ docs/pyboard/hardware/index.rst | 1 + 3 files changed, 378 insertions(+) create mode 100644 docs/library/lcd160cr.rst (limited to 'docs') diff --git a/docs/library/index.rst b/docs/library/index.rst index 3621f9d88..a110ef0d2 100644 --- a/docs/library/index.rst +++ b/docs/library/index.rst @@ -170,6 +170,7 @@ the following libraries. :maxdepth: 2 pyb.rst + lcd160cr.rst .. only:: port_wipy diff --git a/docs/library/lcd160cr.rst b/docs/library/lcd160cr.rst new file mode 100644 index 000000000..c31dd6d2f --- /dev/null +++ b/docs/library/lcd160cr.rst @@ -0,0 +1,376 @@ +:mod:`lcd160cr` --- control of LCD160CR display +=============================================== + +.. module:: lcd160cr + :synopsis: control of LCD160CR display + +This module provides control of the MicroPython LCD160CR display. + +.. image:: http://micropython.org/resources/LCD160CRv10-persp.jpg + :alt: LCD160CRv1.0 picture + :width: 640px + +Further resources are available via the following links: + +* `LCD160CRv1.0 reference manual `_ (100KiB PDF) +* `LCD160CRv1.0 schematics `_ (1.6MiB PDF) + +class LCD160CR +-------------- + +The LCD160CR class provides an interface to the display. Create an +instance of this class and use its methods to draw to the LCD and get +the status of the touch panel. + +For example:: + + import lcd160cr + + lcd = lcd160cr.LCD160CR('X') + lcd.set_orient(lcd160cr.PORTRAIT) + lcd.set_pos(0, 0) + lcd.set_text_color(lcd.rgb(255, 0, 0), lcd.rgb(0, 0, 0)) + lcd.set_font(1) + lcd.write('Hello MicroPython!') + print('touch:', lcd.get_touch()) + +Constructors +------------ + +.. class:: LCD160CR(connect=None, \*, pwr=None, i2c=None, spi=None, i2c_addr=98) + + Construct an LCD160CR object. The parameters are: + + - `connect` is a string specifying the physical connection of the LCD + display to the board; valid values are "X", "Y", "XY", "YX". + Use "X" when the display is connected to a pyboard in the X-skin + position, and "Y" when connected in the Y-skin position. "XY" + and "YX" are used when the display is connected to the right or + left side of the pyboard, respectively. + - `pwr` is a Pin object connected to the LCD's power/enabled pin. + - `i2c` is an I2C object connected to the LCD's I2C interface. + - `spi` is an SPI object connected to the LCD's SPI interface. + - `i2c_addr` is the I2C address of the display. + + One must specify either a valid `connect` or all of `pwr`, `i2c` and `spi`. + If a valid `connect` is given then any of `pwr`, `i2c` or `spi` which are + not passed as parameters (ie they are `None`) will be created based on the + value of `connect`. This allows to override the default interface to the + display if needed. + + The default values are: + + - "X" is for the X-skin and uses: + ``pwr=Pin("X4")``, ``i2c=I2C("X")``, ``spi=SPI("X")`` + - "Y" is for the Y-skin and uses: + ``pwr=Pin("Y4")``, ``i2c=I2C("Y")``, ``spi=SPI("Y")`` + - "XY" is for the right-side and uses: + ``pwr=Pin("X4")``, ``i2c=I2C("Y")``, ``spi=SPI("X")`` + - "YX" is for the left-side and uses: + ``pwr=Pin("Y4")``, ``i2c=I2C("X")``, ``spi=SPI("Y")`` + +Static methods +-------------- + +.. staticmethod:: LCD160CR.rgb(r, g, b) + + Return a 16-bit integer representing the given rgb color values. The + 16-bit value can be used to set the font color (see + :meth:`LCD160CR.set_text_color`) pen color (see :meth:`LCD160CR.set_pen`) + and draw individual pixels. + +.. staticmethod:: LCD160CR.clip_line(data, w, h): + + Clip the given line data. This is for internal use. + +Instance members +---------------- + +The following instance members are publicly accessible. + +.. data:: LCD160CR.w +.. data:: LCD160CR.h + + The width and height of the display, respectively, in pixels. These + members are updated when calling :meth:`LCD160CR.set_orient` and should + be considered read-only. + +Setup commands +-------------- + +.. method:: LCD160CR.set_power(on) + + Turn the display on or off, depending on the given value. + +.. method:: LCD160CR.set_orient(orient) + + Set the orientation of the display. The `orient` parameter can be one + of `PORTRAIT`, `LANDSCAPE`, `PORTRAIT_UPSIDEDOWN`, `LANDSCAPE_UPSIDEDOWN`. + +.. method:: LCD160CR.set_brightness(value) + + Set the brightness of the display, between 0 and 255. + +.. method:: LCD160CR.set_i2c_addr(addr) + + Set the I2C address of the display. The `addr` value must have the + lower 2 bits cleared. + +.. method:: LCD160CR.set_uart_baudrate(baudrate) + + Set the baudrate of the UART interface. + +.. method:: LCD160CR.set_startup_deco(value) + + Set the start-up decoration of the display. The `value` parameter can be a + logical or of `STARTUP_DECO_NONE`, `STARTUP_DECO_MLOGO`, `STARTUP_DECO_INFO`. + +.. method:: LCD160CR.save_to_flash() + + Save the following parameters to flash so they persist on restart and power up: + initial decoration, orientation, brightness, UART baud rate, I2C address. + +Pixel access methods +-------------------- + +The following methods manipulate individual pixels on the display. + +.. method:: LCD160CR.set_pixel(x, y, c) + + Set the specified pixel to the given color. The color should be a 16-bit + integer and can be created by :meth:`LCD160CR.rgb`. + +.. method:: LCD160CR.get_pixel(x, y) + + Get the 16-bit value of the specified pixel. + +.. method:: LCD160CR.get_line(x, y, buf) + + Get a line of pixels into the given buffer. + +.. method:: LCD160CR.screen_dump(buf) + + Dump the entire screen to the given buffer. + +.. method:: LCD160CR.screen_load(buf) + + Load the entire screen from the given buffer. + +Drawing text +------------ + +To draw text one sets the position, color and font, and then uses +`write` to draw the text. + +.. method:: LCD160CR.set_pos(x, y) + + Set the position for text output using :meth:`LCD160CR.write`. The position + is the upper-left corner of the text. + +.. method:: LCD160CR.set_text_color(fg, bg) + + Set the foreground and background color of the text. + +.. method:: LCD160CR.set_font(font, scale=0, bold=0, trans=0, scroll=0) + + Set the font for the text. Subsequent calls to `write` will use the newly + configured font. The parameters are: + + - `font` is the font family to use, valid values are 0, 1, 2, 3. + - `scale` is a scaling value for each character pixel, where the pixels + are drawn as a square with side length equal to `scale + 1`. The value + can be between 0 and 63. + - `bold` controls the number of pixels to overdraw each character pixel, + making a bold effect. The lower 2 bits of `bold` are the number of + pixels to overdraw in the horizontal direction, and the next 2 bits are + for the vertical direction. For example, a `bold` value of 5 will + overdraw 1 pixel in both the horizontal and vertical directions. + - `trans` can be either 0 or 1 and if set to 1 the characters will be + drawn with a transparent background. + - `scroll` can be either 0 or 1 and if set to 1 the display will do a + soft scroll if the text moves to the next line. + +.. method:: LCD160CR.write(s) + + Write text to the display, using the current position, color and font. + As text is written the position is automatically incremented. The + display supports basic VT100 control codes such as newline and backspace. + +Drawing primitive shapes +------------------------ + +Primitive drawing commands use a foreground and background color set by the +`set_pen` method. + +.. method:: LCD160CR.set_pen(line, fill) + + Set the line and fill color for primitive shapes. + +.. method:: LCD160CR.erase() + + Erase the entire display to the pen fill color. + +.. method:: LCD160CR.dot(x, y) + + Draw a single pixel at the given location using the pen line color. + +.. method:: LCD160CR.rect(x, y, w, h) +.. method:: LCD160CR.rect_outline(x, y, w, h) +.. method:: LCD160CR.rect_interior(x, y, w, h) + + Draw a rectangle at the given location and size using the pen line + color for the outline, and the pen fill color for the interior. + The `rect` method draws the outline and interior, while the other methods + just draw one or the other. + +.. method:: LCD160CR.line(x1, y1, x2, y2) + + Draw a line between the given coordinates using the pen line color. + +.. method:: LCD160CR.dot_no_clip(x, y) +.. method:: LCD160CR.rect_no_clip(x, y, w, h) +.. method:: LCD160CR.rect_outline_no_clip(x, y, w, h) +.. method:: LCD160CR.rect_interior_no_clip(x, y, w, h) +.. method:: LCD160CR.line_no_clip(x1, y1, x2, y2) + + These methods are as above but don't do any clipping on the input + coordinates. They are faster than the clipping versions and can be + used when you know that the coordinates are within the display. + +.. method:: LCD160CR.poly_dot(data) + + Draw a sequence of dots using the pen line color. + The `data` should be a buffer of bytes, with each successive pair of + bytes corresponding to coordinate pairs (x, y). + +.. method:: LCD160CR.poly_line(data) + + Similar to :meth:`LCD160CR.poly_dot` but draws lines between the dots. + +Touch screen methods +-------------------- + +.. method:: LCD160CR.touch_config(calib=False, save=False, irq=None) + + Configure the touch panel: + + - If `calib` is `True` then the call will trigger a touch calibration of + the resistive touch sensor. This requires the user to touch various + parts of the screen. + - If `save` is `True` then the touch parameters will be saved to NVRAM + to persist across reset/power up. + - If `irq` is `True` then the display will be configured to pull the IRQ + line low when a touch force is detected. If `irq` is `False` then this + feature is disabled. If `irq` is `None` (the default value) then no + change is made to this setting. + +.. method:: LCD160CR.is_touched() + + Returns a boolean: `True` if there is currently a touch force on the screen, + `False` otherwise. + +.. method:: LCD160CR.get_touch() + + Returns a 3-tuple of: (active, x, y). If there is currently a touch force + on the screen then `active` is 1, otherwise it is 0. The `x` and `y` values + indicate the position of the current or most recent touch. + +Advanced commands +----------------- + +.. method:: LCD160CR.set_spi_win(x, y, w, h) + + Set the window that SPI data is written to. + +.. method:: LCD160CR.fast_spi(flush=True) + + Ready the display to accept RGB pixel data on the SPI bus, resetting the location + of the first byte to go to the top-left corner of the window set by + :meth:`LCD160CR.set_spi_win`. + The method returns an SPI object which can be used to write the pixel data. + + Pixels should be sent as 16-bit RGB values in the 5-6-5 format. The destination + counter will increase as data is sent, and data can be sent in arbitrary sized + chunks. Once the destination counter reaches the end of the window specified by + :meth:`LCD160CR.set_spi_win` it will wrap around to the top-left corner of that window. + +.. method:: LCD160CR.show_framebuf(buf) + + Show the given buffer on the display. `buf` should be an array of bytes containing + the 16-bit RGB values for the pixels, and they will be written to the area + specified by :meth:`LCD160CR.set_spi_win`, starting from the top-left corner. + +.. method:: LCD160CR.set_scroll(on) + + Turn scrolling on or off. This controls globally whether any window regions will + scroll. + +.. method:: LCD160CR.set_scroll_win(win, x=-1, y=0, w=0, h=0, vec=0, pat=0, fill=0x07e0, color=0) + + Configure a window region for scrolling: + + - `win` is the window id to configure. There are 0..7 standard windows for + general purpose use. Window 8 is the text scroll window (the ticker). + - `x`, `y`, `w`, `h` specify the location of the window in the display. + - `vec` specifies the direction and speed of scroll: it is a 16-bit value + of the form ``0bF.ddSSSSSSSSSSSS``. `dd` is 0, 1, 2, 3 for +x, +y, -x, + -y scrolling. `F` sets the speed format, with 0 meaning that the window + is shifted `S % 256` pixel every frame, and 1 meaning that the window + is shifted 1 pixel every `S` frames. + - `pat` is a 16-bit pattern mask for the background. + - `fill` is the fill color. + - `color` is the extra color, either of the text or pattern foreground. + +.. method:: LCD160CR.set_scroll_win_param(win, param, value) + + Set a single parameter of a scrolling window region: + + - `win` is the window id, 0..8. + - `param` is the parameter number to configure, 0..7, and corresponds + to the parameters in the `set_scroll_win` method. + - `value` is the value to set. + +.. method:: LCD160CR.set_scroll_buf(s) + + Set the string for scrolling in window 8. The parameter `s` must be a string + with length 32 or less. + +.. method:: LCD160CR.jpeg(buf) + + Display a JPEG. `buf` should contain the entire JPEG data. + The origin of the JPEG is set by :meth:`LCD160CR.set_pos`. + +.. method:: LCD160CR.jpeg_start(total_len) +.. method:: LCD160CR.jpeg_data(buf) + + Display a JPEG with the data split across multiple buffers. There must be + a single call to `jpeg_start` to begin with, specifying the total number of + bytes in the JPEG. Then this number of bytes must be transferred to the + display using one or more calls to the `jpeg_data` command. + +.. method:: LCD160CR.feed_wdt() + + The first call to this method will start the display's internal watchdog + timer. Subsequent calls will feed the watchdog. The timeout is roughly 30 + seconds. + +.. method:: LCD160CR.reset() + + Reset the display. + +Constants +--------- + +.. data:: lcd160cr.PORTRAIT +.. data:: lcd160cr.LANDSCAPE +.. data:: lcd160cr.PORTRAIT_UPSIDEDOWN +.. data:: lcd160cr.LANDSCAPE_UPSIDEDOWN + + orientation of the display, used by :meth:`LCD160CR.set_orient` + +.. data:: lcd160cr.STARTUP_DECO_NONE +.. data:: lcd160cr.STARTUP_DECO_MLOGO +.. data:: lcd160cr.STARTUP_DECO_INFO + + type of start-up decoration, can be or'd together, used by + :meth:`LCD160CR.set_startup_deco` diff --git a/docs/pyboard/hardware/index.rst b/docs/pyboard/hardware/index.rst index b64908c56..bc4726ce2 100644 --- a/docs/pyboard/hardware/index.rst +++ b/docs/pyboard/hardware/index.rst @@ -13,6 +13,7 @@ For the official skin modules: * `LCD32MKv1.0 schematics `_ (194KiB PDF) * `AMPv1.0 schematics `_ (209KiB PDF) +* LCD160CRv1.0: see :mod:`lcd160cr` Datasheets for the components on the pyboard ============================================ -- cgit v1.2.3 From 7d08bc27e23251b74f4b41f6ecbc0a565e67dbb4 Mon Sep 17 00:00:00 2001 From: Damien George Date: Mon, 23 Jan 2017 15:50:37 +1100 Subject: docs/pyboard/tutorial: Add tutorial for LCD160CR. --- docs/pyboard/tutorial/index.rst | 1 + docs/pyboard/tutorial/lcd160cr_skin.rst | 132 ++++++++++++++++++++++++++++++++ 2 files changed, 133 insertions(+) create mode 100644 docs/pyboard/tutorial/lcd160cr_skin.rst (limited to 'docs') diff --git a/docs/pyboard/tutorial/index.rst b/docs/pyboard/tutorial/index.rst index ae40f47b8..07f136c9b 100644 --- a/docs/pyboard/tutorial/index.rst +++ b/docs/pyboard/tutorial/index.rst @@ -35,6 +35,7 @@ Tutorials requiring extra components fading_led.rst lcd_skin.rst amp_skin.rst + lcd160cr_skin.rst Tips, tricks and useful things to know -------------------------------------- diff --git a/docs/pyboard/tutorial/lcd160cr_skin.rst b/docs/pyboard/tutorial/lcd160cr_skin.rst new file mode 100644 index 000000000..f0bc34e1e --- /dev/null +++ b/docs/pyboard/tutorial/lcd160cr_skin.rst @@ -0,0 +1,132 @@ +The LCD160CR skin +================= + +This tutorial shows how to get started using the LCD160CR skin. + +.. image:: http://micropython.org/resources/LCD160CRv10-persp.jpg + :alt: LCD160CRv1.0 picture + :width: 640px + +For detailed documentation of the driver for the display see the +:mod:`lcd160cr` module. + +Plugging in the display +----------------------- + +The display can be plugged directly into a pyboard (all pyboard versions +are supported). You plug the display onto the top of the pyboard either +in the X or Y positions. The display should cover half of the pyboard. + +Getting the driver +------------------ + +You can control the display directly using a power/enable pin and an I2C +bus, but it is much more convenient to use the driver provided by the +:mod:`lcd160cr` module. This driver is included in recent version of the +pyboard firmware (see `here `__). You +can also find the driver in the GitHub repository +`here `__, and to use this version you will need to copy the file to your +board, into a directory that is searched by import (usually the lib/ +directory). + +Once you have the driver installed you need to import it to use it:: + + import lcd160cr + +Testing the display +------------------- + +There is a test program which you can use to test the features of the display, +and which also serves as a basis to start creating your own code that uses the +LCD. This test program is included in recent versions of the pyboard firmware +and is also available on GitHub +`here `__. + +To run the test from the MicroPython prompt do:: + + >>> import lcd160cr_test + +It will then print some brief instructions. You will need to know which +position your display is connected to (X or Y) and then you can run (assuming +you have the display on position X):: + + >>> test_all('X') + +Drawing some graphics +--------------------- + +You must first create an LCD160CR object which will control the display. Do this +using:: + + >>> import lcd160cr + >>> lcd = lcd160cr.LCD160CR('X') + +This assumes your display is connected in the X position. If it's in the Y +position then use ``lcd = lcd160cr.LCD160CR('Y')`` instead. + +To erase the screen and draw a line, try:: + + >>> lcd.set_pen(lcd.rgb(255, 0, 0), lcd.rgb(64, 64, 128)) + >>> lcd.erase() + >>> lcd.line(10, 10, 50, 80) + +The next example draws random rectangles on the screen. You can copy-and-paste it +into the MicroPython prompt by first pressing "Ctrl-E" at the prompt, then "Ctrl-D" +once you have pasted the text. :: + + from random import randint + for i in range(1000): + fg = lcd.rgb(randint(128, 255), randint(128, 255), randint(128, 255)) + bg = lcd.rgb(randint(0, 128), randint(0, 128), randint(0, 128)) + lcd.set_pen(fg, bg) + lcd.rect(randint(0, lcd.w), randint(0, lcd.h), randint(10, 40), randint(10, 40)) + +Using the touch sensor +---------------------- + +The display includes a resistive touch sensor that can report the position (in +pixels) of a single force-based touch on the screen. To see if there is a touch +on the screen use:: + + >>> lcd.is_touched() + +This will return either ``False`` or ``True``. Run the above command while touching +the screen to see the result. + +To get the location of the touch you can use the method:: + + >>> lcd.get_touched() + +This will return a 3-tuple, with the first entry being 0 or 1 depending on whether +there is currently anything touching the screen (1 if there is), and the second and +third entries in the tuple being the x and y coordinates of the current (or most +recent) touch. + +Directing the MicroPython output to the display +----------------------------------------------- + +The display supports input from a UART and implements basic VT100 commands, which +means it can be used as a simple, general purpose terminal. Let's set up the +pyboard to redirect its output to the display. + +First you need to create a UART object:: + + >>> import pyb + >>> uart = pyb.UART('XA', 115200) + +This assumes your display is connected to position X. If it's on position Y then +use ``uart = pyb.UART('YA', 115200)`` instead. + +Now, connect the REPL output to this UART:: + + >>> pyb.repl_uart(uart) + +From now on anything you type at the MicroPython prompt, and any output you +receive, will appear on the display. + +No set-up commands are required for this mode to work and you can use the display +to monitor the output of any UART, not just from the pyboard. All that is needed +is for the display to have power, ground and the power/enable pin driven high. +Then any characters on the display's UART input will be printed to the screen. +You can adjust the UART baudrate from the default of 115200 using the +`set_uart_baudrate` method. -- cgit v1.2.3 From c707668d9e84f4b27b9d306f6cf2687e83f4425d Mon Sep 17 00:00:00 2001 From: Damien George Date: Tue, 24 Jan 2017 00:17:39 +1100 Subject: docs/library/lcd160cr: Fix set_brightness range, should be 0..31. --- docs/library/lcd160cr.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/library/lcd160cr.rst b/docs/library/lcd160cr.rst index c31dd6d2f..bb5a9b9f9 100644 --- a/docs/library/lcd160cr.rst +++ b/docs/library/lcd160cr.rst @@ -109,7 +109,7 @@ Setup commands .. method:: LCD160CR.set_brightness(value) - Set the brightness of the display, between 0 and 255. + Set the brightness of the display, between 0 and 31. .. method:: LCD160CR.set_i2c_addr(addr) -- cgit v1.2.3 From 56e7ebf07af8d570aadfe53b4686d014af574bf3 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Sat, 28 Jan 2017 11:55:48 +0300 Subject: docs/machine.Timer: Move WiPy adhoc parts to its documentation. --- docs/library/machine.Timer.rst | 95 ++++++++---------------------------------- docs/wipy/quickref.rst | 3 +- docs/wipy/tutorial/index.rst | 1 + docs/wipy/tutorial/timer.rst | 70 +++++++++++++++++++++++++++++++ 4 files changed, 91 insertions(+), 78 deletions(-) create mode 100644 docs/wipy/tutorial/timer.rst (limited to 'docs') diff --git a/docs/library/machine.Timer.rst b/docs/library/machine.Timer.rst index 12db58d5c..318443348 100644 --- a/docs/library/machine.Timer.rst +++ b/docs/library/machine.Timer.rst @@ -1,53 +1,14 @@ .. currentmodule:: machine -class Timer -- control internal timers +class Timer -- control hardware timers ====================================== -.. only:: port_wipy - - Timers can be used for a great variety of tasks, calling a function periodically, - counting events, and generating a PWM signal are among the most common use cases. - Each timer consists of two 16-bit channels and this channels can be tied together to - form one 32-bit timer. The operating mode needs to be configured per timer, but then - the period (or the frequency) can be independently configured on each channel. - By using the callback method, the timer event can call a Python function. - - Example usage to toggle an LED at a fixed frequency:: - - from machine import Timer - from machine import Pin - led = Pin('GP16', mode=Pin.OUT) # enable GP16 as output to drive the LED - tim = Timer(3) # create a timer object using timer 3 - tim.init(mode=Timer.PERIODIC) # initialize it in periodic mode - tim_ch = tim.channel(Timer.A, freq=5) # configure channel A at a frequency of 5Hz - tim_ch.irq(handler=lambda t:led.toggle(), trigger=Timer.TIMEOUT) # toggle a LED on every cycle of the timer - - Example using named function for the callback:: - - from machine import Timer - from machine import Pin - tim = Timer(1, mode=Timer.PERIODIC, width=32) - tim_a = tim.channel(Timer.A | Timer.B, freq=1) # 1 Hz frequency requires a 32 bit timer - - led = Pin('GP16', mode=Pin.OUT) # enable GP16 as output to drive the LED - - def tick(timer): # we will receive the timer object when being called - global led - led.toggle() # toggle the LED - - tim_a.irq(handler=tick, trigger=Timer.TIMEOUT) # create the interrupt - - Further examples:: - - from machine import Timer - tim1 = Timer(1, mode=Timer.ONE_SHOT) # initialize it in one shot mode - tim2 = Timer(2, mode=Timer.PWM) # initialize it in PWM mode - tim1_ch = tim1.channel(Timer.A, freq=10, polarity=Timer.POSITIVE) # start the event counter with a frequency of 10Hz and triggered by positive edges - tim2_ch = tim2.channel(Timer.B, freq=10000, duty_cycle=5000) # start the PWM on channel B with a 50% duty cycle - tim2_ch.freq(20) # set the frequency (can also get) - tim2_ch.duty_cycle(3010) # set the duty cycle to 30.1% (can also get) - tim2_ch.duty_cycle(3020, Timer.NEGATIVE) # set the duty cycle to 30.2% and change the polarity to negative - tim2_ch.period(2000000) # change the period to 2 seconds +Hardware timers deal with timing of periods and events. Timers are perhaps +the most flexible and heterogeneous kind of hardware in MCUs and SoCs, +differently greatly from a model to a model. MicroPython's Timer class +defines a baseline operation of executing a callback with a given period +(or once after some delay), and allow specific boards to define more +non-standard behavior (which thus won't be portable to other boards). .. note:: @@ -61,10 +22,8 @@ Constructors .. class:: Timer(id, ...) - .. only:: port_wipy - - Construct a new timer object of the given id. ``id`` can take values from 0 to 3. - + Construct a new timer object of the given id. Id of -1 constructs a + virtual timer (if supported by a board). Methods ------- @@ -94,8 +53,7 @@ Methods .. method:: Timer.deinit() - Deinitialises the timer. Disables all channels and associated IRQs. - Stops the timer, and disables the timer peripheral. + Deinitialises the timer. Stops the timer, and disables the timer peripheral. .. only:: port_wipy @@ -138,17 +96,17 @@ Methods - ``GP10`` on Timer 3 channel A. - ``GP11`` on Timer 3 channel B. -class TimerChannel --- setup a channel for a timer -================================================== +.. only:: port_wipy -Timer channels are used to generate/capture a signal using a timer. + class TimerChannel --- setup a channel for a timer + ================================================== -TimerChannel objects are created using the Timer.channel() method. + Timer channels are used to generate/capture a signal using a timer. -Methods -------- + TimerChannel objects are created using the Timer.channel() method. -.. only:: port_wipy + Methods + ------- .. method:: timerchannel.irq(\*, trigger, priority=1, handler=None) @@ -194,22 +152,5 @@ Constants .. data:: Timer.ONE_SHOT .. data:: Timer.PERIODIC -.. data:: Timer.PWM - - Selects the timer operating mode. - -.. data:: Timer.A -.. data:: Timer.B - - Selects the timer channel. Must be ORed (``Timer.A`` | ``Timer.B``) when - using a 32-bit timer. - -.. data:: Timer.POSITIVE -.. data:: Timer.NEGATIVE - - Timer channel polarity selection (only relevant in PWM mode). - -.. data:: Timer.TIMEOUT -.. data:: Timer.MATCH - Timer channel IRQ triggers. + Timer operating mode. diff --git a/docs/wipy/quickref.rst b/docs/wipy/quickref.rst index 7a4ea7f7f..2505eb35f 100644 --- a/docs/wipy/quickref.rst +++ b/docs/wipy/quickref.rst @@ -44,7 +44,8 @@ See :ref:`machine.Pin `. :: Timers ------ -See :ref:`machine.Timer ` and :ref:`machine.Pin `. :: +See :ref:`machine.Timer ` and :ref:`machine.Pin `. +Timer ``id``'s take values from 0 to 3.:: from machine import Timer from machine import Pin diff --git a/docs/wipy/tutorial/index.rst b/docs/wipy/tutorial/index.rst index c3d51e2e5..816de27b5 100644 --- a/docs/wipy/tutorial/index.rst +++ b/docs/wipy/tutorial/index.rst @@ -14,4 +14,5 @@ for instructions see :ref:`OTA How-To `. repl.rst blynk.rst wlan.rst + timer.rst reset.rst diff --git a/docs/wipy/tutorial/timer.rst b/docs/wipy/tutorial/timer.rst new file mode 100644 index 000000000..c87ac4495 --- /dev/null +++ b/docs/wipy/tutorial/timer.rst @@ -0,0 +1,70 @@ +Hardware timers +=============== + +Timers can be used for a great variety of tasks, calling a function periodically, +counting events, and generating a PWM signal are among the most common use cases. +Each timer consists of two 16-bit channels and this channels can be tied together to +form one 32-bit timer. The operating mode needs to be configured per timer, but then +the period (or the frequency) can be independently configured on each channel. +By using the callback method, the timer event can call a Python function. + +Example usage to toggle an LED at a fixed frequency:: + + from machine import Timer + from machine import Pin + led = Pin('GP16', mode=Pin.OUT) # enable GP16 as output to drive the LED + tim = Timer(3) # create a timer object using timer 3 + tim.init(mode=Timer.PERIODIC) # initialize it in periodic mode + tim_ch = tim.channel(Timer.A, freq=5) # configure channel A at a frequency of 5Hz + tim_ch.irq(handler=lambda t:led.toggle(), trigger=Timer.TIMEOUT) # toggle a LED on every cycle of the timer + +Example using named function for the callback:: + + from machine import Timer + from machine import Pin + tim = Timer(1, mode=Timer.PERIODIC, width=32) + tim_a = tim.channel(Timer.A | Timer.B, freq=1) # 1 Hz frequency requires a 32 bit timer + + led = Pin('GP16', mode=Pin.OUT) # enable GP16 as output to drive the LED + + def tick(timer): # we will receive the timer object when being called + global led + led.toggle() # toggle the LED + + tim_a.irq(handler=tick, trigger=Timer.TIMEOUT) # create the interrupt + +Further examples:: + + from machine import Timer + tim1 = Timer(1, mode=Timer.ONE_SHOT) # initialize it in one shot mode + tim2 = Timer(2, mode=Timer.PWM) # initialize it in PWM mode + tim1_ch = tim1.channel(Timer.A, freq=10, polarity=Timer.POSITIVE) # start the event counter with a frequency of 10Hz and triggered by positive edges + tim2_ch = tim2.channel(Timer.B, freq=10000, duty_cycle=5000) # start the PWM on channel B with a 50% duty cycle + tim2_ch.freq(20) # set the frequency (can also get) + tim2_ch.duty_cycle(3010) # set the duty cycle to 30.1% (can also get) + tim2_ch.duty_cycle(3020, Timer.NEGATIVE) # set the duty cycle to 30.2% and change the polarity to negative + tim2_ch.period(2000000) # change the period to 2 seconds + + +Additional constants for Timer class +------------------------------------ + +.. data:: Timer.PWM + + PWM timer operating mode. + +.. data:: Timer.A +.. data:: Timer.B + + Selects the timer channel. Must be ORed (``Timer.A`` | ``Timer.B``) when + using a 32-bit timer. + +.. data:: Timer.POSITIVE +.. data:: Timer.NEGATIVE + + Timer channel polarity selection (only relevant in PWM mode). + +.. data:: Timer.TIMEOUT +.. data:: Timer.MATCH + + Timer channel IRQ triggers. -- cgit v1.2.3 From 0aa83142a42f07675a21f8d223dc97b7da0194e4 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Sat, 28 Jan 2017 12:08:25 +0300 Subject: docs/machine: Add explicit note on machine module level and scope. It's very low, hardware level, with associated constraints on operations and callbacks. --- docs/library/machine.Timer.rst | 3 +++ docs/library/machine.rst | 23 ++++++++++++++++++----- 2 files changed, 21 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/library/machine.Timer.rst b/docs/library/machine.Timer.rst index 318443348..eddb2ce78 100644 --- a/docs/library/machine.Timer.rst +++ b/docs/library/machine.Timer.rst @@ -10,6 +10,9 @@ defines a baseline operation of executing a callback with a given period (or once after some delay), and allow specific boards to define more non-standard behavior (which thus won't be portable to other boards). +See discussion of :ref:`important constraints ` on +Timer callbacks. + .. note:: Memory can't be allocated inside irq handlers (an interrupt) and so diff --git a/docs/library/machine.rst b/docs/library/machine.rst index 7870da2ff..753f6b417 100644 --- a/docs/library/machine.rst +++ b/docs/library/machine.rst @@ -1,10 +1,23 @@ -:mod:`machine` --- functions related to the board -================================================= +:mod:`machine` --- functions related to the hardware +==================================================== .. module:: machine - :synopsis: functions related to the board - -The ``machine`` module contains specific functions related to the board. + :synopsis: functions related to the hardware + +The ``machine`` module contains specific functions related to the hardware +on a particular board. Most functions in this module allow to achieve direct +and unrestricted access to and control of hardware blocks on a system +(like CPU, timers, buses, etc.). Used incorrectly, this can lead to +malfunction, lockups, crashes of your board, and in extreme cases, hardware +damage. + +.. _machine_callbacks: + +A note of callbacks used by functions and class methods of ``machine`` module: +all these callbacks should be considered as executing in an interrupt context. +This is true for both physical devices with IDs >= 0 and "virtual" devices +with negative IDs like -1 (these "virtual" devices are still thin shims on +top of real hardware and real hardware intrerrupts). See :ref:`isr_rules`. Reset related functions ----------------------- -- cgit v1.2.3 From 59540dccf125452a8cf4e55f260788a46f7838dc Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Sat, 28 Jan 2017 13:55:51 +0300 Subject: docs/usocket: Clarify exceptions used. --- docs/library/usocket.rst | 25 ++++++++++++++++++------- 1 file changed, 18 insertions(+), 7 deletions(-) (limited to 'docs') diff --git a/docs/library/usocket.rst b/docs/library/usocket.rst index c46e8f4c5..64afa6f59 100644 --- a/docs/library/usocket.rst +++ b/docs/library/usocket.rst @@ -10,6 +10,12 @@ This module provides access to the BSD socket interface. See corresponding `CPython module `_ for comparison. +.. admonition:: Difference to CPython + :class: attention + + CPython used to have a ``socket.error`` exception which is now deprecated, + and is an alias of OSError. In MicroPython, use OSError directly. + Socket address format(s) ------------------------ @@ -51,13 +57,18 @@ Functions s = socket.socket() s.connect(socket.getaddrinfo('www.micropython.org', 80)[0][-1]) -.. only:: port_wipy - - Exceptions - ---------- - - .. data:: socket.error - .. data:: socket.timeout + .. admonition:: Difference to CPython + :class: attention + + CPython raises a ``socket.gaierror`` exception (OSError subclass) in case + of error in this function. MicroPython doesn't have ``socket.gaierror`` + and raises OSError directly. Note that error numbers of ``getaddrinfo()`` + form a separate namespace and may not match error numbers from + ``uerrno`` module. To distinguish ``getaddrinfo()`` errors, they are + represented by negative numbers, whereas standard system errors are + positive numbers (error numbers are accessible using ``e.args[0]`` property + from an exception object). The use of negative values is a provisional + detail which may change in the future. Constants --------- -- cgit v1.2.3 From 74fcb122f0afa8be19b691e720c35f5730175f96 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Sat, 28 Jan 2017 14:46:58 +0300 Subject: docs/usocket: Elaborate "Constants" section. --- docs/library/usocket.rst | 26 +++++++++++++++++++------- 1 file changed, 19 insertions(+), 7 deletions(-) (limited to 'docs') diff --git a/docs/library/usocket.rst b/docs/library/usocket.rst index 64afa6f59..16ba66c2b 100644 --- a/docs/library/usocket.rst +++ b/docs/library/usocket.rst @@ -74,21 +74,33 @@ Constants --------- .. data:: socket.AF_INET + socket.AF_INET6 - family types + Address family types. Availability depends on a particular board. .. data:: socket.SOCK_STREAM -.. data:: socket.SOCK_DGRAM + socket.SOCK_DGRAM - socket types + Socket types. .. data:: socket.IPPROTO_UDP -.. data:: socket.IPPROTO_TCP -.. only:: port_wipy + socket.IPPROTO_TCP - .. data:: socket.IPPROTO_SEC + IP protocol numbers. - protocol numbers +.. data:: socket.SOL_* + + Socket option levels (an argument to ``setsockopt()``). The exact inventory depends on a board. + +.. data:: socket.SO_* + + Socket options (an argument to ``setsockopt()``). The exact inventory depends on a board. + +Constants specific to WiPy: + +.. data:: socket.IPPROTO_SEC + + Special protocol value to create SSL-compatible socket. class socket ============ -- cgit v1.2.3 From f23c47fea701d1adb778092f9f53532d057acffd Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Sat, 28 Jan 2017 15:39:18 +0300 Subject: docs/usocket: Clarify description of various methods. --- docs/library/usocket.rst | 55 ++++++++++++++++++++++++++++++++++++------------ 1 file changed, 41 insertions(+), 14 deletions(-) (limited to 'docs') diff --git a/docs/library/usocket.rst b/docs/library/usocket.rst index 16ba66c2b..a75049727 100644 --- a/docs/library/usocket.rst +++ b/docs/library/usocket.rst @@ -7,8 +7,8 @@ This module provides access to the BSD socket interface. -See corresponding `CPython module `_ for -comparison. +See the corresponding `CPython module `_ +for comparison. .. admonition:: Difference to CPython :class: attention @@ -16,10 +16,19 @@ comparison. CPython used to have a ``socket.error`` exception which is now deprecated, and is an alias of OSError. In MicroPython, use OSError directly. +.. admonition:: Difference to CPython + :class: attention + + For efficiency and consistency, socket objects in MicroPython implement a stream + (file-like) interface directly. In CPython, you need to convert a socket to + a file-like object using ``makefile()`` method. This method is still supported + by MicroPython (but is a no-op), so where compatibility with CPython matters, + be sure to use it. + Socket address format(s) ------------------------ -Functions below which expect a network address, accept it in the format of +The functions below which expect a network address, accept it in the format of `(ipv4_address, port)`, where `ipv4_address` is a string with dot-notation numeric IPv4 address, e.g. ``"8.8.8.8"``, and port is integer port number in the range 1-65535. Note the domain names are not accepted as `ipv4_address`, they should be @@ -141,10 +150,19 @@ Methods .. method:: socket.send(bytes) Send data to the socket. The socket must be connected to a remote socket. + Returns number of bytes sent, which may be smaller than the length of data + ("short write"). .. method:: socket.sendall(bytes) - Send data to the socket. The socket must be connected to a remote socket. + Send all data to the socket. The socket must be connected to a remote socket. + Unlike ``send()``, this method will try to send all of data, by sending data + chunk by chunk consecutively. + + The behavior of this method on non-blocking sockets is undefined. Due to this, + on MicroPython, it's recommended to use ``write()`` method instead, which + has the same "no short writes" policy for blocking sockets, and will return + number of bytes sent on non-blocking sockets. .. method:: socket.recv(bufsize) @@ -189,19 +207,22 @@ Methods Set blocking or non-blocking mode of the socket: if flag is false, the socket is set to non-blocking, else to blocking mode. - This method is a shorthand for certain ``settimeout()`` calls:: + This method is a shorthand for certain ``settimeout()`` calls: - sock.setblocking(True) is equivalent to sock.settimeout(None) - sock.setblocking(False) is equivalent to sock.settimeout(0.0) + * ``sock.setblocking(True)`` is equivalent to ``sock.settimeout(None)`` + * ``sock.setblocking(False)`` is equivalent to ``sock.settimeout(0)`` - .. method:: socket.makefile(mode='rb') + .. method:: socket.makefile(mode='rb', buffering=0) Return a file object associated with the socket. The exact returned type depends on the arguments - given to makefile(). The support is limited to binary modes only ('rb' and 'wb'). + given to makefile(). The support is limited to binary modes only ('rb', 'wb', and 'rwb'). CPython's arguments: ``encoding``, ``errors`` and ``newline`` are not supported. - The socket must be in blocking mode; it can have a timeout, but the file object’s internal buffer - may end up in a inconsistent state if a timeout occurs. + .. admonition:: Difference to CPython + :class: attention + + As MicroPython doesn't support buffered streams, values of ``buffering`` + parameter is ignored and treated as if it was 0 (unbuffered). .. admonition:: Difference to CPython :class: attention @@ -213,12 +234,15 @@ Methods Read up to size bytes from the socket. Return a bytes object. If ``size`` is not given, it reads all data available from the socket until ``EOF``; as such the method will not return until - the socket is closed. + the socket is closed. This function tries to read as much data as + requested (no "short reads"). This may be not possible with + non-blocking socket though, and then less data will be returned. .. method:: socket.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. + that many bytes. Otherwise, read at most ``len(buf)`` bytes. Just as + ``read()``, this method follows "no short reads" policy. Return value: number of bytes read and stored into ``buf``. @@ -230,6 +254,9 @@ Methods .. method:: socket.write(buf) - Write the buffer of bytes to the socket. + Write the buffer of bytes to the socket. This function will try to + write all data to a socket (no "short writes"). This may be not possible + with a non-blocking socket though, and returned value will be less than + the length of ``buf``. Return value: number of bytes written. -- cgit v1.2.3 From 6947a7f6a975dd9ebf1af6ea7ddf21c364339078 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Sat, 28 Jan 2017 15:49:54 +0300 Subject: docs/usocket: Dedent Methods section. This was apparently of an ::only directive which was later removed. --- docs/library/usocket.rst | 190 +++++++++++++++++++++++------------------------ 1 file changed, 95 insertions(+), 95 deletions(-) (limited to 'docs') diff --git a/docs/library/usocket.rst b/docs/library/usocket.rst index a75049727..dd0f5708b 100644 --- a/docs/library/usocket.rst +++ b/docs/library/usocket.rst @@ -117,146 +117,146 @@ class socket Methods ------- - .. method:: socket.close +.. method:: socket.close - Mark the socket closed. Once that happens, all future operations on the socket - object will fail. The remote end will receive no more data (after queued data is flushed). + Mark the socket closed. Once that happens, all future operations on the socket + object will fail. The remote end will receive no more data (after queued data is flushed). - Sockets are automatically closed when they are garbage-collected, but it is recommended - to close() them explicitly, or to use a with statement around them. + Sockets are automatically closed when they are garbage-collected, but it is recommended + to close() them explicitly, or to use a with statement around them. - .. method:: socket.bind(address) +.. method:: socket.bind(address) - Bind the socket to address. The socket must not already be bound. + Bind the socket to address. The socket must not already be bound. - .. method:: socket.listen([backlog]) +.. method:: socket.listen([backlog]) - 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 - that the system will allow before refusing new connections. If not specified, a default - reasonable value is chosen. + 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 + that the system will allow before refusing new connections. If not specified, a default + reasonable value is chosen. - .. method:: socket.accept() +.. method:: socket.accept() - Accept a connection. The socket must be bound to an address and listening for connections. - The return value is a pair (conn, address) where conn is a new socket object usable to send - and receive data on the connection, and address is the address bound to the socket on the - other end of the connection. + Accept a connection. The socket must be bound to an address and listening for connections. + The return value is a pair (conn, address) where conn is a new socket object usable to send + and receive data on the connection, and address is the address bound to the socket on the + other end of the connection. - .. method:: socket.connect(address) +.. method:: socket.connect(address) - Connect to a remote socket at address. + Connect to a remote socket at address. - .. method:: socket.send(bytes) +.. method:: socket.send(bytes) - Send data to the socket. The socket must be connected to a remote socket. - Returns number of bytes sent, which may be smaller than the length of data - ("short write"). + Send data to the socket. The socket must be connected to a remote socket. + Returns number of bytes sent, which may be smaller than the length of data + ("short write"). - .. method:: socket.sendall(bytes) +.. method:: socket.sendall(bytes) - Send all data to the socket. The socket must be connected to a remote socket. - Unlike ``send()``, this method will try to send all of data, by sending data - chunk by chunk consecutively. + Send all data to the socket. The socket must be connected to a remote socket. + Unlike ``send()``, this method will try to send all of data, by sending data + chunk by chunk consecutively. - The behavior of this method on non-blocking sockets is undefined. Due to this, - on MicroPython, it's recommended to use ``write()`` method instead, which - has the same "no short writes" policy for blocking sockets, and will return - number of bytes sent on non-blocking sockets. + The behavior of this method on non-blocking sockets is undefined. Due to this, + on MicroPython, it's recommended to use ``write()`` method instead, which + has the same "no short writes" policy for blocking sockets, and will return + number of bytes sent on non-blocking sockets. - .. method:: socket.recv(bufsize) +.. method:: socket.recv(bufsize) - Receive data from the socket. The return value is a bytes object representing the data - received. The maximum amount of data to be received at once is specified by bufsize. + Receive data from the socket. The return value is a bytes object representing the data + received. The maximum amount of data to be received at once is specified by bufsize. - .. method:: socket.sendto(bytes, address) +.. method:: socket.sendto(bytes, address) - Send data to the socket. The socket should not be connected to a remote socket, since the - destination socket is specified by `address`. + Send data to the socket. The socket should not be connected to a remote socket, since the + destination socket is specified by `address`. - .. method:: socket.recvfrom(bufsize) +.. method:: socket.recvfrom(bufsize) - Receive data from the socket. The return value is a pair (bytes, address) where bytes is a - bytes object representing the data received and address is the address of the socket sending - the data. + Receive data from the socket. The return value is a pair (bytes, address) where bytes is a + bytes object representing the data received and address is the address of the socket sending + the data. - .. method:: socket.setsockopt(level, optname, value) +.. method:: socket.setsockopt(level, optname, value) - Set the value of the given socket option. The needed symbolic constants are defined in the - socket module (SO_* etc.). The value can be an integer or a bytes-like object representing - a buffer. + Set the value of the given socket option. The needed symbolic constants are defined in the + socket module (SO_* etc.). The value can be an integer or a bytes-like object representing + a buffer. - .. method:: socket.settimeout(value) +.. method:: socket.settimeout(value) - Set a timeout on blocking socket operations. The value argument can be a nonnegative floating - point number expressing seconds, or None. If a non-zero value is given, subsequent socket operations - will raise an ``OSError`` exception if the timeout period value has elapsed before the operation has - completed. If zero is given, the socket is put in non-blocking mode. If None is given, the socket - is put in blocking mode. + Set a timeout on blocking socket operations. The value argument can be a nonnegative floating + point number expressing seconds, or None. If a non-zero value is given, subsequent socket operations + will raise an ``OSError`` exception if the timeout period value has elapsed before the operation has + completed. If zero is given, the socket is put in non-blocking mode. If None is given, the socket + is put in blocking mode. - .. admonition:: Difference to CPython - :class: attention + .. admonition:: Difference to CPython + :class: attention - CPython raises a ``socket.timeout`` exception in case of timeout, - which is an ``OSError`` subclass. MicroPython raises an OSError directly - instead. If you use ``except OSError:`` to catch the exception, - your code will work both in MicroPython and CPython. + CPython raises a ``socket.timeout`` exception in case of timeout, + which is an ``OSError`` subclass. MicroPython raises an OSError directly + instead. If you use ``except OSError:`` to catch the exception, + your code will work both in MicroPython and CPython. - .. method:: socket.setblocking(flag) +.. method:: socket.setblocking(flag) - Set blocking or non-blocking mode of the socket: if flag is false, the socket is set to non-blocking, - else to blocking mode. + Set blocking or non-blocking mode of the socket: if flag is false, the socket is set to non-blocking, + else to blocking mode. - This method is a shorthand for certain ``settimeout()`` calls: + This method is a shorthand for certain ``settimeout()`` calls: - * ``sock.setblocking(True)`` is equivalent to ``sock.settimeout(None)`` - * ``sock.setblocking(False)`` is equivalent to ``sock.settimeout(0)`` + * ``sock.setblocking(True)`` is equivalent to ``sock.settimeout(None)`` + * ``sock.setblocking(False)`` is equivalent to ``sock.settimeout(0)`` - .. method:: socket.makefile(mode='rb', buffering=0) +.. method:: socket.makefile(mode='rb', buffering=0) - Return a file object associated with the socket. The exact returned type depends on the arguments - given to makefile(). The support is limited to binary modes only ('rb', 'wb', and 'rwb'). - CPython's arguments: ``encoding``, ``errors`` and ``newline`` are not supported. + Return a file object associated with the socket. The exact returned type depends on the arguments + given to makefile(). The support is limited to binary modes only ('rb', 'wb', and 'rwb'). + CPython's arguments: ``encoding``, ``errors`` and ``newline`` are not supported. - .. admonition:: Difference to CPython - :class: attention + .. admonition:: Difference to CPython + :class: attention - As MicroPython doesn't support buffered streams, values of ``buffering`` - parameter is ignored and treated as if it was 0 (unbuffered). + As MicroPython doesn't support buffered streams, values of ``buffering`` + parameter is ignored and treated as if it was 0 (unbuffered). - .. admonition:: Difference to CPython - :class: attention + .. admonition:: Difference to CPython + :class: attention - Closing the file object returned by makefile() WILL close the - original socket as well. + Closing the file object returned by makefile() WILL close the + original socket as well. - .. method:: socket.read([size]) +.. method:: socket.read([size]) - Read up to size bytes from the socket. Return a bytes object. If ``size`` is not given, it - reads all data available from the socket until ``EOF``; as such the method will not return until - the socket is closed. This function tries to read as much data as - requested (no "short reads"). This may be not possible with - non-blocking socket though, and then less data will be returned. + Read up to size bytes from the socket. Return a bytes object. If ``size`` is not given, it + reads all data available from the socket until ``EOF``; as such the method will not return until + the socket is closed. This function tries to read as much data as + requested (no "short reads"). This may be not possible with + non-blocking socket though, and then less data will be returned. - .. method:: socket.readinto(buf[, nbytes]) +.. method:: socket.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. Just as - ``read()``, this method follows "no short reads" policy. + Read bytes into the ``buf``. If ``nbytes`` is specified then read at most + that many bytes. Otherwise, read at most ``len(buf)`` bytes. Just as + ``read()``, this method follows "no short reads" policy. - Return value: number of bytes read and stored into ``buf``. + Return value: number of bytes read and stored into ``buf``. - .. method:: socket.readline() +.. method:: socket.readline() - Read a line, ending in a newline character. + Read a line, ending in a newline character. - Return value: the line read. + Return value: the line read. - .. method:: socket.write(buf) +.. method:: socket.write(buf) - Write the buffer of bytes to the socket. This function will try to - write all data to a socket (no "short writes"). This may be not possible - with a non-blocking socket though, and returned value will be less than - the length of ``buf``. + Write the buffer of bytes to the socket. This function will try to + write all data to a socket (no "short writes"). This may be not possible + with a non-blocking socket though, and returned value will be less than + the length of ``buf``. - Return value: number of bytes written. + Return value: number of bytes written. -- cgit v1.2.3 From ef6fb66d2323d5c60fffdc77886a2ce170fa5e20 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Sat, 28 Jan 2017 16:35:40 +0300 Subject: docs/uio: Describe differences between uPy an CPy stream hierarchy. --- docs/library/uio.rst | 65 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 65 insertions(+) (limited to 'docs') diff --git a/docs/library/uio.rst b/docs/library/uio.rst index 9b4c87df8..352939932 100644 --- a/docs/library/uio.rst +++ b/docs/library/uio.rst @@ -7,6 +7,71 @@ This module contains additional types of stream (file-like) objects and helper functions. +Conceptual hierarchy +-------------------- + +.. admonition:: Difference to CPython + :class: attention + + Conceptual hierarchy of stream base classes is simplified in MicroPython, + as described in this section. + +(Abstract) base stream classes, which serve as a foundation for behavior +of all the concrete classes, adhere to few dichotomies (pair-wise +classifications) in CPython. In MicroPython, they are somewhat simplified +and made implicit to achieve higher efficiencies and save resources. + +An important dichotomy in CPython is unbuffered vs buffered streams. In +MicroPython, all streams are currently unbuffered. This is because all +modern OSes, and even many RTOSes and filesystem drivers already perform +buffering on their side. Adding another later of buffering is counter- +productive (an issue known as "bufferbloat") and spends precious memory. +Note that there still cases where buffering may be useful, so we may +introduce optional buffering support at a later time. + +But in CPython, another important dichotomy is tied with "bufferedness" - +it's whether a stream may incur short read/writes or not. A short read +is when a user asks e.g. 10 bytes from a stream, but gets less, similarly +for writes. In CPython, unbuffered streams are automatically short +operation susceptible, while buffered are guarantee against them. The +no short read/writes is an important traits, as it allows to develop +more concise and efficient programs - something which is highly desirable +for MicroPython. So, while MicroPython doesn't support buffered streams, +it still provides for no-short-operations streams. Whether there will +be short operations or not depends on each particular class' needs, but +developers are strongly advised to favor no-short-operations behavior +for the reasons stated above. For example, MicroPython sockets are +guaranteed to avoid short read/writes. Actually, at this time, there is +no example of a short-operations stream class in the core, and one would +be a port-specific class, where such a need is governed by hardware +peculiarities. + +The no-short-operations behavior gets tricky in case of non-blocking +streams, blockedness vs non-blockedness being another CPython dichotomy, +fully supported by MicroPython. Non-blocking streams never wait for +data either to arrive or be written - they read/write whatever possible, +or signal lack of data (or ability to write data). Clearly, this conflicts +with "no-short-operations" policy, and indeed, a case of non-blocking +buffered (and this no-short-ops) streams is convoluted in CPython - in +some places, such combination is prohibited, in some it's undefined or +just not documented, in some cases it raises verbose exceptions. The +matter is much simpler in MicroPython: non-blocking stream are important +for efficient asynchronuous operations, so this property prevails on +the "no-short-ops" one. So, while blocking streams will avoid short +reads/writes whenever possible (the only case to get a short read is +if end of file is reached, or in case of error (but errors don't +return short data, but raise exceptions)), non-blocking streams may +produce short data to avoid blocking the operation. + +The final dichotomy is binary vs text streams. MicroPython of course +supports these, but while in CPython text streams are inherently +buffered, they aren't in MicroPython. (Indeed, that's one of the cases +for which we may introduce buffering support.) + +Note that for efficiency, MicroPython doesn't provide abstract base +classes corresponding to the hierarchy above, and it's not possible +to implement, or subclass, a stream class in pure Python. + Functions --------- -- cgit v1.2.3 From bdb0d22fe2619393e2d8cd591dd14cd4081f8fc5 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Sat, 28 Jan 2017 12:57:08 +0300 Subject: docs/conf.py: Add myself as a copyright holder on the docs. Based on the following statistics: $ git log docs |grep Author | sort | uniq -c | sort -n -r 175 Author: Paul Sokolovsky 135 Author: Damien George 31 Author: Daniel Campora 26 Author: danicampora 14 Author: Peter Hinch git blame stats script from http://stackoverflow.com/a/13687302/496009: $ sh git-authors docs 9977 author Damien George 2679 author Paul Sokolovsky 1699 author Daniel Campora 1580 author danicampora 1286 author Peter Hinch 282 author Shuning Bian 249 author Dave Hylands Total lines per this script: 18417, my contribution is 14.5%. --- docs/conf.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/conf.py b/docs/conf.py index 6026aee56..1a552be2e 100755 --- a/docs/conf.py +++ b/docs/conf.py @@ -90,7 +90,7 @@ source_suffix = '.rst' # General information about the project. project = 'MicroPython' -copyright = '2014-2016, Damien P. George and contributors' +copyright = '2014-2017, Damien P. George, Paul Sokolovsky, and contributors' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the @@ -253,7 +253,7 @@ latex_elements = { # author, documentclass [howto, manual, or own class]). latex_documents = [ (master_doc, 'MicroPython.tex', 'MicroPython Documentation', - 'Damien P. George and contributors', 'manual'), + 'Damien P. George, Paul Sokolovsky, and contributors', 'manual'), ] # The name of an image file (relative to this directory) to place at the top of @@ -283,7 +283,7 @@ latex_documents = [ # (source start file, name, description, authors, manual section). man_pages = [ ('index', 'micropython', 'MicroPython Documentation', - ['Damien P. George and contributors'], 1), + ['Damien P. George, Paul Sokolovsky, and contributors'], 1), ] # If true, show URL addresses after external links. @@ -297,7 +297,7 @@ man_pages = [ # dir menu entry, description, category) texinfo_documents = [ (master_doc, 'MicroPython', 'MicroPython Documentation', - 'Damien P. George and contributors', 'MicroPython', 'One line description of project.', + 'Damien P. George, Paul Sokolovsky, and contributors', 'MicroPython', 'One line description of project.', 'Miscellaneous'), ] -- cgit v1.2.3 From 0ddeedfc733b8a5c2f4e1939d0dd31c77e38e39d Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Sun, 29 Jan 2017 16:18:33 +0300 Subject: docs/uio: Typo fixes/lexical improvements. --- docs/library/uio.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/library/uio.rst b/docs/library/uio.rst index 352939932..1239c6394 100644 --- a/docs/library/uio.rst +++ b/docs/library/uio.rst @@ -24,8 +24,8 @@ and made implicit to achieve higher efficiencies and save resources. An important dichotomy in CPython is unbuffered vs buffered streams. In MicroPython, all streams are currently unbuffered. This is because all modern OSes, and even many RTOSes and filesystem drivers already perform -buffering on their side. Adding another later of buffering is counter- -productive (an issue known as "bufferbloat") and spends precious memory. +buffering on their side. Adding another layer of buffering is counter- +productive (an issue known as "bufferbloat") and takes precious memory. Note that there still cases where buffering may be useful, so we may introduce optional buffering support at a later time. @@ -34,7 +34,7 @@ it's whether a stream may incur short read/writes or not. A short read is when a user asks e.g. 10 bytes from a stream, but gets less, similarly for writes. In CPython, unbuffered streams are automatically short operation susceptible, while buffered are guarantee against them. The -no short read/writes is an important traits, as it allows to develop +no short read/writes is an important trait, as it allows to develop more concise and efficient programs - something which is highly desirable for MicroPython. So, while MicroPython doesn't support buffered streams, it still provides for no-short-operations streams. Whether there will @@ -47,7 +47,7 @@ be a port-specific class, where such a need is governed by hardware peculiarities. The no-short-operations behavior gets tricky in case of non-blocking -streams, blockedness vs non-blockedness being another CPython dichotomy, +streams, blocking vs non-blocking behavior being another CPython dichotomy, fully supported by MicroPython. Non-blocking streams never wait for data either to arrive or be written - they read/write whatever possible, or signal lack of data (or ability to write data). Clearly, this conflicts @@ -56,7 +56,7 @@ buffered (and this no-short-ops) streams is convoluted in CPython - in some places, such combination is prohibited, in some it's undefined or just not documented, in some cases it raises verbose exceptions. The matter is much simpler in MicroPython: non-blocking stream are important -for efficient asynchronuous operations, so this property prevails on +for efficient asynchronous operations, so this property prevails on the "no-short-ops" one. So, while blocking streams will avoid short reads/writes whenever possible (the only case to get a short read is if end of file is reached, or in case of error (but errors don't -- cgit v1.2.3 From 5ec5bfb0d31c04b3d44e109dd5dca779c3a070e0 Mon Sep 17 00:00:00 2001 From: Damien George Date: Mon, 30 Jan 2017 18:19:29 +1100 Subject: docs/pyboard/tutorial/lcd160cr_skin: Fix typo, get_touched->get_touch. --- docs/pyboard/tutorial/lcd160cr_skin.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/pyboard/tutorial/lcd160cr_skin.rst b/docs/pyboard/tutorial/lcd160cr_skin.rst index f0bc34e1e..11ebad9a6 100644 --- a/docs/pyboard/tutorial/lcd160cr_skin.rst +++ b/docs/pyboard/tutorial/lcd160cr_skin.rst @@ -95,7 +95,7 @@ the screen to see the result. To get the location of the touch you can use the method:: - >>> lcd.get_touched() + >>> lcd.get_touch() This will return a 3-tuple, with the first entry being 0 or 1 depending on whether there is currently anything touching the screen (1 if there is), and the second and -- cgit v1.2.3 From 50a9dd59f5848d536d2057498671d8fe90c76ef1 Mon Sep 17 00:00:00 2001 From: Damien George Date: Fri, 3 Feb 2017 12:48:54 +1100 Subject: docs: For LCD160CR driver and tutorial, add link to positioning image. --- docs/library/lcd160cr.rst | 3 +++ docs/pyboard/tutorial/lcd160cr_skin.rst | 6 ++++-- 2 files changed, 7 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/library/lcd160cr.rst b/docs/library/lcd160cr.rst index bb5a9b9f9..39f492fc4 100644 --- a/docs/library/lcd160cr.rst +++ b/docs/library/lcd160cr.rst @@ -69,6 +69,9 @@ Constructors - "YX" is for the left-side and uses: ``pwr=Pin("Y4")``, ``i2c=I2C("X")``, ``spi=SPI("Y")`` + See `this image `_ + for how the display can be connected to the pyboard. + Static methods -------------- diff --git a/docs/pyboard/tutorial/lcd160cr_skin.rst b/docs/pyboard/tutorial/lcd160cr_skin.rst index 11ebad9a6..fc9d63538 100644 --- a/docs/pyboard/tutorial/lcd160cr_skin.rst +++ b/docs/pyboard/tutorial/lcd160cr_skin.rst @@ -3,9 +3,9 @@ The LCD160CR skin This tutorial shows how to get started using the LCD160CR skin. -.. image:: http://micropython.org/resources/LCD160CRv10-persp.jpg +.. image:: http://micropython.org/resources/LCD160CRv10-positions.jpg :alt: LCD160CRv1.0 picture - :width: 640px + :width: 800px For detailed documentation of the driver for the display see the :mod:`lcd160cr` module. @@ -16,6 +16,8 @@ Plugging in the display The display can be plugged directly into a pyboard (all pyboard versions are supported). You plug the display onto the top of the pyboard either in the X or Y positions. The display should cover half of the pyboard. +See the picture above for how to achieve this; the left half of the picture +shows the X position, and the right half shows the Y position. Getting the driver ------------------ -- cgit v1.2.3 From d5e9ab6e61729f533dbed5c2b6b27307ce6c3b55 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Sun, 5 Feb 2017 14:20:17 +0300 Subject: extmod/machine_pulse: Make time_pulse_us() not throw exceptions. machine.time_pulse_us() is intended to provide very fine timing, including while working with signal bursts, where each transition is tracked in row. Throwing and handling an exception may take too much time and "signal loss". So instead, in case of a timeout, just return negative value. Cases of timeout while waiting for initial signal stabilization, and during actual timing, are recognized. The documentation is updated accordingly, and rewritten somewhat to clarify the function behavior. --- docs/library/machine.rst | 11 +++++++---- drivers/dht/dht.c | 4 ++-- extmod/machine_pulse.c | 6 ++---- tests/extmod/machine_pulse.py | 11 ++--------- tests/extmod/machine_pulse.py.exp | 4 ++-- 5 files changed, 15 insertions(+), 21 deletions(-) (limited to 'docs') diff --git a/docs/library/machine.rst b/docs/library/machine.rst index 753f6b417..c6da71585 100644 --- a/docs/library/machine.rst +++ b/docs/library/machine.rst @@ -118,12 +118,15 @@ Miscellaneous functions microseconds. The `pulse_level` argument should be 0 to time a low pulse or 1 to time a high pulse. - The function first waits while the pin input is different to the `pulse_level` - parameter, then times the duration that the pin is equal to `pulse_level`. + If the current input value of the pin is different to `pulse_level`, + the function first (*) waits until the pin input becomes equal to `pulse_level`, + then (**) times the duration that the pin is equal to `pulse_level`. If the pin is already equal to `pulse_level` then timing starts straight away. - The function will raise an OSError with ETIMEDOUT if either of the waits is - longer than the given timeout value (which is in microseconds). + The function will return -2 if there was timeout waiting for condition marked + (*) above, and -1 if there was timeout during the main measurement, marked (**) + above. The timeout is the same for both cases and given by `timeout_us` (which + is in microseconds). .. _machine_constants: diff --git a/drivers/dht/dht.c b/drivers/dht/dht.c index 1f0cffc6f..6bdda44b4 100644 --- a/drivers/dht/dht.c +++ b/drivers/dht/dht.c @@ -65,7 +65,7 @@ STATIC mp_obj_t dht_readinto(mp_obj_t pin_in, mp_obj_t buf_in) { // time pulse, should be 80us ticks = machine_time_pulse_us(pin, 1, 150); - if (ticks == (mp_uint_t)-1) { + if ((mp_int_t)ticks < 0) { goto timeout; } @@ -73,7 +73,7 @@ STATIC mp_obj_t dht_readinto(mp_obj_t pin_in, mp_obj_t buf_in) { uint8_t *buf = bufinfo.buf; for (int i = 0; i < 40; ++i) { ticks = machine_time_pulse_us(pin, 1, 100); - if (ticks == (mp_uint_t)-1) { + if ((mp_int_t)ticks < 0) { goto timeout; } buf[i / 8] = (buf[i / 8] << 1) | (ticks > 48); diff --git a/extmod/machine_pulse.c b/extmod/machine_pulse.c index b2a78d72e..5f837479d 100644 --- a/extmod/machine_pulse.c +++ b/extmod/machine_pulse.c @@ -34,7 +34,7 @@ mp_uint_t machine_time_pulse_us(mp_hal_pin_obj_t pin, int pulse_level, mp_uint_t mp_uint_t start = mp_hal_ticks_us(); while (mp_hal_pin_read(pin) != pulse_level) { if ((mp_uint_t)(mp_hal_ticks_us() - start) >= timeout_us) { - return (mp_uint_t)-1; + return (mp_uint_t)-2; } } start = mp_hal_ticks_us(); @@ -57,9 +57,7 @@ STATIC mp_obj_t machine_time_pulse_us_(size_t n_args, const mp_obj_t *args) { timeout_us = mp_obj_get_int(args[2]); } mp_uint_t us = machine_time_pulse_us(pin, level, timeout_us); - if (us == (mp_uint_t)-1) { - mp_raise_OSError(MP_ETIMEDOUT); - } + // May return -1 or -2 in case of timeout return mp_obj_new_int(us); } MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(machine_time_pulse_us_obj, 2, 3, machine_time_pulse_us_); diff --git a/tests/extmod/machine_pulse.py b/tests/extmod/machine_pulse.py index b6e126435..6491b5409 100644 --- a/tests/extmod/machine_pulse.py +++ b/tests/extmod/machine_pulse.py @@ -43,12 +43,5 @@ t = machine.time_pulse_us(p, 0) print(type(t)) p = ConstPin(0) -try: - machine.time_pulse_us(p, 1, 10) -except OSError: - print("OSError") - -try: - machine.time_pulse_us(p, 0, 10) -except OSError: - print("OSError") +print(machine.time_pulse_us(p, 1, 10)) +print(machine.time_pulse_us(p, 0, 10)) diff --git a/tests/extmod/machine_pulse.py.exp b/tests/extmod/machine_pulse.py.exp index f9a474218..20d4c1043 100644 --- a/tests/extmod/machine_pulse.py.exp +++ b/tests/extmod/machine_pulse.py.exp @@ -5,5 +5,5 @@ value: 1 value: 0 value: 1 -OSError -OSError +-2 +-1 -- cgit v1.2.3 From 27c149efe030b6fd24c0cc1475ea509da1a72821 Mon Sep 17 00:00:00 2001 From: Damien George Date: Mon, 6 Feb 2017 13:19:52 +1100 Subject: stmhal: Add pyb.fault_debug() function, to control hard-fault behaviour. This new function controls what happens on a hard-fault: - debugging disabled: board will do a reset - debugging enabled: board will print registers and stack and flash LEDs The default is disabled, ie to do a reset. This is different to previous behaviour which flashed the LEDs and waited indefinitely. --- docs/library/pyb.rst | 13 +++++++++++++ stmhal/modpyb.c | 9 +++++++++ stmhal/stm32_it.c | 20 +++++++------------- stmhal/stm32_it.h | 2 ++ tests/pyb/pyb1.py | 3 +++ 5 files changed, 34 insertions(+), 13 deletions(-) (limited to 'docs') diff --git a/docs/library/pyb.rst b/docs/library/pyb.rst index 910b2f45b..9c4933808 100644 --- a/docs/library/pyb.rst +++ b/docs/library/pyb.rst @@ -80,6 +80,19 @@ Reset related functions Activate the bootloader without BOOT\* pins. +.. function:: fault_debug(value) + + Enable or disable hard-fault debugging. A hard-fault is when there is a fatal + error in the underlying system, like an invalid memory access. + + If the `value` argument is `False` then the board will automatically reset if + there is a hard fault. + + If `value` is `True` then, when the board has a hard fault, it will print the + registers and the stack trace, and then cycle the LEDs indefinitely. + + The default value is disabled, i.e. to automatically reset. + Interrupt related functions --------------------------- diff --git a/stmhal/modpyb.c b/stmhal/modpyb.c index 53b4335e7..93ae5d40b 100644 --- a/stmhal/modpyb.c +++ b/stmhal/modpyb.c @@ -38,6 +38,7 @@ #include "lib/oofatfs/ff.h" #include "lib/oofatfs/diskio.h" #include "gccollect.h" +#include "stm32_it.h" #include "irq.h" #include "systick.h" #include "led.h" @@ -64,6 +65,12 @@ #include "extmod/vfs.h" #include "extmod/utime_mphal.h" +STATIC mp_obj_t pyb_fault_debug(mp_obj_t value) { + pyb_hard_fault_debug = mp_obj_is_true(value); + return mp_const_none; +} +STATIC MP_DEFINE_CONST_FUN_OBJ_1(pyb_fault_debug_obj, pyb_fault_debug); + /// \function millis() /// Returns the number of milliseconds since the board was last reset. /// @@ -131,6 +138,8 @@ MP_DECLARE_CONST_FUN_OBJ_KW(pyb_main_obj); // defined in main.c STATIC const mp_map_elem_t pyb_module_globals_table[] = { { MP_OBJ_NEW_QSTR(MP_QSTR___name__), MP_OBJ_NEW_QSTR(MP_QSTR_pyb) }, + { MP_OBJ_NEW_QSTR(MP_QSTR_fault_debug), (mp_obj_t)&pyb_fault_debug_obj }, + { MP_OBJ_NEW_QSTR(MP_QSTR_bootloader), (mp_obj_t)&machine_bootloader_obj }, { MP_OBJ_NEW_QSTR(MP_QSTR_hard_reset), (mp_obj_t)&machine_reset_obj }, { MP_OBJ_NEW_QSTR(MP_QSTR_info), (mp_obj_t)&machine_info_obj }, diff --git a/stmhal/stm32_it.c b/stmhal/stm32_it.c index 245b2ade4..4152050a9 100644 --- a/stmhal/stm32_it.c +++ b/stmhal/stm32_it.c @@ -71,6 +71,7 @@ #include STM32_HAL_H #include "py/obj.h" +#include "py/mphal.h" #include "pendsv.h" #include "irq.h" #include "pybthread.h" @@ -95,11 +96,6 @@ extern PCD_HandleTypeDef pcd_hs_handle; // Set the following to 1 to get some more information on the Hard Fault // More information about decoding the fault registers can be found here: // http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.dui0646a/Cihdjcfc.html -#define REPORT_HARD_FAULT_REGS 0 - -#if REPORT_HARD_FAULT_REGS - -#include "py/mphal.h" STATIC char *fmt_hex(uint32_t val, char *buf) { const char *hexDig = "0123456789abcdef"; @@ -142,7 +138,13 @@ typedef struct { uint32_t r0, r1, r2, r3, r12, lr, pc, xpsr; } ExceptionRegisters_t; +int pyb_hard_fault_debug = 0; + void HardFault_C_Handler(ExceptionRegisters_t *regs) { + if (!pyb_hard_fault_debug) { + NVIC_SystemReset(); + } + // We need to disable the USB so it doesn't try to write data out on // the VCP and then block indefinitely waiting for the buffer to drain. pyb_usb_flags = 0; @@ -209,14 +211,6 @@ void HardFault_Handler(void) { " b HardFault_C_Handler \n" // Off to C land ); } -#else -void HardFault_Handler(void) { - /* Go to infinite loop when Hard Fault exception occurs */ - while (1) { - __fatal_error("HardFault"); - } -} -#endif // REPORT_HARD_FAULT_REGS /** * @brief This function handles NMI exception. diff --git a/stmhal/stm32_it.h b/stmhal/stm32_it.h index fc61d57be..a168cda83 100644 --- a/stmhal/stm32_it.h +++ b/stmhal/stm32_it.h @@ -63,6 +63,8 @@ ****************************************************************************** */ +extern int pyb_hard_fault_debug; + void NMI_Handler(void); void HardFault_Handler(void); void MemManage_Handler(void); diff --git a/tests/pyb/pyb1.py b/tests/pyb/pyb1.py index 0087ec050..00adc8553 100644 --- a/tests/pyb/pyb1.py +++ b/tests/pyb/pyb1.py @@ -40,3 +40,6 @@ pyb.sync() print(len(pyb.unique_id())) pyb.wfi() + +pyb.fault_debug(True) +pyb.fault_debug(False) -- cgit v1.2.3 From 9779c99317f229435c07f11fd18223956de77b41 Mon Sep 17 00:00:00 2001 From: Damien George Date: Tue, 7 Feb 2017 12:35:39 +1100 Subject: stmhal: Add ability to skip booting from SD card via /flash/SKIPSD file. --- docs/pyboard/general.rst | 5 +++++ stmhal/main.c | 5 ++++- 2 files changed, 9 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/pyboard/general.rst b/docs/pyboard/general.rst index 107bae69a..48e014644 100644 --- a/docs/pyboard/general.rst +++ b/docs/pyboard/general.rst @@ -11,6 +11,11 @@ is inserted into the slot, it is available as ``/sd``. When the pyboard boots up, it needs to choose a filesystem to boot from. If there is no SD card, then it uses the internal filesystem ``/flash`` as the boot filesystem, otherwise, it uses the SD card ``/sd``. +If needed, you can prevent the use of the SD card by creating an empty file +called ``/flash/SKIPSD``. If this file exists when the pyboard boots +up then the SD card will be skipped and the pyboard will always boot from the +internal filesystem (in this case the SD card won't be mounted but you can still +mount and use it later in your program using ``os.mount``). (Note that on older versions of the board, ``/flash`` is called ``0:/`` and ``/sd`` is called ``1:/``). diff --git a/stmhal/main.c b/stmhal/main.c index 7bf6f6a3a..7bfdc52c3 100644 --- a/stmhal/main.c +++ b/stmhal/main.c @@ -568,7 +568,10 @@ soft_reset: #if MICROPY_HW_HAS_SDCARD // if an SD card is present then mount it on /sd/ if (sdcard_is_present()) { - mounted_sdcard = init_sdcard_fs(first_soft_reset); + // if there is a file in the flash called "SKIPSD", then we don't mount the SD card + if (!mounted_flash || f_stat(&fs_user_mount_flash.fatfs, "/SKIPSD", NULL) != FR_OK) { + mounted_sdcard = init_sdcard_fs(first_soft_reset); + } } #endif -- cgit v1.2.3 From 3217bbe4910416b9084691ea5ff1ec1530e15ee4 Mon Sep 17 00:00:00 2001 From: Damien George Date: Tue, 7 Feb 2017 16:58:43 +1100 Subject: docs/esp8266/tutorial: Specify the baudrate in picocom example command. --- docs/esp8266/tutorial/repl.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/esp8266/tutorial/repl.rst b/docs/esp8266/tutorial/repl.rst index 1922da128..21e889c9a 100644 --- a/docs/esp8266/tutorial/repl.rst +++ b/docs/esp8266/tutorial/repl.rst @@ -24,7 +24,7 @@ terminal programs that will work, so pick your favourite! For example, on Linux you can try running:: - picocom /dev/ttyUSB0 + picocom /dev/ttyUSB0 -b115200 Once you have made the connection over the serial port you can test if it is working by hitting enter a few times. You should see the Python REPL prompt, -- cgit v1.2.3 From 21f08524baf11e62384814b7cb8fcd2b5a8998fb Mon Sep 17 00:00:00 2001 From: Damien George Date: Tue, 7 Feb 2017 20:04:40 +1100 Subject: docs: Add M-logo as favicon. --- docs/conf.py | 2 +- docs/static/favicon.ico | Bin 0 -> 1406 bytes 2 files changed, 1 insertion(+), 1 deletion(-) create mode 100644 docs/static/favicon.ico (limited to 'docs') diff --git a/docs/conf.py b/docs/conf.py index 1a552be2e..66ea325e9 100755 --- a/docs/conf.py +++ b/docs/conf.py @@ -178,7 +178,7 @@ else: # The name of an image file (within the static path) to use as favicon of the # docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 # pixels large. -#html_favicon = None +html_favicon = 'favicon.ico' # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, diff --git a/docs/static/favicon.ico b/docs/static/favicon.ico new file mode 100644 index 000000000..49c615414 Binary files /dev/null and b/docs/static/favicon.ico differ -- cgit v1.2.3 From 2f76c3ca0ad809e26f12722192e6fbdeab317566 Mon Sep 17 00:00:00 2001 From: Dave Hylands Date: Sat, 11 Feb 2017 09:39:39 -0800 Subject: docs/library/pyb.Pin: Minor typo fix, B6 should be A0. On the PYBv1.0, X1 maps to A0, not B6. --- docs/library/pyb.Pin.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/library/pyb.Pin.rst b/docs/library/pyb.Pin.rst index 4f589fff8..b766c5280 100644 --- a/docs/library/pyb.Pin.rst +++ b/docs/library/pyb.Pin.rst @@ -21,7 +21,7 @@ Usage Model: CPU pins which correspond to the board pins are available as ``pyb.cpu.Name``. For the CPU pins, the names are the port letter followed by the pin number. On the PYBv1.0, ``pyb.Pin.board.X1`` and - ``pyb.Pin.cpu.B6`` are the same pin. + ``pyb.Pin.cpu.A0`` are the same pin. You can also use strings:: -- cgit v1.2.3 From 0c821f7def92a2f461a440c210cd5944707d4244 Mon Sep 17 00:00:00 2001 From: Damien George Date: Mon, 13 Feb 2017 13:06:51 +1100 Subject: docs/library/machine: Make separate TOC for WiPy vs non-WiPy. WiPy is the only port with ADC and SD, so they shouldn't be included in other ports' documentation. --- docs/library/machine.rst | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/library/machine.rst b/docs/library/machine.rst index c6da71585..50884e7be 100644 --- a/docs/library/machine.rst +++ b/docs/library/machine.rst @@ -156,7 +156,22 @@ Constants Classes ------- -.. toctree:: +.. only:: not port_wipy + + .. toctree:: + :maxdepth: 1 + + machine.I2C.rst + machine.Pin.rst + machine.RTC.rst + machine.SPI.rst + machine.Timer.rst + machine.UART.rst + machine.WDT.rst + +.. only:: port_wipy + + .. toctree:: :maxdepth: 1 machine.ADC.rst -- cgit v1.2.3 From ee3615d80022d1b5e5c0fdca466f20e50f07e63c Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Tue, 14 Feb 2017 13:14:46 +0300 Subject: docs/uos: Remove mention of uos.sep. MicroPython guarantees '/' to be a path separator, so extra constant taking precious ROM space are not needed. MicroPython never had such constant, only one vendor port had it (now unmaintained). --- docs/library/uos.rst | 7 ------- 1 file changed, 7 deletions(-) (limited to 'docs') diff --git a/docs/library/uos.rst b/docs/library/uos.rst index 242e8c3d0..cd0c5cae8 100644 --- a/docs/library/uos.rst +++ b/docs/library/uos.rst @@ -116,10 +116,3 @@ Functions Duplicate the terminal (the REPL) on the passed stream-like object. The given object must at least implement the ``.read()`` and ``.write()`` methods. - -Constants ---------- - -.. data:: sep - - separation character used in paths -- cgit v1.2.3 From d80df91ef2818ccef3185c9ecffcc8c396cc7d9f Mon Sep 17 00:00:00 2001 From: Damien George Date: Fri, 17 Feb 2017 16:57:22 +1100 Subject: docs/library/lcd160cr: Mention the valid values for set_power() method. --- docs/library/lcd160cr.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/library/lcd160cr.rst b/docs/library/lcd160cr.rst index 39f492fc4..56af097a1 100644 --- a/docs/library/lcd160cr.rst +++ b/docs/library/lcd160cr.rst @@ -103,7 +103,8 @@ Setup commands .. method:: LCD160CR.set_power(on) - Turn the display on or off, depending on the given value. + Turn the display on or off, depending on the given value of `on`: 0 or `False` + will turn the display off, and 1 or `True` will turn it on. .. method:: LCD160CR.set_orient(orient) -- cgit v1.2.3 From b7fa63c7ced460fd2d3aceb35257a62ff08831c1 Mon Sep 17 00:00:00 2001 From: Rami Ali Date: Tue, 7 Feb 2017 16:43:41 +1100 Subject: tools: Add gen-cpydiff.py to generate docs differences. This patch introduces the a small framework to track differences between uPy and CPython. The framework consists of: - A set of "tests" which test for an individual feature that differs between uPy and CPy. Each test is like a normal uPy test in the test suite, but has a special comment at the start with some meta-data: a category (eg syntax, core language), a human-readable description of the difference, a cause, and a workaround. Following the meta-data there is a short code snippet which demonstrates the difference. See tests/cpydiff directory for the initial set of tests. - A program (this patch) which runs all the tests (on uPy and CPy) and generates nicely-formated .rst documenting the differences. - Integration into the docs build so that everything is automatic, and the differences appear in a way that is easy for users to read/reference (see latter commits). The idea with using this new framework is: - When a new difference is found it's easy to write a short test for it, along with a description, and add it to the existing ones. It's also easy for contributors to submit tests for differences they find. - When something is no longer different the tool will give an error and difference can be removed (or promoted to a proper feature test). --- docs/differences/index_template.txt | 8 ++ tools/gen-cpydiff.py | 213 ++++++++++++++++++++++++++++++++++++ 2 files changed, 221 insertions(+) create mode 100644 docs/differences/index_template.txt create mode 100644 tools/gen-cpydiff.py (limited to 'docs') diff --git a/docs/differences/index_template.txt b/docs/differences/index_template.txt new file mode 100644 index 000000000..6ade2c2da --- /dev/null +++ b/docs/differences/index_template.txt @@ -0,0 +1,8 @@ +MicroPython Differences from CPython +==================================== + +The operations listed in this section produce conflicting results in MicroPython when compared to standard Python. + +.. toctree:: + :maxdepth: 2 + diff --git a/tools/gen-cpydiff.py b/tools/gen-cpydiff.py new file mode 100644 index 000000000..6f83bb6e8 --- /dev/null +++ b/tools/gen-cpydiff.py @@ -0,0 +1,213 @@ +# This file is part of the MicroPython project, http://micropython.org/ +# +# The MIT License (MIT) +# +# Copyright (c) 2016 Rami Ali +# +# Permission is hereby granted, free of charge, to any person obtaining a copy +# of this software and associated documentation files (the "Software"), to deal +# in the Software without restriction, including without limitation the rights +# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +# copies of the Software, and to permit persons to whom the Software is +# furnished to do so, subject to the following conditions: +# +# The above copyright notice and this permission notice shall be included in +# all copies or substantial portions of the Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +# THE SOFTWARE. + +""" gen-cpydiff generates documentation which outlines operations that differ between MicroPython + and CPython. This script is called by the docs Makefile for html and Latex and may be run + manually using the command make gen-cpydiff. """ + +import os +import errno +import subprocess +import time +import re +from collections import namedtuple + +TESTPATH = '../tests/cpydiff/' +UPYPATH = '../unix/micropython' +DOCPATH = '../docs/genrst/' +INDEXTEMPLATE = '../docs/differences/index_template.txt' +INDEX = 'index.rst' + +HEADER = '.. This document was generated by tools/gen-cpydiff.py\n\n' +UIMPORTLIST = {'struct', 'collections', 'json'} +CLASSMAP = {'Core': 'Core Language', 'Types': 'Builtin Types'} +INDEXPRIORITY = ['syntax', 'core_language', 'builtin_types', 'modules'] +RSTCHARS = ['=', '-', '~', '`', ':'] +SPLIT = '"""\n|categories: |description: |cause: |workaround: ' +TAB = ' ' + +Output = namedtuple('output', ['name', 'class_', 'desc', 'cause', 'workaround', 'code', + 'output_cpy', 'output_upy', 'status']) + +def readfiles(): + """ Reads test files """ + tests = list(filter(lambda x: x.endswith('.py'), os.listdir(TESTPATH))) + tests.sort() + files = [] + + for test in tests: + text = open(TESTPATH + test, 'r').read() + + try: + class_, desc, cause, workaround, code = [x.rstrip() for x in \ + list(filter(None, re.split(SPLIT, text)))] + output = Output(test, class_, desc, cause, workaround, code, '', '', '') + files.append(output) + except IndexError: + print('Incorrect format in file ' + TESTPATH + test) + + return files + +def uimports(code): + """ converts CPython module names into MicroPython equivalents """ + for uimport in UIMPORTLIST: + uimport = bytes(uimport, 'utf8') + code = code.replace(uimport, b'u' + uimport) + return code + +def run_tests(tests): + """ executes all tests """ + results = [] + for test in tests: + with open(TESTPATH + test.name, 'rb') as f: + input_cpy = f.read() + input_upy = uimports(input_cpy) + + process = subprocess.Popen('python', shell=True, stdout=subprocess.PIPE, stdin=subprocess.PIPE, stderr=subprocess.PIPE) + output_cpy = [com.decode('utf8') for com in process.communicate(input_cpy)] + + process = subprocess.Popen(UPYPATH, shell=True, stdout=subprocess.PIPE, stdin=subprocess.PIPE, stderr=subprocess.PIPE) + output_upy = [com.decode('utf8') for com in process.communicate(input_upy)] + + if output_cpy[0] == output_upy[0] and output_cpy[1] == output_upy[1]: + status = 'Supported' + print('Supported operation!\nFile: ' + TESTPATH + test.name) + else: + status = 'Unsupported' + + output = Output(test.name, test.class_, test.desc, test.cause, + test.workaround, test.code, output_cpy, output_upy, status) + results.append(output) + + results.sort(key=lambda x: x.class_) + return results + +def indent(block, spaces): + """ indents paragraphs of text for rst formatting """ + new_block = '' + for line in block.split('\n'): + new_block += spaces + line + '\n' + return new_block + +def gen_table(contents): + """ creates a table given any set of columns """ + xlengths = [] + ylengths = [] + for column in contents: + col_len = 0 + for entry in column: + lines = entry.split('\n') + for line in lines: + col_len = max(len(line) + 2, col_len) + xlengths.append(col_len) + for i in range(len(contents[0])): + ymax = 0 + for j in range(len(contents)): + ymax = max(ymax, len(contents[j][i].split('\n'))) + ylengths.append(ymax) + + table_divider = '+' + ''.join(['-' * i + '+' for i in xlengths]) + '\n' + table = table_divider + for i in range(len(ylengths)): + row = [column[i] for column in contents] + row = [entry + '\n' * (ylengths[i]-len(entry.split('\n'))) for entry in row] + row = [entry.split('\n') for entry in row] + for j in range(ylengths[i]): + k = 0 + for entry in row: + width = xlengths[k] + table += ''.join(['| {:{}}'.format(entry[j], width - 1)]) + k += 1 + table += '|\n' + table += table_divider + return table + '\n' + +def gen_rst(results): + """ creates restructured text documents to display tests """ + + # make sure the destination directory exists + try: + os.mkdir(DOCPATH) + except OSError as e: + if e.args[0] != errno.EEXIST and e.args[0] != errno.EISDIR: + raise + + toctree = [] + class_ = [] + for output in results: + section = output.class_.split(',') + for i in range(len(section)): + section[i] = section[i].rstrip() + if section[i] in CLASSMAP: + section[i] = CLASSMAP[section[i]] + if i >= len(class_) or section[i] != class_[i]: + if i == 0: + filename = section[i].replace(' ', '_').lower() + rst = open(DOCPATH + filename + '.rst', 'w') + rst.write(HEADER) + rst.write(section[i] + '\n') + rst.write(RSTCHARS[0] * len(section[i])) + rst.write(time.strftime("\nGenerated %a %d %b %Y %X UTC\n\n", time.gmtime())) + toctree.append(filename) + else: + rst.write(section[i] + '\n') + rst.write(RSTCHARS[min(i, len(RSTCHARS)-1)] * len(section[i])) + rst.write('\n\n') + class_ = section + rst.write('**' + output.desc + '**\n\n') + if output.cause != 'Unknown': + rst.write('**Cause:** ' + output.cause + '\n\n') + if output.workaround != 'Unknown': + rst.write('**Workaround:** ' + output.workaround + '\n\n') + + rst.write('Sample code::\n\n' + indent(output.code, TAB) + '\n') + output_cpy = indent(''.join(output.output_cpy[0:2]), TAB).rstrip() + output_cpy = ('::\n\n' if output_cpy != '' else '') + output_cpy + output_upy = indent(''.join(output.output_upy[0:2]), TAB).rstrip() + output_upy = ('::\n\n' if output_upy != '' else '') + output_upy + table = gen_table([['CPy output:', output_cpy], ['uPy output:', output_upy]]) + rst.write(table) + + template = open(INDEXTEMPLATE, 'r') + index = open(DOCPATH + INDEX, 'w') + index.write(HEADER) + index.write(template.read()) + for section in INDEXPRIORITY: + if section in toctree: + index.write(indent(section + '.rst', TAB)) + toctree.remove(section) + for section in toctree: + index.write(indent(section + '.rst', TAB)) + +def main(): + """ Main function """ + + # clear search path to make sure tests use only builtin modules + os.environ['MICROPYPATH'] = '' + + files = readfiles() + results = run_tests(files) + gen_rst(results) + +main() -- cgit v1.2.3 From 3218ccd70d8f387662987f6c1beb79102288b13d Mon Sep 17 00:00:00 2001 From: Rami Ali Date: Tue, 7 Feb 2017 16:00:34 +1100 Subject: docs: Modify Makefile and indexes to generate cPy-differences pages. --- .gitignore | 4 ++++ docs/Makefile | 18 ++++++++++++++---- docs/esp8266_contents.rst | 1 + docs/esp8266_index.rst | 1 + docs/pyboard_contents.rst | 1 + docs/pyboard_index.rst | 1 + docs/topindex.html | 4 ++++ docs/unix_contents.rst | 1 + docs/unix_index.rst | 1 + docs/wipy_contents.rst | 1 + docs/wipy_index.rst | 1 + 11 files changed, 30 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/.gitignore b/.gitignore index a6295928d..280db388f 100644 --- a/.gitignore +++ b/.gitignore @@ -38,3 +38,7 @@ __pycache__/ ###################### GNUmakefile user.props + +# Generated rst files +###################### +genrst/ diff --git a/docs/Makefile b/docs/Makefile index d81d11eeb..b4e338ad5 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -6,6 +6,9 @@ SPHINXOPTS = SPHINXBUILD = sphinx-build PAPER = BUILDDIR = build/$(MICROPY_PORT) +CPYDIFFDIR = ../tools +CPYDIFF = gen-cpydiff.py +GENRSTDIR = genrst # Run "make FORCE= ..." to avoid rebuilding from scratch (and risk # producing incorrect docs). FORCE = -E @@ -48,11 +51,18 @@ help: @echo " pseudoxml to make pseudoxml-XML files for display purposes" @echo " linkcheck to check all external links for integrity" @echo " doctest to run all doctests embedded in the documentation (if enabled)" + @echo " cpydiff to generate the MicroPython differences from CPython" clean: rm -rf $(BUILDDIR)/* + rm -f $(GENRSTDIR)/* -html: +cpydiff: + @echo "Generating MicroPython Differences." + rm -f $(GENRSTDIR)/* + cd $(CPYDIFFDIR) && python $(CPYDIFF) + +html: cpydiff $(SPHINXBUILD) $(FORCE) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." @@ -106,20 +116,20 @@ epub: @echo @echo "Build finished. The epub file is in $(BUILDDIR)/epub." -latex: +latex: cpydiff $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex @echo @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." @echo "Run \`make' in that directory to run these through (pdf)latex" \ "(use \`make latexpdf' here to do that automatically)." -latexpdf: +latexpdf: cpydiff $(SPHINXBUILD) $(FORCE) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex @echo "Running LaTeX files through pdflatex..." $(MAKE) -C $(BUILDDIR)/latex all-pdf @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." -latexpdfja: +latexpdfja: cpydiff $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex @echo "Running LaTeX files through platex and dvipdfmx..." $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja diff --git a/docs/esp8266_contents.rst b/docs/esp8266_contents.rst index 30def3df2..7c35460bd 100644 --- a/docs/esp8266_contents.rst +++ b/docs/esp8266_contents.rst @@ -8,4 +8,5 @@ MicroPython documentation contents esp8266/tutorial/index.rst library/index.rst reference/index.rst + genrst/index.rst license.rst diff --git a/docs/esp8266_index.rst b/docs/esp8266_index.rst index 82de9d6df..8654c43aa 100644 --- a/docs/esp8266_index.rst +++ b/docs/esp8266_index.rst @@ -5,6 +5,7 @@ MicroPython documentation and references esp8266/quickref.rst library/index.rst + genrst/index.rst license.rst esp8266_contents.rst diff --git a/docs/pyboard_contents.rst b/docs/pyboard_contents.rst index 5ced479ef..658dd366f 100644 --- a/docs/pyboard_contents.rst +++ b/docs/pyboard_contents.rst @@ -9,5 +9,6 @@ MicroPython documentation contents library/index.rst reference/index.rst pyboard/hardware/index.rst + genrst/index.rst license.rst diff --git a/docs/pyboard_index.rst b/docs/pyboard_index.rst index 38ccb1ac9..4caa4cc88 100644 --- a/docs/pyboard_index.rst +++ b/docs/pyboard_index.rst @@ -8,6 +8,7 @@ MicroPython documentation and references pyboard/tutorial/index.rst library/index.rst pyboard/hardware/index.rst + genrst/index.rst license.rst pyboard_contents.rst diff --git a/docs/topindex.html b/docs/topindex.html index 75039233e..3cbf21615 100644 --- a/docs/topindex.html +++ b/docs/topindex.html @@ -47,6 +47,10 @@ MicroPython libraries, including the machine module {% endif %}

+

+ Micropython Differences
+ MicroPython operations which differ from CPython +

diff --git a/docs/unix_contents.rst b/docs/unix_contents.rst index ec0a6f0e8..8c5a586b2 100644 --- a/docs/unix_contents.rst +++ b/docs/unix_contents.rst @@ -5,4 +5,5 @@ MicroPython documentation contents library/index.rst reference/index.rst + genrst/index.rst license.rst diff --git a/docs/unix_index.rst b/docs/unix_index.rst index 027f24c2e..7fa1753c2 100644 --- a/docs/unix_index.rst +++ b/docs/unix_index.rst @@ -4,6 +4,7 @@ MicroPython documentation and references .. toctree:: library/index.rst + genrst/index.rst license.rst unix_contents.rst diff --git a/docs/wipy_contents.rst b/docs/wipy_contents.rst index 2beffa236..0e50a7c6e 100644 --- a/docs/wipy_contents.rst +++ b/docs/wipy_contents.rst @@ -8,4 +8,5 @@ MicroPython documentation contents wipy/tutorial/index.rst library/index.rst reference/index.rst + genrst/index.rst license.rst diff --git a/docs/wipy_index.rst b/docs/wipy_index.rst index 9fe3dce89..a390aecb1 100644 --- a/docs/wipy_index.rst +++ b/docs/wipy_index.rst @@ -7,6 +7,7 @@ MicroPython documentation and references wipy/general.rst wipy/tutorial/index.rst library/index.rst + genrst/index.rst license.rst wipy_contents.rst -- cgit v1.2.3 From e2f1a8a7ee7b0a48ceb7a38bf0eff016234914a0 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Sun, 26 Feb 2017 00:55:33 +0300 Subject: docs/uhashlib: Provide port-neutral description. TODO: Remove WiPy-specific chunks. --- docs/library/uhashlib.rst | 52 +++++++++++++++++++++++++---------------------- 1 file changed, 28 insertions(+), 24 deletions(-) (limited to 'docs') diff --git a/docs/library/uhashlib.rst b/docs/library/uhashlib.rst index 223c72dfe..2c340e40b 100644 --- a/docs/library/uhashlib.rst +++ b/docs/library/uhashlib.rst @@ -1,33 +1,41 @@ -:mod:`uhashlib` -- hashing algorithm -==================================== +:mod:`uhashlib` -- hashing algorithms +===================================== .. module:: uhashlib - :synopsis: hashing algorithm + :synopsis: hashing algorithms -.. only:: port_pyboard +This module implements binary data hashing algorithms. The exact inventory +of available algorithms depends on a board. Among the algorithms which may +be implemented: - This module implements binary data hashing algorithms. Currently, it - implements SHA256 algorithm. Choosing SHA256 was a deliberate choice, - as a modern, cryptographically secure algorithm. This means that a - single algorithm can cover both use cases of "any hash algorithm" and - security-related usage, and thus save space omitting legacy algorithms - like MD5 or SHA1. +* SHA256 - The current generation, modern hashing algorithm (of SHA2 series). + It is suitable for cryptographically-secure purposes. Included in the + MicroPython core and any board is recommended to provide this, unless + it has particular code size constraints. -.. only:: port_wipy - - This module implements binary data hashing algorithms. Currently, it - implements SHA1 and SHA256 algorithms only. These two algorithms are - more than enough for today's web applications. +* SHA1 - A previous generation algorithm. Not recommended for new usages, + but SHA1 is a part of number of Internet standards and existing + applications, so boards targetting network connectivity and + interoperatiability will try to provide this. +* MD5 - A legacy algorithm, not considered cryptographically secure. Only + selected boards, targetting interoperatibility with legacy applications, + will offer this. Constructors ------------ -.. only:: port_pyboard +.. class:: uhashlib.sha256([data]) - .. class:: uhashlib.sha256([data]) - - Create a hasher object and optionally feed ``data`` into it. + Create an SHA256 hasher object and optionally feed ``data`` into it. + +.. class:: uhashlib.sha1([data]) + + Create an SHA1 hasher object and optionally feed ``data`` into it. + +.. class:: uhashlib.md5([data]) + + Create an MD5 hasher object and optionally feed ``data`` into it. .. only:: port_wipy @@ -69,11 +77,7 @@ Methods .. method:: hash.digest() Return hash for all data passed through hash, as a bytes object. After this - method is called, more data cannot be fed into hash any longer. - - .. only:: port_wipy - - SHA1 hashes are 20-byte long. SHA256 hashes are 32-byte long. + method is called, more data cannot be fed into the hash any longer. .. method:: hash.hexdigest() -- cgit v1.2.3 From ae116c2430f9c990dcf619f4b8f90b2fc0c18984 Mon Sep 17 00:00:00 2001 From: Krzysztof Blazewicz Date: Sat, 25 Feb 2017 13:50:19 +0100 Subject: docs/Makefile: define and use PYTHON as the interpreter for CPYDIFF User can override PYTHON executable before running script, gen-cpydiff.py works only with Python3 and most systems register its executable as 'python3'. --- docs/Makefile | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/Makefile b/docs/Makefile index b4e338ad5..e9c128e90 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -2,6 +2,7 @@ # # You can set these variables from the command line. +PYTHON = python3 SPHINXOPTS = SPHINXBUILD = sphinx-build PAPER = @@ -60,7 +61,7 @@ clean: cpydiff: @echo "Generating MicroPython Differences." rm -f $(GENRSTDIR)/* - cd $(CPYDIFFDIR) && python $(CPYDIFF) + cd $(CPYDIFFDIR) && $(PYTHON) $(CPYDIFF) html: cpydiff $(SPHINXBUILD) $(FORCE) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html -- cgit v1.2.3 From ed81574fe9f8f011db2f119d29767380eac2ec14 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Tue, 28 Feb 2017 00:38:15 +0300 Subject: docs/machine: Fix formatting of Constants section. Render related constants grouped together, with common description. --- docs/library/machine.rst | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) (limited to 'docs') diff --git a/docs/library/machine.rst b/docs/library/machine.rst index 50884e7be..c677bcbf0 100644 --- a/docs/library/machine.rst +++ b/docs/library/machine.rst @@ -134,24 +134,24 @@ Constants --------- .. data:: machine.IDLE -.. data:: machine.SLEEP -.. data:: machine.DEEPSLEEP + machine.SLEEP + machine.DEEPSLEEP - irq wake values + IRQ wake values. .. data:: machine.PWRON_RESET -.. data:: machine.HARD_RESET -.. data:: machine.WDT_RESET -.. data:: machine.DEEPSLEEP_RESET -.. data:: machine.SOFT_RESET + machine.HARD_RESET + machine.WDT_RESET + machine.DEEPSLEEP_RESET + machine.SOFT_RESET - reset causes + Reset causes. .. data:: machine.WLAN_WAKE -.. data:: machine.PIN_WAKE -.. data:: machine.RTC_WAKE + machine.PIN_WAKE + machine.RTC_WAKE - wake reasons + Wake-up reasons. Classes ------- -- cgit v1.2.3 From 1f549a3496ac543390a170a7eb7b242475063016 Mon Sep 17 00:00:00 2001 From: Peter Hinch Date: Mon, 27 Feb 2017 07:32:37 +0000 Subject: docs/library/lcd160cr: Add note about supported JPEG format/encodings. --- docs/library/lcd160cr.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/library/lcd160cr.rst b/docs/library/lcd160cr.rst index 56af097a1..a04f39882 100644 --- a/docs/library/lcd160cr.rst +++ b/docs/library/lcd160cr.rst @@ -341,7 +341,9 @@ Advanced commands .. method:: LCD160CR.jpeg(buf) - Display a JPEG. `buf` should contain the entire JPEG data. + Display a JPEG. `buf` should contain the entire JPEG data. JPEG data should + not include EXIF information. The following encodings are supported: Baseline + DCT, Huffman coding, 8 bits per sample, 3 color components, YCbCr4:2:2. The origin of the JPEG is set by :meth:`LCD160CR.set_pos`. .. method:: LCD160CR.jpeg_start(total_len) -- cgit v1.2.3 From f9d18d96b7dcd8be718aa3d35ec7626a0cd2e0ff Mon Sep 17 00:00:00 2001 From: Rami Ali Date: Mon, 27 Feb 2017 17:16:32 +1100 Subject: docs/library: Add framebuf documentation. --- docs/library/framebuf.rst | 129 ++++++++++++++++++++++++++++++++++++++++++++++ docs/library/index.rst | 1 + 2 files changed, 130 insertions(+) create mode 100644 docs/library/framebuf.rst (limited to 'docs') diff --git a/docs/library/framebuf.rst b/docs/library/framebuf.rst new file mode 100644 index 000000000..657ad461b --- /dev/null +++ b/docs/library/framebuf.rst @@ -0,0 +1,129 @@ +:mod:`framebuf` --- Frame buffer manipulation +============================================= + +.. module:: framebuf + :synopsis: Frame buffer manipulation + +This module provides a general frame buffer which can be used to create +bitmap images, which can then be sent to a display. + +class FrameBuffer +----------------- + +The FrameBuffer class provides a pixel buffer which can be drawn upon with +pixels, lines, rectangles, text and even other FrameBuffer's. It is useful +when generating output for displays. + +For example:: + + import framebuf + + # FrameBuffer needs 2 bytes for every RGB565 pixel + fbuf = FrameBuffer(bytearray(10 * 100 * 2), 10, 100, framebuf.RGB565) + + fbuf.fill(0) + fbuf.text('MicroPython!', 0, 0, 0xffff) + fbuf.hline(0, 10, 96, 0xffff) + +Constructors +------------ + +.. class:: FrameBuffer(buffer, width, height, format, stride=width) + + Construct a FrameBuffer object. The parameters are: + + - `buffer` is an object with a buffer protocol which must be large + enough to contain every pixel defined by the width, height and + format of the FrameBuffer. + - `width` is the width of the FrameBuffer in pixels + - `height` is the height of the FrameBuffer in pixels + - `format` specifies the type of pixel used in the FrameBuffer; + valid values are ``framebuf.MVLSB``, ``framebuf.RGB565`` + and ``framebuf.GS4_HMSB``. MVLSB is monochrome 8-bit color, + RGB565 is RGB 16-bit color, and GS4_HMSB is grayscale 4-bit color. + Where a color value c is passed to a method, c is a small integer + with an encoding that is dependent on the format of the FrameBuffer. + - `stride` is the number of pixels between each horizontal line + of pixels in the FrameBuffer. This defaults to `width` but may + need adjustments when implementing a FrameBuffer within another + larger FrameBuffer or screen. The `buffer` size must accommodate + an increased step size. + + One must specify valid `buffer`, `width`, `height`, `format` and + optionally `stride`. Invalid `buffer` size or dimensions may lead to + unexpected errors. + +Drawing primitive shapes +------------------------ + +The following methods draw shapes onto the FrameBuffer. + +.. method:: FrameBuffer.fill(c) + + Fill the entire FrameBuffer with the specified color. + +.. method:: FrameBuffer.pixel(x, y[, c]) + + If `c` is not given, get the color value of the specified pixel. + If `c` is given, set the specified pixel to the given color. + +.. method:: FrameBuffer.hline(x, y, w, c) +.. method:: FrameBuffer.vline(x, y, h, c) +.. method:: FrameBuffer.line(x1, y1, x2, y2, c) + + Draw a line from a set of coordinates using the given color and + a thickness of 1 pixel. The `line` method draws the line up to + a second set of coordinates whereas the `hline` and `vline` + methods draw horizontal and vertical lines respectively up to + a given length. + +.. method:: FrameBuffer.rect(x, y, w, h, c) +.. method:: FrameBuffer.fill_rect(x, y, w, h, c) + + Draw a rectangle at the given location, size and color. The `rect` + method draws only a 1 pixel outline whereas the `fill_rect` method + draws both the outline and interior. + +Drawing text +------------ + +.. method:: FrameBuffer.text(s, x, y[, c]) + + Write text to the FrameBuffer using the the coordinates as the upper-left + corner of the text. The color of the text can be defined by the optional + argument but is otherwise a default value of 1. All characters have + dimensions of 8x8 pixels and there is currently no way to change the font. + + +Other methods +------------- + +.. method:: FrameBuffer.scroll(xstep, ystep) + + Shift the contents of the FrameBuffer by the given vector. This may + leave a footprint of the previous colors in the FrameBuffer. + +.. method:: FrameBuffer.blit(fbuf, x, y[, key]) + + Draw another FrameBuffer on top of the current one at the given coordinates. + If `key` is specified then it should be a color integer and the + corresponding color will be considered transparent: all pixels with that + color value will not be drawn. + + This method works between FrameBuffer's utilising different formats, but the + resulting colors may be unexpected due to the mismatch in color formats. + +Constants +--------- + +.. data:: framebuf.MVLSB + + Monochrome (1-bit) color format + +.. data:: framebuf.RGB565 + + Red Green Blue (16-bit, 5+6+5) color format + +.. data:: framebuf.GS4_HMSB + + Grayscale (4-bit) color format diff --git a/docs/library/index.rst b/docs/library/index.rst index a110ef0d2..5d64d01f7 100644 --- a/docs/library/index.rst +++ b/docs/library/index.rst @@ -153,6 +153,7 @@ the following libraries. .. toctree:: :maxdepth: 1 + framebuf.rst machine.rst micropython.rst network.rst -- cgit v1.2.3 From 2646b9e0224a9d41932f8d8b819897b4482bbc3b Mon Sep 17 00:00:00 2001 From: Rami Ali Date: Mon, 27 Feb 2017 17:17:45 +1100 Subject: docs/library/lcd160cr: Add link to framebuf page. --- docs/library/lcd160cr.rst | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs') diff --git a/docs/library/lcd160cr.rst b/docs/library/lcd160cr.rst index a04f39882..76828d32d 100644 --- a/docs/library/lcd160cr.rst +++ b/docs/library/lcd160cr.rst @@ -304,6 +304,10 @@ Advanced commands the 16-bit RGB values for the pixels, and they will be written to the area specified by :meth:`LCD160CR.set_spi_win`, starting from the top-left corner. + The `framebuf `_ module can be used to construct frame buffers + and provides drawing primitives. Using a frame buffer will improve + performance of animations when compared to drawing directly to the screen. + .. method:: LCD160CR.set_scroll(on) Turn scrolling on or off. This controls globally whether any window regions will -- cgit v1.2.3 From e73a0b944fbb391f314e7f64ec49e503d53d179a Mon Sep 17 00:00:00 2001 From: James Ouyang Date: Fri, 17 Feb 2017 15:01:13 -0800 Subject: docs/esp8266/tutorial: Update since esptool 1.3 added Python 3 support. esptool 1.3 now supports both Python 2.7 and 3.4+. Updated github link to now-official espressif repo. --- docs/esp8266/tutorial/intro.rst | 24 ++++++++++++++---------- 1 file changed, 14 insertions(+), 10 deletions(-) (limited to 'docs') diff --git a/docs/esp8266/tutorial/intro.rst b/docs/esp8266/tutorial/intro.rst index fe824cfff..e7a38d3e5 100644 --- a/docs/esp8266/tutorial/intro.rst +++ b/docs/esp8266/tutorial/intro.rst @@ -72,15 +72,17 @@ For best results it is recommended to first erase the entire flash of your device before putting on new MicroPython firmware. Currently we only support esptool.py to copy across the firmware. You can find -this tool here: ``__, or install it -using pip (at least version 1.2.1 is required):: +this tool here: ``__, or install it +using pip:: pip install esptool -It requires Python 2.7, so you may need to use ``pip2`` instead of ``pip`` in -the command above. Any other -flashing program should work, so feel free to try them out, or refer to the -documentation for your board to see its recommendations. +Versions starting with 1.3 support both Python 2.7 and Python 3.4 (or newer). +An older version (at least 1.2.1 is needed) works fine but will require Python +2.7. + +Any other flashing program should work, so feel free to try them out or refer +to the documentation for your board to see its recommendations. Using esptool.py you can erase the flash with the command:: @@ -88,7 +90,7 @@ Using esptool.py you can erase the flash with the command:: And then deploy the new firmware using:: - esptool.py --port /dev/ttyUSB0 --baud 460800 write_flash --flash_size=detect 0 esp8266-2016-05-03-v1.8.bin + esptool.py --port /dev/ttyUSB0 --baud 460800 write_flash --flash_size=detect 0 esp8266-20170108-v1.8.7.bin You might need to change the "port" setting to something else relevant for your PC. You may also need to reduce the baudrate if you get errors when flashing @@ -99,7 +101,7 @@ For some boards with a particular FlashROM configuration (e.g. some variants of a NodeMCU board) you may need to use the following command to deploy the firmware (note the ``-fm dio`` option):: - esptool.py --port /dev/ttyUSB0 --baud 460800 write_flash --flash_size=detect -fm dio 0 esp8266-2016-05-03-v1.8.bin + esptool.py --port /dev/ttyUSB0 --baud 460800 write_flash --flash_size=detect -fm dio 0 esp8266-20170108-v1.8.7.bin If the above commands run without error then MicroPython should be installed on your board! @@ -158,7 +160,9 @@ after it, here are troubleshooting recommendations: esptool.py, which had a different programming algorithm:: pip install esptool==1.0.1 This version doesn't support ``--flash_size=detect`` option, so you will - need to specify FlashROM size explicitly (in megabits). + need to specify FlashROM size explicitly (in megabits). It also requires + Python 2.7, so you may need to use ``pip2`` instead of ``pip`` in the + command above. * The ``--flash_size`` option in the commands above is mandatory. Omitting it will lead to a corrupted firmware. @@ -179,7 +183,7 @@ after it, here are troubleshooting recommendations: application in the ESP8266 community. * If you still experience problems with even flashing the firmware, please - refer to esptool.py project page, https://github.com/themadinventor/esptool + refer to esptool.py project page, https://github.com/espressif/esptool for additional documentation and bug tracker where you can report problems. * If you are able to flash firmware, but ``--verify`` option or -- cgit v1.2.3 From fcab4356077435f0f4f9b068acb76e21d6cc20a6 Mon Sep 17 00:00:00 2001 From: Damien George Date: Wed, 15 Mar 2017 21:54:56 +1100 Subject: docs/library/framebuf: Fix typo in bit-width for MVLSB description. --- docs/library/framebuf.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/library/framebuf.rst b/docs/library/framebuf.rst index 657ad461b..91fc362fd 100644 --- a/docs/library/framebuf.rst +++ b/docs/library/framebuf.rst @@ -39,7 +39,7 @@ Constructors - `height` is the height of the FrameBuffer in pixels - `format` specifies the type of pixel used in the FrameBuffer; valid values are ``framebuf.MVLSB``, ``framebuf.RGB565`` - and ``framebuf.GS4_HMSB``. MVLSB is monochrome 8-bit color, + and ``framebuf.GS4_HMSB``. MVLSB is monochrome 1-bit color, RGB565 is RGB 16-bit color, and GS4_HMSB is grayscale 4-bit color. Where a color value c is passed to a method, c is a small integer with an encoding that is dependent on the format of the FrameBuffer. -- cgit v1.2.3 From 9b80a1e3e93e51fdac8a288de58474e4b26efd46 Mon Sep 17 00:00:00 2001 From: Christopher Arndt Date: Sun, 5 Mar 2017 19:56:36 +0100 Subject: utime module documentation fixes and cleanup: * Fix mis-spelling of `ticks_add` in code examples. * Be consistent about parentheses after function names. * Be consistent about formatting of function, variable and constant names. * Be consistent about spaces and punctuation. * Fix some language errors (missing or wrong words, wrong word order). * Keep line length under 90 chars. Signed-off-by: Christopher Arndt --- docs/library/utime.rst | 113 +++++++++++++++++++++++++------------------------ 1 file changed, 58 insertions(+), 55 deletions(-) (limited to 'docs') diff --git a/docs/library/utime.rst b/docs/library/utime.rst index 109c3560c..0b47a036e 100644 --- a/docs/library/utime.rst +++ b/docs/library/utime.rst @@ -58,7 +58,7 @@ Functions .. only:: port_unix or port_pyboard or port_esp8266 .. function:: sleep(seconds) - + Sleep for the given number of seconds. Seconds can be a floating-point number to sleep for a fractional number of seconds. Note that other MicroPython ports may not accept floating-point argument, for compatibility with them use ``sleep_ms()`` @@ -67,32 +67,32 @@ Functions .. only:: port_wipy .. function:: sleep(seconds) - + Sleep for the given number of seconds. .. only:: port_unix or port_pyboard or port_wipy or port_esp8266 - .. function:: sleep_ms(ms) + .. function:: sleep_ms(ms) Delay for given number of milliseconds, should be positive or 0. - .. function:: sleep_us(us) + .. function:: sleep_us(us) - Delay for given number of microseconds, should be positive or 0 + Delay for given number of microseconds, should be positive or 0. - .. function:: ticks_ms() + .. function:: ticks_ms() - Returns an increasing millisecond counter with an arbitrary reference point, - that wraps around after some value. This value is not explicitly exposed, - but we will refer to it as `TICKS_MAX` to simplify discussion. Period of - the values is `TICKS_PERIOD = TICKS_MAX + 1`. `TICKS_PERIOD` is guaranteed - to be a power of two, but otherwise may differ from port to port. The same - period value is used for all of ticks_ms(), ticks_us(), ticks_cpu() functions - (for simplicity). Thus, these functions will return a value in range - [0 .. `TICKS_MAX`], inclusive, total `TICKS_PERIOD` values. Note that only - non-negative values are used. For the most part, you should treat values - returned by these functions as opaque. The only operations available for them - are ``ticks_diff()`` and ``ticks_add()`` functions described below. + Returns an increasing millisecond counter with an arbitrary reference point, that + wraps around after some value. This value is not explicitly exposed, but we will + refer to it as ``TICKS_MAX`` to simplify discussion. Period of the values is + ``TICKS_PERIOD = TICKS_MAX + 1``. ``TICKS_PERIOD`` is guaranteed to be a power of + two, but otherwise may differ from port to port. The same period value is used + for all of ``ticks_ms()``, ``ticks_us()``, ``ticks_cpu()`` functions (for + simplicity). Thus, these functions will return a value in range [``0`` .. + ``TICKS_MAX``], inclusive, total ``TICKS_PERIOD`` values. Note that only + non-negative values are used. For the most part, you should treat values returned + by these functions as opaque. The only operations available for them are + ``ticks_diff()`` and ``ticks_add()`` functions described below. Note: Performing standard mathematical operations (+, -) or relational operators (<, <=, >, >=) directly on these value will lead to invalid @@ -100,15 +100,15 @@ Functions as arguments to ``ticks_diff()`` or ``ticks_add()`` will also lead to invalid results from the latter functions. - .. function:: ticks_us() + .. function:: ticks_us() - Just like ``ticks_ms`` above, but in microseconds. + Just like ``ticks_ms()`` above, but in microseconds. -.. function:: ticks_cpu() +.. function:: ticks_cpu() - Similar to ``ticks_ms`` and ``ticks_us``, but with the highest possible resolution + Similar to ``ticks_ms()`` and ``ticks_us()``, but with the highest possible resolution in the system. This is usually CPU clocks, and that's why the function is named that - way. But it doesn't have to a CPU clock, some other timing source available in a + way. But it doesn't have to be a CPU clock, some other timing source available in a system (e.g. high-resolution timer) can be used instead. The exact timing unit (resolution) of this function is not specified on ``utime`` module level, but documentation for a specific port may provide more specific information. This @@ -118,13 +118,13 @@ Functions Availability: Not every port implements this function. -.. function:: ticks_add(ticks, delta) +.. function:: ticks_add(ticks, delta) Offset ticks value by a given number, which can be either positive or negative. Given a ``ticks`` value, this function allows to calculate ticks value ``delta`` ticks before or after it, following modular-arithmetic definition of tick values (see ``ticks_ms()`` above). ``ticks`` parameter must be a direct result of call - to ``tick_ms()``, ``ticks_us()``, ``ticks_cpu()`` functions (or from previous + to ``ticks_ms()``, ``ticks_us()``, or ``ticks_cpu()`` functions (or from previous call to ``ticks_add()``). However, ``delta`` can be an arbitrary integer number or numeric expression. ``ticks_add()`` is useful for calculating deadlines for events/tasks. (Note: you must use ``ticks_diff()`` function to work with @@ -133,35 +133,37 @@ Functions Examples:: # Find out what ticks value there was 100ms ago - print(tick_add(time.ticks_ms(), -100)) + print(ticks_add(time.ticks_ms(), -100)) # Calculate deadline for operation and test for it - deadline = tick_add(time.ticks_ms(), 200) + deadline = ticks_add(time.ticks_ms(), 200) while ticks_diff(deadline, time.ticks_ms()) > 0: do_a_little_of_something() # Find out TICKS_MAX used by this port - print(tick_add(0, -1)) - - -.. function:: ticks_diff(ticks1, ticks2) - - Measure ticks difference between values returned from ticks_ms(), ticks_us(), or ticks_cpu() - functions. The argument order is the same as for subtraction operator, - ``tick_diff(ticks1, ticks2)`` has the same meaning as ``ticks1 - ticks2``. However, values returned by - ticks_ms(), etc. functions may wrap around, so directly using subtraction on them will - produce incorrect result. That is why ticks_diff() is needed, it implements modular - (or more specifically, ring) arithmetics to produce correct result even for wrap-around - values (as long as they not too distant inbetween, see below). The function returns - **signed** value in the range [`-TICKS_PERIOD/2` .. `TICKS_PERIOD/2-1`] (that's a typical - range definition for two's-complement signed binary integers). If the result is negative, - it means that `ticks1` occured earlier in time than `ticks2`. Otherwise, it means that - `ticks1` occured after `ticks2`. This holds `only` if `ticks1` and `ticks2` are apart from - each other for no more than `TICKS_PERIOD/2-1` ticks. If that does not hold, incorrect - result will be returned. Specifically, if 2 tick values are apart for `TICKS_PERIOD/2-1` - ticks, that value will be returned by the function. However, if `TICKS_PERIOD/2` of - real-time ticks has passed between them, the function will return `-TICKS_PERIOD/2` - instead, i.e. result value will wrap around to the negative range of possible values. + print(ticks_add(0, -1)) + + +.. function:: ticks_diff(ticks1, ticks2) + + Measure ticks difference between values returned from ``ticks_ms()``, ``ticks_us()``, + or ``ticks_cpu()`` functions. The argument order is the same as for subtraction + operator, ``ticks_diff(ticks1, ticks2)`` has the same meaning as ``ticks1 - ticks2``. + However, values returned by ``ticks_ms()``, etc. functions may wrap around, so + directly using subtraction on them will produce incorrect result. That is why + ``ticks_diff()`` is needed, it implements modular (or more specifically, ring) + arithmetics to produce correct result even for wrap-around values (as long as they not + too distant inbetween, see below). The function returns **signed** value in the range + [``-TICKS_PERIOD/2`` .. ``TICKS_PERIOD/2-1``] (that's a typical range definition for + two's-complement signed binary integers). If the result is negative, it means that + ``ticks1`` occured earlier in time than ``ticks2``. Otherwise, it means that + ``ticks1`` occured after ``ticks2``. This holds ``only`` if ``ticks1`` and ``ticks2`` + are apart from each other for no more than ``TICKS_PERIOD/2-1`` ticks. If that does + not hold, incorrect result will be returned. Specifically, if two tick values are + apart for ``TICKS_PERIOD/2-1`` ticks, that value will be returned by the function. + However, if ``TICKS_PERIOD/2`` of real-time ticks has passed between them, the + function will return ``-TICKS_PERIOD/2`` instead, i.e. result value will wrap around + to the negative range of possible values. Informal rationale of the constraints above: Suppose you are locked in a room with no means to monitor passing of time except a standard 12-notch clock. Then if you look at @@ -200,20 +202,21 @@ Functions print("Oops, running late, tell task to run faster!") task.run(run_faster=true) - Note: Do not pass ``time()`` values to ``ticks_diff()``, and should use + Note: Do not pass ``time()`` values to ``ticks_diff()``, you should use normal mathematical operations on them. But note that ``time()`` may (and will) also overflow. This is known as https://en.wikipedia.org/wiki/Year_2038_problem . .. function:: time() - Returns the number of seconds, as an integer, since the Epoch, assuming that underlying - RTC is set and maintained as described above. If an RTC is not set, this function returns - number of seconds since a port-specific reference point in time (for embedded boards without - a battery-backed RTC, usually since power up or reset). If you want to develop portable - MicroPython application, you should not rely on this function to provide higher than second - precision. If you need higher precision, use ``ticks_ms()`` and ``ticks_us()`` functions, - if you need calendar time, ``localtime()`` without an argument is a better choice. + Returns the number of seconds, as an integer, since the Epoch, assuming that + underlying RTC is set and maintained as described above. If an RTC is not set, this + function returns number of seconds since a port-specific reference point in time (for + embedded boards without a battery-backed RTC, usually since power up or reset). If you + want to develop portable MicroPython application, you should not rely on this function + to provide higher than second precision. If you need higher precision, use + ``ticks_ms()`` and ``ticks_us()`` functions, if you need calendar time, + ``localtime()`` without an argument is a better choice. .. admonition:: Difference to CPython :class: attention -- cgit v1.2.3 From fb981107eb6eef3af2b7a6b1c8da53e95c316e86 Mon Sep 17 00:00:00 2001 From: transistortim Date: Sun, 19 Mar 2017 00:09:58 +0100 Subject: docs/library/machine.I2C: Fix scan() doc to match implementation. Since eaef6b5324fa2ff425802d4abeea45aa945bfc14 writes are used instead of reads. --- docs/library/machine.I2C.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/library/machine.I2C.rst b/docs/library/machine.I2C.rst index cdeb246eb..45944709e 100644 --- a/docs/library/machine.I2C.rst +++ b/docs/library/machine.I2C.rst @@ -100,7 +100,7 @@ General Methods 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 - its address (including a read bit) is sent on the bus. + its address (including a write bit) is sent on the bus. Note: on WiPy the I2C object must be in master mode for this method to be valid. -- cgit v1.2.3 From bb296482c385d51f1eb8041e18beb5aa9668637c Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Tue, 4 Apr 2017 00:29:23 +0300 Subject: docs/library/btree: Add btree module docs. --- docs/library/btree.rst | 144 +++++++++++++++++++++++++++++++++++++++++++++++++ docs/library/index.rst | 1 + 2 files changed, 145 insertions(+) create mode 100644 docs/library/btree.rst (limited to 'docs') diff --git a/docs/library/btree.rst b/docs/library/btree.rst new file mode 100644 index 000000000..aebcbc160 --- /dev/null +++ b/docs/library/btree.rst @@ -0,0 +1,144 @@ +:mod:`btree` -- simple BTree database +===================================== + +.. module:: btree + :synopsis: simple BTree database + +The ``btree`` module implements a simple key-value database using external +storage (disk files, or in general case, a random-access stream). Keys are +stored sorted in the database, and besides efficient retrieval by a key +value, a database also supports efficient ordered range scans (retrieval +of values with the keys in a given range). On the application interface +side, BTree database work as close a possible to a way standard `dict` +type works, one notable difference is that both keys and values must +be `bytes` objects (so, if you want to store objects of other types, you +need to serialize them to `bytes` first). + +The module is based on the well-known BerkelyDB library, version 1.xx. + +Example:: + + import btree + + # First, we need to open a stream which holds a database + # This is usually a file, but can be in-memory database + # using uio.BytesIO, a raw flash section, etc. + f = open("mydb", "w+b") + + # Now open a database itself + db = btree.open(f) + + # The keys you add will be sorted internally in the database + db[b"3"] = b"three" + db[b"1"] = b"one" + db[b"2"] = b"two" + + # Prints b'two' + print(db[b"2"]) + + # Iterate over sorted keys in the database, starting from b"2" + # until the end of the database, returning only values. + # Mind that arguments passed to values() method are *key* values. + # Prints: + # b'two' + # b'three' + for word in db.values(b"2"): + print(word) + + del db[b"2"] + + # No longer true, prints False + print(b"2" in db) + + # Prints: + # b"1" + # b"3" + for key in db: + print(key) + + db.close() + + # Don't forget to close the underlying stream! + f.close() + + +Functions +--------- + +.. function:: open(stream, \*, flags=0, cachesize=0, pagesize=0, minkeypage=0) + + Open a database from a random-access `stream` (like an open file). All + other parameters are optional and keyword-only, and allow to tweak advanced + paramters of the database operation (most users will not need them): + + * `flags` - Currently unused. + * `cachesize` - Suggested maximum memory cache size in bytes. For a + board with enough memory using larger values may improve performance. + The value is only a recommendation, the module may use more memory if + values set too low. + * `pagesize` - Page size used for the nodes in BTree. Acceptable range + is 512-65536. If 0, underlying I/O block size will be used (the best + compromise between memory usage and performance). + * `minkeypage` - Minimum number of keys to store per page. Default value + of 0 equivalent to 2. + + Returns a `BTree` object, which implements a dictionary protocol (set + of methods), and some additional methods described below. + +Methods +------- + +.. method:: btree.close() + + Close the database. It's mandatory to close the database at the end of + processing, as some unwritten data may be still in the cache. Note that + this does not close underlying streamw with which the database was opened, + it should be closed separately (which is also mandatory to make sure that + data flushed from buffer to the underlying storage). + +.. method:: btree.flush() + + Flush any data in cache to the underlying stream. + +.. method:: btree.__getitem__(key) +.. method:: btree.get(key, default=None) +.. method:: btree.__setitem__(key, val) +.. method:: btree.__detitem__(key) +.. method:: btree.__contains__(key) + + Standard dictionary methods. + +.. method:: btree.__iter__() + + A BTree object can be iterated over directly (similar to a dictionary) + to get access to all keys in order. + +.. method:: btree.keys([start_key, [end_key, [flags]]]) +.. method:: btree.values([start_key, [end_key, [flags]]]) +.. method:: btree.items([start_key, [end_key, [flags]]]) + + These methods are similar to standard dictionary methods, but also can + take optional parameters to iterate over a key sub-range, instead of + the entire database. Note that for all 3 methods, `start_key` and + `end_key` arguments represent key values. For example, ``values()`` + method will iterate over values corresponding to they key range + given. None values for `start_key` means "from the first key", no + `end_key` or its value of None means "until the end of database". + By default, range is inclusive of `start_key` and exclusive of + `end_key`, you can include `end_key` in iteration by passing `flags` + of `btree.INCL`. You can iterate in descending key direction + by passing `flags` of `btree.DESC`. The flags values can be ORed + together. + +Constants +--------- + +.. data:: INCL + + A flag for `keys()`, `values()`, `items()` methods to specify that + scanning should be inclusive of the end key. + +.. data:: DESC + + A flag for `keys()`, `values()`, `items()` methods to specify that + scanning should be in descending direction of keys. diff --git a/docs/library/index.rst b/docs/library/index.rst index 5d64d01f7..1a61f6882 100644 --- a/docs/library/index.rst +++ b/docs/library/index.rst @@ -153,6 +153,7 @@ the following libraries. .. toctree:: :maxdepth: 1 + btree.rst framebuf.rst machine.rst micropython.rst -- cgit v1.2.3 From 468c6f9da147d6e752e437a32211e317a116b6df Mon Sep 17 00:00:00 2001 From: Peter Hinch Date: Sat, 1 Apr 2017 07:00:09 +0100 Subject: extmod/modframebuf: Make monochrome bitmap formats start with MONO_. MONO_xxx is much easier to read if you're not familiar with the code. MVLSB is deprecated but kept for backwards compatibility, for the time being. This patch also updates the associated docs and tests. --- docs/library/framebuf.rst | 25 ++++++++++++++++++++++++- extmod/modframebuf.c | 5 +++-- tests/extmod/framebuf1.py | 7 ++++--- tests/extmod/framebuf1.py.exp | 7 ++++--- 4 files changed, 35 insertions(+), 9 deletions(-) (limited to 'docs') diff --git a/docs/library/framebuf.rst b/docs/library/framebuf.rst index 91fc362fd..61f0635f3 100644 --- a/docs/library/framebuf.rst +++ b/docs/library/framebuf.rst @@ -116,9 +116,32 @@ Other methods Constants --------- -.. data:: framebuf.MVLSB +.. data:: framebuf.MONO_VLSB Monochrome (1-bit) color format + This defines a mapping where the bits in a byte are vertically mapped with + bit 0 being nearest the top of the screen. Consequently each byte occupies + 8 vertical pixels. Subsequent bytes appear at successive horizontal + locations until the rightmost edge is reached. Further bytes are rendered + at locations starting at the leftmost edge, 8 pixels lower. + +.. data:: framebuf.MONO_HLSB + + Monochrome (1-bit) color format + This defines a mapping where the bits in a byte are horizontally mapped. + Each byte occupies 8 horizontal pixels with bit 0 being the leftmost. + Subsequent bytes appear at successive horizontal locations until the + rightmost edge is reached. Further bytes are rendered on the next row, one + pixel lower. + +.. data:: framebuf.MONO_HMSB + + Monochrome (1-bit) color format + This defines a mapping where the bits in a byte are horizontally mapped. + Each byte occupies 8 horizontal pixels with bit 7 being the leftmost. + Subsequent bytes appear at successive horizontal locations until the + rightmost edge is reached. Further bytes are rendered on the next row, one + pixel lower. .. data:: framebuf.RGB565 diff --git a/extmod/modframebuf.c b/extmod/modframebuf.c index 33985dd00..b8e84fe1c 100644 --- a/extmod/modframebuf.c +++ b/extmod/modframebuf.c @@ -579,10 +579,11 @@ STATIC const mp_rom_map_elem_t framebuf_module_globals_table[] = { { MP_ROM_QSTR(MP_QSTR_FrameBuffer), MP_ROM_PTR(&mp_type_framebuf) }, { MP_ROM_QSTR(MP_QSTR_FrameBuffer1), MP_ROM_PTR(&legacy_framebuffer1_obj) }, { MP_ROM_QSTR(MP_QSTR_MVLSB), MP_OBJ_NEW_SMALL_INT(FRAMEBUF_MVLSB) }, + { MP_ROM_QSTR(MP_QSTR_MONO_VLSB), MP_OBJ_NEW_SMALL_INT(FRAMEBUF_MVLSB) }, { MP_ROM_QSTR(MP_QSTR_RGB565), MP_OBJ_NEW_SMALL_INT(FRAMEBUF_RGB565) }, { MP_ROM_QSTR(MP_QSTR_GS4_HMSB), MP_OBJ_NEW_SMALL_INT(FRAMEBUF_GS4_HMSB) }, - { MP_ROM_QSTR(MP_QSTR_MHLSB), MP_OBJ_NEW_SMALL_INT(FRAMEBUF_MHLSB) }, - { MP_ROM_QSTR(MP_QSTR_MHMSB), MP_OBJ_NEW_SMALL_INT(FRAMEBUF_MHMSB) }, + { MP_ROM_QSTR(MP_QSTR_MONO_HLSB), MP_OBJ_NEW_SMALL_INT(FRAMEBUF_MHLSB) }, + { MP_ROM_QSTR(MP_QSTR_MONO_HMSB), MP_OBJ_NEW_SMALL_INT(FRAMEBUF_MHMSB) }, }; STATIC MP_DEFINE_CONST_DICT(framebuf_module_globals, framebuf_module_globals_table); diff --git a/tests/extmod/framebuf1.py b/tests/extmod/framebuf1.py index 0a8e1ae55..990b0b120 100644 --- a/tests/extmod/framebuf1.py +++ b/tests/extmod/framebuf1.py @@ -9,9 +9,9 @@ w = 5 h = 16 size = w * h // 8 buf = bytearray(size) -maps = {framebuf.MVLSB : 'MVLSB', - framebuf.MHLSB : 'MHLSB', - framebuf.MHMSB : 'MHMSB'} +maps = {framebuf.MONO_VLSB : 'MONO_VLSB', + framebuf.MONO_HLSB : 'MONO_HLSB', + framebuf.MONO_HMSB : 'MONO_HMSB'} for mapping in maps.keys(): for x in range(size): @@ -107,3 +107,4 @@ except ValueError: # test legacy constructor fbuf = framebuf.FrameBuffer1(buf, w, h) fbuf = framebuf.FrameBuffer1(buf, w, h, w) +print(framebuf.MVLSB == framebuf.MONO_VLSB) diff --git a/tests/extmod/framebuf1.py.exp b/tests/extmod/framebuf1.py.exp index 736ad7a45..d954623de 100644 --- a/tests/extmod/framebuf1.py.exp +++ b/tests/extmod/framebuf1.py.exp @@ -1,4 +1,4 @@ -MVLSB +MONO_VLSB 0 bytearray(b'\xff\xff\xff\xff\xff\xff\xff\xff\xff\xff') bytearray(b'\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00') @@ -20,7 +20,7 @@ bytearray(b'\x00\x7f\x7f\x04\x04\x00\x00\x00\x00\x00') bytearray(b'\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00') bytearray(b'\xaaU\xaaU\xaa\x00\x00\x00\x00\x00') -MHLSB +MONO_HLSB 0 bytearray(b'\xf8\xf8\xf8\xf8\xf8\xf8\xf8\xf8\xf8\xf8') bytearray(b'\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00') @@ -42,7 +42,7 @@ bytearray(b'``x````\x00\x00\x00') bytearray(b'\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00') bytearray(b'P\xa8P\xa8P\xa8P\xa8\x00\x00') -MHMSB +MONO_HMSB 0 bytearray(b'\x1f\x1f\x1f\x1f\x1f\x1f\x1f\x1f\x1f\x1f') bytearray(b'\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00') @@ -65,3 +65,4 @@ bytearray(b'\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00') bytearray(b'\n\x15\n\x15\n\x15\n\x15\x00\x00') ValueError +True -- cgit v1.2.3 From 0a861db91c9566e9cc6021dc3620c7ecd9af3edd Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Wed, 5 Apr 2017 11:39:34 +0300 Subject: docs/utime: De-conditionalize description of sleep_ms() and friends. These are basic MicroPython API, and all ports should implement them. --- docs/library/utime.rst | 48 +++++++++++++++++++++++------------------------- 1 file changed, 23 insertions(+), 25 deletions(-) (limited to 'docs') diff --git a/docs/library/utime.rst b/docs/library/utime.rst index 0b47a036e..980fefe13 100644 --- a/docs/library/utime.rst +++ b/docs/library/utime.rst @@ -70,39 +70,37 @@ Functions Sleep for the given number of seconds. -.. only:: port_unix or port_pyboard or port_wipy or port_esp8266 +.. function:: sleep_ms(ms) - .. function:: sleep_ms(ms) + Delay for given number of milliseconds, should be positive or 0. - Delay for given number of milliseconds, should be positive or 0. +.. function:: sleep_us(us) - .. function:: sleep_us(us) + Delay for given number of microseconds, should be positive or 0. - Delay for given number of microseconds, should be positive or 0. +.. function:: ticks_ms() - .. function:: ticks_ms() + Returns an increasing millisecond counter with an arbitrary reference point, that + wraps around after some value. This value is not explicitly exposed, but we will + refer to it as ``TICKS_MAX`` to simplify discussion. Period of the values is + ``TICKS_PERIOD = TICKS_MAX + 1``. ``TICKS_PERIOD`` is guaranteed to be a power of + two, but otherwise may differ from port to port. The same period value is used + for all of ``ticks_ms()``, ``ticks_us()``, ``ticks_cpu()`` functions (for + simplicity). Thus, these functions will return a value in range [``0`` .. + ``TICKS_MAX``], inclusive, total ``TICKS_PERIOD`` values. Note that only + non-negative values are used. For the most part, you should treat values returned + by these functions as opaque. The only operations available for them are + ``ticks_diff()`` and ``ticks_add()`` functions described below. - Returns an increasing millisecond counter with an arbitrary reference point, that - wraps around after some value. This value is not explicitly exposed, but we will - refer to it as ``TICKS_MAX`` to simplify discussion. Period of the values is - ``TICKS_PERIOD = TICKS_MAX + 1``. ``TICKS_PERIOD`` is guaranteed to be a power of - two, but otherwise may differ from port to port. The same period value is used - for all of ``ticks_ms()``, ``ticks_us()``, ``ticks_cpu()`` functions (for - simplicity). Thus, these functions will return a value in range [``0`` .. - ``TICKS_MAX``], inclusive, total ``TICKS_PERIOD`` values. Note that only - non-negative values are used. For the most part, you should treat values returned - by these functions as opaque. The only operations available for them are - ``ticks_diff()`` and ``ticks_add()`` functions described below. + Note: Performing standard mathematical operations (+, -) or relational + operators (<, <=, >, >=) directly on these value will lead to invalid + result. Performing mathematical operations and then passing their results + as arguments to ``ticks_diff()`` or ``ticks_add()`` will also lead to + invalid results from the latter functions. - Note: Performing standard mathematical operations (+, -) or relational - operators (<, <=, >, >=) directly on these value will lead to invalid - result. Performing mathematical operations and then passing their results - as arguments to ``ticks_diff()`` or ``ticks_add()`` will also lead to - invalid results from the latter functions. +.. function:: ticks_us() - .. function:: ticks_us() - - Just like ``ticks_ms()`` above, but in microseconds. + Just like ``ticks_ms()`` above, but in microseconds. .. function:: ticks_cpu() -- cgit v1.2.3 From 906d58f6f29e9a293e2a7cd3485d9191614c66df Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Wed, 5 Apr 2017 11:44:10 +0300 Subject: docs/uos: De-conditionalize statvfs() description. It's a standard function, and it's already described (in the library intro) that for any given port, any function may be missing. --- docs/library/uos.rst | 42 ++++++++++++++++++++---------------------- 1 file changed, 20 insertions(+), 22 deletions(-) (limited to 'docs') diff --git a/docs/library/uos.rst b/docs/library/uos.rst index cd0c5cae8..bb3c20017 100644 --- a/docs/library/uos.rst +++ b/docs/library/uos.rst @@ -61,28 +61,26 @@ Functions Get the status of a file or directory. -.. only:: port_unix or port_pyboard or port_esp8266 - - .. function:: statvfs(path) - - Get the status of a fileystem. - - Returns a tuple with the filesystem information in the following order: - - * ``f_bsize`` -- file system block size - * ``f_frsize`` -- fragment size - * ``f_blocks`` -- size of fs in f_frsize units - * ``f_bfree`` -- number of free blocks - * ``f_bavail`` -- number of free blocks for unpriviliged users - * ``f_files`` -- number of inodes - * ``f_ffree`` -- number of free inodes - * ``f_favail`` -- number of free inodes for unpriviliged users - * ``f_flag`` -- mount flags - * ``f_namemax`` -- maximum filename length - - Parameters related to inodes: ``f_files``, ``f_ffree``, ``f_avail`` - and the ``f_flags`` parameter may return ``0`` as they can be unavailable - in a port-specific implementation. +.. function:: statvfs(path) + + Get the status of a fileystem. + + Returns a tuple with the filesystem information in the following order: + + * ``f_bsize`` -- file system block size + * ``f_frsize`` -- fragment size + * ``f_blocks`` -- size of fs in f_frsize units + * ``f_bfree`` -- number of free blocks + * ``f_bavail`` -- number of free blocks for unpriviliged users + * ``f_files`` -- number of inodes + * ``f_ffree`` -- number of free inodes + * ``f_favail`` -- number of free inodes for unpriviliged users + * ``f_flag`` -- mount flags + * ``f_namemax`` -- maximum filename length + + Parameters related to inodes: ``f_files``, ``f_ffree``, ``f_avail`` + and the ``f_flags`` parameter may return ``0`` as they can be unavailable + in a port-specific implementation. .. function:: sync() -- cgit v1.2.3 From 4333b2fb539b60b7f536db70a63595620919b3b6 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Wed, 5 Apr 2017 11:47:15 +0300 Subject: docs/machine.SPI: Remove outdated wipy chunk. --- docs/library/machine.SPI.rst | 12 ------------ 1 file changed, 12 deletions(-) (limited to 'docs') diff --git a/docs/library/machine.SPI.rst b/docs/library/machine.SPI.rst index e8a8a2d8c..82858629f 100644 --- a/docs/library/machine.SPI.rst +++ b/docs/library/machine.SPI.rst @@ -10,18 +10,6 @@ SS (Slave Select), to select a particular device on a bus with which communication takes place. Management of an SS signal should happen in user code (via machine.Pin class). -.. only:: port_wipy - - See usage model of I2C; SPI is very similar. Main difference is - parameters to init the SPI bus:: - - from machine import SPI - spi = SPI(0, mode=SPI.MASTER, baudrate=1000000, polarity=0, phase=0, firstbit=SPI.MSB) - - Only required parameter is mode, must be SPI.MASTER. Polarity can be 0 or - 1, and is the level the idle clock line sits at. Phase can be 0 or 1 to - sample data on the first or second clock edge respectively. - Constructors ------------ -- cgit v1.2.3 From 9a38b7afe0058620c09cf54b0bbc1c20f32a5e22 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Wed, 5 Apr 2017 11:58:17 +0300 Subject: cc3200/modmachine: Return frequency value directly, like other ports. --- cc3200/mods/modmachine.c | 5 +---- docs/library/machine.rst | 11 +---------- 2 files changed, 2 insertions(+), 14 deletions(-) (limited to 'docs') diff --git a/cc3200/mods/modmachine.c b/cc3200/mods/modmachine.c index 3c4e5a116..fd1485607 100644 --- a/cc3200/mods/modmachine.c +++ b/cc3200/mods/modmachine.c @@ -111,10 +111,7 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(machine_info_obj, 0, 1, machine_info) #endif STATIC mp_obj_t machine_freq(void) { - mp_obj_t tuple[1] = { - mp_obj_new_int(HAL_FCPU_HZ), - }; - return mp_obj_new_tuple(1, tuple); + return mp_obj_new_int(HAL_FCPU_HZ); } STATIC MP_DEFINE_CONST_FUN_OBJ_0(machine_freq_obj, machine_freq); diff --git a/docs/library/machine.rst b/docs/library/machine.rst index c677bcbf0..1007f142f 100644 --- a/docs/library/machine.rst +++ b/docs/library/machine.rst @@ -52,16 +52,7 @@ Power related functions .. function:: freq() - .. only:: not port_wipy - - Returns CPU frequency in hertz. - - .. only:: port_wipy - - Returns a tuple of clock frequencies: ``(sysclk,)`` - These correspond to: - - - sysclk: frequency of the CPU + Returns CPU frequency in hertz. .. function:: idle() -- cgit v1.2.3 From d46899626e93b35de549edd6d8954527398a8036 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Wed, 5 Apr 2017 12:09:36 +0300 Subject: docs/machine.Pin: Move wipy-specific details to its own docs. --- docs/library/machine.Pin.rst | 52 ------------------------------------------- docs/wipy/general.rst | 53 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 53 insertions(+), 52 deletions(-) (limited to 'docs') diff --git a/docs/library/machine.Pin.rst b/docs/library/machine.Pin.rst index 952131f09..d3aa37b45 100644 --- a/docs/library/machine.Pin.rst +++ b/docs/library/machine.Pin.rst @@ -38,58 +38,6 @@ Usage Model:: # configure an irq callback p0.irq(lambda p:print(p)) -.. only:: port_wipy - - On the WiPy board the pins are identified by their string id:: - - from machine import Pin - g = machine.Pin('GP9', mode=Pin.OUT, pull=None, drive=Pin.MED_POWER, alt=-1) - - You can also configure the Pin to generate interrupts. For instance:: - - from machine import Pin - - def pincb(pin): - print(pin.id()) - - pin_int = Pin('GP10', mode=Pin.IN, pull=Pin.PULL_DOWN) - pin_int.irq(trigger=Pin.IRQ_RISING, handler=pincb) - # the callback can be triggered manually - pin_int.irq()() - # to disable the callback - pin_int.irq().disable() - - Now every time a falling edge is seen on the gpio pin, the callback will be - executed. Caution: mechanical push buttons have "bounce" and pushing or - releasing a switch will often generate multiple edges. - See: http://www.eng.utah.edu/~cs5780/debouncing.pdf for a detailed - explanation, along with various techniques for debouncing. - - All pin objects go through the pin mapper to come up with one of the - gpio pins. - - For the ``drive`` parameter the strengths are: - - - ``Pin.LOW_POWER`` - 2mA drive capability. - - ``Pin.MED_POWER`` - 4mA drive capability. - - ``Pin.HIGH_POWER`` - 6mA drive capability. - - For the ``alt`` parameter please refer to the pinout and alternate functions - table at `_ - for the specific alternate functions that each pin supports. - - For interrupts, the ``priority`` can take values in the range 1-7. And the - ``wake`` parameter has the following properties: - - - If ``wake_from=machine.Sleep.ACTIVE`` any pin can wake the board. - - If ``wake_from=machine.Sleep.SUSPENDED`` pins ``GP2``, ``GP4``, ``GP10``, - ``GP11``, GP17`` or ``GP24`` can wake the board. Note that only 1 - of this pins can be enabled as a wake source at the same time, so, only - the last enabled pin as a ``machine.Sleep.SUSPENDED`` wake source will have effect. - - If ``wake_from=machine.Sleep.SUSPENDED`` pins ``GP2``, ``GP4``, ``GP10``, - ``GP11``, ``GP17`` and ``GP24`` can wake the board. In this case all of the - 6 pins can be enabled as a ``machine.Sleep.HIBERNATE`` wake source at the same time. - Constructors ------------ diff --git a/docs/wipy/general.rst b/docs/wipy/general.rst index 0991dbaea..0d0327f4b 100644 --- a/docs/wipy/general.rst +++ b/docs/wipy/general.rst @@ -179,3 +179,56 @@ Details on sleep modes * ``machine.sleep()``: 950uA (in WLAN STA mode). Wake sources are ``Pin``, ``RTC`` and ``WLAN`` * ``machine.deepsleep()``: ~350uA. Wake sources are ``Pin`` and ``RTC``. + +Additional details for machine.Pin +---------------------------------- + +On the WiPy board the pins are identified by their string id:: + + from machine import Pin + g = machine.Pin('GP9', mode=Pin.OUT, pull=None, drive=Pin.MED_POWER, alt=-1) + +You can also configure the Pin to generate interrupts. For instance:: + + from machine import Pin + + def pincb(pin): + print(pin.id()) + + pin_int = Pin('GP10', mode=Pin.IN, pull=Pin.PULL_DOWN) + pin_int.irq(trigger=Pin.IRQ_RISING, handler=pincb) + # the callback can be triggered manually + pin_int.irq()() + # to disable the callback + pin_int.irq().disable() + +Now every time a falling edge is seen on the gpio pin, the callback will be +executed. Caution: mechanical push buttons have "bounce" and pushing or +releasing a switch will often generate multiple edges. +See: http://www.eng.utah.edu/~cs5780/debouncing.pdf for a detailed +explanation, along with various techniques for debouncing. + +All pin objects go through the pin mapper to come up with one of the +gpio pins. + +For the ``drive`` parameter the strengths are: + + - ``Pin.LOW_POWER`` - 2mA drive capability. + - ``Pin.MED_POWER`` - 4mA drive capability. + - ``Pin.HIGH_POWER`` - 6mA drive capability. + +For the ``alt`` parameter please refer to the pinout and alternate functions +table at `_ +for the specific alternate functions that each pin supports. + +For interrupts, the ``priority`` can take values in the range 1-7. And the +``wake`` parameter has the following properties: + + - If ``wake_from=machine.Sleep.ACTIVE`` any pin can wake the board. + - If ``wake_from=machine.Sleep.SUSPENDED`` pins ``GP2``, ``GP4``, ``GP10``, + ``GP11``, GP17`` or ``GP24`` can wake the board. Note that only 1 + of this pins can be enabled as a wake source at the same time, so, only + the last enabled pin as a ``machine.Sleep.SUSPENDED`` wake source will have effect. + - If ``wake_from=machine.Sleep.SUSPENDED`` pins ``GP2``, ``GP4``, ``GP10``, + ``GP11``, ``GP17`` and ``GP24`` can wake the board. In this case all of the + 6 pins can be enabled as a ``machine.Sleep.HIBERNATE`` wake source at the same time. -- cgit v1.2.3 From 390d5a3bf101eba5952c3f757f27b82ff0bdfed1 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Wed, 5 Apr 2017 13:05:04 +0300 Subject: docs/machine.Pin: Move wipy-specific methods to its docs. --- docs/library/machine.Pin.rst | 10 ---------- docs/wipy/general.rst | 7 +++++++ 2 files changed, 7 insertions(+), 10 deletions(-) (limited to 'docs') diff --git a/docs/library/machine.Pin.rst b/docs/library/machine.Pin.rst index d3aa37b45..216ebcb2a 100644 --- a/docs/library/machine.Pin.rst +++ b/docs/library/machine.Pin.rst @@ -225,16 +225,6 @@ Methods This method returns a callback object. -.. only:: port_wipy - - .. 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)`` - - Availability: WiPy. - - Attributes ---------- diff --git a/docs/wipy/general.rst b/docs/wipy/general.rst index 0d0327f4b..d7b35cc4e 100644 --- a/docs/wipy/general.rst +++ b/docs/wipy/general.rst @@ -232,3 +232,10 @@ For interrupts, the ``priority`` can take values in the range 1-7. And the - If ``wake_from=machine.Sleep.SUSPENDED`` pins ``GP2``, ``GP4``, ``GP10``, ``GP11``, ``GP17`` and ``GP24`` can wake the board. In this case all of the 6 pins can be enabled as a ``machine.Sleep.HIBERNATE`` wake source at the same time. + +Additional Pin methods: + +.. method:: machine.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)`` -- cgit v1.2.3 From e5278b98fe2aad840d58e33a0c06af2e2b55cbde Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Fri, 7 Apr 2017 10:52:50 +0300 Subject: docs/esp8266/general: Start explicit "Known Issues", mentioned RTC inaccuracy. --- docs/esp8266/general.rst | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/esp8266/general.rst b/docs/esp8266/general.rst index cd659f80a..47df80d7b 100644 --- a/docs/esp8266/general.rst +++ b/docs/esp8266/general.rst @@ -107,8 +107,16 @@ This will allow to keep the structure of your application clear, as well as allow to install multiple applications on a board, and switch among them. +Known Issues +------------ + Real-time clock ---------------- +~~~~~~~~~~~~~~~ + +RTC in ESP8266 has very bad accuracy, drift may be seconds per minute. As +a workaround, to measure short enough intervals you can use +``utime.time()``, etc. functions, and for wall clock time, synchronize from +the net using included ``ntpdate.py`` module. Due to limitations of the ESP8266 chip the internal real-time clock (RTC) will overflow every 7:45h. If a long-term working RTC time is required then -- cgit v1.2.3 From bcf3c8bf17caad7a2f46ee69f1d9563d884c2f23 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Sun, 9 Apr 2017 00:06:54 +0300 Subject: docs/library/builtins: int: Add notice on byteorder param for to/from_bytes. --- docs/library/builtins.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) (limited to 'docs') diff --git a/docs/library/builtins.rst b/docs/library/builtins.rst index d53c4d377..46f762660 100644 --- a/docs/library/builtins.rst +++ b/docs/library/builtins.rst @@ -67,6 +67,16 @@ All builtin functions are described here. They are also available via .. class:: int() + .. classmethod:: from_bytes(bytes, byteorder) + + In MicroPython, `byteorder` parameter must be positional (this is + compatible with CPython). + + .. method:: to_bytes(size, byteorder) + + In MicroPython, `byteorder` parameter must be positional (this is + compatible with CPython). + .. function:: isinstance() .. function:: issubclass() -- cgit v1.2.3 From 1d74559b6b3eb1e9f0eb2aceceb898f6d24f5dd4 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Sun, 9 Apr 2017 00:25:27 +0300 Subject: docs/library/machine.UART: Remove some conditionals. --- docs/library/machine.UART.rst | 35 ++++++++--------------------------- 1 file changed, 8 insertions(+), 27 deletions(-) (limited to 'docs') diff --git a/docs/library/machine.UART.rst b/docs/library/machine.UART.rst index 0b6b24e89..fe7597eb5 100644 --- a/docs/library/machine.UART.rst +++ b/docs/library/machine.UART.rst @@ -15,17 +15,13 @@ UART objects can be created and initialised using:: uart = UART(1, 9600) # init with given baudrate uart.init(9600, bits=8, parity=None, stop=1) # init with given parameters -.. only:: port_machineoard +Supported paramters differ on a board: - Bits can be 7, 8 or 9. Parity can be None, 0 (even) or 1 (odd). Stop can be 1 or 2. - - *Note:* with parity=None, only 8 and 9 bits are supported. With parity enabled, - only 7 and 8 bits are supported. - -.. only:: port_wipy - - Bits can be 5, 6, 7, 8. Parity can be ``None``, ``UART.EVEN`` or ``UART.ODD``. Stop can be 1 or 2. +Pyboard: Bits can be 7, 8 or 9. Stop can be 1 or 2. With `parity=None`, +only 8 and 9 bits are supported. With parity enabled, only 7 and 8 bits +are supported. +WiPy/CC3200: Bits can be 5, 6, 7, 8. Stop can be 1 or 2. A UART object acts like a stream object and reading and writing is done using the standard stream methods:: @@ -47,22 +43,12 @@ using the standard stream methods:: uart.any() # returns True if any characters waiting -.. only:: port_wipy - - To check if there is anything to be read, use:: - - uart.any() # returns the number of characters available for reading - Constructors ------------ -.. only:: port_wipy +.. class:: UART(id, ...) - .. 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 - will be made based on the given pins. + Construct a UART object of the given id. Methods ------- @@ -75,7 +61,7 @@ Methods - ``baudrate`` is the clock rate. - ``bits`` is the number of bits per character, 7, 8 or 9. - - ``parity`` is the parity, ``None``, ``UART.EVEN`` or ``UART.ODD``. + - ``parity`` is the parity, ``None``, 0 (even) or 1 (odd). - ``stop`` is the number of stop bits, 1 or 2. - ``pins`` is a 4 or 2 item list indicating the TX, RX, RTS and CTS pins (in that order). Any of the pins can be None if one wants the UART to operate with limited functionality. @@ -159,11 +145,6 @@ Methods Constants --------- - .. data:: UART.EVEN - .. data:: UART.ODD - - parity types (along with ``None``) - .. data:: UART.RX_ANY IRQ trigger sources -- cgit v1.2.3 From 3acace588a51b5f45a28ae3f63d662b6be0e8d4d Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Sun, 9 Apr 2017 00:42:32 +0300 Subject: docs/utime: Deconditionalize description of sleep(). --- docs/library/utime.rst | 18 +++++------------- 1 file changed, 5 insertions(+), 13 deletions(-) (limited to 'docs') diff --git a/docs/library/utime.rst b/docs/library/utime.rst index 980fefe13..871f6c678 100644 --- a/docs/library/utime.rst +++ b/docs/library/utime.rst @@ -55,20 +55,12 @@ Functions which expresses a time as per localtime. It returns an integer which is the number of seconds since Jan 1, 2000. -.. only:: port_unix or port_pyboard or port_esp8266 +.. function:: sleep(seconds) - .. function:: sleep(seconds) - - Sleep for the given number of seconds. Seconds can be a floating-point number to - sleep for a fractional number of seconds. Note that other MicroPython ports may - not accept floating-point argument, for compatibility with them use ``sleep_ms()`` - and ``sleep_us()`` functions. - -.. only:: port_wipy - - .. function:: sleep(seconds) - - Sleep for the given number of seconds. + Sleep for the given number of seconds. Some boards may accept `seconds` as a + floating-point number to sleep for a fractional number of seconds. Note that + other boards may not accept a floating-point argument, for compatibility with + them use ``sleep_ms()`` and ``sleep_us()`` functions. .. function:: sleep_ms(ms) -- cgit v1.2.3 From 2e58474580fe459c03e52c7662d28786f3885fdf Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Sun, 9 Apr 2017 00:48:28 +0300 Subject: docs/usocket: Deconditionalize. Notes on WiPy incompatibilities with the standard socket module API are moved under "Known issues" to its documentation. --- docs/library/usocket.rst | 12 ------------ docs/wipy/general.rst | 14 ++++++++++++++ 2 files changed, 14 insertions(+), 12 deletions(-) (limited to 'docs') diff --git a/docs/library/usocket.rst b/docs/library/usocket.rst index dd0f5708b..71deaebc4 100644 --- a/docs/library/usocket.rst +++ b/docs/library/usocket.rst @@ -41,18 +41,6 @@ Functions Create a new socket using the given address family, socket type and protocol number. - .. only:: port_wipy - - .. note:: - - SSL sockets need to be created the following way before wrapping them with - ``ssl.wrap_socket``:: - - import socket - import ssl - s = socket(socket.AF_INET, socket.SOCK_STREAM, socket.IPPROTO_SEC) - ss = ssl.wrap_socket(s) - .. function:: socket.getaddrinfo(host, port) Translate the host/port argument into a sequence of 5-tuples that contain all the diff --git a/docs/wipy/general.rst b/docs/wipy/general.rst index d7b35cc4e..9b3f54df2 100644 --- a/docs/wipy/general.rst +++ b/docs/wipy/general.rst @@ -239,3 +239,17 @@ Additional Pin methods: 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)`` + +Known issues +------------ + +Incompatible way to create SSL sockets +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +SSL sockets need to be created the following way before wrapping them with. +``ssl.wrap_socket``:: + + import socket + import ssl + s = socket(socket.AF_INET, socket.SOCK_STREAM, socket.IPPROTO_SEC) + ss = ssl.wrap_socket(s) -- cgit v1.2.3 From b87432b8fb8332548be11b63c9139065ce565f91 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Sun, 9 Apr 2017 00:57:16 +0300 Subject: docs/uhashlib: Deconditionalize. Notes on WiPy incompatibilities with the standard module API are moved under "Known issues" to its documentation. --- docs/library/uhashlib.rst | 30 ------------------------------ docs/wipy/general.rst | 20 ++++++++++++++++++++ 2 files changed, 20 insertions(+), 30 deletions(-) (limited to 'docs') diff --git a/docs/library/uhashlib.rst b/docs/library/uhashlib.rst index 2c340e40b..cd0216dae 100644 --- a/docs/library/uhashlib.rst +++ b/docs/library/uhashlib.rst @@ -37,36 +37,6 @@ Constructors Create an MD5 hasher object and optionally feed ``data`` into it. -.. only:: port_wipy - - .. class:: uhashlib.sha1([data[, block_size]]) - - Create a sha1 hasher object and optionally feed ``data`` or ``data and block_size`` into it. - - .. class:: uhashlib.sha256([data[, block_size]]) - - Create a sha256 hasher object and optionally feed ``data`` or ``data and block_size`` into it. - - .. admonition:: CPython extension - :class: attention - - Due to hardware implementation details of the WiPy, data must be buffered before being - digested, which would make it impossible to calculate the hash of big blocks of data that - do not fit in RAM. In this case, since most likely the total size of the data is known - in advance, the size can be passed to the constructor and hence the HASH hardware engine - of the WiPy can be properly initialized without needing buffering. If ``block_size`` is - to be given, an initial chunk of ``data`` must be passed as well. **When using this extension, - care must be taken to make sure that the length of all intermediate chunks (including the - initial one) is a multiple of 4 bytes.** The last chunk may be of any length. - - Example:: - - hash = uhashlib.sha1('abcd1234', 1001) # length of the initial piece is multiple of 4 bytes - hash.update('1234') # also multiple of 4 bytes - ... - hash.update('12345') # last chunk may be of any length - hash.digest() - Methods ------- diff --git a/docs/wipy/general.rst b/docs/wipy/general.rst index 9b3f54df2..eca9bbe45 100644 --- a/docs/wipy/general.rst +++ b/docs/wipy/general.rst @@ -253,3 +253,23 @@ SSL sockets need to be created the following way before wrapping them with. import ssl s = socket(socket.AF_INET, socket.SOCK_STREAM, socket.IPPROTO_SEC) ss = ssl.wrap_socket(s) + +Incompatibilities in uhashlib module +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Due to hardware implementation details of the WiPy, data must be buffered before being +digested, which would make it impossible to calculate the hash of big blocks of data that +do not fit in RAM. In this case, since most likely the total size of the data is known +in advance, the size can be passed to the constructor and hence the HASH hardware engine +of the WiPy can be properly initialized without needing buffering. If ``block_size`` is +to be given, an initial chunk of ``data`` must be passed as well. **When using this extension, +care must be taken to make sure that the length of all intermediate chunks (including the +initial one) is a multiple of 4 bytes.** The last chunk may be of any length. + +Example:: + + hash = uhashlib.sha1('abcd1234', 1001) # length of the initial piece is multiple of 4 bytes + hash.update('1234') # also multiple of 4 bytes + ... + hash.update('12345') # last chunk may be of any length + hash.digest() -- cgit v1.2.3 From a1c39ffb69d711858e47e172d4ca8d98990d2bf9 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Fri, 14 Apr 2017 01:12:04 +0300 Subject: docs/esp8266/tutorial/intro: Reword section on flash size requirement. Give a clearly dissuading tone on end users trying 512KB version - it has to many end-usery features lacking. --- docs/esp8266/tutorial/intro.rst | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/esp8266/tutorial/intro.rst b/docs/esp8266/tutorial/intro.rst index e7a38d3e5..67ed0ba67 100644 --- a/docs/esp8266/tutorial/intro.rst +++ b/docs/esp8266/tutorial/intro.rst @@ -20,9 +20,12 @@ characteristic of a board is how much flash it has, how the GPIO pins are connected to the outside world, and whether it includes a built-in USB-serial convertor to make the UART available to your PC. -The minimum requirement for flash size is 512k. A board with this amount of -flash will not have room for a filesystem, but otherwise is fully functional. -If your board has 1Mbyte or more of flash then it will support a filesystem. +The minimum requirement for flash size is 1Mbyte. There is also a special +build for boards with 512KB, but it is highly limited comparing to the +normal build: there is no support for filesystem, and thus features which +depend on it won't work (WebREPL, upip, etc.). As such, 512KB build will +be more interesting for users who build from source and fine-tune parameters +for their particular application. Names of pins will be given in this tutorial using the chip names (eg GPIO0) and it should be straightforward to find which pin this corresponds to on your -- cgit v1.2.3 From ae831ec0a8ff45a31d993798cd315027eba3d897 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Sun, 16 Apr 2017 09:18:47 +0300 Subject: docs/library/micropython: Deconditionalize. --- docs/library/micropython.rst | 38 ++++++++++++++++++-------------------- 1 file changed, 18 insertions(+), 20 deletions(-) (limited to 'docs') diff --git a/docs/library/micropython.rst b/docs/library/micropython.rst index 14e4c917e..967f822ec 100644 --- a/docs/library/micropython.rst +++ b/docs/library/micropython.rst @@ -7,26 +7,6 @@ Functions --------- -.. only:: port_pyboard or port_unix - - .. function:: mem_info([verbose]) - - Print information about currently used memory. If the ``verbose`` argument - is given then extra information is printed. - - The information that is printed is implementation dependent, but currently - includes the amount of stack and heap used. In verbose mode it prints out - the entire heap indicating which blocks are used and which are free. - - .. function:: qstr_info([verbose]) - - Print information about currently interned strings. If the ``verbose`` - argument is given then extra information is printed. - - The information that is printed is implementation dependent, but currently - includes the number of interned strings and the amount of RAM they use. In - verbose mode it prints out the names of all RAM-interned strings. - .. function:: alloc_emergency_exception_buf(size) Allocate ``size`` bytes of RAM for the emergency exception buffer (a good @@ -37,3 +17,21 @@ Functions A good way to use this function is to put it at the start of your main script (eg boot.py or main.py) and then the emergency exception buffer will be active for all the code following it. + +.. function:: mem_info([verbose]) + + Print information about currently used memory. If the ``verbose`` argument + is given then extra information is printed. + + The information that is printed is implementation dependent, but currently + includes the amount of stack and heap used. In verbose mode it prints out + the entire heap indicating which blocks are used and which are free. + +.. function:: qstr_info([verbose]) + + Print information about currently interned strings. If the ``verbose`` + argument is given then extra information is printed. + + The information that is printed is implementation dependent, but currently + includes the number of interned strings and the amount of RAM they use. In + verbose mode it prints out the names of all RAM-interned strings. -- cgit v1.2.3 From a0fb360f1b3f32131be6267c7ce0dbe74ed91f77 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Sun, 16 Apr 2017 09:22:47 +0300 Subject: docs/library/uos: urandom: Generalize description. Don't give a guarantee of HW RNG, only a possibility of its usage. --- docs/library/uos.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/library/uos.rst b/docs/library/uos.rst index bb3c20017..e1ea72967 100644 --- a/docs/library/uos.rst +++ b/docs/library/uos.rst @@ -88,8 +88,8 @@ Functions .. function:: urandom(n) - Return a bytes object with n random bytes, generated by the hardware - random number generator. + Return a bytes object with n random bytes. Whenever possible, it is + generated by the hardware random number generator. .. only:: port_wipy -- cgit v1.2.3 From ac8843ceecb645b11737ea42d0f4248d742383cd Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Sun, 16 Apr 2017 09:41:32 +0300 Subject: docs/library/ussl: Deconditionalize, wipy notes moved to its documentation. --- docs/library/ussl.rst | 100 +++++++++++++++----------------------------------- docs/wipy/general.rst | 23 ++++++++++++ 2 files changed, 53 insertions(+), 70 deletions(-) (limited to 'docs') diff --git a/docs/library/ussl.rst b/docs/library/ussl.rst index 5371ed129..36f6d65a4 100644 --- a/docs/library/ussl.rst +++ b/docs/library/ussl.rst @@ -1,86 +1,46 @@ -:mod:`ussl` -- ssl module -=============================== +:mod:`ussl` -- SSL/TLS module +============================= .. module:: ussl :synopsis: TLS/SSL wrapper for socket objects -This module provides access to Transport Layer Security (often known as -“Secure Sockets Layer”) encryption and peer authentication facilities for -network sockets, both client-side and server-side. +This module provides access to Transport Layer Security (previously and +widely known as “Secure Sockets Layer”) encryption and peer authentication +facilities for network sockets, both client-side and server-side. -.. only:: not port_wipy +Functions +--------- - Functions - --------- +.. function:: ssl.wrap_socket(sock, server_side=False, keyfile=None, certfile=None, cert_reqs=CERT_NONE, ca_certs=None) - .. function:: ssl.wrap_socket(sock, server_side=False) + Takes a stream `sock` (usually usocket.socket instance of ``SOCK_STREAM`` type), + and returns an instance of ssl.SSLSocket, which wraps the underlying stream in + an SSL context. Returned object has the usual stream interface methods like + `read()`, `write()`, etc. In MicroPython, the returned object does not expose + socket interface and methods like `recv()`, `send()`. In particular, a + server-side SSL socket should be created from a normal socket returned from + `accept()` on a non-SSL listening server socket. - Takes a stream `sock` (usually usocket.socket instance of ``SOCK_STREAM`` type), - and returns an instance of ssl.SSLSocket, which wraps the underlying stream in - an SSL context. Returned object has the usual stream interface methods like - `read()`, `write()`, etc. In MicroPython, the returned object does not expose - socket interface and methods like `recv()`, `send()`. In particular, a - server-side SSL socket should be created from a normal socket returned from - `accept()` on a non-SSL listening server socket. + Depending on the underlying module implementation for a particular board, + some or all keyword arguments above may be not supported. - .. warning:: +.. warning:: - Currently, this function does NOT validate server certificates, which makes - an SSL connection established prone to man-in-the-middle attacks. + Some implementations of ``ssl`` module do NOT validate server certificates, + which makes an SSL connection established prone to man-in-the-middle attacks. +Exceptions +---------- -.. only:: port_wipy +.. data:: ssl.SSLError - Functions - --------- + This exception does NOT exist. Instead its base class, OSError, is used. - .. function:: ssl.wrap_socket(sock, keyfile=None, certfile=None, server_side=False, cert_reqs=CERT_NONE, ca_certs=None) +Constants +--------- - Takes an instance sock of socket.socket, and returns an instance of ssl.SSLSocket, a subtype of - ``socket.socket``, which wraps the underlying socket in an SSL context. sock must be a ``SOCK_STREAM`` - socket and protocol number ``socket.IPPROTO_SEC``; other socket types are unsupported. Example:: +.. data:: ssl.CERT_NONE + ssl.CERT_OPTIONAL + ssl.CERT_REQUIRED - import socket - import ssl - s = socket(socket.AF_INET, socket.SOCK_STREAM, socket.IPPROTO_SEC) - ss = ssl.wrap_socket(s) - ss.connect(socket.getaddrinfo('www.google.com', 443)[0][-1]) - - Certificates must be used in order to validate the other side of the connection, and also to - authenticate ourselves with the other end. Such certificates must be stored as files using the - FTP server, and they must be placed in specific paths with specific names. - - - The certificate to validate the other side goes in: **'/flash/cert/ca.pem'** - - The certificate to authenticate ourselves goes in: **'/flash/cert/cert.pem'** - - The key for our own certificate goes in: **'/flash/cert/private.key'** - - .. note:: - - When these files are stored, they are placed inside the internal **hidden** file system - (just like firmware updates), and therefore they are never visible. - - For instance to connect to the Blynk servers using certificates, take the file ``ca.pem`` located - in the `blynk examples folder `_ - and put it in '/flash/cert/'. Then do:: - - import socket - import ssl - s = socket.socket(socket.AF_INET, socket.SOCK_STREAM, socket.IPPROTO_SEC) - ss = ssl.wrap_socket(s, cert_reqs=ssl.CERT_REQUIRED, ca_certs='/flash/cert/ca.pem') - ss.connect(socket.getaddrinfo('cloud.blynk.cc', 8441)[0][-1]) - - SSL sockets inherit all methods and from the standard sockets, see the :mod:`usocket` module. - - Exceptions - ---------- - - .. data:: ssl.SSLError - - Constants - --------- - - .. data:: ssl.CERT_NONE - .. data:: ssl.CERT_OPTIONAL - .. data:: ssl.CERT_REQUIRED - - supported values in ``cert_reqs`` + Supported values for `cert_reqs` parameter. diff --git a/docs/wipy/general.rst b/docs/wipy/general.rst index eca9bbe45..024f78966 100644 --- a/docs/wipy/general.rst +++ b/docs/wipy/general.rst @@ -254,6 +254,29 @@ SSL sockets need to be created the following way before wrapping them with. s = socket(socket.AF_INET, socket.SOCK_STREAM, socket.IPPROTO_SEC) ss = ssl.wrap_socket(s) +Certificates must be used in order to validate the other side of the connection, and also to +authenticate ourselves with the other end. Such certificates must be stored as files using the +FTP server, and they must be placed in specific paths with specific names. + +- The certificate to validate the other side goes in: **'/flash/cert/ca.pem'** +- The certificate to authenticate ourselves goes in: **'/flash/cert/cert.pem'** +- The key for our own certificate goes in: **'/flash/cert/private.key'** + +.. note:: + + When these files are stored, they are placed inside the internal **hidden** file system + (just like firmware updates), and therefore they are never visible. + +For instance to connect to the Blynk servers using certificates, take the file ``ca.pem`` located +in the `blynk examples folder `_. +and put it in '/flash/cert/'. Then do:: + + import socket + import ssl + s = socket.socket(socket.AF_INET, socket.SOCK_STREAM, socket.IPPROTO_SEC) + ss = ssl.wrap_socket(s, cert_reqs=ssl.CERT_REQUIRED, ca_certs='/flash/cert/ca.pem') + ss.connect(socket.getaddrinfo('cloud.blynk.cc', 8441)[0][-1]) + Incompatibilities in uhashlib module ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- cgit v1.2.3 From a8ece0358fd5821dd0e9f215f8d852a62de834c0 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Sun, 16 Apr 2017 09:54:55 +0300 Subject: docs/machine.UART: Deconditionalize normal methods. --- docs/library/machine.UART.rst | 22 ++++++++-------------- 1 file changed, 8 insertions(+), 14 deletions(-) (limited to 'docs') diff --git a/docs/library/machine.UART.rst b/docs/library/machine.UART.rst index fe7597eb5..55a5f354d 100644 --- a/docs/library/machine.UART.rst +++ b/docs/library/machine.UART.rst @@ -69,15 +69,14 @@ Methods When no pins are given, then the default set of TX and RX pins is taken, and hardware flow control will be disabled. If pins=None, no pin assignment will be made. -.. only:: not port_esp8266 +.. method:: UART.deinit() - .. method:: UART.deinit() + Turn off the UART bus. - Turn off the UART bus. +.. method:: UART.any() - .. method:: UART.any() - - Return the number of characters available for reading. + Return true value if there're characters available for reading. On some + boards, the number of available characters is returned. .. method:: UART.read([nbytes]) @@ -107,13 +106,10 @@ Methods Return value: number of bytes written or ``None`` on timeout. -.. 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. - Return value: ``None``. + Send a break condition on the bus. This drives the bus low for a duration + longer than required for a normal transmission of a character. .. only:: port_wipy @@ -140,8 +136,6 @@ Methods Returns an irq object. -.. only:: not port_esp8266 - Constants --------- -- cgit v1.2.3 From 9ef6bb5480e38b4ce3d195511e1d43a04094d48e Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Sun, 16 Apr 2017 10:12:01 +0300 Subject: docs/machine: Move machine.main() misnomer to wipy's known issues. --- docs/library/machine.rst | 7 ------- docs/wipy/general.rst | 10 ++++++++++ 2 files changed, 10 insertions(+), 7 deletions(-) (limited to 'docs') diff --git a/docs/library/machine.rst b/docs/library/machine.rst index 1007f142f..dbf8b8b4c 100644 --- a/docs/library/machine.rst +++ b/docs/library/machine.rst @@ -85,13 +85,6 @@ Miscellaneous functions .. only:: port_wipy - .. function:: main(filename) - - Set the filename of the main script to run after boot.py is finished. If - this function is not called then the default file main.py will be executed. - - It only makes sense to call this function from within boot.py. - .. function:: rng() Return a 24-bit software generated random number. diff --git a/docs/wipy/general.rst b/docs/wipy/general.rst index 024f78966..b3d8e7892 100644 --- a/docs/wipy/general.rst +++ b/docs/wipy/general.rst @@ -296,3 +296,13 @@ Example:: ... hash.update('12345') # last chunk may be of any length hash.digest() + +Unrelated function in machine module +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. function:: main(filename) + + Set the filename of the main script to run after boot.py is finished. If + this function is not called then the default file main.py will be executed. + + It only makes sense to call this function from within boot.py. -- cgit v1.2.3 From a78703f188f5caef33a0dc3230291c939f3c3034 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Sun, 16 Apr 2017 10:14:05 +0300 Subject: docs/library/machine: Typo fix in machine_callbacks section. --- docs/library/machine.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/library/machine.rst b/docs/library/machine.rst index dbf8b8b4c..ea11a1ff4 100644 --- a/docs/library/machine.rst +++ b/docs/library/machine.rst @@ -17,7 +17,7 @@ A note of callbacks used by functions and class methods of ``machine`` module: all these callbacks should be considered as executing in an interrupt context. This is true for both physical devices with IDs >= 0 and "virtual" devices with negative IDs like -1 (these "virtual" devices are still thin shims on -top of real hardware and real hardware intrerrupts). See :ref:`isr_rules`. +top of real hardware and real hardware interrupts). See :ref:`isr_rules`. Reset related functions ----------------------- -- cgit v1.2.3 From fabaa6143745cf09928dfc13367ddc91e0eb9ad2 Mon Sep 17 00:00:00 2001 From: Damien George Date: Tue, 18 Apr 2017 12:13:51 +1000 Subject: docs/library/machine.UART: Remove pyboard-specific section. stmhal doesn't have a machine.UART class so this section is not needed. --- docs/library/machine.UART.rst | 11 ----------- 1 file changed, 11 deletions(-) (limited to 'docs') diff --git a/docs/library/machine.UART.rst b/docs/library/machine.UART.rst index 55a5f354d..c29d079b7 100644 --- a/docs/library/machine.UART.rst +++ b/docs/library/machine.UART.rst @@ -32,17 +32,6 @@ using the standard stream methods:: uart.readinto(buf) # read and store into the given buffer uart.write('abc') # write the 3 characters -.. only:: port_pyboard - - Individual characters can be read/written using:: - - uart.readchar() # read 1 character and returns it as an integer - uart.writechar(42) # write 1 character - - To check if there is anything to be read, use:: - - uart.any() # returns True if any characters waiting - Constructors ------------ -- cgit v1.2.3 From 27f0862550fe9008d3a3b784ac31c105134f1a69 Mon Sep 17 00:00:00 2001 From: Damien George Date: Tue, 18 Apr 2017 13:20:07 +1000 Subject: docs/wipy/quickref: Update reference for change to I2C API. --- docs/wipy/quickref.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/wipy/quickref.rst b/docs/wipy/quickref.rst index 2505eb35f..f60c81f5f 100644 --- a/docs/wipy/quickref.rst +++ b/docs/wipy/quickref.rst @@ -112,7 +112,7 @@ See :ref:`machine.I2C `. :: from machine import I2C # configure the I2C bus - i2c = I2C(0, I2C.MASTER, baudrate=100000) + i2c = I2C(baudrate=100000) i2c.scan() # returns list of slave addresses i2c.writeto(0x42, 'hello') # send 5 bytes to slave with address 0x42 i2c.readfrom(0x42, 5) # receive 5 bytes from slave -- cgit v1.2.3 From c49b265389c487ebeb12290fcbf7c0af89cdb038 Mon Sep 17 00:00:00 2001 From: Damien George Date: Tue, 18 Apr 2017 15:04:30 +1000 Subject: docs/wipy/general: Add section about specifics of I2C implementation. --- docs/wipy/general.rst | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) (limited to 'docs') diff --git a/docs/wipy/general.rst b/docs/wipy/general.rst index b3d8e7892..8b9b91c53 100644 --- a/docs/wipy/general.rst +++ b/docs/wipy/general.rst @@ -240,6 +240,23 @@ Additional Pin methods: 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)`` +Additional details for machine.I2C +---------------------------------- + +On the WiPy there is a single hardware I2C peripheral, identified by "0". By +default this is the peripheral that is used when constructing an I2C instance. +The default pins are GP23 for SCL and GP13 for SDA, and one can create the +default I2C peripheral simply by doing:: + + i2c = machine.I2C() + +The pins and frequency can be specified as:: + + i2c = machine.I2C(freq=400000, scl='GP23', sda='GP13') + +Only certain pins can be used as SCL/SDA. Please refer to the pinout for further +information. + Known issues ------------ -- cgit v1.2.3 From 1f1a03d0c39f3b733372e523bc4906a2b40cfff0 Mon Sep 17 00:00:00 2001 From: Damien George Date: Tue, 18 Apr 2017 15:04:51 +1000 Subject: docs/library/machine.I2C: Deconditionalise all methods. The cc3200 port is now similar enough to the standard machine.I2C API so that all conditionals can be removed. --- docs/library/machine.I2C.rst | 104 +++++++++++++------------------------------ 1 file changed, 31 insertions(+), 73 deletions(-) (limited to 'docs') diff --git a/docs/library/machine.I2C.rst b/docs/library/machine.I2C.rst index 45944709e..e62d465e0 100644 --- a/docs/library/machine.I2C.rst +++ b/docs/library/machine.I2C.rst @@ -9,86 +9,55 @@ level it consists of 2 wires: SCL and SDA, the clock and data lines respectively I2C objects are created attached to a specific bus. They can be initialised when created, or initialised later on. -.. only:: port_wipy +Printing the I2C object gives you information about its configuration. - Example:: +Example usage:: - from machine import I2C + from machine import I2C - i2c = I2C(0) # create on bus 0 - i2c = I2C(0, I2C.MASTER) # create and init as a master - i2c.init(I2C.MASTER, baudrate=20000) # init as a master - i2c.deinit() # turn off the peripheral + i2c = I2C(freq=400000) # create I2C peripheral at frequency of 400kHz + # depending on the port, extra parameters may be required + # to select the peripheral and/or pins to use -Printing the i2c object gives you information about its configuration. + i2c.scan() # scan for slaves, returning a list of 7-bit addresses -.. only:: port_wipy + i2c.writeto(42, b'123') # write 3 bytes to slave with 7-bit address 42 + i2c.readfrom(42, 4) # read 4 bytes from slave with 7-bit address 42 - A master must specify the recipient's address:: - - i2c.init(I2C.MASTER) - i2c.writeto(0x42, '123') # send 3 bytes to slave with address 0x42 - i2c.writeto(addr=0x42, b'456') # keyword for address - - Master also has other methods:: - - i2c.scan() # scan for slaves on the bus, returning - # a list of valid addresses - i2c.readfrom_mem(0x42, 2, 3) # read 3 bytes from memory of slave 0x42, - # starting at address 2 in the slave - i2c.writeto_mem(0x42, 2, 'abc') # write 'abc' (3 bytes) to memory of slave 0x42 - # starting at address 2 in the slave, timeout after 1 second + i2c.readfrom_mem(42, 8, 3) # read 3 bytes from memory of slave 42, + # starting at memory-address 8 in the slave + i2c.writeto_mem(42, 2, b'\x10') # write 1 byte to memory of slave 42 + # starting at address 2 in the slave Constructors ------------ -.. only:: port_wipy - - .. 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). +.. class:: I2C(id=-1, \*, scl, sda, freq=400000) -.. only:: not port_wipy + Construct and return a new I2C object using the following parameters: - .. class:: I2C(id=-1, \*, scl, sda, freq=400000) - - Construct and return a new I2C object using the following parameters: - - - `id` identifies the particular I2C peripheral. The default - value of -1 selects a software implementation of I2C which can - work (in most cases) with arbitrary pins for SCL and SDA. - If `id` is -1 then `scl` and `sda` must be specified. Other - allowed values for `id` depend on the particular port/board, - and specifying `scl` and `sda` may or may not be required or - allowed in this case. - - `scl` should be a pin object specifying the pin to use for SCL. - - `sda` should be a pin object specifying the pin to use for SDA. - - `freq` should be an integer which sets the maximum frequency - for SCL. + - `id` identifies the particular I2C peripheral. The default + value of -1 selects a software implementation of I2C which can + work (in most cases) with arbitrary pins for SCL and SDA. + If `id` is -1 then `scl` and `sda` must be specified. Other + allowed values for `id` depend on the particular port/board, + and specifying `scl` and `sda` may or may not be required or + allowed in this case. + - `scl` should be a pin object specifying the pin to use for SCL. + - `sda` should be a pin object specifying the pin to use for SDA. + - `freq` should be an integer which sets the maximum frequency + for SCL. General Methods --------------- -.. only:: port_wipy - - .. method:: I2C.init(mode, \*, baudrate=100000, pins=(SDA, SCL)) - - Initialise the I2C bus with the given parameters: +.. method:: I2C.init(scl, sda, \*, freq=400000) - - ``mode`` must be ``I2C.MASTER`` - - ``baudrate`` is the SCL clock rate - - ``pins`` is an optional tuple with the pins to assign to the I2C bus. + Initialise the I2C bus with the given arguments: -.. only:: port_esp8266 - - .. method:: I2C.init(scl, sda, \*, freq=400000) - - Initialise the I2C bus with the given arguments: - - - `scl` is a pin object for the SCL line - - `sda` is a pin object for the SDA line - - `freq` is the SCL clock rate + - `scl` is a pin object for the SCL line + - `sda` is a pin object for the SDA line + - `freq` is the SCL clock rate .. method:: I2C.deinit() @@ -102,8 +71,6 @@ General Methods those that respond. A device responds if it pulls the SDA line low after its address (including a write bit) is sent on the bus. - Note: on WiPy the I2C object must be in master mode for this method to be valid. - Primitive I2C operations ------------------------ @@ -204,12 +171,3 @@ methods are convenience functions to communicate with such devices. On WiPy the return value is the number of bytes written. Otherwise the return value is `None`. - -Constants ---------- - -.. data:: I2C.MASTER - - for initialising the bus to master mode - - Availability: WiPy. -- cgit v1.2.3 From d4675e7674788546420ac6a89a42f8afda191488 Mon Sep 17 00:00:00 2001 From: Damien George Date: Tue, 18 Apr 2017 15:27:37 +1000 Subject: docs/library/machine.*: Add cross-reference label to individual classes. --- 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') diff --git a/docs/library/machine.ADC.rst b/docs/library/machine.ADC.rst index 2752878ff..4c7a04d74 100644 --- a/docs/library/machine.ADC.rst +++ b/docs/library/machine.ADC.rst @@ -1,4 +1,5 @@ .. 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 e62d465e0..e2eb62ca3 100644 --- a/docs/library/machine.I2C.rst +++ b/docs/library/machine.I2C.rst @@ -1,4 +1,5 @@ .. 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 216ebcb2a..369c08f44 100644 --- a/docs/library/machine.Pin.rst +++ b/docs/library/machine.Pin.rst @@ -1,4 +1,5 @@ .. 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 6dc8b3e9a..2a53b9146 100644 --- a/docs/library/machine.RTC.rst +++ b/docs/library/machine.RTC.rst @@ -1,4 +1,5 @@ .. currentmodule:: machine +.. _machine.RTC: class RTC -- real time clock ============================ diff --git a/docs/library/machine.SD.rst b/docs/library/machine.SD.rst index 21c28aa20..0eb024602 100644 --- a/docs/library/machine.SD.rst +++ b/docs/library/machine.SD.rst @@ -1,4 +1,5 @@ .. 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 82858629f..fbb44d038 100644 --- a/docs/library/machine.SPI.rst +++ b/docs/library/machine.SPI.rst @@ -1,4 +1,5 @@ .. currentmodule:: machine +.. _machine.SPI: class SPI -- a Serial Peripheral Interface bus protocol (master side) ===================================================================== diff --git a/docs/library/machine.Timer.rst b/docs/library/machine.Timer.rst index eddb2ce78..ef46f9dd7 100644 --- a/docs/library/machine.Timer.rst +++ b/docs/library/machine.Timer.rst @@ -1,4 +1,5 @@ .. currentmodule:: machine +.. _machine.Timer: class Timer -- control hardware timers ====================================== diff --git a/docs/library/machine.UART.rst b/docs/library/machine.UART.rst index c29d079b7..0b2ebbd0b 100644 --- a/docs/library/machine.UART.rst +++ b/docs/library/machine.UART.rst @@ -1,4 +1,5 @@ .. 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 1d79b4c4e..5ca6dce45 100644 --- a/docs/library/machine.WDT.rst +++ b/docs/library/machine.WDT.rst @@ -1,4 +1,5 @@ .. currentmodule:: machine +.. _machine.WDT: class WDT -- watchdog timer =========================== -- cgit v1.2.3 From daa5ba5629c8211a3f13e3854acea0bc36071f56 Mon Sep 17 00:00:00 2001 From: Damien George Date: Tue, 18 Apr 2017 15:28:18 +1000 Subject: docs/esp8266/quickref: Add links from quickref page to machine classes. --- docs/esp8266/quickref.rst | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) (limited to 'docs') diff --git a/docs/esp8266/quickref.rst b/docs/esp8266/quickref.rst index 845a94ba7..5ff33e02b 100644 --- a/docs/esp8266/quickref.rst +++ b/docs/esp8266/quickref.rst @@ -88,7 +88,7 @@ Use the :mod:`time ` module:: Timers ------ -Virtual (RTOS-based) timers are supported. Use the ``machine.Timer`` class +Virtual (RTOS-based) timers are supported. Use the :ref:`machine.Timer ` class with timer ID of -1:: from machine import Timer @@ -102,7 +102,7 @@ The period is in milliseconds. Pins and GPIO ------------- -Use the ``machine.Pin`` class:: +Use the :ref:`machine.Pin ` class:: from machine import Pin @@ -155,7 +155,7 @@ ADC (analog to digital conversion) ADC is available on a dedicated pin. Note that input voltages on the ADC pin must be between 0v and 1.0v. -Use the ``machine.ADC`` class:: +Use the :ref:`machine.ADC ` class:: from machine import ADC @@ -166,7 +166,8 @@ Software SPI bus ---------------- There are two SPI drivers. One is implemented in software (bit-banging) -and works on all pins:: +and works on all pins, and is accessed via the :ref:`machine.SPI ` +class:: from machine import Pin, SPI @@ -208,7 +209,8 @@ constructor and init (as those are fixed):: I2C bus ------- -The I2C driver is implemented in software and works on all pins:: +The I2C driver is implemented in software and works on all pins, +and is accessed via the :ref:`machine.I2C ` class:: from machine import Pin, I2C -- cgit v1.2.3 From 850f79e552a170912cfd88f5001a9ac343a22f5d Mon Sep 17 00:00:00 2001 From: Damien George Date: Tue, 18 Apr 2017 15:39:27 +1000 Subject: docs/library/machine.I2C: Remove WiPy-specific return values. cc3200 has been updated to conform to the API and now returns None. --- docs/library/machine.I2C.rst | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/library/machine.I2C.rst b/docs/library/machine.I2C.rst index e2eb62ca3..a1b417890 100644 --- a/docs/library/machine.I2C.rst +++ b/docs/library/machine.I2C.rst @@ -160,8 +160,7 @@ methods are convenience functions to communicate with such devices. The argument `addrsize` specifies the address size in bits (on ESP8266 this argument is not recognised and the address size is always 8 bits). - On WiPy the return value is the number of bytes read. Otherwise the - return value is `None`. + The method returns `None`. .. method:: I2C.writeto_mem(addr, memaddr, buf, \*, addrsize=8) @@ -170,5 +169,4 @@ methods are convenience functions to communicate with such devices. The argument `addrsize` specifies the address size in bits (on ESP8266 this argument is not recognised and the address size is always 8 bits). - On WiPy the return value is the number of bytes written. Otherwise the - return value is `None`. + The method returns `None`. -- cgit v1.2.3 From 29b26f392283edbdd18808d450ab7dd649dbc200 Mon Sep 17 00:00:00 2001 From: Damien George Date: Tue, 18 Apr 2017 15:40:04 +1000 Subject: docs/library/machine.SPI: Fix formatting of bullet list to stop warning. --- docs/library/machine.SPI.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/library/machine.SPI.rst b/docs/library/machine.SPI.rst index fbb44d038..080f6fdfb 100644 --- a/docs/library/machine.SPI.rst +++ b/docs/library/machine.SPI.rst @@ -45,7 +45,7 @@ Methods a hardware SPI block. Arbitrary pin assignments are possible only for a bitbanging SPI driver (``id`` = -1). - ``pins`` - WiPy port doesn't ``sck``, ``mosi``, ``miso`` arguments, and instead allows to - specify them as a tuple of ``pins`` parameter. + specify them as a tuple of ``pins`` parameter. .. method:: SPI.deinit() -- cgit v1.2.3 From 6d221fe284f977dbf55fd4668efae281b045c237 Mon Sep 17 00:00:00 2001 From: Damien George Date: Wed, 10 May 2017 12:44:21 +1000 Subject: docs/library/uos: Add description of uos.ilistdir() function. --- docs/library/uos.rst | 15 +++++++++++++++ 1 file changed, 15 insertions(+) (limited to 'docs') diff --git a/docs/library/uos.rst b/docs/library/uos.rst index e1ea72967..d1f83d2cc 100644 --- a/docs/library/uos.rst +++ b/docs/library/uos.rst @@ -37,6 +37,21 @@ Functions Get the current directory. +.. function:: ilistdir([dir]) + + This function returns an iterator which then yields 3-tuples corresponding to + the entries in the directory that it is listing. With no argument it lists the + current directory, otherwise it lists the directory given by `dir`. + + The 3-tuples have the form `(name, type, inode)`: + + - `name` is a string (or bytes if `dir` is a bytes object) and is the name of + the entry; + - `type` is an integer that specifies the type of the entry, with 0x4000 for + directories and 0x8000 for regular files; + - `inode` is an integer corresponding to the inode of the file, and may be 0 + for filesystems that don't have such a notion. + .. function:: listdir([dir]) With no argument, list the current directory. Otherwise list the given directory. -- cgit v1.2.3 From c19f07bd52aeb59ac8bdfa1e575e2323f6a14c6e Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Sun, 14 May 2017 22:52:16 +0300 Subject: docs/machine.Pin: There's no toggle() method in MicroPython hardware API. May be a port-specific method, not portable, not part of the official specification. --- docs/library/machine.Pin.rst | 9 --------- 1 file changed, 9 deletions(-) (limited to 'docs') diff --git a/docs/library/machine.Pin.rst b/docs/library/machine.Pin.rst index 369c08f44..6d6ba7bfd 100644 --- a/docs/library/machine.Pin.rst +++ b/docs/library/machine.Pin.rst @@ -158,15 +158,6 @@ Methods and get the value of the pin. It is equivalent to Pin.value([x]). See :meth:`Pin.value` for more details. -.. method:: Pin.toggle() - - Toggle the output value of the pin. Equivalent to ``pin.value(not pin.out_value())``. - Returns ``None``. - - Not all ports implement this method. - - Availability: WiPy. - .. method:: Pin.id() Get the pin identifier. This may return the ``id`` as specified in the -- cgit v1.2.3 From 0ba136fbe9bf2f20555480ef4de1778e48ea3105 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Sun, 14 May 2017 23:12:06 +0300 Subject: docs/machine.Signal: Add initial draft description of Signal class. --- docs/library/machine.Signal.rst | 96 +++++++++++++++++++++++++++++++++++++++++ docs/library/machine.rst | 1 + 2 files changed, 97 insertions(+) create mode 100644 docs/library/machine.Signal.rst (limited to 'docs') diff --git a/docs/library/machine.Signal.rst b/docs/library/machine.Signal.rst new file mode 100644 index 000000000..486908627 --- /dev/null +++ b/docs/library/machine.Signal.rst @@ -0,0 +1,96 @@ +.. currentmodule:: machine +.. _machine.Signal: + +class Signal -- control and sense external I/O devices +====================================================== + +The Signal class is a simple extension of Pin class. Unlike Pin, which +can be only in "absolute" 0 and 1 states, a Signal can be in "asserted" +(on) or "deasserted" (off) states, while being inverted (active-low) or +not. Summing up, it adds logical inversion support to Pin functionality. +While this may seem a simple addition, it is exactly what is needed to +support wide array of simple digital devices in a way portable across +different boards, which is one of the major MicroPython goals. Regardless +whether different users have an active-high or active-low LED, a normally +open or normally closed relay - you can develop single, nicely looking +application which works with each of them, and capture hardware +configuration differences in few lines on the config file of your app. + +Following is the guide when Signal vs Pin should be used: + +* Use Signal: If you want to control a simple on/off (including software + PWM!) devices like LEDs, multi-segment indicators, relays, buzzers, or + read simple binary sensors, like normally open or normally closed buttons, + pulled high or low, Reed switches, moisture/flame detectors, etc. etc. + Summing up, if you have a real physical device/sensor requiring GPIO + access, you likely should use a Signal. + +* Use Pin: If you implement a higher-level protocol or bus to communicate + with more complex devices. + +The split between Pin and Signal come from the usecases above and the +architecture of MicroPython: Pin offers the lowest overhead, which may +be important when bit-banging protocols. But Signal adds additional +flexibility on top of Pin, at the cost of minor overhead (much smaller +than if you implemented active-high vs active-low device differences in +Python manually!). Also, Pin is low-level object which needs to be +implemented for each support board, while Signal is a high-level object +which comes for free once Pin is implemented. + +If in doubt, give the Signal a try! Once again, it is developed to save +developers from the need to handle unexciting differences like active-low +vs active-high signals, and allow other users to share and enjoy your +application, instead of being frustrated by the fact that it doesn't +work for them simply because their LEDs or relays are wired in a slightly +different way. + +Constructors +------------ + +.. class:: Signal(pin_obj, invert=False) + Signal(pin_arguments..., \*, invert=False) + + Create a Signal object. There're two ways to create it: + + * By wrapping existing Pin object - universal method which works for + any board. + * By passing required Pin parameters directly to Signal constructor, + skipping the need to create intermediate Pin object. Available on + many, but not all boards. + + The arguments are: + + - ``pin_obj`` is existing Pin object. + + - ``pin_arguments`` are the same arguments as can be passed to Pin constructor. + + - ``invert`` - if True, the signal will be inverted (active low). + +Methods +------- + +.. method:: Signal.value([x]) + + This method allows to set and get the value of the signal, depending on whether + the argument ``x`` is supplied or not. + + If the argument is omitted then this method gets the signal level, 1 meaning + signal is asserted (active) and 0 - signal inactive. + + If the argument is supplied then this method sets the signal level. The + argument ``x`` can be anything that converts to a boolean. If it converts + to ``True``, the signal is active, otherwise it is inactive. + + Correspondence between signal being active and actual logic level on the + underlying pin depends on whether signal is inverted (active-low) or not. + For non-inverted signal, active status corresponds to logical 1, inactive - + to logical 0. For inverted/active-low signal, active status corresponds + to logical 0, while inactive - to logical 1. + +.. method:: Signal.on() + + Activate signal. + +.. method:: Signal.off() + + Deactivate signal. diff --git a/docs/library/machine.rst b/docs/library/machine.rst index ea11a1ff4..c2c6b83fd 100644 --- a/docs/library/machine.rst +++ b/docs/library/machine.rst @@ -147,6 +147,7 @@ Classes machine.I2C.rst machine.Pin.rst + machine.Signal.rst machine.RTC.rst machine.SPI.rst machine.Timer.rst -- cgit v1.2.3 From d5713c8618e8d809f354b6be72b7410dc5ac840a Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Mon, 15 May 2017 00:26:44 +0300 Subject: docs/library/index: Add important summary of the intro section as warning. To make them harder to miss. --- docs/library/index.rst | 11 +++++++++++ 1 file changed, 11 insertions(+) (limited to 'docs') diff --git a/docs/library/index.rst b/docs/library/index.rst index 1a61f6882..770920a1f 100644 --- a/docs/library/index.rst +++ b/docs/library/index.rst @@ -1,6 +1,17 @@ MicroPython libraries ===================== +.. warning:: + + Important summary of this section + + * MicroPython implements a subset of Python functionality for each module. + * To ease extensibility, MicroPython versions of standard Python modules + usually have ``u`` (micro) prefix. + * Any particular MicroPython variant or port may miss any feature/function + described in this general documentation, due to resource constraints. + + This chapter describes modules (function and class libraries) which are built into MicroPython. There are a few categories of modules: -- cgit v1.2.3 From e4a53570d08643d62ba8e2b72919ae1693162e9a Mon Sep 17 00:00:00 2001 From: Damien George Date: Wed, 17 May 2017 12:38:33 +1000 Subject: docs: Change single occurrence of "Micropython" to "MicroPython". --- docs/topindex.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/topindex.html b/docs/topindex.html index 3cbf21615..f32f3cea6 100644 --- a/docs/topindex.html +++ b/docs/topindex.html @@ -48,7 +48,7 @@ {% endif %}

- Micropython Differences
+ MicroPython Differences
MicroPython operations which differ from CPython

-- cgit v1.2.3 From f351c6db5e4c0bf75d5d647e69a047da739606a8 Mon Sep 17 00:00:00 2001 From: Damien George Date: Wed, 17 May 2017 19:53:13 +1000 Subject: drivers/display/lcd160cr: Fix get_line method and enhance screen_dump. The docs are updated and describe the new behaviour of these methods. --- docs/library/lcd160cr.rst | 18 +++++++++++++----- drivers/display/lcd160cr.py | 38 +++++++++++++++++++++++--------------- 2 files changed, 36 insertions(+), 20 deletions(-) (limited to 'docs') diff --git a/docs/library/lcd160cr.rst b/docs/library/lcd160cr.rst index 76828d32d..bd4741298 100644 --- a/docs/library/lcd160cr.rst +++ b/docs/library/lcd160cr.rst @@ -150,11 +150,19 @@ The following methods manipulate individual pixels on the display. .. method:: LCD160CR.get_line(x, y, buf) - Get a line of pixels into the given buffer. - -.. method:: LCD160CR.screen_dump(buf) - - Dump the entire screen to the given buffer. + Low-level method to get a line of pixels into the given buffer. + To read `n` pixels `buf` should be `2*n+1` bytes in length. The first byte + is a dummy byte and should be ignored, and subsequent bytes represent the + pixels in the line starting at coordinate `(x, y)`. + +.. method:: LCD160CR.screen_dump(buf, x=0, y=0, w=None, h=None) + + Dump the contents of the screen to the given buffer. The parameters `x` and `y` + specify the starting coordinate, and `w` and `h` the size of the region. If `w` + or `h` are `None` then they will take on their maximum values, set by the size + of the screen minus the given `x` and `y` values. `buf` should be large enough + to hold `2*w*h` bytes. If it's smaller then only the initial horizontal lines + will be stored. .. method:: LCD160CR.screen_load(buf) diff --git a/drivers/display/lcd160cr.py b/drivers/display/lcd160cr.py index 0cf52f2ef..dd9ab9985 100644 --- a/drivers/display/lcd160cr.py +++ b/drivers/display/lcd160cr.py @@ -257,6 +257,7 @@ class LCD160CR: def get_line(self, x, y, buf): l = len(buf) // 2 self._fcmd2b(' self.h: - h = self.h - for i in range(h): - ix = i * self.w * 2 - self.get_line(0, i, line) - for j in range(1, len(line)): - buf[ix] = line[j] - ix += 1 - self.get_line(self.w // 2, i, line) - for j in range(1, len(line)): - buf[ix] = line[j] - ix += 1 + def screen_dump(self, buf, x=0, y=0, w=None, h=None): + if w is None: + w = self.w - x + if h is None: + h = self.h - y + if w <= 127: + line = bytearray(2 * w + 1) + line2 = None + else: + # split line if more than 254 bytes needed + buflen = (w + 1) // 2 + line = bytearray(2 * buflen + 1) + line2 = memoryview(line)[:2 * (w - buflen) + 1] + for i in range(min(len(buf) // (2 * w), h)): + ix = i * w * 2 + self.get_line(x, y + i, line) + buf[ix:ix + len(line) - 1] = memoryview(line)[1:] + ix += len(line) - 1 + if line2: + self.get_line(x + buflen, y + i, line2) + buf[ix:ix + len(line2) - 1] = memoryview(line2)[1:] + ix += len(line2) - 1 def screen_load(self, buf): l = self.w * self.h * 2+2 -- cgit v1.2.3 From d007351b3377f97316c4af2adcec164fb5e56dca Mon Sep 17 00:00:00 2001 From: Damien George Date: Thu, 18 May 2017 00:25:09 +1000 Subject: docs/library/micropython: Document the newer micropython functions. --- docs/library/micropython.rst | 79 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 79 insertions(+) (limited to 'docs') diff --git a/docs/library/micropython.rst b/docs/library/micropython.rst index 967f822ec..7f4002856 100644 --- a/docs/library/micropython.rst +++ b/docs/library/micropython.rst @@ -7,6 +7,32 @@ Functions --------- +.. function:: const(expr) + + Used to declare that the expression is a constant so that the compile can + optimise it. The use of this function should be as follows:: + + from micropython import const + + CONST_X = const(123) + CONST_Y = const(2 * CONST_X + 1) + + Constants declared this way are still accessible as global variables from + outside the module they are declared in. On the other hand, if a constant + begins with an underscore then it is hidden, it is not available as a global + variable, and does not take up any memory during execution. + + This `const` function is recognised directly by the MicroPython parser and is + provided as part of the `micropython` module mainly so that scripts can be + written which run under both CPython and MicroPython, by following the above + pattern. + +.. function:: opt_level([level]) + + If `level` is given then this function sets the optimisation level for subsequent + compilation of scripts, and returns `None`. Otherwise it returns the current + optimisation level. + .. function:: alloc_emergency_exception_buf(size) Allocate ``size`` bytes of RAM for the emergency exception buffer (a good @@ -35,3 +61,56 @@ Functions The information that is printed is implementation dependent, but currently includes the number of interned strings and the amount of RAM they use. In verbose mode it prints out the names of all RAM-interned strings. + +.. function:: stack_use() + + Return an integer representing the current amount of stack that is being + used. The absolute value of this is not particularly useful, rather it + should be used to compute differences in stack usage at different points. + +.. function:: heap_lock() +.. function:: heap_unlock() + + Lock or unlock the heap. When locked no memory allocation can occur and a + `MemoryError` will be raised if any heap allocation is attempted. + + These functions can be nested, ie `heap_lock()` can be called multiple times + in a row and the lock-depth will increase, and then `heap_unlock()` must be + called the same number of times to make the heap available again. + +.. function:: kbd_intr(chr) + + Set the character that will raise a `KeyboardInterrupt` exception. By + default this is set to 3 during script execution, corresponding to Ctrl-C. + Passing -1 to this function will disable capture of Ctrl-C, and passing 3 + will restore it. + + This function can be used to prevent the capturing of Ctrl-C on the + incoming stream of characters that is usually used for the REPL, in case + that stream is used for other purposes. + +.. function:: schedule(fun, arg) + + Schedule the function `fun` to be executed "very soon". The function + is passed the value `arg` as its single argument. "very soon" means that + the MicroPython runtime will do its best to execute the function at the + earliest possible time, given that it is also trying to be efficient, and + that the following conditions hold: + + - A scheduled function will never preempt another scheduled function. + - Scheduled functions are always executed "between opcodes" which means + that all fundamental Python operations (such as appending to a list) + are guaranteed to be atomic. + - A given port may define "critical regions" within which scheduled + functions will never be executed. Functions may be scheduled within + a critical region but they will not be executed until that region + is exited. An example of a critical region is a preempting interrupt + handler (an IRQ). + + A use for this function is to schedule a callback from a preempting IRQ. + Such an IRQ puts restrictions on the code that runs in the IRQ (for example + the heap may be locked) and scheduling a function to call later will lift + those restrictions. + + There is a finite stack to hold the scheduled functions and `schedule` + will raise a `RuntimeError` if the stack is full. -- cgit v1.2.3 From 436d97b3f9230b882fd152f36433a26832a0634b Mon Sep 17 00:00:00 2001 From: Damien George Date: Wed, 17 May 2017 17:24:59 +1000 Subject: docs/library/machine.UART: Update and improve uart.any() docs. --- docs/library/machine.UART.rst | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/library/machine.UART.rst b/docs/library/machine.UART.rst index 0b2ebbd0b..f9c8efef7 100644 --- a/docs/library/machine.UART.rst +++ b/docs/library/machine.UART.rst @@ -65,8 +65,16 @@ Methods .. method:: UART.any() - Return true value if there're characters available for reading. On some - boards, the number of available characters is returned. + Returns an integer counting the number of characters that can be read without + blocking. It will return 0 if there are no characters available and a positive + number if there are characters. The method may return 1 even if there is more + than one character available for reading. + + For more sophisticated querying of available characters use select.poll:: + + poll = select.poll() + poll.register(uart, select.POLLIN) + poll.poll(timeout) .. method:: UART.read([nbytes]) -- cgit v1.2.3 From 3ebd67fc099161b43b61fd18e8e98b8274ebe9b4 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Sun, 21 May 2017 15:50:16 +0300 Subject: library/machine.Pin: Remove .id() method and .board class attr. Both aren't part of generic Hardware API: It's impossible to implement .id() method in a generic case (e.g., when Pin is instantiated by the underlying OS/RTOS). .board attribute is an obvious space hog which instead can be implemented on Python level if needed. --- docs/library/machine.Pin.rst | 18 ------------------ 1 file changed, 18 deletions(-) (limited to 'docs') diff --git a/docs/library/machine.Pin.rst b/docs/library/machine.Pin.rst index 6d6ba7bfd..2efd84688 100644 --- a/docs/library/machine.Pin.rst +++ b/docs/library/machine.Pin.rst @@ -158,11 +158,6 @@ Methods and get the value of the pin. It is equivalent to Pin.value([x]). See :meth:`Pin.value` for more details. -.. method:: Pin.id() - - Get the pin identifier. This may return the ``id`` as specified in the - constructor. Or it may return a canonical software-specific pin id. - .. method:: Pin.mode([mode]) Get or set the pin mode. @@ -217,19 +212,6 @@ Methods This method returns a callback object. -Attributes ----------- - -.. class:: Pin.board - - Contains all ``Pin`` objects supported by the board. Examples:: - - Pin.board.GP25 - led = Pin(Pin.board.GP25, mode=Pin.OUT) - Pin.board.GP2.alt_list() - - Availability: WiPy. - Constants --------- -- cgit v1.2.3 From 825460a093a6bcd8fb79119b5f6ee8408f63603b Mon Sep 17 00:00:00 2001 From: Damien George Date: Fri, 26 May 2017 19:07:37 +1000 Subject: docs: Bump version to 1.9. --- docs/conf.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/conf.py b/docs/conf.py index 66ea325e9..e813f2383 100755 --- a/docs/conf.py +++ b/docs/conf.py @@ -97,9 +97,9 @@ copyright = '2014-2017, Damien P. George, Paul Sokolovsky, and contributors' # built documents. # # The short X.Y version. -version = '1.8' +version = '1.9' # The full version, including alpha/beta/rc tags. -release = '1.8.7' +release = '1.9' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. -- cgit v1.2.3 From ca16c3821053e5bf2b87aeb10007f73f31dc1eac Mon Sep 17 00:00:00 2001 From: Ville Skyttä Date: Mon, 29 May 2017 10:08:14 +0300 Subject: various: Spelling fixes --- cc3200/README.md | 2 +- docs/library/btree.rst | 2 +- docs/library/machine.SD.rst | 2 +- docs/library/machine.UART.rst | 2 +- docs/library/uhashlib.rst | 4 ++-- docs/library/utime.rst | 4 ++-- docs/sphinx_selective_exclude/README.md | 2 +- docs/sphinx_selective_exclude/modindex_exclude.py | 2 +- esp8266/README.md | 2 +- esp8266/machine_rtc.c | 2 +- examples/conwaylife.py | 4 ++-- examples/embedding/Makefile.upylib | 2 +- examples/embedding/README.md | 2 +- extmod/modlwip.c | 4 ++-- extmod/modwebsocket.c | 2 +- lib/timeutils/timeutils.c | 2 +- lib/utils/stdout_helpers.c | 2 +- py/asmthumb.c | 2 +- py/builtinimport.c | 4 ++-- py/compile.c | 4 ++-- py/misc.h | 2 +- py/mkenv.mk | 2 +- py/mpconfig.h | 2 +- py/obj.c | 2 +- py/objstr.c | 4 ++-- py/py.mk | 2 +- py/ringbuf.h | 2 +- py/stream.c | 2 +- py/vm.c | 4 ++-- qemu-arm/README.md | 2 +- tests/basics/namedtuple1.py | 2 +- tests/basics/try_reraise2.py | 2 +- tests/pyb/can.py | 2 +- tests/thread/stress_aes.py | 2 +- tests/wipy/uart.py | 2 +- tools/insert-usb-ids.py | 2 +- tools/pyboard.py | 2 +- unix/Makefile | 2 +- unix/modsocket.c | 2 +- windows/windows_mphal.c | 2 +- zephyr/modutime.c | 2 +- 41 files changed, 49 insertions(+), 49 deletions(-) (limited to 'docs') diff --git a/cc3200/README.md b/cc3200/README.md index 753fd450a..53cad3ba0 100644 --- a/cc3200/README.md +++ b/cc3200/README.md @@ -138,7 +138,7 @@ If `WIPY_IP`, `WIPY_USER` or `WIPY_PWD` are omitted the default values (the ones ## Regarding old revisions of the CC3200-LAUNCHXL First silicon (pre-release) revisions of the CC3200 had issues with the ram blocks, and MicroPython cannot run -there. Make sure to use a **v4.1 (or higer) LAUNCHXL board** when trying this port, otherwise it won't work. +there. Make sure to use a **v4.1 (or higher) LAUNCHXL board** when trying this port, otherwise it won't work. ### Note regarding FileZilla diff --git a/docs/library/btree.rst b/docs/library/btree.rst index aebcbc160..bd7890586 100644 --- a/docs/library/btree.rst +++ b/docs/library/btree.rst @@ -69,7 +69,7 @@ Functions Open a database from a random-access `stream` (like an open file). All other parameters are optional and keyword-only, and allow to tweak advanced - paramters of the database operation (most users will not need them): + parameters of the database operation (most users will not need them): * `flags` - Currently unused. * `cachesize` - Suggested maximum memory cache size in bytes. For a diff --git a/docs/library/machine.SD.rst b/docs/library/machine.SD.rst index 0eb024602..608e95831 100644 --- a/docs/library/machine.SD.rst +++ b/docs/library/machine.SD.rst @@ -34,7 +34,7 @@ Methods .. method:: SD.init(id=0, pins=('GP10', 'GP11', 'GP15')) - Enable the SD card. In order to initalize the card, give it a 3-tuple: + Enable the SD card. In order to initialize the card, give it a 3-tuple: ``(clk_pin, cmd_pin, dat0_pin)``. .. method:: SD.deinit() diff --git a/docs/library/machine.UART.rst b/docs/library/machine.UART.rst index f9c8efef7..64ff28e1a 100644 --- a/docs/library/machine.UART.rst +++ b/docs/library/machine.UART.rst @@ -16,7 +16,7 @@ UART objects can be created and initialised using:: uart = UART(1, 9600) # init with given baudrate uart.init(9600, bits=8, parity=None, stop=1) # init with given parameters -Supported paramters differ on a board: +Supported parameters differ on a board: Pyboard: Bits can be 7, 8 or 9. Stop can be 1 or 2. With `parity=None`, only 8 and 9 bits are supported. With parity enabled, only 7 and 8 bits diff --git a/docs/library/uhashlib.rst b/docs/library/uhashlib.rst index cd0216dae..6b9a764ba 100644 --- a/docs/library/uhashlib.rst +++ b/docs/library/uhashlib.rst @@ -15,11 +15,11 @@ be implemented: * SHA1 - A previous generation algorithm. Not recommended for new usages, but SHA1 is a part of number of Internet standards and existing - applications, so boards targetting network connectivity and + applications, so boards targeting network connectivity and interoperatiability will try to provide this. * MD5 - A legacy algorithm, not considered cryptographically secure. Only - selected boards, targetting interoperatibility with legacy applications, + selected boards, targeting interoperatibility with legacy applications, will offer this. Constructors diff --git a/docs/library/utime.rst b/docs/library/utime.rst index 871f6c678..f3a067cde 100644 --- a/docs/library/utime.rst +++ b/docs/library/utime.rst @@ -146,8 +146,8 @@ Functions too distant inbetween, see below). The function returns **signed** value in the range [``-TICKS_PERIOD/2`` .. ``TICKS_PERIOD/2-1``] (that's a typical range definition for two's-complement signed binary integers). If the result is negative, it means that - ``ticks1`` occured earlier in time than ``ticks2``. Otherwise, it means that - ``ticks1`` occured after ``ticks2``. This holds ``only`` if ``ticks1`` and ``ticks2`` + ``ticks1`` occurred earlier in time than ``ticks2``. Otherwise, it means that + ``ticks1`` occurred after ``ticks2``. This holds ``only`` if ``ticks1`` and ``ticks2`` are apart from each other for no more than ``TICKS_PERIOD/2-1`` ticks. If that does not hold, incorrect result will be returned. Specifically, if two tick values are apart for ``TICKS_PERIOD/2-1`` ticks, that value will be returned by the function. diff --git a/docs/sphinx_selective_exclude/README.md b/docs/sphinx_selective_exclude/README.md index cc9725c21..dab140739 100644 --- a/docs/sphinx_selective_exclude/README.md +++ b/docs/sphinx_selective_exclude/README.md @@ -66,7 +66,7 @@ index for PDF, just the same as for HTML. search_auto_exclude ------------------- -Even if you exclude soem documents from toctree:: using only:: +Even if you exclude some documents from toctree:: using only:: directive, they will be indexed for full-text search, so user may find them and get confused. This plugin follows very simple idea that if you didn't include some documents in the toctree, then diff --git a/docs/sphinx_selective_exclude/modindex_exclude.py b/docs/sphinx_selective_exclude/modindex_exclude.py index 18b49cc80..bf8db795e 100644 --- a/docs/sphinx_selective_exclude/modindex_exclude.py +++ b/docs/sphinx_selective_exclude/modindex_exclude.py @@ -2,7 +2,7 @@ # This is a Sphinx documentation tool extension which allows to # exclude some Python modules from the generated indexes. Modules # are excluded both from "modindex" and "genindex" index tables -# (in the latter case, all members of a module are exlcuded). +# (in the latter case, all members of a module are excluded). # To control exclusion, set "modindex_exclude" variable in Sphinx # conf.py to the list of modules to exclude. Note: these should be # modules (as defined by py:module directive, not just raw filenames). diff --git a/esp8266/README.md b/esp8266/README.md index 897bb4737..d717d26fe 100644 --- a/esp8266/README.md +++ b/esp8266/README.md @@ -100,7 +100,7 @@ programming). __WiFi__ -Initally, the device configures itself as a WiFi access point (AP). +Initially, the device configures itself as a WiFi access point (AP). - ESSID: MicroPython-xxxxxx (x’s are replaced with part of the MAC address). - Password: micropythoN (note the upper-case N). - IP address of the board: 192.168.4.1. diff --git a/esp8266/machine_rtc.c b/esp8266/machine_rtc.c index 019b705ba..b17bcb261 100644 --- a/esp8266/machine_rtc.c +++ b/esp8266/machine_rtc.c @@ -93,7 +93,7 @@ void pyb_rtc_set_us_since_2000(uint64_t nowus) { int64_t delta = nowus - (((uint64_t)rtc_last_ticks * cal) >> 12); // As the calibration value jitters quite a bit, to make the - // clock at least somewhat practially usable, we need to store it + // clock at least somewhat practically usable, we need to store it system_rtc_mem_write(MEM_CAL_ADDR, &cal, sizeof(cal)); system_rtc_mem_write(MEM_DELTA_ADDR, &delta, sizeof(delta)); }; diff --git a/examples/conwaylife.py b/examples/conwaylife.py index f99796175..323f42e85 100644 --- a/examples/conwaylife.py +++ b/examples/conwaylife.py @@ -8,7 +8,7 @@ lcd.light(1) def conway_step(): for x in range(128): # loop over x coordinates for y in range(32): # loop over y coordinates - # count number of neigbours + # count number of neighbours num_neighbours = (lcd.get(x - 1, y - 1) + lcd.get(x, y - 1) + lcd.get(x + 1, y - 1) + @@ -25,7 +25,7 @@ def conway_step(): if self and not (2 <= num_neighbours <= 3): lcd.pixel(x, y, 0) # not enough, or too many neighbours: cell dies elif not self and num_neighbours == 3: - lcd.pixel(x, y, 1) # exactly 3 neigbours around an empty cell: cell is born + lcd.pixel(x, y, 1) # exactly 3 neighbours around an empty cell: cell is born # randomise the start def conway_rand(): diff --git a/examples/embedding/Makefile.upylib b/examples/embedding/Makefile.upylib index 873c0fd34..4663ad30a 100644 --- a/examples/embedding/Makefile.upylib +++ b/examples/embedding/Makefile.upylib @@ -170,7 +170,7 @@ SRC_QSTR_AUTO_DEPS += include $(MPTOP)/py/mkrules.mk # Value of configure's --host= option (required for cross-compilation). -# Deduce it from CROSS_COMPILE by default, but can be overriden. +# Deduce it from CROSS_COMPILE by default, but can be overridden. ifneq ($(CROSS_COMPILE),) CROSS_COMPILE_HOST = --host=$(patsubst %-,%,$(CROSS_COMPILE)) else diff --git a/examples/embedding/README.md b/examples/embedding/README.md index 989ce1fc8..804dfede6 100644 --- a/examples/embedding/README.md +++ b/examples/embedding/README.md @@ -18,7 +18,7 @@ Building the example is as simple as running: It's worth to trace what's happening behind the scenes though: 1. As a first step, a MicroPython library is built. This is handled by a -seperate makefile, Makefile.upylib. It is more or less complex, but the +separate makefile, Makefile.upylib. It is more or less complex, but the good news is that you won't need to change anything in it, just use it as is, the main Makefile shows how. What may require editing though is a MicroPython configuration file. MicroPython is highly configurable, so diff --git a/extmod/modlwip.c b/extmod/modlwip.c index c72849cf9..47669cb3a 100644 --- a/extmod/modlwip.c +++ b/extmod/modlwip.c @@ -373,7 +373,7 @@ STATIC err_t _lwip_tcp_recv(void *arg, struct tcp_pcb *tcpb, struct pbuf *p, err } /*******************************************************************************/ -// Functions for socket send/recieve operations. Socket send/recv and friends call +// Functions for socket send/receive operations. Socket send/recv and friends call // these to do the work. // Helper function for send/sendto to handle UDP packets. @@ -805,7 +805,7 @@ STATIC mp_obj_t lwip_socket_connect(mp_obj_t self_in, mp_obj_t addr_in) { mp_raise_OSError(MP_EINPROGRESS); } } - // Register our recieve callback. + // Register our receive callback. tcp_recv(socket->pcb.tcp, _lwip_tcp_recv); socket->state = STATE_CONNECTING; err = tcp_connect(socket->pcb.tcp, &dest, port, _lwip_tcp_connected); diff --git a/extmod/modwebsocket.c b/extmod/modwebsocket.c index 8200ea708..9e17d6a6d 100644 --- a/extmod/modwebsocket.c +++ b/extmod/modwebsocket.c @@ -132,7 +132,7 @@ STATIC mp_uint_t websocket_read(mp_obj_t self_in, void *buf, mp_uint_t size, int self->buf_pos = 0; self->to_recv = to_recv; - self->msg_sz = sz; // May be overriden by FRAME_OPT + self->msg_sz = sz; // May be overridden by FRAME_OPT if (to_recv != 0) { self->state = FRAME_OPT; } else { diff --git a/lib/timeutils/timeutils.c b/lib/timeutils/timeutils.c index 0af39a295..06915f25a 100644 --- a/lib/timeutils/timeutils.c +++ b/lib/timeutils/timeutils.c @@ -165,7 +165,7 @@ mp_uint_t timeutils_mktime(mp_uint_t year, mp_int_t month, mp_int_t mday, // // tm_tomorrow = list(time.localtime()) // tm_tomorrow[2] += 1 # Adds 1 to mday - // tomorrow = time.mktime(tm_tommorrow) + // tomorrow = time.mktime(tm_tomorrow) // // And not have to worry about all the weird overflows. // diff --git a/lib/utils/stdout_helpers.c b/lib/utils/stdout_helpers.c index 5f7a17d32..3de119757 100644 --- a/lib/utils/stdout_helpers.c +++ b/lib/utils/stdout_helpers.c @@ -9,7 +9,7 @@ * implementation below can be used. */ -// Send "cooked" string of given length, where every occurance of +// Send "cooked" string of given length, where every occurrence of // LF character is replaced with CR LF. void mp_hal_stdout_tx_strn_cooked(const char *str, size_t len) { while (len--) { diff --git a/py/asmthumb.c b/py/asmthumb.c index 749c1e405..7e92e4de4 100644 --- a/py/asmthumb.c +++ b/py/asmthumb.c @@ -52,7 +52,7 @@ void asm_thumb_end_pass(asm_thumb_t *as) { #if defined(MCU_SERIES_F7) if (as->base.pass == MP_ASM_PASS_EMIT) { - // flush D-cache, so the code emited is stored in memory + // flush D-cache, so the code emitted is stored in memory SCB_CleanDCache_by_Addr((uint32_t*)as->base.code_base, as->base.code_size); // invalidate I-cache SCB_InvalidateICache(); diff --git a/py/builtinimport.c b/py/builtinimport.c index d01ebbe73..6994fc48f 100644 --- a/py/builtinimport.c +++ b/py/builtinimport.c @@ -271,7 +271,7 @@ mp_obj_t mp_builtin___import__(size_t n_args, const mp_obj_t *args) { if (level != 0) { // What we want to do here is to take name of current module, // chop trailing components, and concatenate with passed-in - // module name, thus resolving relative import name into absolue. + // module name, thus resolving relative import name into absolute. // This even appears to be correct per // http://legacy.python.org/dev/peps/pep-0328/#relative-imports-and-name // "Relative imports use a module's __name__ attribute to determine that @@ -441,7 +441,7 @@ mp_obj_t mp_builtin___import__(size_t n_args, const mp_obj_t *args) { #if MICROPY_CPYTHON_COMPAT // Store module as "__main__" in the dictionary of loaded modules (returned by sys.modules). mp_obj_dict_store(MP_OBJ_FROM_PTR(&MP_STATE_VM(mp_loaded_modules_dict)), MP_OBJ_NEW_QSTR(MP_QSTR___main__), module_obj); - // Store real name in "__main__" attribute. Choosen semi-randonly, to reuse existing qstr's. + // Store real name in "__main__" attribute. Chosen semi-randonly, to reuse existing qstr's. mp_obj_dict_store(MP_OBJ_FROM_PTR(o->globals), MP_OBJ_NEW_QSTR(MP_QSTR___main__), MP_OBJ_NEW_QSTR(mod_name)); #endif } diff --git a/py/compile.c b/py/compile.c index 8533e0528..3b6a264d6 100644 --- a/py/compile.c +++ b/py/compile.c @@ -939,7 +939,7 @@ STATIC void c_del_stmt(compiler_t *comp, mp_parse_node_t pn) { } } } else { - // some arbitrary statment that we can't delete (eg del 1) + // some arbitrary statement that we can't delete (eg del 1) goto cannot_delete; } @@ -1090,7 +1090,7 @@ STATIC void compile_import_name(compiler_t *comp, mp_parse_node_struct_t *pns) { STATIC void compile_import_from(compiler_t *comp, mp_parse_node_struct_t *pns) { mp_parse_node_t pn_import_source = pns->nodes[0]; - // extract the preceeding .'s (if any) for a relative import, to compute the import level + // extract the preceding .'s (if any) for a relative import, to compute the import level uint import_level = 0; do { mp_parse_node_t pn_rel; diff --git a/py/misc.h b/py/misc.h index 146b9a8e4..caa5945bf 100644 --- a/py/misc.h +++ b/py/misc.h @@ -197,7 +197,7 @@ int DEBUG_printf(const char *fmt, ...); extern mp_uint_t mp_verbose_flag; // This is useful for unicode handling. Some CPU archs has -// special instructions for efficient implentation of this +// special instructions for efficient implementation of this // function (e.g. CLZ on ARM). // NOTE: this function is unused at the moment #ifndef count_lead_ones diff --git a/py/mkenv.mk b/py/mkenv.mk index eb1e44fef..b167b2533 100644 --- a/py/mkenv.mk +++ b/py/mkenv.mk @@ -32,7 +32,7 @@ ifeq ($(BUILD_VERBOSE),0) $(info Use make V=1 or set BUILD_VERBOSE in your environment to increase build verbosity.) endif -# default settings; can be overriden in main Makefile +# default settings; can be overridden in main Makefile PY_SRC ?= $(TOP)/py BUILD ?= build diff --git a/py/mpconfig.h b/py/mpconfig.h index a61d431e5..78e346d73 100644 --- a/py/mpconfig.h +++ b/py/mpconfig.h @@ -32,7 +32,7 @@ // mpconfigport.h is a file containing configuration settings for a // particular port. mpconfigport.h is actually a default name for -// such config, and it can be overriden using MP_CONFIGFILE preprocessor +// such config, and it can be overridden using MP_CONFIGFILE preprocessor // define (you can do that by passing CFLAGS_EXTRA='-DMP_CONFIGFILE=""' // argument to make when using standard MicroPython makefiles). // This is useful to have more than one config per port, for example, diff --git a/py/obj.c b/py/obj.c index 98ffa930b..493945a22 100644 --- a/py/obj.c +++ b/py/obj.c @@ -401,7 +401,7 @@ mp_obj_t mp_obj_id(mp_obj_t o_in) { return MP_OBJ_NEW_SMALL_INT(id); } else { // If that didn't work, well, let's return long int, just as - // a (big) positve value, so it will never clash with the range + // a (big) positive value, so it will never clash with the range // of small int returned in previous case. return mp_obj_new_int_from_uint((mp_uint_t)id); } diff --git a/py/objstr.c b/py/objstr.c index 70de0a693..a1e223572 100644 --- a/py/objstr.c +++ b/py/objstr.c @@ -798,7 +798,7 @@ STATIC mp_obj_t str_uni_strip(int type, size_t n_args, const mp_obj_t *args) { } assert(last_good_char_pos >= first_good_char_pos); - //+1 to accomodate the last character + //+1 to accommodate the last character size_t stripped_len = last_good_char_pos - first_good_char_pos + 1; if (stripped_len == orig_str_len) { // If nothing was stripped, don't bother to dup original string @@ -1811,7 +1811,7 @@ STATIC mp_obj_t str_islower(mp_obj_t self_in) { } #if MICROPY_CPYTHON_COMPAT -// These methods are superfluous in the presense of str() and bytes() +// These methods are superfluous in the presence of str() and bytes() // constructors. // TODO: should accept kwargs too STATIC mp_obj_t bytes_decode(size_t n_args, const mp_obj_t *args) { diff --git a/py/py.mk b/py/py.mk index 5ff1fd6a6..70891677d 100644 --- a/py/py.mk +++ b/py/py.mk @@ -25,7 +25,7 @@ ifeq ($(MICROPY_SSL_AXTLS),1) CFLAGS_MOD += -DMICROPY_SSL_AXTLS=1 -I../lib/axtls/ssl -I../lib/axtls/crypto -I../lib/axtls/config LDFLAGS_MOD += -Lbuild -laxtls else ifeq ($(MICROPY_SSL_MBEDTLS),1) -# Can be overriden by ports which have "builtin" mbedTLS +# Can be overridden by ports which have "builtin" mbedTLS MICROPY_SSL_MBEDTLS_INCLUDE ?= ../lib/mbedtls/include CFLAGS_MOD += -DMICROPY_SSL_MBEDTLS=1 -I$(MICROPY_SSL_MBEDTLS_INCLUDE) LDFLAGS_MOD += -L../lib/mbedtls/library -lmbedx509 -lmbedtls -lmbedcrypto diff --git a/py/ringbuf.h b/py/ringbuf.h index 5662594f7..5e108afad 100644 --- a/py/ringbuf.h +++ b/py/ringbuf.h @@ -33,7 +33,7 @@ typedef struct _ringbuf_t { uint16_t iput; } ringbuf_t; -// Static initalization: +// Static initialization: // byte buf_array[N]; // ringbuf_t buf = {buf_array, sizeof(buf_array)}; diff --git a/py/stream.c b/py/stream.c index c915110e0..d3fc767bb 100644 --- a/py/stream.c +++ b/py/stream.c @@ -51,7 +51,7 @@ STATIC mp_obj_t stream_readall(mp_obj_t self_in); #define STREAM_CONTENT_TYPE(stream) (((stream)->is_text) ? &mp_type_str : &mp_type_bytes) // Returns error condition in *errcode, if non-zero, return value is number of bytes written -// before error condition occured. If *errcode == 0, returns total bytes written (which will +// before error condition occurred. If *errcode == 0, returns total bytes written (which will // be equal to input size). mp_uint_t mp_stream_rw(mp_obj_t stream, void *buf_, mp_uint_t size, int *errcode, byte flags) { byte *buf = buf_; diff --git a/py/vm.c b/py/vm.c index 5094e3e45..ad3d9e29c 100644 --- a/py/vm.c +++ b/py/vm.c @@ -947,7 +947,7 @@ unwind_jump:; DECODE_UINT; // unum & 0xff == n_positional // (unum >> 8) & 0xff == n_keyword - // We have folowing stack layout here: + // We have following stack layout here: // fun arg0 arg1 ... kw0 val0 kw1 val1 ... seq dict <- TOS sp -= (unum & 0xff) + ((unum >> 7) & 0x1fe) + 2; #if MICROPY_STACKLESS @@ -1018,7 +1018,7 @@ unwind_jump:; DECODE_UINT; // unum & 0xff == n_positional // (unum >> 8) & 0xff == n_keyword - // We have folowing stack layout here: + // We have following stack layout here: // fun self arg0 arg1 ... kw0 val0 kw1 val1 ... seq dict <- TOS sp -= (unum & 0xff) + ((unum >> 7) & 0x1fe) + 3; #if MICROPY_STACKLESS diff --git a/qemu-arm/README.md b/qemu-arm/README.md index 329ae4d92..0cf93c7d5 100644 --- a/qemu-arm/README.md +++ b/qemu-arm/README.md @@ -4,7 +4,7 @@ provided by QEMU (http://qemu.org). The purposes of this port are to enable: 1. Continuous integration - - run tests agains architecture-specific parts of code base + - run tests against architecture-specific parts of code base 2. Experimentation - simulation & prototyping of anything that has architecture-specific code diff --git a/tests/basics/namedtuple1.py b/tests/basics/namedtuple1.py index 132dcf96b..70372f7ca 100644 --- a/tests/basics/namedtuple1.py +++ b/tests/basics/namedtuple1.py @@ -76,7 +76,7 @@ T4 = namedtuple("TupTuple", ("foo", "bar")) t = T4(1, 2) print(t.foo, t.bar) -# Try single string with comma field seperator +# Try single string with comma field separator # Not implemented so far #T2 = namedtuple("TupComma", "foo,bar") #t = T2(1, 2) diff --git a/tests/basics/try_reraise2.py b/tests/basics/try_reraise2.py index d9434397c..5648d2467 100644 --- a/tests/basics/try_reraise2.py +++ b/tests/basics/try_reraise2.py @@ -1,4 +1,4 @@ -# Reraise not the latest occured exception +# Reraise not the latest occurred exception def f(): try: raise ValueError("val", 3) diff --git a/tests/pyb/can.py b/tests/pyb/can.py index 617eb7ccc..7f2d070ec 100644 --- a/tests/pyb/can.py +++ b/tests/pyb/can.py @@ -158,7 +158,7 @@ print(can.recv(1)) del can -# Testing asyncronous send +# Testing asynchronous send can = CAN(1, CAN.LOOPBACK) can.setfilter(0, CAN.MASK16, 0, (0, 0, 0, 0)) diff --git a/tests/thread/stress_aes.py b/tests/thread/stress_aes.py index ecc963c92..df75e616c 100644 --- a/tests/thread/stress_aes.py +++ b/tests/thread/stress_aes.py @@ -8,7 +8,7 @@ # # The AES code comes first (code originates from a C version authored by D.P.George) # and then the test harness at the bottom. It can be tuned to be more/less -# agressive by changing the amount of data to encrypt, the number of loops and +# aggressive by changing the amount of data to encrypt, the number of loops and # the number of threads. # # MIT license; Copyright (c) 2016 Damien P. George on behalf of Pycom Ltd diff --git a/tests/wipy/uart.py b/tests/wipy/uart.py index a3a1c14e8..8e794015d 100644 --- a/tests/wipy/uart.py +++ b/tests/wipy/uart.py @@ -95,7 +95,7 @@ print(uart1.read() == None) print(uart1.write(b'123') == 3) print(uart0.read() == b'123') -# no pin assignemnt +# no pin assignment uart0 = UART(0, 1000000, pins=(None, None)) print(uart0.write(b'123456789') == 9) print(uart1.read() == None) diff --git a/tools/insert-usb-ids.py b/tools/insert-usb-ids.py index 420db34c5..cdccd3be9 100644 --- a/tools/insert-usb-ids.py +++ b/tools/insert-usb-ids.py @@ -1,4 +1,4 @@ -# Reads the USB VID and PID from the file specifed by sys.arg[1] and then +# Reads the USB VID and PID from the file specified by sys.argv[1] and then # inserts those values into the template file specified by sys.argv[2], # printing the result to stdout diff --git a/tools/pyboard.py b/tools/pyboard.py index 5eac030bd..921ffc52d 100755 --- a/tools/pyboard.py +++ b/tools/pyboard.py @@ -69,7 +69,7 @@ class TelnetToSerial: self.tn.write(bytes(password, 'ascii') + b"\r\n") if b'for more information.' in self.tn.read_until(b'Type "help()" for more information.', timeout=read_timeout): - # login succesful + # login successful from collections import deque self.fifo = deque() return diff --git a/unix/Makefile b/unix/Makefile index 837ddf2b7..006bce0ef 100644 --- a/unix/Makefile +++ b/unix/Makefile @@ -262,7 +262,7 @@ coverage_test: coverage gcov -o build-coverage/extmod ../extmod/*.c # Value of configure's --host= option (required for cross-compilation). -# Deduce it from CROSS_COMPILE by default, but can be overriden. +# Deduce it from CROSS_COMPILE by default, but can be overridden. ifneq ($(CROSS_COMPILE),) CROSS_COMPILE_HOST = --host=$(patsubst %-,%,$(CROSS_COMPILE)) else diff --git a/unix/modsocket.c b/unix/modsocket.c index 9ca04b88b..c7be6461e 100644 --- a/unix/modsocket.c +++ b/unix/modsocket.c @@ -58,7 +58,7 @@ from socket_more_funcs2 import * ------------------- I.e. this module should stay lean, and more functions (if needed) - should be add to seperate modules (C or Python level). + should be add to separate modules (C or Python level). */ #define MICROPY_SOCKET_EXTRA (0) diff --git a/windows/windows_mphal.c b/windows/windows_mphal.c index 1dd3105d8..a73140e54 100644 --- a/windows/windows_mphal.c +++ b/windows/windows_mphal.c @@ -72,7 +72,7 @@ void mp_hal_stdio_mode_orig(void) { // Previous versions of the mp_hal code would install a handler whenever Ctrl-C input is // allowed and remove the handler again when it is not. That is not necessary though (1), // and it might introduce problems (2) because console notifications are delivered to the -// application in a seperate thread. +// application in a separate thread. // (1) mp_hal_set_interrupt_char effectively enables/disables processing of Ctrl-C via the // ENABLE_PROCESSED_INPUT flag so in raw mode console_sighandler won't be called. // (2) if mp_hal_set_interrupt_char would remove the handler while Ctrl-C was issued earlier, diff --git a/zephyr/modutime.c b/zephyr/modutime.c index 378068bb3..0c268046a 100644 --- a/zephyr/modutime.c +++ b/zephyr/modutime.c @@ -36,7 +36,7 @@ #include "extmod/utime_mphal.h" STATIC mp_obj_t mod_time_time(void) { - /* The absense of FP support is deliberate. The Zephyr port uses + /* The absence of FP support is deliberate. The Zephyr port uses * single precision floats so the fraction component will start to * lose precision on devices with a long uptime. */ -- cgit v1.2.3 From 3496d9e4bd39452484d8a99e991ef7c0a92d5b51 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Mon, 29 May 2017 20:51:30 +0300 Subject: docs/machine.Pin: Remove out_value() method. This method isn't implemented in any port. It seemed to have originated in cc3200 port, but actually never was implemented there either. In general case, it's impossible to implement this method (for example, for a perfect GPO, which has only output latch without any feedback look into a CPU). --- docs/library/machine.Pin.rst | 6 ------ 1 file changed, 6 deletions(-) (limited to 'docs') diff --git a/docs/library/machine.Pin.rst b/docs/library/machine.Pin.rst index 2efd84688..e7f314154 100644 --- a/docs/library/machine.Pin.rst +++ b/docs/library/machine.Pin.rst @@ -146,12 +146,6 @@ Methods When setting the value this method returns ``None``. -.. method:: Pin.out_value() - - Return the value stored in the output buffer of a pin, regardless of its mode. - - Not all ports implement this method. - .. method:: Pin.__call__([x]) Pin objects are callable. The call method provides a (fast) shortcut to set -- cgit v1.2.3 From d5b8825d5f5c6110f9cf3bd39848cfe94137d291 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Mon, 29 May 2017 20:56:13 +0300 Subject: docs/machine.Pin: Add on() and off() methods. --- docs/library/machine.Pin.rst | 8 ++++++++ 1 file changed, 8 insertions(+) (limited to 'docs') diff --git a/docs/library/machine.Pin.rst b/docs/library/machine.Pin.rst index e7f314154..05ceb4ad3 100644 --- a/docs/library/machine.Pin.rst +++ b/docs/library/machine.Pin.rst @@ -152,6 +152,14 @@ Methods and get the value of the pin. It is equivalent to Pin.value([x]). See :meth:`Pin.value` for more details. +.. method:: Pin.on() + + Set pin to "1" output level. + +.. method:: Pin.off() + + Set pin to "0" output level. + .. method:: Pin.mode([mode]) Get or set the pin mode. -- cgit v1.2.3 From 272a5d95e040994039eb91830d310339253bcbb9 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Tue, 30 May 2017 07:36:25 +0300 Subject: docs/esp8266: Consistently replace Pin.high/low methods with .on/off. --- docs/esp8266/quickref.rst | 4 ++-- docs/esp8266/tutorial/pins.rst | 4 ++-- docs/esp8266/tutorial/repl.rst | 9 +++++---- 3 files changed, 9 insertions(+), 8 deletions(-) (limited to 'docs') diff --git a/docs/esp8266/quickref.rst b/docs/esp8266/quickref.rst index 5ff33e02b..406a5bb45 100644 --- a/docs/esp8266/quickref.rst +++ b/docs/esp8266/quickref.rst @@ -107,8 +107,8 @@ Use the :ref:`machine.Pin ` class:: from machine import Pin p0 = Pin(0, Pin.OUT) # create output pin on GPIO0 - p0.high() # set pin to high - p0.low() # set pin to low + p0.on() # turn on pin, set to high + p0.off() # turn off pin, set to low p0.value(1) # set pin to high p2 = Pin(2, Pin.IN) # create input pin on GPIO2 diff --git a/docs/esp8266/tutorial/pins.rst b/docs/esp8266/tutorial/pins.rst index a44f40d3a..cd45c83cd 100644 --- a/docs/esp8266/tutorial/pins.rst +++ b/docs/esp8266/tutorial/pins.rst @@ -35,8 +35,8 @@ Then set its value using:: Or:: - >>> pin.low() - >>> pin.high() + >>> pin.off() + >>> pin.on() External interrupts ------------------- diff --git a/docs/esp8266/tutorial/repl.rst b/docs/esp8266/tutorial/repl.rst index 21e889c9a..ba64fcccb 100644 --- a/docs/esp8266/tutorial/repl.rst +++ b/docs/esp8266/tutorial/repl.rst @@ -101,11 +101,12 @@ turn it on and off using the following code:: >>> import machine >>> pin = machine.Pin(2, machine.Pin.OUT) - >>> pin.high() - >>> pin.low() + >>> pin.on() + >>> pin.off() -Note that ``high`` might turn the LED off and ``low`` might turn it on (or vice -versa), depending on how the LED is wired on your board. +Note that ``on`` method of a Pin might turn the LED off and ``off`` might +turn it on (or vice versa), depending on how the LED is wired on your board. +To resolve this, machine.Signal class is provided. Line editing ~~~~~~~~~~~~ -- cgit v1.2.3 From 22ca5390f7ec55400bd55cec5e52fc6c704f8be7 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Wed, 31 May 2017 22:57:11 +0300 Subject: docs/esp8266/quickref: Polish Pin.on()/off() examples. --- docs/esp8266/quickref.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/esp8266/quickref.rst b/docs/esp8266/quickref.rst index 406a5bb45..ccf6365c8 100644 --- a/docs/esp8266/quickref.rst +++ b/docs/esp8266/quickref.rst @@ -107,9 +107,9 @@ Use the :ref:`machine.Pin ` class:: from machine import Pin p0 = Pin(0, Pin.OUT) # create output pin on GPIO0 - p0.on() # turn on pin, set to high - p0.off() # turn off pin, set to low - p0.value(1) # set pin to high + p0.on() # set pin to "on" (high) level + p0.off() # set pin to "off" (low) level + p0.value(1) # set pin to on/high p2 = Pin(2, Pin.IN) # create input pin on GPIO2 print(p2.value()) # get value, 0 or 1 -- cgit v1.2.3 From 92206a78aeddf81eca08fb25589231e5a62df69c Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Sat, 3 Jun 2017 13:34:28 +0300 Subject: docs/network: Move confusingly-named cc3200 Server class to its reference. cc3200 port has network.Server class to control behavior of builtin Telnet/FTP server of that port. --- docs/library/network.rst | 46 ---------------------------------------------- docs/wipy/general.rst | 37 +++++++++++++++++++++++++++++++++++++ 2 files changed, 37 insertions(+), 46 deletions(-) (limited to 'docs') diff --git a/docs/library/network.rst b/docs/library/network.rst index 251e68c76..75640250f 100644 --- a/docs/library/network.rst +++ b/docs/library/network.rst @@ -29,52 +29,6 @@ For example:: data = s.recv(1000) s.close() -.. only:: port_wipy - - .. _network.Server: - - class Server - ============ - - The ``Server`` class controls the behaviour and the configuration of the FTP and telnet - services running on the WiPy. Any changes performed using this class' methods will - affect both. - - 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) - - Constructors - ------------ - - .. class:: network.Server(id, ...) - - Create a server instance, see ``init`` for parameters of initialization. - - Methods - ------- - - .. method:: server.init(\*, login=('micro', 'python'), timeout=300) - - Init (and effectively start the server). Optionally a new ``user``, ``password`` - and ``timeout`` (in seconds) can be passed. - - .. method:: server.deinit() - - Stop the server - - .. method:: server.timeout([timeout_in_seconds]) - - Get or set the server timeout. - - .. method:: server.isrunning() - - Returns ``True`` if the server is running, ``False`` otherwise. - .. only:: port_pyboard class CC3K diff --git a/docs/wipy/general.rst b/docs/wipy/general.rst index 8b9b91c53..ca6f77ab0 100644 --- a/docs/wipy/general.rst +++ b/docs/wipy/general.rst @@ -323,3 +323,40 @@ Unrelated function in machine module this function is not called then the default file main.py will be executed. It only makes sense to call this function from within boot.py. + +Adhoc way to control telnet/FTP server via network module +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The ``Server`` class controls the behaviour and the configuration of the FTP and telnet +services running on the WiPy. Any changes performed using this class' methods will +affect both. + +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) + +.. class:: network.Server(id, ...) + + Create a server instance, see ``init`` for parameters of initialization. + +.. method:: server.init(\*, login=('micro', 'python'), timeout=300) + + Init (and effectively start the server). Optionally a new ``user``, ``password`` + and ``timeout`` (in seconds) can be passed. + +.. method:: server.deinit() + + Stop the server + +.. method:: server.timeout([timeout_in_seconds]) + + Get or set the server timeout. + +.. method:: server.isrunning() + + Returns ``True`` if the server is running, ``False`` otherwise. + -- cgit v1.2.3 From 1ce44f30467e4882580ca8545f15ba7d882cb428 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Sat, 3 Jun 2017 13:51:13 +0300 Subject: docs/uos: Deconditionalize, remove minor port-specific details. For a couple of ports, there was information which directory is set as current after boot. This information doesn't belong to "uos" module, and is moved to boards' references (which actually already contained information on which directory is chosen for boot, even if without explicit mentioning that it becomes current directory, which is now done). --- docs/library/uos.rst | 21 +-------------------- docs/pyboard/general.rst | 4 +++- docs/wipy/general.rst | 2 +- 3 files changed, 5 insertions(+), 22 deletions(-) (limited to 'docs') diff --git a/docs/library/uos.rst b/docs/library/uos.rst index d1f83d2cc..82ed5dbc9 100644 --- a/docs/library/uos.rst +++ b/docs/library/uos.rst @@ -4,28 +4,9 @@ .. module:: uos :synopsis: basic "operating system" services -The ``os`` module contains functions for filesystem access and ``urandom`` +The ``uos`` module contains functions for filesystem access and ``urandom`` function. -Port specifics --------------- - -The filesystem has ``/`` as the root directory and the -available physical drives are accessible from here. They are currently: - - ``/flash`` -- the internal flash filesystem - - ``/sd`` -- the SD card (if it exists) - -.. only:: port_pyboard - - On boot up, the current directory is ``/flash`` if no SD card is inserted, - otherwise it is ``/sd``. - -.. only:: port_wipy - - On boot up, the current directory is ``/flash``. - Functions --------- diff --git a/docs/pyboard/general.rst b/docs/pyboard/general.rst index 48e014644..1d040f6cc 100644 --- a/docs/pyboard/general.rst +++ b/docs/pyboard/general.rst @@ -10,7 +10,9 @@ is inserted into the slot, it is available as ``/sd``. When the pyboard boots up, it needs to choose a filesystem to boot from. If there is no SD card, then it uses the internal filesystem ``/flash`` as the boot -filesystem, otherwise, it uses the SD card ``/sd``. +filesystem, otherwise, it uses the SD card ``/sd``. After the boot, the current +directory is set to one of the directories above. + If needed, you can prevent the use of the SD card by creating an empty file called ``/flash/SKIPSD``. If this file exists when the pyboard boots up then the SD card will be skipped and the pyboard will always boot from the diff --git a/docs/wipy/general.rst b/docs/wipy/general.rst index ca6f77ab0..1e396518e 100644 --- a/docs/wipy/general.rst +++ b/docs/wipy/general.rst @@ -53,7 +53,7 @@ which is stored within the external serial flash memory. If a micro SD card is hooked-up and mounted, it will be available as well. When the WiPy starts up, it always boots from the ``boot.py`` located in the -``/flash`` file system. +``/flash`` file system. On boot up, the current directory is ``/flash``. The file system is accessible via the native FTP server running in the WiPy. Open your FTP client of choice and connect to: -- cgit v1.2.3 From e91b1cdae38d693fbd34a57341d8c72737f0ec22 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Sat, 3 Jun 2017 14:19:53 +0300 Subject: docs/uos: Move cc3200 port legacy VFS mounting functions to its ref doc. This patch also unconditionalizes uos.dupterm(), though exact interface and semantics is yet to be defined. --- docs/library/uos.rst | 26 ++++---------------------- docs/wipy/general.rst | 23 +++++++++++++++++++++++ 2 files changed, 27 insertions(+), 22 deletions(-) (limited to 'docs') diff --git a/docs/library/uos.rst b/docs/library/uos.rst index 82ed5dbc9..3d0aa46c7 100644 --- a/docs/library/uos.rst +++ b/docs/library/uos.rst @@ -87,26 +87,8 @@ Functions Return a bytes object with n random bytes. Whenever possible, it is generated by the hardware random number generator. -.. only:: port_wipy +.. function:: dupterm(stream_object) - .. function:: mount(block_device, mount_point, \*, readonly=False) - - Mounts a block device (like an ``SD`` object) in the specified mount - point. Example:: - - os.mount(sd, '/sd') - - .. function:: unmount(path) - - Unmounts a previously mounted block device from the given path. - - .. function:: mkfs(block_device or path) - - Formats the specified path, must be either ``/flash`` or ``/sd``. - A block device can also be passed like an ``SD`` object before - being mounted. - - .. function:: dupterm(stream_object) - - Duplicate the terminal (the REPL) on the passed stream-like object. - The given object must at least implement the ``.read()`` and ``.write()`` methods. + Duplicate or switch MicroPython terminal (the REPL) on the passed stream-like + object. The given object must implement the `.readinto()` and `.write()` + methods. If ``None`` is passed, previously set redirection is cancelled. diff --git a/docs/wipy/general.rst b/docs/wipy/general.rst index 1e396518e..f28edb4e4 100644 --- a/docs/wipy/general.rst +++ b/docs/wipy/general.rst @@ -360,3 +360,26 @@ Example:: Returns ``True`` if the server is running, ``False`` otherwise. +Adhoc VFS-like support +~~~~~~~~~~~~~~~~~~~~~~ + +WiPy doesn't implement full MicroPython VFS support, instead following +functions are defined in ``uos`` module: + +.. function:: mount(block_device, mount_point, \*, readonly=False) + + Mounts a block device (like an ``SD`` object) in the specified mount + point. Example:: + + os.mount(sd, '/sd') + +.. function:: unmount(path) + + Unmounts a previously mounted block device from the given path. + +.. function:: mkfs(block_device or path) + + Formats the specified path, must be either ``/flash`` or ``/sd``. + A block device can also be passed like an ``SD`` object before + being mounted. + -- cgit v1.2.3 From f245f5d7cc62ae60c73d51d9962a995ff3e579c5 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Sat, 3 Jun 2017 14:50:54 +0300 Subject: docs/machine: Sort machine classes in logical order, not alphabetically. The list starts with the simplest functionality - GPIO, proceeds to communication interfaces (UART, SPI, I2C), the to time(r) related things, then everything else. --- docs/library/machine.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) (limited to 'docs') diff --git a/docs/library/machine.rst b/docs/library/machine.rst index c2c6b83fd..7ea7f565e 100644 --- a/docs/library/machine.rst +++ b/docs/library/machine.rst @@ -145,13 +145,13 @@ Classes .. toctree:: :maxdepth: 1 - machine.I2C.rst machine.Pin.rst machine.Signal.rst - machine.RTC.rst + machine.UART.rst machine.SPI.rst + machine.I2C.rst + machine.RTC.rst machine.Timer.rst - machine.UART.rst machine.WDT.rst .. only:: port_wipy @@ -159,12 +159,12 @@ Classes .. toctree:: :maxdepth: 1 - machine.ADC.rst - machine.I2C.rst machine.Pin.rst - machine.RTC.rst - machine.SD.rst + machine.UART.rst machine.SPI.rst + machine.I2C.rst + machine.RTC.rst machine.Timer.rst - machine.UART.rst machine.WDT.rst + machine.ADC.rst + machine.SD.rst -- cgit v1.2.3 From cd64b3082e501f5a54cb15ab3087be91c8f90338 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Sun, 9 Apr 2017 13:21:35 +0300 Subject: docs/network: First step to describe standard network class interface. This adds description of implied AbstractNIC base class, which should be "subclasses" and implemented by a particular network device class. This is just an initial step in that direction, the API and description will be elabotated further. --- docs/library/network.rst | 109 +++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 106 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/library/network.rst b/docs/library/network.rst index 75640250f..27fa0dcb2 100644 --- a/docs/library/network.rst +++ b/docs/library/network.rst @@ -14,14 +14,20 @@ module. For example:: - # configure a specific network interface + # connect/ show IP config a specific network interface # see below for examples of specific drivers import network + import utime nic = network.Driver(...) + if not nic.isconnected(): + nic.connect() + print("Waiting for connection...") + while not nic.isconnected(): + utime.sleep(1) print(nic.ifconfig()) - # now use socket as usual - import socket + # now use usocket as usual + import usocket as socket addr = socket.getaddrinfo('micropython.org', 80)[0][-1] s = socket.socket() s.connect(addr) @@ -29,6 +35,103 @@ For example:: data = s.recv(1000) s.close() +Common network adapter interface +================================ + +This section describes an (implied) abstract base class for all network +interface classes implemented by different ports of MicroPython for +different hardware. This means that MicroPython does not actually +provide `AbstractNIC` class, but any actual NIC class, as described +in the following sections, implements methods as described here. + +.. class:: AbstractNIC(id=None, ...) + +Instantiate a network interface object. Parameters are network interface +dependent. If there are more than one interface of the same type, the first +parameter should be `id`. + + .. method:: active([is_active]) + + Activate ("up") or deactivate ("down") the network interface, if + a boolean argument is passed. Otherwise, query current state if + no argument is provided. Most other methods require an active + interface (behavior of calling them on inactive interface is + undefined). + + .. method:: connect([service_id, key=None, \*, ...]) + + Connect the interface to a network. This method is optional, and + available only for interfaces which are not "always connected". + If no parameters are given, connect to the default (or the only) + service. If a single parameter is given, it is the primary identifier + of a service to connect to. It may be accompanied by a key + (password) required to access said service. There can be further + arbitrary keyword-only parameters, depending on the networking medium + type and/or particular device. Parameters can be used to: a) + specify alternative service identifer types; b) provide additional + connection parameters. For various medium types, there are different + sets of predefined/recommended parameters, among them: + + * WiFi: `bssid` keyword to connect by BSSID (MAC address) instead + of access point name + + .. method:: disconnect() + + Disconnect from network. + + .. method:: isconnected() + + Returns ``True`` if connected to network, otherwise returns ``False``. + + .. method:: scan(\*, ...) + + Scan for the available network services/connections. Returns a + list of tuples with discovered service parameters. For various + network media, there are different variants of predefined/ + recommended tuple formats, among them: + + * WiFi: (ssid, bssid, channel, RSSI, authmode, hidden). There + may be further fields, specific to a particular device. + + The function may accept additional keyword arguments to filter scan + results (e.g. scan for a particular service, on a particular channel, + for services of a particular set, etc.), and to affect scan + duration and other parameters. Where possible, parameter names + should match those in connect(). + + .. method:: status() + + Return detailed status of the interface, values are dependent + on the network medium/technology. + + .. method:: ifconfig([(ip, subnet, gateway, dns)]) + + Get/set IP-level network interface parameters: IP address, subnet mask, + gateway and DNS server. When called with no arguments, this method returns + a 4-tuple with the above information. To set the above values, pass a + 4-tuple with the required information. For example:: + + nic.ifconfig(('192.168.0.4', '255.255.255.0', '192.168.0.1', '8.8.8.8')) + + .. method:: config('param') + config(param=value, ...) + + Get or set general network interface parameters. These methods allow to work + with additional parameters beyond standard IP configuration (as dealt with by + ``ifconfig()``). These include network-specific and hardware-specific + parameters and status values. For setting parameters, the keyword argument + syntax should be used, and multiple parameters can be set at once. For + querying, a parameter name should be quoted as a string, and only one + parameter can be queried at a time:: + + # Set WiFi access point name (formally known as ESSID) and WiFi channel + ap.config(essid='My AP', channel=11) + # Query params one by one + print(ap.config('essid')) + print(ap.config('channel')) + # Extended status information also available this way + print(sta.config('rssi')) + .. only:: port_pyboard class CC3K -- cgit v1.2.3 From 869cdcfdfc860b1177baf9b0f8818915ba54f3f5 Mon Sep 17 00:00:00 2001 From: Damien George Date: Sun, 11 Jun 2017 23:04:00 +1000 Subject: docs: Bump version to 1.9.1. --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/conf.py b/docs/conf.py index e813f2383..8fb53e890 100755 --- a/docs/conf.py +++ b/docs/conf.py @@ -99,7 +99,7 @@ copyright = '2014-2017, Damien P. George, Paul Sokolovsky, and contributors' # The short X.Y version. version = '1.9' # The full version, including alpha/beta/rc tags. -release = '1.9' +release = '1.9.1' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. -- cgit v1.2.3