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.rst | 23 ++++++++++++++++++----- 1 file changed, 18 insertions(+), 5 deletions(-) (limited to 'docs/library/machine.rst') 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 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/library/machine.rst') 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 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/library/machine.rst') 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 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/library/machine.rst') 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 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/library/machine.rst') 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 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/library/machine.rst') 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/library/machine.rst') 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 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/library/machine.rst') 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 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/library/machine.rst') 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