From 47fef77cf7b26467fe49ac86c22c449369337a49 Mon Sep 17 00:00:00 2001 From: per1234 Date: Sun, 3 Jun 2018 16:58:37 -0700 Subject: [PATCH 1/4] Explain difference between pulseIn() and pulseInLong() Likely the question "What's the difference between this and pulseIn()" will be the first thing a user will want to know when visiting this page. Although this information was somewhat alluded to at the end of the description, it's much better for it to be at the start of the text. Reference: https://github.com/arduino/Arduino/pull/2495#issue-25936527 --- Language/Functions/Advanced IO/pulseInLong.adoc | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Language/Functions/Advanced IO/pulseInLong.adoc b/Language/Functions/Advanced IO/pulseInLong.adoc index aab2979dc..d01d007b8 100644 --- a/Language/Functions/Advanced IO/pulseInLong.adoc +++ b/Language/Functions/Advanced IO/pulseInLong.adoc @@ -17,6 +17,8 @@ subCategories: [ "Advanced I/O" ] [float] === Description +`pulseInLong()` is an alternative to link:../pulsein[pulseIn()] which is better at handling long pulse and interrupt affected scenarios. + Reads a pulse (either HIGH or LOW) on a pin. For example, if value is HIGH, `pulseInLong()` waits for the pin to go `HIGH`, starts timing, then waits for the pin to go `LOW` and stops timing. Returns the length of the pulse in microseconds or 0 if no complete pulse was received within the timeout. The timing of this function has been determined empirically and will probably show errors in shorter pulses. Works on pulses from 10 microseconds to 3 minutes in length. Please also note that if the pin is already high when the function is called, it will wait for the pin to go LOW and then HIGH before it starts counting. This routine can be used only if interrupts are activated. Furthermore the highest resolution is obtained with large intervals. From b1613d799e40f2cab40aecd4d25010731f665600 Mon Sep 17 00:00:00 2001 From: per1234 Date: Sun, 3 Jun 2018 17:03:13 -0700 Subject: [PATCH 2/4] Improve the explanation of pulseInLong()'s pulse handling Previously there was an initial incomplete description of how pulses are handled, followed by a note clarifying how it actually works. Combining all the information into a single statement avoids confusion and makes the documentation less verbose. --- Language/Functions/Advanced IO/pulseInLong.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Language/Functions/Advanced IO/pulseInLong.adoc b/Language/Functions/Advanced IO/pulseInLong.adoc index d01d007b8..313b0b5b4 100644 --- a/Language/Functions/Advanced IO/pulseInLong.adoc +++ b/Language/Functions/Advanced IO/pulseInLong.adoc @@ -19,9 +19,9 @@ subCategories: [ "Advanced I/O" ] === Description `pulseInLong()` is an alternative to link:../pulsein[pulseIn()] which is better at handling long pulse and interrupt affected scenarios. -Reads a pulse (either HIGH or LOW) on a pin. For example, if value is HIGH, `pulseInLong()` waits for the pin to go `HIGH`, starts timing, then waits for the pin to go `LOW` and stops timing. Returns the length of the pulse in microseconds or 0 if no complete pulse was received within the timeout. +Reads a pulse (either HIGH or LOW) on a pin. For example, if value is HIGH, `pulseInLong()` waits for the pin to go from `LOW` to `HIGH`, starts timing, then waits for the pin to go `LOW` and stops timing. Returns the length of the pulse in microseconds or 0 if no complete pulse was received within the timeout. -The timing of this function has been determined empirically and will probably show errors in shorter pulses. Works on pulses from 10 microseconds to 3 minutes in length. Please also note that if the pin is already high when the function is called, it will wait for the pin to go LOW and then HIGH before it starts counting. This routine can be used only if interrupts are activated. Furthermore the highest resolution is obtained with large intervals. +The timing of this function has been determined empirically and will probably show errors in shorter pulses. Works on pulses from 10 microseconds to 3 minutes in length. This routine can be used only if interrupts are activated. Furthermore the highest resolution is obtained with large intervals. [%hardbreaks] From 8daf49983c13d8bdd0182855daffb6ae6f01c3f5 Mon Sep 17 00:00:00 2001 From: per1234 Date: Sun, 3 Jun 2018 17:04:42 -0700 Subject: [PATCH 3/4] Improve documentation of how pulseInLong()'s timeout works Previously it was not clear that the function returns after the timeout expires. --- Language/Functions/Advanced IO/pulseInLong.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Language/Functions/Advanced IO/pulseInLong.adoc b/Language/Functions/Advanced IO/pulseInLong.adoc index 313b0b5b4..217808f55 100644 --- a/Language/Functions/Advanced IO/pulseInLong.adoc +++ b/Language/Functions/Advanced IO/pulseInLong.adoc @@ -19,7 +19,7 @@ subCategories: [ "Advanced I/O" ] === Description `pulseInLong()` is an alternative to link:../pulsein[pulseIn()] which is better at handling long pulse and interrupt affected scenarios. -Reads a pulse (either HIGH or LOW) on a pin. For example, if value is HIGH, `pulseInLong()` waits for the pin to go from `LOW` to `HIGH`, starts timing, then waits for the pin to go `LOW` and stops timing. Returns the length of the pulse in microseconds or 0 if no complete pulse was received within the timeout. +Reads a pulse (either HIGH or LOW) on a pin. For example, if value is HIGH, `pulseInLong()` waits for the pin to go from `LOW` to `HIGH`, starts timing, then waits for the pin to go `LOW` and stops timing. Returns the length of the pulse in microseconds or gives up and returns 0 if no complete pulse was received within the timeout. The timing of this function has been determined empirically and will probably show errors in shorter pulses. Works on pulses from 10 microseconds to 3 minutes in length. This routine can be used only if interrupts are activated. Furthermore the highest resolution is obtained with large intervals. [%hardbreaks] From e8174b7d8fa56ffbe102946d57d4e78e099f1f2c Mon Sep 17 00:00:00 2001 From: per1234 Date: Sun, 3 Jun 2018 17:10:07 -0700 Subject: [PATCH 4/4] Use consistent formatting in pulseInLong() description Code markdown was used on some instances of the words HIGH and LOW and not on others. A search of the rest of the reference pages shows them to be quite inconsistent in formatting but code markdown is used in the majority of instances and I feel that's the correct usage. --- Language/Functions/Advanced IO/pulseInLong.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Language/Functions/Advanced IO/pulseInLong.adoc b/Language/Functions/Advanced IO/pulseInLong.adoc index 217808f55..22940fd55 100644 --- a/Language/Functions/Advanced IO/pulseInLong.adoc +++ b/Language/Functions/Advanced IO/pulseInLong.adoc @@ -19,7 +19,7 @@ subCategories: [ "Advanced I/O" ] === Description `pulseInLong()` is an alternative to link:../pulsein[pulseIn()] which is better at handling long pulse and interrupt affected scenarios. -Reads a pulse (either HIGH or LOW) on a pin. For example, if value is HIGH, `pulseInLong()` waits for the pin to go from `LOW` to `HIGH`, starts timing, then waits for the pin to go `LOW` and stops timing. Returns the length of the pulse in microseconds or gives up and returns 0 if no complete pulse was received within the timeout. +Reads a pulse (either `HIGH` or `LOW`) on a pin. For example, if `value` is `HIGH`, `pulseInLong()` waits for the pin to go from `LOW` to `HIGH`, starts timing, then waits for the pin to go `LOW` and stops timing. Returns the length of the pulse in microseconds or gives up and returns 0 if no complete pulse was received within the timeout. The timing of this function has been determined empirically and will probably show errors in shorter pulses. Works on pulses from 10 microseconds to 3 minutes in length. This routine can be used only if interrupts are activated. Furthermore the highest resolution is obtained with large intervals. [%hardbreaks]