diff --git a/cc3200/mods/pybtimer.c b/cc3200/mods/pybtimer.c
index 35ef0a57a1a156f32dd9b8b0eb295375c96f0ca7..1975cb4b25af21f070ae5990f3f4ad9501e00285 100644
--- a/cc3200/mods/pybtimer.c
+++ b/cc3200/mods/pybtimer.c
@@ -315,8 +315,9 @@ STATIC void pyb_timer_print(const mp_print_t *print, mp_obj_t self_in, mp_print_
/// Initialise the timer. Initialisation must give the desired mode
/// and an optional timer width
///
+/// tim.init(mode=Timer.ONE_SHOT, width=32) # one shot mode
/// tim.init(mode=Timer.PERIODIC) # configure in free running periodic mode
-/// tim.init(mode=Timer.ONE_SHOT, width=16) # one shot mode splitted into two 16-bit independent timers
+/// split into two 16-bit independent timers
///
/// Keyword arguments:
///
@@ -326,7 +327,7 @@ STATIC void pyb_timer_print(const mp_print_t *print, mp_obj_t self_in, mp_print_
STATIC mp_obj_t pyb_timer_init_helper(pyb_timer_obj_t *tim, mp_uint_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
static const mp_arg_t allowed_args[] = {
{ MP_QSTR_mode, MP_ARG_REQUIRED | MP_ARG_INT, },
- { MP_QSTR_width, MP_ARG_KW_ONLY | MP_ARG_INT, {.u_int = 32} },
+ { MP_QSTR_width, MP_ARG_KW_ONLY | MP_ARG_INT, {.u_int = 16} },
};
// parse args
@@ -405,7 +406,7 @@ STATIC mp_obj_t pyb_timer_deinit(mp_obj_t self_in) {
}
STATIC MP_DEFINE_CONST_FUN_OBJ_1(pyb_timer_deinit_obj, pyb_timer_deinit);
-/// \method channel(channel, *, freq, polarity, duty_cycle)
+/// \method channel(channel, *, freq, period, polarity, duty_cycle)
/// Initialise the timer channel. Initialization requires at least a frequency param. With no
/// extra params given besides the channel id, the channel is returned with the previous configuration
/// os 'None', if it hasn't been initialized before.
@@ -735,7 +736,7 @@ STATIC mp_obj_t pyb_timer_channel_duty_cycle(mp_uint_t n_args, const mp_obj_t *a
}
STATIC MP_DEFINE_CONST_FUN_OBJ_VAR_BETWEEN(pyb_timer_channel_duty_cycle_obj, 1, 3, pyb_timer_channel_duty_cycle);
-/// \method callback(handler, value, priority)
+/// \method callback(handler, priority, value)
/// create a callback object associated with the timer channel
STATIC mp_obj_t pyb_timer_channel_callback (mp_uint_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
mp_arg_val_t args[mpcallback_INIT_NUM_ARGS];
@@ -753,10 +754,21 @@ STATIC mp_obj_t pyb_timer_channel_callback (mp_uint_t n_args, const mp_obj_t *po
goto invalid_args;
}
+ uint32_t _config = (ch->channel == TIMER_B) ? ((ch->timer->config & TIMER_B) >> 8) : (ch->timer->config & TIMER_A);
+
+ // validate and set the value if we are in edge count mode
+ if (_config == TIMER_CFG_A_CAP_COUNT) {
+ uint32_t c_value = args[3].u_int;
+ if (!c_value || c_value > 0xFFFF) {
+ // zero or exceeds the maximum value of a 16-bit timer
+ goto invalid_args;
+ }
+ MAP_TimerMatchSet(ch->timer->timer, ch->channel, c_value);
+ }
+
// disable the callback first
pyb_timer_channel_callback_disable(ch);
- uint32_t _config = (ch->channel == TIMER_B) ? ((ch->timer->config & TIMER_B) >> 8) : (ch->timer->config & TIMER_A);
uint8_t shift = (ch->channel == TIMER_B) ? 8 : 0;
switch (_config) {
case TIMER_CFG_A_ONE_SHOT:
@@ -778,13 +790,9 @@ STATIC mp_obj_t pyb_timer_channel_callback (mp_uint_t n_args, const mp_obj_t *po
default:
break;
}
+ // special case for a 32-bit timer
if (ch->channel == (TIMER_A | TIMER_B)) {
- // again a special case for the pwm match interrupt
- if (_config == TIMER_CFG_A_PWM) {
- ch->timer->intflags |= TIMER_TIMB_MATCH;
- } else {
- ch->timer->intflags |= (ch->timer->intflags << 8);
- }
+ ch->timer->intflags |= (ch->timer->intflags << 8);
}
void (*pfnHandler)(void);
@@ -835,6 +843,12 @@ STATIC mp_obj_t pyb_timer_channel_callback (mp_uint_t n_args, const mp_obj_t *po
// create the callback
_callback = mpcallback_new (ch, args[1].u_obj, &pyb_timer_channel_cb_methods);
+ // reload the timer
+ uint32_t period_c;
+ uint32_t match;
+ compute_prescaler_period_and_match_value(ch, &period_c, &match);
+ MAP_TimerLoadSet(ch->timer->timer, ch->channel, period_c);
+
// enable the callback before returning
pyb_timer_channel_callback_enable(ch);
}
diff --git a/docs/library/pyb.Pin.rst b/docs/library/pyb.Pin.rst
index 9f9100a783829169ab6ab645f21207d0451a4e1b..77a96494e6451ffcdaf9e94d7f43d746eb1e6e00 100644
--- a/docs/library/pyb.Pin.rst
+++ b/docs/library/pyb.Pin.rst
@@ -262,9 +262,9 @@ Methods
Return a 5-tuple with the configuration of the pin:
``(name, alternate-function, mode, type, strength)``
- .. method:: pin.callback(mode, priority=1, handler=None, wakes=pyb.Sleep.ACTIVE)
+ .. method:: pin.callback(\*, mode, priority=1, handler=None, wakes=pyb.Sleep.ACTIVE)
- Create a callback to be triggered when data is received on the UART.
+ Create a callback to be triggered when the input level at the pin changes.
- ``mode`` configures the pin level which can generate an interrupt. Possible values are:
@@ -286,8 +286,8 @@ Methods
of this pins can be enabled as a wake source at the same time, so, only
the last enabled pin as a ``pyb.Sleep.SUSPENDED`` wake source will have effect.
- If ``wakes=pyb.Sleep.SUSPENDED`` pins ``GPIO2``, ``GPIO4``, ``GPIO10``,
- ``GPIO11``, GPIO17`` and ``GPIO24`` can wake the board. In this case all this 6
- pins can be enabled as a ``pyb.Sleep.HIBERNATE`` wake source at the same time.
+ ``GPIO11``, ``GPIO17`` and ``GPIO24`` can wake the board. In this case all of the
+ 6 pins can be enabled as a ``pyb.Sleep.HIBERNATE`` wake source at the same time.
- Values can be ORed to make a pin generate interrupts in more than one power
mode.
diff --git a/docs/library/pyb.RTC.rst b/docs/library/pyb.RTC.rst
index dacd2d7bb930037fe27a5a9e155ca233c4d97037..478731247a32f03ee8298d6ad85c5c69f8b4d2c1 100644
--- a/docs/library/pyb.RTC.rst
+++ b/docs/library/pyb.RTC.rst
@@ -32,13 +32,23 @@ Methods
date and time. With 1 argument (being an 8-tuple) it sets the date
and time.
- The 8-tuple has the following format:
+ .. only:: port_pyboard
- (year, month, day, weekday, hours, minutes, seconds, subseconds)
-
- ``weekday`` is 1-7 for Monday through Sunday.
+ The 8-tuple has the following format:
+
+ (year, month, day, weekday, hours, minutes, seconds, subseconds)
+
+ ``weekday`` is 1-7 for Monday through Sunday.
+
+ ``subseconds`` counts down from 255 to 0
+
+ .. only:: port_wipy
- ``subseconds`` counts down from 255 to 0
+ The 8-tuple has the following format:
+
+ ``(year, month, day, weekday, hours, minutes, seconds, milliseconds)``
+
+ ``weekday`` is 0-6 for Monday through Sunday.
.. only:: port_pyboard
diff --git a/docs/library/pyb.SD.rst b/docs/library/pyb.SD.rst
index 84feb83486e4ec0bdd32c1445d7ab251e6ce686a..cbdfdfd04a494bf2675990c2aa8b2e08f32d14eb 100644
--- a/docs/library/pyb.SD.rst
+++ b/docs/library/pyb.SD.rst
@@ -15,7 +15,7 @@ Example usage::
# data, clk and cmd pins must be passed along with
# their respective alternate functions
- sd = pyb.SD('GPIO15', 8, 'GPIO16', 8, 'GPIO17', 8)
+ sd = pyb.SD('GPIO15', 8, 'GPIO10', 6, 'GPIO11', 6)
sd.enable() # enable and mount the SD card
sd.disable() # disable and unmount it
diff --git a/docs/library/pyb.Timer.rst b/docs/library/pyb.Timer.rst
index d2fe9ecbb959cfed9aa80e99c0222329ceec1a3b..ca1d4702e595b607828268879e32d113eddd3754 100644
--- a/docs/library/pyb.Timer.rst
+++ b/docs/library/pyb.Timer.rst
@@ -3,214 +3,339 @@
class Timer -- control internal timers
======================================
-Timers can be used for a great variety of tasks. At the moment, only
-the simplest case is implemented: that of calling a function periodically.
+.. only:: port_pyboard
+
+ Timers can be used for a great variety of tasks. At the moment, only
+ the simplest case is implemented: that of calling a function periodically.
+
+ Each timer consists of a counter that counts up at a certain rate. The rate
+ at which it counts is the peripheral clock frequency (in Hz) divided by the
+ timer prescaler. When the counter reaches the timer period it triggers an
+ event, and the counter resets back to zero. By using the callback method,
+ the timer event can call a Python function.
+
+ Example usage to toggle an LED at a fixed frequency::
+
+ tim = pyb.Timer(4) # create a timer object using timer 4
+ tim.init(freq=2) # trigger at 2Hz
+ tim.callback(lambda t:pyb.LED(1).toggle())
+
+ Example using named function for the callback::
+
+ def tick(timer): # we will receive the timer object when being called
+ print(timer.counter()) # show current timer's counter value
+ tim = pyb.Timer(4, freq=1) # create a timer object using timer 4 - trigger at 1Hz
+ tim.callback(tick) # set the callback to our tick function
+
+ Further examples::
+
+ tim = pyb.Timer(4, freq=100) # freq in Hz
+ tim = pyb.Timer(4, prescaler=0, period=99)
+ tim.counter() # get counter (can also set)
+ tim.prescaler(2) # set prescaler (can also get)
+ tim.period(199) # set period (can also get)
+ tim.callback(lambda t: ...) # set callback for update interrupt (t=tim instance)
+ tim.callback(None) # clear callback
+
+ *Note:* Timer 3 is reserved for internal use. Timer 5 controls
+ the servo driver, and Timer 6 is used for timed ADC/DAC reading/writing.
+ It is recommended to use the other timers in your programs.
+
+.. 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 2 16-bit channels and this channels can be tied together to
+ form 1 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::
+
+ tim = pyb.Timer(4) # create a timer object using timer 4
+ tim.init(mode=Timer.PERIODIC) # initialize it in periodic mode
+ tim_ch = tim.channel(Timer.A, freq=2) # configure channel A at a frequency of 2Hz
+ tim_ch.callback(handler=lambda t:led.toggle()) # toggle a LED on every cycle of the timer
+
+ Example using named function for the callback::
+
+ tim = Timer(1, mode=Timer.PERIODIC)
+ tim_a = tim.channel(Timer.A, freq=1000)
+
+ led = Pin('GPIO2', af=0, mode=Pin.OUT)
+
+ def tick(timer): # we will receive the timer object when being called
+ print(timer.time()) # show current timer's time value (is microseconds)
+ led.toggle() # toggle the LED
+
+ tim_a.callback(handler=tick)
+
+ Further examples::
+
+ tim1 = pyb.Timer(2, mode=Timer.EVENT_COUNT) # initialize it capture mode
+ tim2 = pyb.Timer(1, mode=Timer.PWM) # initialize it in PWM mode
+ 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
+ tim_ch = tim2.channel(Timer.B, freq=10000, duty_cycle=50) # start the PWM on channel B with a 50% duty cycle
+ tim_ch.time() # get the current time in usec (can also be set)
+ tim_ch.freq(20) # set the frequency (can also get)
+ tim_ch.duty_cycle(30) # set the duty cycle to 30% (can also get)
+ tim_ch.duty_cycle(30, Timer.NEGATIVE) # set the duty cycle to 30% and change the polarity to negative
+ tim_ch.event_count() # get the number of captured events
+ tim_ch.event_time() # get the the time of the last captured event
+ tim_ch.period(2000000) # change the period to 2 seconds
-Each timer consists of a counter that counts up at a certain rate. The rate
-at which it counts is the peripheral clock frequency (in Hz) divided by the
-timer prescaler. When the counter reaches the timer period it triggers an
-event, and the counter resets back to zero. By using the callback method,
-the timer event can call a Python function.
-
-Example usage to toggle an LED at a fixed frequency::
-
- tim = pyb.Timer(4) # create a timer object using timer 4
- tim.init(freq=2) # trigger at 2Hz
- tim.callback(lambda t:pyb.LED(1).toggle())
-
-Example using named function for the callback::
-
- def tick(timer): # we will receive the timer object when being called
- print(timer.counter()) # show current timer's counter value
- tim = pyb.Timer(4, freq=1) # create a timer object using timer 4 - trigger at 1Hz
- tim.callback(tick) # set the callback to our tick function
-
-Further examples::
-
- tim = pyb.Timer(4, freq=100) # freq in Hz
- tim = pyb.Timer(4, prescaler=0, period=99)
- tim.counter() # get counter (can also set)
- tim.prescaler(2) # set prescaler (can also get)
- tim.period(199) # set period (can also get)
- tim.callback(lambda t: ...) # set callback for update interrupt (t=tim instance)
- tim.callback(None) # clear callback
-
-*Note:* Timer 3 is reserved for internal use. Timer 5 controls
-the servo driver, and Timer 6 is used for timed ADC/DAC reading/writing.
-It is recommended to use the other timers in your programs.
*Note:* Memory can't be allocated during a callback (an interrupt) and so
exceptions raised within a callback don't give much information. See
:func:`micropython.alloc_emergency_exception_buf` for how to get around this
limitation.
+
Constructors
------------
.. class:: pyb.Timer(id, ...)
- Construct a new timer object of the given id. If additional
- arguments are given, then the timer is initialised by ``init(...)``.
- ``id`` can be 1 to 14, excluding 3.
+ .. only:: port_pyboard
+
+ Construct a new timer object of the given id. If additional
+ arguments are given, then the timer is initialised by ``init(...)``.
+ ``id`` can be 1 to 14, excluding 3.
+
+ .. only:: port_wipy
+
+ Construct a new timer object of the given id. If additional
+ arguments are given, then the timer is initialised by ``init(...)``.
+ ``id`` can be 1 to 4.
Methods
-------
-.. method:: timer.callback(fun)
+.. only:: port_pyboard
- Set the function to be called when the timer triggers.
- ``fun`` is passed 1 argument, the timer object.
- If ``fun`` is ``None`` then the callback will be disabled.
+ .. method:: timer.init(\*, freq, prescaler, period)
+
+ Initialise the timer. Initialisation must be either by frequency (in Hz)
+ or by prescaler and period::
+
+ tim.init(freq=100) # set the timer to trigger at 100Hz
+ tim.init(prescaler=83, period=999) # set the prescaler and period directly
+
+ Keyword arguments:
+
+ - ``freq`` --- specifies the periodic frequency of the timer. You migh also
+ view this as the frequency with which the timer goes through one complete cycle.
+
+ - ``prescaler`` [0-0xffff] - specifies the value to be loaded into the
+ timer's Prescaler Register (PSC). The timer clock source is divided by
+ (``prescaler + 1``) to arrive at the timer clock. Timers 2-7 and 12-14
+ have a clock source of 84 MHz (pyb.freq()[2] \* 2), and Timers 1, and 8-11
+ have a clock source of 168 MHz (pyb.freq()[3] \* 2).
+
+ - ``period`` [0-0xffff] for timers 1, 3, 4, and 6-15. [0-0x3fffffff] for timers 2 & 5.
+ Specifies the value to be loaded into the timer's AutoReload
+ Register (ARR). This determines the period of the timer (i.e. when the
+ counter cycles). The timer counter will roll-over after ``period + 1``
+ timer clock cycles.
+
+ - ``mode`` can be one of:
+
+ - ``Timer.UP`` - configures the timer to count from 0 to ARR (default)
+ - ``Timer.DOWN`` - configures the timer to count from ARR down to 0.
+ - ``Timer.CENTER`` - confgures the timer to count from 0 to ARR and
+ then back down to 0.
+
+ - ``div`` can be one of 1, 2, or 4. Divides the timer clock to determine
+ the sampling clock used by the digital filters.
+
+ - ``callback`` - as per Timer.callback()
+
+ - ``deadtime`` - specifies the amount of "dead" or inactive time between
+ transitions on complimentary channels (both channels will be inactive)
+ for this time). ``deadtime`` may be an integer between 0 and 1008, with
+ the following restrictions: 0-128 in steps of 1. 128-256 in steps of
+ 2, 256-512 in steps of 8, and 512-1008 in steps of 16. ``deadime``
+ measures ticks of ``source_freq`` divided by ``div`` clock ticks.
+ ``deadtime`` is only available on timers 1 and 8.
+
+ You must either specify freq or both of period and prescaler.
-.. method:: timer.channel(channel, mode, ...)
+.. only:: port_wipy
- If only a channel number is passed, then a previously initialized channel
- object is returned (or ``None`` if there is no previous channel).
-
- Othwerwise, a TimerChannel object is initialized and returned.
-
- Each channel can be configured to perform pwm, output compare, or
- input capture. All channels share the same underlying timer, which means
- that they share the same timer clock.
-
- Keyword arguments:
-
- - ``mode`` can be one of:
-
- - ``Timer.PWM`` --- configure the timer in PWM mode (active high).
- - ``Timer.PWM_INVERTED`` --- configure the timer in PWM mode (active low).
- - ``Timer.OC_TIMING`` --- indicates that no pin is driven.
- - ``Timer.OC_ACTIVE`` --- the pin will be made active when a compare match occurs (active is determined by polarity)
- - ``Timer.OC_INACTIVE`` --- the pin will be made inactive when a compare match occurs.
- - ``Timer.OC_TOGGLE`` --- the pin will be toggled when an compare match occurs.
- - ``Timer.OC_FORCED_ACTIVE`` --- the pin is forced active (compare match is ignored).
- - ``Timer.OC_FORCED_INACTIVE`` --- the pin is forced inactive (compare match is ignored).
- - ``Timer.IC`` --- configure the timer in Input Capture mode.
- - ``Timer.ENC_A`` --- configure the timer in Encoder mode. The counter only changes when CH1 changes.
- - ``Timer.ENC_B`` --- configure the timer in Encoder mode. The counter only changes when CH2 changes.
- - ``Timer.ENC_AB`` --- configure the timer in Encoder mode. The counter changes when CH1 or CH2 changes.
-
- - ``callback`` - as per TimerChannel.callback()
-
- - ``pin`` None (the default) or a Pin object. If specified (and not None)
- this will cause the alternate function of the the indicated pin
- to be configured for this timer channel. An error will be raised if
- the pin doesn't support any alternate functions for this timer channel.
+ .. method:: timer.init(mode, \*, width=16)
+
+ Initialise the timer. Example::
+
+ tim.init(Timer.PERIODIC) # periodic 16-bit timer
+ tim.init(Timer.ONE_SHOT, width=32) # one shot 32-bit timer
- Keyword arguments for Timer.PWM modes:
-
- - ``pulse_width`` - determines the initial pulse width value to use.
- - ``pulse_width_percent`` - determines the initial pulse width percentage to use.
-
- Keyword arguments for Timer.OC modes:
-
- - ``compare`` - determines the initial value of the compare register.
-
- - ``polarity`` can be one of:
+ Keyword arguments:
+
+ - ``mode`` can be one of:
+
+ - ``Timer.ONE_SHOT`` - The timer runs once until the configured
+ period of the channel expires.
+ - ``Timer.PERIODIC`` - The timer runs periodically at the configured
+ frequency of the channel.
+ - ``Timer.EDGE_TIME`` - Meaure the time pin level changes.
+ - ``Timer.EDGE_COUNT`` - Count the number of pin level changes.
+
+ - ``width`` must be either 16 or 32 (bits). For really low frequencies <= ~1Hz
+ (or large periods), 32-bit timers should be used. 32-bit mode is only available
+ for ``ONE_SHOT`` AND ``PERIODIC`` modes.
- - ``Timer.HIGH`` - output is active high
- - ``Timer.LOW`` - output is acive low
-
- Optional keyword arguments for Timer.IC modes:
-
- - ``polarity`` can be one of:
+.. method:: timer.deinit()
- - ``Timer.RISING`` - captures on rising edge.
- - ``Timer.FALLING`` - captures on falling edge.
- - ``Timer.BOTH`` - captures on both edges.
-
- Note that capture only works on the primary channel, and not on the
- complimentary channels.
+ Deinitialises the timer.
- Notes for Timer.ENC modes:
+ .. only:: port_pyboard
+
+ Disables the callback (and the associated irq).
+
+ Disables any channel callbacks (and the associated irq).
+ Stops the timer, and disables the timer peripheral.
+
+.. only:: port_pyboard
- - Requires 2 pins, so one or both pins will need to be configured to use
- the appropriate timer AF using the Pin API.
- - Read the encoder value using the timer.counter() method.
- - Only works on CH1 and CH2 (and not on CH1N or CH2N)
- - The channel number is ignored when setting the encoder mode.
+ .. method:: timer.callback(fun)
+
+ Set the function to be called when the timer triggers.
+ ``fun`` is passed 1 argument, the timer object.
+ If ``fun`` is ``None`` then the callback will be disabled.
+
+.. only:: port_pyboard
+
+ .. method:: timer.channel(channel, mode, ...)
+
+ If only a channel number is passed, then a previously initialized channel
+ object is returned (or ``None`` if there is no previous channel).
- PWM Example::
-
- timer = pyb.Timer(2, freq=1000)
- ch2 = timer.channel(2, pyb.Timer.PWM, pin=pyb.Pin.board.X2, pulse_width=8000)
- ch3 = timer.channel(3, pyb.Timer.PWM, pin=pyb.Pin.board.X3, pulse_width=16000)
+ Othwerwise, a TimerChannel object is initialized and returned.
+
+ Each channel can be configured to perform pwm, output compare, or
+ input capture. All channels share the same underlying timer, which means
+ that they share the same timer clock.
+
+ Keyword arguments:
+
+ - ``mode`` can be one of:
+
+ - ``Timer.PWM`` --- configure the timer in PWM mode (active high).
+ - ``Timer.PWM_INVERTED`` --- configure the timer in PWM mode (active low).
+ - ``Timer.OC_TIMING`` --- indicates that no pin is driven.
+ - ``Timer.OC_ACTIVE`` --- the pin will be made active when a compare match occurs (active is determined by polarity)
+ - ``Timer.OC_INACTIVE`` --- the pin will be made inactive when a compare match occurs.
+ - ``Timer.OC_TOGGLE`` --- the pin will be toggled when an compare match occurs.
+ - ``Timer.OC_FORCED_ACTIVE`` --- the pin is forced active (compare match is ignored).
+ - ``Timer.OC_FORCED_INACTIVE`` --- the pin is forced inactive (compare match is ignored).
+ - ``Timer.IC`` --- configure the timer in Input Capture mode.
+ - ``Timer.ENC_A`` --- configure the timer in Encoder mode. The counter only changes when CH1 changes.
+ - ``Timer.ENC_B`` --- configure the timer in Encoder mode. The counter only changes when CH2 changes.
+ - ``Timer.ENC_AB`` --- configure the timer in Encoder mode. The counter changes when CH1 or CH2 changes.
+
+ - ``callback`` - as per TimerChannel.callback()
+
+ - ``pin`` None (the default) or a Pin object. If specified (and not None)
+ this will cause the alternate function of the the indicated pin
+ to be configured for this timer channel. An error will be raised if
+ the pin doesn't support any alternate functions for this timer channel.
+
+ Keyword arguments for Timer.PWM modes:
+
+ - ``pulse_width`` - determines the initial pulse width value to use.
+ - ``pulse_width_percent`` - determines the initial pulse width percentage to use.
+
+ Keyword arguments for Timer.OC modes:
+
+ - ``compare`` - determines the initial value of the compare register.
+
+ - ``polarity`` can be one of:
+
+ - ``Timer.HIGH`` - output is active high
+ - ``Timer.LOW`` - output is acive low
+
+ Optional keyword arguments for Timer.IC modes:
+
+ - ``polarity`` can be one of:
+
+ - ``Timer.RISING`` - captures on rising edge.
+ - ``Timer.FALLING`` - captures on falling edge.
+ - ``Timer.BOTH`` - captures on both edges.
+
+ Note that capture only works on the primary channel, and not on the
+ complimentary channels.
+
+ Notes for Timer.ENC modes:
+
+ - Requires 2 pins, so one or both pins will need to be configured to use
+ the appropriate timer AF using the Pin API.
+ - Read the encoder value using the timer.counter() method.
+ - Only works on CH1 and CH2 (and not on CH1N or CH2N)
+ - The channel number is ignored when setting the encoder mode.
+
+ PWM Example::
+
+ timer = pyb.Timer(2, freq=1000)
+ ch2 = timer.channel(2, pyb.Timer.PWM, pin=pyb.Pin.board.X2, pulse_width=8000)
+ ch3 = timer.channel(3, pyb.Timer.PWM, pin=pyb.Pin.board.X3, pulse_width=16000)
-.. method:: timer.counter([value])
+.. only:: port_wipy
- Get or set the timer counter.
+ .. method:: timer.channel(channel, \**, freq, period, polarity=Timer.POSITIVE, duty_cycle=0)
+
+ If only a channel identifier passed, then a previously initialized channel
+ object is returned (or ``None`` if there is no previous channel).
+
+ Othwerwise, a TimerChannel object is initialized and returned.
+
+ The operating mode is is the one configured to the Timer object that was used to
+ create the channel.
-.. method:: timer.deinit()
+ - ``channel`` if the width of the timer is 16-bit, then must be either ``TIMER.A``, ``TIMER.B``.
+ If the width is 32-bit then it **must be** ``TIMER.A | TIMER.B``.
- Deinitialises the timer.
-
- Disables the callback (and the associated irq).
- Disables any channel callbacks (and the associated irq).
- Stops the timer, and disables the timer peripheral.
+ Keyword only arguments:
-.. method:: timer.freq([value])
+ - ``freq`` sets the frequency in Hz.
+ - ``period`` sets the period in microseconds.
- Get or set the frequency for the timer (changes prescaler and period if set).
+ .. note::
-.. method:: timer.init(\*, freq, prescaler, period)
+ Either ``freq`` or ``period`` must be given, never both.
- Initialise the timer. Initialisation must be either by frequency (in Hz)
- or by prescaler and period::
-
- tim.init(freq=100) # set the timer to trigger at 100Hz
- tim.init(prescaler=83, period=999) # set the prescaler and period directly
-
- Keyword arguments:
-
- - ``freq`` --- specifies the periodic frequency of the timer. You migh also
- view this as the frequency with which the timer goes through one complete cycle.
-
- - ``prescaler`` [0-0xffff] - specifies the value to be loaded into the
- timer's Prescaler Register (PSC). The timer clock source is divided by
- (``prescaler + 1``) to arrive at the timer clock. Timers 2-7 and 12-14
- have a clock source of 84 MHz (pyb.freq()[2] \* 2), and Timers 1, and 8-11
- have a clock source of 168 MHz (pyb.freq()[3] \* 2).
-
- - ``period`` [0-0xffff] for timers 1, 3, 4, and 6-15. [0-0x3fffffff] for timers 2 & 5.
- Specifies the value to be loaded into the timer's AutoReload
- Register (ARR). This determines the period of the timer (i.e. when the
- counter cycles). The timer counter will roll-over after ``period + 1``
- timer clock cycles.
-
- - ``mode`` can be one of:
+ - ``polarity`` this is applicable for:
+
+ - ``PWM``, defines the polarity of the duty cycle
+ - ``EDGE_TIME`` and ``EDGE_COUNT``, defines the polarity of the pin level change to detect.
+ To detect both rising and falling edges, make ``polarity=Timer.POSITIVE | Timer.NEGATIVE``.
+ - ``duty_cycle`` only applicable to ``PWM``. It's a percentage (0-100)
- - ``Timer.UP`` - configures the timer to count from 0 to ARR (default)
- - ``Timer.DOWN`` - configures the timer to count from ARR down to 0.
- - ``Timer.CENTER`` - confgures the timer to count from 0 to ARR and
- then back down to 0.
-
- - ``div`` can be one of 1, 2, or 4. Divides the timer clock to determine
- the sampling clock used by the digital filters.
-
- - ``callback`` - as per Timer.callback()
-
- - ``deadtime`` - specifies the amount of "dead" or inactive time between
- transitions on complimentary channels (both channels will be inactive)
- for this time). ``deadtime`` may be an integer between 0 and 1008, with
- the following restrictions: 0-128 in steps of 1. 128-256 in steps of
- 2, 256-512 in steps of 8, and 512-1008 in steps of 16. ``deadime``
- measures ticks of ``source_freq`` divided by ``div`` clock ticks.
- ``deadtime`` is only available on timers 1 and 8.
-
- You must either specify freq or both of period and prescaler.
+.. only:: port_pyboard
-.. method:: timer.period([value])
+ .. method:: timer.counter([value])
- Get or set the period of the timer.
+ Get or set the timer counter.
-.. method:: timer.prescaler([value])
+.. only:: port_pyboard
- Get or set the prescaler for the timer.
+ .. method:: timer.freq([value])
+
+ Get or set the frequency for the timer (changes prescaler and period if set).
-.. method:: timer.source_freq()
+.. only:: port_pyboard
- Get the frequency of the source of the timer.
+ .. method:: timer.period([value])
+
+ Get or set the period of the timer.
+
+ .. method:: timer.prescaler([value])
+
+ Get or set the prescaler for the timer.
+
+ .. method:: timer.source_freq()
+
+ Get the frequency of the source of the timer.
class TimerChannel --- setup a channel for a timer
==================================================
@@ -222,37 +347,93 @@ TimerChannel objects are created using the Timer.channel() method.
Methods
-------
-.. method:: timerchannel.callback(fun)
-
- Set the function to be called when the timer channel triggers.
- ``fun`` is passed 1 argument, the timer object.
- If ``fun`` is ``None`` then the callback will be disabled.
-
-.. method:: timerchannel.capture([value])
-
- Get or set the capture value associated with a channel.
- capture, compare, and pulse_width are all aliases for the same function.
- capture is the logical name to use when the channel is in input capture mode.
-
-.. method:: timerchannel.compare([value])
+.. only:: port_pyboard
+
+ .. method:: timerchannel.callback(fun)
+
+ Set the function to be called when the timer channel triggers.
+ ``fun`` is passed 1 argument, the timer object.
+ If ``fun`` is ``None`` then the callback will be disabled.
+
+.. only:: port_wipy
+
+ .. method:: timerchannel.callback(\**, value, priority=1, handler=None)
+
+ The behavior of this callback is heaviliy dependent on the operating
+ mode of the timer channel:
+
+ - If mode is ``Timer.PERIODIC`` the callback is executed periodically
+ with the configured frequency or period.
+ - If mode is ``Timer.ONE_SHOT`` the callback is executed once when
+ the configured timer expires.
+ - If mode is ``Timer.EDGE_COUNT`` the callback is executed when reaching
+ the configured number of events (see ``value`` param below).
+ - If mode is ``Timer.PWM`` the callback is executed when reaching the duty
+ cycle value.
+
+ The accepted params are:
+
+ - ``priority`` level of the interrupt. Can take values in the range 1-7.
+ Higher values represent higher priorities.
+ - ``handler`` is an optional function to be called when the interrupt is triggered.
+ - ``value`` is **only valid** when in ``Timer.EDGE_COUNT`` mode and is used to set
+ the number of edge events that will trigger the interrupt.
+
+ Returns a callback object.
+
+.. only:: port_pyboard
+
+ .. method:: timerchannel.capture([value])
+
+ Get or set the capture value associated with a channel.
+ capture, compare, and pulse_width are all aliases for the same function.
+ capture is the logical name to use when the channel is in input capture mode.
+
+ .. method:: timerchannel.compare([value])
+
+ Get or set the compare value associated with a channel.
+ capture, compare, and pulse_width are all aliases for the same function.
+ compare is the logical name to use when the channel is in output compare mode.
+
+ .. method:: timerchannel.pulse_width([value])
+
+ Get or set the pulse width value associated with a channel.
+ capture, compare, and pulse_width are all aliases for the same function.
+ pulse_width is the logical name to use when the channel is in PWM mode.
+
+ In edge aligned mode, a pulse_width of ``period + 1`` corresponds to a duty cycle of 100%
+ In center aligned mode, a pulse width of ``period`` corresponds to a duty cycle of 100%
+
+ .. method:: timerchannel.pulse_width_percent([value])
+
+ Get or set the pulse width percentage associated with a channel. The value
+ is a number between 0 and 100 and sets the percentage of the timer period
+ for which the pulse is active. The value can be an integer or
+ floating-point number for more accuracy. For example, a value of 25 gives
+ a duty cycle of 25%.
+
+.. only:: port_wipy
+
+ .. method:: timerchannel.freq([value])
+
+ Get or set the timer channel frequency (in Hz).
+
+ .. method:: timerchannel.period([value])
+
+ Get or set the timer channel period (in microseconds).
+
+ .. method:: timerchannel.time([value])
- Get or set the compare value associated with a channel.
- capture, compare, and pulse_width are all aliases for the same function.
- compare is the logical name to use when the channel is in output compare mode.
+ Get or set the timer channel current **time** value (in microseconds).
+
+ .. method:: timerchannel.event_count()
-.. method:: timerchannel.pulse_width([value])
+ Get the number of edge events counted.
- Get or set the pulse width value associated with a channel.
- capture, compare, and pulse_width are all aliases for the same function.
- pulse_width is the logical name to use when the channel is in PWM mode.
-
- In edge aligned mode, a pulse_width of ``period + 1`` corresponds to a duty cycle of 100%
- In center aligned mode, a pulse width of ``period`` corresponds to a duty cycle of 100%
+ .. method:: timerchannel.event_time()
-.. method:: timerchannel.pulse_width_percent([value])
+ Get the time of ocurrance of the last event.
- Get or set the pulse width percentage associated with a channel. The value
- is a number between 0 and 100 and sets the percentage of the timer period
- for which the pulse is active. The value can be an integer or
- floating-point number for more accuracy. For example, a value of 25 gives
- a duty cycle of 25%.
+ .. method:: timerchannel.duty_cycle([value])
+
+ Get or set the duty cycle of the PWM signal (in the range of 0-100).
diff --git a/docs/library/pyb.rst b/docs/library/pyb.rst
index 5b682e2d61471d752ea6d4d06096a963259ad48d..478ca7f27857db01c5435b1ebeb982ccbf4dda04 100644
--- a/docs/library/pyb.rst
+++ b/docs/library/pyb.rst
@@ -247,7 +247,7 @@ Miscellaneous functions
.. function:: repl_uart(uart)
- Get or set the UART object that the REPL is repeated on.
+ Get or set the UART object where the REPL is repeated on.
.. only:: port_pyboard
@@ -269,13 +269,13 @@ Miscellaneous functions
.. function:: unique_id()
- Returns a string of 12 bytes (96 bits), which is the unique ID for the MCU.
+ Returns a string of 12 bytes (96 bits), which is the unique ID of the MCU.
.. only:: port_wipy
.. function:: unique_id()
- Returns a string of 6 bytes (48 bits), which is the unique ID for the MCU.
+ Returns a string of 6 bytes (48 bits), which is the unique ID of the MCU.
This also corresponds to the ``MAC address`` of the WiPy.
Classes
diff --git a/docs/library/uhashlib.rst b/docs/library/uhashlib.rst
index a8f580fd845054f5bf9c68b96cefa2cf89c6a5ba..5de4b6f7baba2a37829b29e0721dba265ea90551 100644
--- a/docs/library/uhashlib.rst
+++ b/docs/library/uhashlib.rst
@@ -43,7 +43,7 @@ Constructors
:class: attention
Due to hardware implementation details of the WiPy, data must be buffered before being
- digested, which would make impossible to calculate the hash of big blocks of data that
+ 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
diff --git a/docs/pyboard/quickref.rst b/docs/pyboard/quickref.rst
index ebd3c774da20cc2e56db584e7ecae4a1c6b0bb39..2a1429cb05e27c71d822b5a220dbd09366d36a92 100644
--- a/docs/pyboard/quickref.rst
+++ b/docs/pyboard/quickref.rst
@@ -1,6 +1,4 @@
-.. only:: port_pyboard
-
- .. _quickref:
+.. _quickref:
Quick reference for the pyboard
===============================
diff --git a/docs/wipy/general.rst b/docs/wipy/general.rst
index 894990619327def14a71ae345880819459bfa7db..3aad440ba47d7c44063b88d2d88fe1cb14feaa23 100644
--- a/docs/wipy/general.rst
+++ b/docs/wipy/general.rst
@@ -35,12 +35,12 @@ If you power up normally, or press the reset button, the WiPy will boot
into standard mode: the ``boot.py`` file will be executed first, then
``main.py`` will run.
-You can override this boot sequence by pulling ``GPIO28`` **up** during reset.
-The heart beat LED will flash slowly 3 times to signal that safe boot is being
-requested, and then 3 more times quickly to let you know that safe boot is
-going to be performed. While safe booting, the WiPy runs the factory firmware
-and skips the execution of ``boot.py`` and ``main.py``. This is useful to
-recover from any crash situation.
+You can override this boot sequence by pulling ``GPIO28`` **up** (connect
+it to the 3v3 output pin) during reset. The heart beat LED will flash slowly
+3 times to signal that safe boot is being requested, and then 3 more times
+quickly to let you know that safe boot is going to be performed. While safe
+booting, the WiPy runs the factory firmware and skips the execution of
+``boot.py`` and ``main.py``. This is useful to recover from any crash situation.
The heart beat LED
------------------
diff --git a/docs/wipy/quickref.rst b/docs/wipy/quickref.rst
index 9733a8714b2b76d060d7312c0fce036c62b01fb2..a8e0bdc98a7406619f292fc86de9893490370178 100644
--- a/docs/wipy/quickref.rst
+++ b/docs/wipy/quickref.rst
@@ -1,6 +1,4 @@
-.. only:: port_wipy
-
- .. _quickref_:
+.. _quickref_:
Quick reference for the WiPy
============================
@@ -20,7 +18,7 @@ See :mod:`pyb`. ::
pyb.delay(50) # wait 50 milliseconds
pyb.millis() # number of milliseconds since boot-up
pyb.freq() # get the CPU frequency
- pyb.unique_id() # return the 6-byte unique id of the board (it's MAC address)
+ pyb.unique_id() # return the 6-byte unique id of the board (the WiPy's MAC address)
Pins and GPIO
-------------
@@ -176,7 +174,7 @@ See :ref:`pyb.SD <pyb.SD>`. ::
# SD card pins need special configuration so we pass 'em to the constructor
# data pin, data af, clock pin, clock af, cmd pin, cmd af
- sd = SD('GPIO15', 8, 'GPIO16', 8, 'GPIO17', 8)
+ sd = pyb.SD('GPIO15', 8, 'GPIO10', 6, 'GPIO11', 6)
sd.enable()
WLAN (WiFi)
@@ -213,16 +211,16 @@ See ``pyb.Sleep``. ::
Sleep.suspend() # everything except for WLAN is powered down (~950uA)
# wakes from Pin, RTC or WLAN
- Sleep.hibernate() # deepest sleep mode, mcu starts from reset. Wakes from Pin and RTC.
+ Sleep.hibernate() # deepest sleep mode, MCU starts from reset. Wakes from Pin and RTC.
Heart beat LED
------------------------------
+--------------
See :ref:`pyb.HeartBeat <pyb.HeartBeat>`. ::
from pyb import HeartBeat
- # disable the heart beat indication (you are free to use this led connected to GPIO25)
- HeartBeat.disable()
+ # disable the heart beat indication (you are free to use this LED connected to GPIO25)
+ HeartBeat().disable()
# enable the heart beat again
- HeartBeat.enable()
+ HeartBeat().enable()