From e178ef252094b8235295d21a72621a58b92623ab Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivan=20Peji=C4=87?= Date: Mon, 9 Feb 2015 01:42:08 +0100 Subject: [PATCH] docs: Add additional example/note for Timer's callback usage. Add example: using named function for the Timer's callback. Add note: improving traceback inside interrupt timers. --- docs/library/micropython.rst | 3 ++- docs/library/pyb.Timer.rst | 11 +++++++++++ 2 files changed, 13 insertions(+), 1 deletion(-) diff --git a/docs/library/micropython.rst b/docs/library/micropython.rst index c4706c4c61..7564f29ae2 100644 --- a/docs/library/micropython.rst +++ b/docs/library/micropython.rst @@ -29,7 +29,8 @@ Functions Allocate ``size`` bytes of RAM for the emergency exception buffer (a good size is around 100 bytes). The buffer is used to create exceptions in cases - when normal RAM allocation would fail (eg within an interrupt handler). + when normal RAM allocation would fail (eg within an interrupt handler) and + therefore give useful traceback information in these situations. 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 diff --git a/docs/library/pyb.Timer.rst b/docs/library/pyb.Timer.rst index b2f10320cf..d2fe9ecbb9 100644 --- a/docs/library/pyb.Timer.rst +++ b/docs/library/pyb.Timer.rst @@ -18,6 +18,13 @@ Example usage to toggle an LED at a fixed frequency:: 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 @@ -32,6 +39,10 @@ Further examples:: 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 ------------