Skip to content

Commit ceb1690

Browse files
author
danicampora
committed
docs: Several corrections to the classes in the machine module.
1 parent 04db848 commit ceb1690

11 files changed

Lines changed: 72 additions & 92 deletions

‎docs/library/machine.HeartBeat.rst‎

Lines changed: 0 additions & 47 deletions
This file was deleted.

‎docs/library/machine.Pin.rst‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -13,15 +13,18 @@ Usage Model:
1313

1414
Board pins are identified by their string id::
1515

16-
g = machine.Pin('GP9', mode=machine.Pin.OUT, pull=None, drive=machine.Pin.MED_POWER, alt=-1)
16+
from machine import Pin
17+
g = machine.Pin('GP9', mode=Pin.OUT, pull=None, drive=Pin.MED_POWER, alt=-1)
1718

1819
You can also configure the Pin to generate interrupts. For instance::
1920

21+
from machine import Pin
22+
2023
def pincb(pin):
2124
print(pin.id())
2225

23-
pin_int = machine.Pin('GP10', mode=Pin.IN, pull=machine.Pin.PULL_DOWN)
24-
pin_int.irq(mode=machine.Pin.IRQ_RISING, handler=pincb)
26+
pin_int = Pin('GP10', mode=Pin.IN, pull=Pin.PULL_DOWN)
27+
pin_int.irq(mode=Pin.IRQ_RISING, handler=pincb)
2528
# the callback can be triggered manually
2629
pin_int.irq()()
2730
# to disable the callback

‎docs/library/machine.SD.rst‎

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -26,16 +26,15 @@ Constructors
2626

2727
.. class:: machine.SD(id,... )
2828

29-
Create a SD card object. See init for parameters if initialization.
29+
Create a SD card object. See ``init()`` for parameters if initialization.
3030

3131
Methods
3232
-------
3333

34-
.. method:: sd.init(id, pins=('GP10', 'GP11', 'GP15'))
34+
.. method:: sd.init(id=0, pins=('GP10', 'GP11', 'GP15'))
3535

36-
Enable the SD card.
37-
In order to initalize the card, give it a 3-tuple ``(clk_pin, cmd_pin, dat0_pin)``
38-
ID defaults to zero.
36+
Enable the SD card. In order to initalize the card, give it a 3-tuple:
37+
``(clk_pin, cmd_pin, dat0_pin)``.
3938

4039
.. method:: sd.deinit()
4140

‎docs/library/machine.Timer.rst‎

Lines changed: 11 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -19,13 +19,15 @@ class Timer -- control internal timers
1919

2020
Example usage to toggle an LED at a fixed frequency::
2121

22-
tim = machine.Timer(4) # create a timer object using timer 4
23-
tim.init(mode=Timer.PERIODIC) # initialize it in periodic mode
24-
tim_ch = tim.channel(Timer.A, freq=2) # configure channel A at a frequency of 2Hz
25-
tim_ch.callback(handler=lambda t:led.toggle()) # toggle a LED on every cycle of the timer
22+
from machine import Timer
23+
tim = Timer(4) # create a timer object using timer 4
24+
tim.init(mode=Timer.PERIODIC) # initialize it in periodic mode
25+
tim_ch = tim.channel(Timer.A, freq=2) # configure channel A at a frequency of 2Hz
26+
tim_ch.callback(handler=lambda t:led.toggle()) # toggle a LED on every cycle of the timer
2627

2728
Example using named function for the callback::
2829

30+
from machine import Timer
2931
tim = Timer(1, mode=Timer.PERIODIC)
3032
tim_a = tim.channel(Timer.A, freq=1000)
3133

@@ -39,8 +41,9 @@ class Timer -- control internal timers
3941

4042
Further examples::
4143

42-
tim1 = machine.Timer(2, mode=Timer.EVENT_COUNT) # initialize it capture mode
43-
tim2 = machine.Timer(1, mode=Timer.PWM) # initialize it in PWM mode
44+
from machine import Timer
45+
tim1 = Timer(2, mode=Timer.EVENT_COUNT) # initialize it capture mode
46+
tim2 = Timer(1, mode=Timer.PWM) # initialize it in PWM mode
4447
tim_ch = tim1.channel(Timer.A, freq=1, polarity=Timer.POSITIVE) # start the event counter with a frequency of 1Hz and triggered by positive edges
4548
tim_ch = tim2.channel(Timer.B, freq=10000, duty_cycle=50) # start the PWM on channel B with a 50% duty cycle
4649
tim_ch.time() # get the current time in usec (can also be set)
@@ -54,8 +57,8 @@ class Timer -- control internal timers
5457

5558
.. note::
5659

57-
Memory can't be allocated during a callback (an interrupt) and so
58-
exceptions raised within a callback don't give much information. See
60+
Memory can't be allocated inside irq handlers (an interrupt) and so
61+
exceptions raised within a handler don't give much information. See
5962
:func:`micropython.alloc_emergency_exception_buf` for how to get around this
6063
limitation.
6164

‎docs/library/machine.UART.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -155,7 +155,7 @@ Methods
155155
This means that when the handler function is called there will be between 1 to 8
156156
characters waiting.
157157

158-
Returns a irq object.
158+
Returns an irq object.
159159

160160
Constants
161161
---------

‎docs/library/machine.WDT.rst‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,8 @@ watchdog periodically to prevent it from expiring and resetting the system.
1010

1111
Example usage::
1212

13-
wdt = machine.WDT(timeout=2000) # enable with a timeout of 2s
13+
from machine import WDT
14+
wdt = WDT(timeout=2000) # enable it with a timeout of 2s
1415
wdt.feed()
1516

1617
Constructors

‎docs/library/machine.rst‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -121,7 +121,6 @@ Classes
121121
:maxdepth: 1
122122

123123
machine.ADC.rst
124-
machine.HeartBeat.rst
125124
machine.I2C.rst
126125
machine.Pin.rst
127126
machine.RTC.rst

‎docs/library/network.rst‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,10 @@ For example::
3434
class server
3535
============
3636

37+
The server class controls the behaviour and the configuration of the FTP and telnet
38+
services running on the WiPy. Any changes performed using this class' methods will
39+
affect both.
40+
3741
Constructors
3842
------------
3943

‎docs/library/ussl.rst‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,11 @@ Functions
3131
- The certificate to authenticate ourselves goes in: **'/flash/cert/cert.pem'**
3232
- The key for our own certificate goes in: **'/flash/cert/private.key'**
3333

34+
.. note::
35+
36+
When these files are stored, they are placed inside the internal **hidden** file system
37+
(just like firmware updates), and therefore they are never visible.
38+
3439
For instance to connect to the Blynk servers using certificates, take the file ``ca.pem`` located
3540
in the `blynk examples folder <https://github.com/wipy/wipy/tree/master/examples/blynk>`_
3641
and put it in '/flash/cert/'. Then do::

‎docs/wipy/general.rst‎

Lines changed: 31 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -18,11 +18,9 @@ Before applying power
1818

1919
The GPIO pins of the WiPy are NOT 5V tolerant, connecting them to voltages higer
2020
than 3.6V will cause irreparable damage to the board. ADC pins, when configured
21-
in analog mode cannot withstand volatges above 1.8V. Keep these considerations in
21+
in analog mode cannot withstand voltages above 1.8V. Keep these considerations in
2222
mind when wiring your electronics.
2323

24-
25-
2624
WLAN default behaviour
2725
----------------------
2826

@@ -33,29 +31,43 @@ to gain access to the interactive prompt, open a telnet session to that IP addre
3331
the default port (23). You will be asked for credentials:
3432
``login: micro`` and ``password: python``
3533

36-
Local file system and SD card
37-
-----------------------------
34+
Telnet REPL
35+
-----------
36+
37+
Linux stock telnet works like a charm (also on OSX), but other tools like putty
38+
work quite too. The default credentials are: **user:** ``micro``, **password:** ``python``.
39+
See :ref:`network.server <network.server>` for info on how to change the defaults.
40+
For instance, on a linux shell (when connected to the WiPy in AP mode)::
41+
42+
$ telnet 192.168.1.1
43+
44+
Local file system and FTP access
45+
--------------------------------
3846

3947
There is a small internal file system (a drive) on the WiPy, called ``/flash``,
4048
which is stored within the external serial flash memory. If a micro SD card
41-
is hooked-up and enabled, it is available as ``/sd``.
49+
is hooked-up and mounted, it will be available as well.
4250

43-
When the WiPy boots up, it always boots from the ``boot.py`` located in the
44-
``/flash`` file system. If during the boot process the SD card is enabled and
45-
it's selected as the current drive then the WiPy will try to execute ``main.py``
46-
that should be located in the SD card.
51+
When the WiPy starts up, it always boots from the ``boot.py`` located in the
52+
``/flash`` file system.
4753

4854
The file system is accessible via the native FTP server running in the WiPy.
4955
Open your FTP client of choice and connect to:
5056

51-
``ftp://192.168.1.1``, ``user: micro``, ``password: python``
57+
**url:** ``ftp://192.168.1.1``, **user:** ``micro``, **password:** ``python``
58+
59+
See :ref:`network.server <network.server>` for info on how to change the defaults.
60+
The recommended clients are: Linux stock FTP (also in OSX), Filezilla and FireFTP.
61+
For example, on a linux shell::
62+
63+
$ ftp 192.168.1.1
5264

53-
The FTP server on the WiPy doesn't support active mode, only passive, so for instance
54-
if using the native unix ftp client, just after logging in::
65+
The FTP server on the WiPy doesn't support active mode, only passive, therefore,
66+
if using the native unix ftp client, just after logging in do::
5567

5668
ftp> passive
5769

58-
Besides that, the FTP server only supports onw data connection at a time. Check out
70+
Besides that, the FTP server only supports one data connection at a time. Check out
5971
the Filezilla settings section below for more info.
6072

6173
FileZilla settings
@@ -74,16 +86,17 @@ Upgrading the firmware Over The Air
7486

7587
OTA software updates can be performed through the FTP server. Upload the ``mcuimg.bin`` file
7688
to: ``/flash/sys/mcuimg.bin`` it will take around 6s. You won't see the file being stored
77-
inside ``/flash/sys/`` because it's actually saved bypassing the user file system, but rest
78-
assured that it was successfully transferred, and it has been signed with a MD5 checksum to
79-
verify its integrity. Now, reset the MCU by pressing the switch on the board, or by typing::
89+
inside ``/flash/sys/`` because it's actually saved bypassing the user file system, so it
90+
ends up inside the internal **hidden** file system, but rest assured that it was successfully
91+
transferred, and it has been signed with a MD5 checksum to verify its integrity. Now, reset
92+
the WiPy by pressing the switch on the board, or by typing::
8093

8194
import machine
8295
machine.reset()
8396

8497
Software updates can be found in: https://github.com/wipy/wipy/releases
8598
It's always recommended to update to the latest software, but make sure to
86-
read the ``release notes`` before.
99+
read the **release notes** before.
87100

88101
Boot modes
89102
----------

0 commit comments

Comments
 (0)