diff --git a/.drone.yml b/.drone.yml index 34276eb08..1dcd73639 100644 --- a/.drone.yml +++ b/.drone.yml @@ -7,4 +7,4 @@ pipeline: - bcmi-labs/reference when: branch: [master] - event: push \ No newline at end of file + event: push diff --git a/AsciiDoc_sample/AsciiDoc_Dictionary/AsciiDoc_Template-Dictionary.adoc b/AsciiDoc_sample/AsciiDoc_Dictionary/AsciiDoc_Template-Dictionary.adoc index d24aa95c7..2b40a4736 100644 --- a/AsciiDoc_sample/AsciiDoc_Dictionary/AsciiDoc_Template-Dictionary.adoc +++ b/AsciiDoc_sample/AsciiDoc_Dictionary/AsciiDoc_Template-Dictionary.adoc @@ -3,7 +3,7 @@ // This is a documentation file for authors and editors of the Arduino Manutius content platform. // Below you can find a list of all the possible page elements with the corresponding -// AsciiDoc syntax +// AsciiDoc syntax // GENERAL GUIDELINES @@ -99,14 +99,14 @@ mailto:webmaster@arduino.cc[This is an e-mail link] This is `code` in a sentence + `This is a whole line of code` + -// HINT: Please note that sometimes when copy-pasting code a few spaces can be added at the beginnng of each line of code. +// HINT: Please note that sometimes when copy-pasting code a few spaces can be added at the beginnng of each line of code. // If that happens, please remove the extra spaces. Thanks! -This can be a lot more code +This can be a lot more code [source,arduino] ---- -for (int 1; i<=99; i++) { - Serial.println('We want more code!'); +for (int i = 0; i <= 99; i++) { + Serial.println('We want more code!'); } ---- [%hardbreaks] @@ -115,7 +115,7 @@ for (int 1; i<=99; i++) { // TABLES |=== -|Name of Column 1 |Name of Column 2 |Name of Column 3 +|Name of Column 1 |Name of Column 2 |Name of Column 3 |Cell in column 1, row 1 |Cell in column 2, row 1 @@ -135,7 +135,7 @@ for (int 1; i<=99; i++) { // IMAGES -// If you need to add an image to the Asciidoc please create a folder called 'attachments' in the same directory as the Asciidoc file, +// If you need to add an image to the Asciidoc please create a folder called 'attachments' in the same directory as the Asciidoc file, // place the image there and reference it as shown below. Images can be in SVG and PNG format, max size 200KB. // To include an image on its own line (i.e., a block image), use the image:: prefix in front of the file name and square brackets after it [] diff --git a/AsciiDoc_sample/Reference_Terms/AsciiDoc_Template-Parent_Of_Entities.adoc b/AsciiDoc_sample/Reference_Terms/AsciiDoc_Template-Parent_Of_Entities.adoc index 86e1fff77..4fdc98960 100644 --- a/AsciiDoc_sample/Reference_Terms/AsciiDoc_Template-Parent_Of_Entities.adoc +++ b/AsciiDoc_sample/Reference_Terms/AsciiDoc_Template-Parent_Of_Entities.adoc @@ -1,6 +1,6 @@ --- title: Parent of Entity Title -categories: [ "Functions" ] +categories: [ "Functions" ] subCategories: [ "Subcategory Name" ] --- // ARDUINO LANGUAGE REFERENCE TAG (above) ►►►►► ALWAYS INCLUDE IN YOUR FILE ◄◄◄◄◄ @@ -78,15 +78,16 @@ http://arduino.cc[serialEvent()] [float] === See also -// Link relevant content by category, such as other Reference terms (please add the tag #LANGUAGE#), +// Link relevant content by category, such as other Reference terms (please add the tag #LANGUAGE#), // definitions (please add the tag #DEFINITION#), and examples of Projects and Tutorials // (please add the tag #EXAMPLE#) ►►►►► THIS SECTION IS MANDATORY ◄◄◄◄◄ [role="language"] // Whenever you want to link to another Reference term, or more in general to a relative link, -// use the syntax shown below. Please note that the file format is subsituted by attribute. +// use the syntax shown below. Please note that the file format is substituted by attribute. // Please note that you always need to replace spaces that you might find in folder/file names with %20 +// The entire link to Reference pages must be lower case, regardless of the case of the folders and files in this repository. * #LANGUAGE# link:../AsciiDoc_Template-Single_Entity[Single Entity] * #LANGUAGE# link:../../AsciiDoc_Dictionary/AsciiDoc_Template-Dictionary[AsciiDoc Template Dictionary] diff --git a/AsciiDoc_sample/Reference_Terms/AsciiDoc_Template-Single_Entity.adoc b/AsciiDoc_sample/Reference_Terms/AsciiDoc_Template-Single_Entity.adoc index f13b90bc6..a9e23d242 100644 --- a/AsciiDoc_sample/Reference_Terms/AsciiDoc_Template-Single_Entity.adoc +++ b/AsciiDoc_sample/Reference_Terms/AsciiDoc_Template-Single_Entity.adoc @@ -12,8 +12,6 @@ subCategories: [ "Subcategory Name" ] - - // PAGE TITLE = title @@ -42,7 +40,8 @@ image::http://arduino.cc/en/uploads/Main/ArduinoUno_R3_Front_450px.jpg[caption=" [float] === Parameters // List all available parameters, please describe them one by one adding the data type (e.g int, boolean, char, String, float, long, double...) ►►►►► THIS SECTION IS MANDATORY FOR FUNCTIONS ◄◄◄◄◄ -`pin`: the number of the pin to write to. Allowed data types: int. + +`pin`: the number of the pin to write to. Allowed data types: int. + `value`: the duty cycle between 0 (always off) and 255 (always on). Allowed data types: int. @@ -56,7 +55,6 @@ Nothing - // HOW TO USE SECTION STARTS [#howtouse] -- @@ -66,7 +64,6 @@ Nothing // Describe what the example code is all about and add relevant code ►►►►► THIS SECTION IS MANDATORY ◄◄◄◄◄ Sets the output to the LED proportional to the value read from the potentiometer. - [source,arduino] // Add relevant code that exemplify the use of the Reference term, // Please note that sometimes when copy-pasting code, a few spaces can be added at the beginnng of each line of code. @@ -76,13 +73,11 @@ int ledPin = 9; // LED connected to digital pin 9 int analogPin = 3; // potentiometer connected to analog pin 3 int val = 0; // variable to store the read value -void setup() -{ +void setup() { pinMode(ledPin, OUTPUT); // sets the pin as output } -void loop() -{ +void loop() { val = analogRead(analogPin); // read the input pin analogWrite(ledPin, val / 4); // analogRead values go from 0 to 1023, analogWrite values from 0 to 255 } @@ -102,22 +97,23 @@ image::http://arduino.cc/en/uploads/Main/ArduinoUno_R3_Front_450px.jpg[caption=" // HOW TO USE SECTION ENDS + // SEE ALSO SECTION [#see_also] -- [float] === See also -// Link relevant content by category, such as other Reference terms (please add the tag #LANGUAGE#), +// Link relevant content by category, such as other Reference terms (please add the tag #LANGUAGE#), // definitions: (please add the tag #DEFINITION#), and examples of Projects and Tutorials // examples: (please add the tag #EXAMPLE#) - [role="language"] // Whenever you want to link to another Reference term, or more in general to a relative link, -// use the syntax shown below. Please note that the file format is subsituted by attribute. +// use the syntax shown below. Please note that the file format is substituted by attribute. // Please note that you always need to replace spaces that you might find in folder/file names with %20 -// for language tag, items will be automatically generated for any other item of the same subcategory, +// The entire link to Reference pages must be lower case, regardless of the case of the folders and files in this repository. +// For language tag, items will be automatically generated for any other item of the same subcategory, // no need to add links to other pages of the same subcategory // if you don't include this section, a minimal version with only the other pages of the same subcategory will be generated. * #LANGUAGE# link:../AsciiDoc_Template-Parent_Of_Entities[Parent Of Entities] @@ -133,4 +129,3 @@ image::http://arduino.cc/en/uploads/Main/ArduinoUno_R3_Front_450px.jpg[caption=" -- // SEE ALSO SECTION ENDS - diff --git a/LICENSE.md b/LICENSE.md index c90487cb0..53764dac4 100644 --- a/LICENSE.md +++ b/LICENSE.md @@ -264,7 +264,7 @@ subject to and limited by the following restrictions: UNLESS OTHERWISE MUTUALLY AGREED TO BY THE PARTIES IN WRITING, LICENSOR OFFERS THE WORK AS-IS AND MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND CONCERNING THE WORK, EXPRESS, IMPLIED, STATUTORY OR OTHERWISE, -INCLUDING, WITHOUT LIMITATION, WARRANTIES OF TITLE, MERCHANTIBILITY, +INCLUDING, WITHOUT LIMITATION, WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NONINFRINGEMENT, OR THE ABSENCE OF LATENT OR OTHER DEFECTS, ACCURACY, OR THE PRESENCE OF ABSENCE OF ERRORS, WHETHER OR NOT DISCOVERABLE. SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION diff --git a/Language/Functions/Advanced IO/noTone.adoc b/Language/Functions/Advanced IO/noTone.adoc index 54e748666..14e3663d0 100644 --- a/Language/Functions/Advanced IO/noTone.adoc +++ b/Language/Functions/Advanced IO/noTone.adoc @@ -27,7 +27,7 @@ Stops the generation of a square wave triggered by `tone()`. Has no effect if no [float] === Parameters -`pin`: the pin on which to stop generating the tone +`pin`: the Arduino pin on which to stop generating the tone [float] === Returns @@ -45,8 +45,19 @@ Nothing [float] === Notes and Warnings -If you want to play different pitches on multiple pins, you need to call noTone() on one pin before calling `tone()` on the next pin. +If you want to play different pitches on multiple pins, you need to call `noTone()` on one pin before calling `tone()` on the next pin. [%hardbreaks] -- // HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Functions/Advanced IO/pulseIn.adoc b/Language/Functions/Advanced IO/pulseIn.adoc index d1df8544f..5252f6814 100644 --- a/Language/Functions/Advanced IO/pulseIn.adoc +++ b/Language/Functions/Advanced IO/pulseIn.adoc @@ -20,25 +20,27 @@ subCategories: [ "Advanced I/O" ] Reads a pulse (either `HIGH` or `LOW`) on a pin. For example, if `value` is `HIGH`, `pulseIn()` 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 longer pulses. Works on pulses from 10 microseconds to 3 minutes in length. + +NOTE: if the optional timeout is used code will execute faster. [%hardbreaks] [float] === Syntax -`pulseIn(pin, value)` - +`pulseIn(pin, value)` + `pulseIn(pin, value, timeout)` + [float] === Parameters -`pin`: the number of the pin on which you want to read the pulse. (int) +`pin`: the number of the Arduino pin on which you want to read the pulse. Allowed data types: `int`. + +`value`: type of pulse to read: either link:../../../variables/constants/highlow/[HIGH] or link:../../../variables/constants/highlow/[LOW]. Allowed data types: `int`. + +`timeout` (optional): the number of microseconds to wait for the pulse to start; default is one second. Allowed data types: `unsigned long`. -`value`: type of pulse to read: either link:../../../variables/constants/constants/[HIGH] or link:../../../variables/constants/constants/[LOW]. (int) -`timeout` (optional): the number of microseconds to wait for the pulse to start; default is one second (unsigned long) [float] === Returns -the length of the pulse (in microseconds) or 0 if no pulse started before the timeout (unsigned long) +The length of the pulse (in microseconds) or 0 if no pulse started before the timeout. Data type: `unsigned long`. -- // OVERVIEW SECTION ENDS @@ -53,24 +55,35 @@ the length of the pulse (in microseconds) or 0 if no pulse started before the ti [float] === Example Code // Describe what the example code is all about and add relevant code ►►►►► THIS SECTION IS MANDATORY ◄◄◄◄◄ -The example calculated the time duration of a pulse on pin 7. +The example prints the time duration of a pulse on pin 7. [source,arduino] ---- int pin = 7; unsigned long duration; -void setup() -{ +void setup() { + Serial.begin(9600); pinMode(pin, INPUT); } -void loop() -{ +void loop() { duration = pulseIn(pin, HIGH); + Serial.println(duration); } ---- [%hardbreaks] -- // HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Functions/Advanced IO/pulseInLong.adoc b/Language/Functions/Advanced IO/pulseInLong.adoc index 22940fd55..1fdc88a1c 100644 --- a/Language/Functions/Advanced IO/pulseInLong.adoc +++ b/Language/Functions/Advanced IO/pulseInLong.adoc @@ -27,20 +27,20 @@ The timing of this function has been determined empirically and will probably sh [float] === Syntax -`pulseInLong(pin, value)` - +`pulseInLong(pin, value)` + `pulseInLong(pin, value, timeout)` + [float] === Parameters -`pin`: the number of the pin on which you want to read the pulse. (int) +`pin`: the number of the Arduino pin on which you want to read the pulse. Allowed data types: `int`. + +`value`: type of pulse to read: either link:../../../variables/constants/highlow/[HIGH] or link:../../../variables/constants/highlow/[LOW]. Allowed data types: `int`. + +`timeout` (optional): the number of microseconds to wait for the pulse to start; default is one second. Allowed data types: `unsigned long`. -`value`: type of pulse to read: either link:../../../variables/constants/constants/[HIGH] or link:../../../variables/constants/constants/[LOW]. (int) -`timeout` (optional): the number of microseconds to wait for the pulse to start; default is one second (unsigned long) [float] === Returns -the length of the pulse (in microseconds) or 0 if no pulse started before the timeout (unsigned long) +The length of the pulse (in microseconds) or 0 if no pulse started before the timeout. Data type: `unsigned long`. -- // OVERVIEW SECTION ENDS @@ -55,7 +55,7 @@ the length of the pulse (in microseconds) or 0 if no pulse started before the ti [float] === Example Code // Describe what the example code is all about and add relevant code ►►►►► THIS SECTION IS MANDATORY ◄◄◄◄◄ -The example calculated the time duration of a pulse on pin 7. +The example prints the time duration of a pulse on pin 7. [source,arduino] ---- @@ -63,18 +63,31 @@ int pin = 7; unsigned long duration; void setup() { + Serial.begin(9600); pinMode(pin, INPUT); } void loop() { duration = pulseInLong(pin, HIGH); + Serial.println(duration); } ---- [%hardbreaks] [float] === Notes and Warnings -This function relies on micros() so cannot be used in link:../../interrupts/nointerrupts[noInterrupts()] context. +This function relies on `micros()` so cannot be used in link:../../interrupts/nointerrupts[noInterrupts()] context. -- // HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Functions/Advanced IO/shiftIn.adoc b/Language/Functions/Advanced IO/shiftIn.adoc index 45f9d85e7..83929a746 100644 --- a/Language/Functions/Advanced IO/shiftIn.adoc +++ b/Language/Functions/Advanced IO/shiftIn.adoc @@ -32,16 +32,25 @@ Note: this is a software implementation; Arduino also provides an link:https://w [float] === Parameters -`dataPin`: the pin on which to input each bit (int) +`dataPin`: the pin on which to input each bit. Allowed data types: `int`. + +`clockPin`: the pin to toggle to signal a read from *dataPin*. + +`bitOrder`: which order to shift in the bits; either *MSBFIRST* or *LSBFIRST*. (Most Significant Bit First, or, Least Significant Bit First). -`clockPin`: the pin to toggle to signal a read from *dataPin* - -`bitOrder`: which order to shift in the bits; either *MSBFIRST* or *LSBFIRST*. -(Most Significant Bit First, or, Least Significant Bit First) [float] === Returns -the value read (byte) +The value read. Data type: `byte`. + +-- +// OVERVIEW SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also -- -// OVERVIEW SECTION ENDS \ No newline at end of file +// SEE ALSO SECTION ENDS diff --git a/Language/Functions/Advanced IO/shiftOut.adoc b/Language/Functions/Advanced IO/shiftOut.adoc index b7793fe51..57d9fec25 100644 --- a/Language/Functions/Advanced IO/shiftOut.adoc +++ b/Language/Functions/Advanced IO/shiftOut.adoc @@ -28,14 +28,11 @@ This is a software implementation; see also the https://www.arduino.cc/en/Refere [float] === Parameters -`dataPin`: the pin on which to output each bit (int) +`dataPin`: the pin on which to output each bit. Allowed data types: `int`. + +`clockPin`: the pin to toggle once the dataPin has been set to the correct value. Allowed data types: `int`. + +`bitOrder`: which order to shift out the bits; either MSBFIRST or LSBFIRST. (Most Significant Bit First, or, Least Significant Bit First). + +`value`: the data to shift out. Allowed data types: `byte`. -`clockPin`: the pin to toggle once the dataPin has been set to the correct value (int) - -`bitOrder`: which order to shift out the bits; either MSBFIRST or LSBFIRST. -(Most Significant Bit First, or, Least Significant Bit First) - -`value`: the data to shift out. (byte) [float] === Returns @@ -121,3 +118,14 @@ shiftOut(dataPin, clock, LSBFIRST, (data >> 8)); -- // HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Functions/Advanced IO/tone.adoc b/Language/Functions/Advanced IO/tone.adoc index 562f8988c..3468cd109 100644 --- a/Language/Functions/Advanced IO/tone.adoc +++ b/Language/Functions/Advanced IO/tone.adoc @@ -17,9 +17,9 @@ subCategories: [ "Advanced I/O" ] [float] === Description -Generates a square wave of the specified frequency (and 50% duty cycle) on a pin. A duration can be specified, otherwise the wave continues until a call to link:../noTone[noTone()]. The pin can be connected to a piezo buzzer or other speaker to play tones. +Generates a square wave of the specified frequency (and 50% duty cycle) on a pin. A duration can be specified, otherwise the wave continues until a call to link:../notone[noTone()]. The pin can be connected to a piezo buzzer or other speaker to play tones. -Only one tone can be generated at a time. If a tone is already playing on a different pin, the call to tone() will have no effect. If the tone is playing on the same pin, the call will set its frequency. +Only one tone can be generated at a time. If a tone is already playing on a different pin, the call to `tone()` will have no effect. If the tone is playing on the same pin, the call will set its frequency. Use of the `tone()` function will interfere with PWM output on pins 3 and 11 (on boards other than the Mega). @@ -29,19 +29,16 @@ It is not possible to generate tones lower than 31Hz. For technical details, see [float] === Syntax -`tone(pin, frequency)` - +`tone(pin, frequency)` + `tone(pin, frequency, duration)` -[%hardbreaks] + [float] === Parameters -`pin`: the pin on which to generate the tone - -`frequency`: the frequency of the tone in hertz - `unsigned int` +`pin`: the Arduino pin on which to generate the tone. + +`frequency`: the frequency of the tone in hertz. Allowed data types: `unsigned int`. + +`duration`: the duration of the tone in milliseconds (optional). Allowed data types: `unsigned long`. -`duration`: the duration of the tone in milliseconds (optional) - `unsigned long` -[%hardbreaks] [float] === Returns @@ -59,7 +56,10 @@ Nothing [float] === Notes and Warnings -If you want to play different pitches on multiple pins, you need to call `noTone()` on one pin before calling `tone()` on the next pin. + +* If you want to play different pitches on multiple pins, you need to call `noTone()` on one pin before calling `tone()` on the next pin. +* This function is non-blocking, which means that even if you provide the `duration` parameter the sketch execution will continue immediately even if the tone hasn't finished playing. + [%hardbreaks] -- @@ -77,11 +77,12 @@ If you want to play different pitches on multiple pins, you need to call `noTone * #LANGUAGE# link:../../analog-io/analogwrite[analogWrite()] [role="example"] -* #EXAMPLE# http://arduino.cc/en/Tutorial/Tone[Tone^] -* #EXAMPLE# http://arduino.cc/en/Tutorial/Tone[Pitch follower^] -* #EXAMPLE# http://arduino.cc/en/Tutorial/Tone3[Simple Keyboard^] -* #EXAMPLE# http://arduino.cc/en/Tutorial/Tone4[multiple tones^] -* #EXAMPLE# http://arduino.cc/en/Tutorial/PWM[PWM^] + +* #EXAMPLE# https://www.arduino.cc/en/Tutorial/BuiltInExamples/toneMelody[Tone Melody^] +* #EXAMPLE# https://www.arduino.cc/en/Tutorial/tonePitchFollower[Pitch Follower^] +* #EXAMPLE# https://www.arduino.cc/en/Tutorial/BuiltInExamples/toneKeyboard[Tone Keyboard^] +* #EXAMPLE# https://www.arduino.cc/en/Tutorial/BuiltInExamples/toneMultiple[Tone Multiple^] +* #EXAMPLE# https://www.arduino.cc/en/Tutorial/PWM[PWM^] -- -// SEE ALSO SECTION ENDS \ No newline at end of file +// SEE ALSO SECTION ENDS diff --git a/Language/Functions/Analog IO/analogRead.adoc b/Language/Functions/Analog IO/analogRead.adoc index c175b384e..8eac217a5 100644 --- a/Language/Functions/Analog IO/analogRead.adoc +++ b/Language/Functions/Analog IO/analogRead.adoc @@ -4,43 +4,60 @@ categories: [ "Functions" ] subCategories: [ "Analog I/O" ] --- - - - = analogRead() - // OVERVIEW SECTION STARTS [#overview] -- [float] === Description -Reads the value from the specified analog pin. The Arduino board contains a 6 channel (8 channels on the Mini and Nano, 16 on the Mega), 10-bit analog to digital converter. This means that it will map input voltages between 0 and 5 volts into integer values between 0 and 1023. This yields a resolution between readings of: 5 volts / 1024 units or, .0049 volts (4.9 mV) per unit. The input range and resolution can be changed using link:../analogreference[analogReference()]. +Reads the value from the specified analog pin. Arduino boards contain a multichannel, 10-bit analog to digital converter. This means that it will map input voltages between 0 and the operating voltage(5V or 3.3V) into integer values between 0 and 1023. On an Arduino UNO, for example, this yields a resolution between readings of: 5 volts / 1024 units or, 0.0049 volts (4.9 mV) per unit. See the table below for the usable pins, operating voltage and maximum resolution for some Arduino boards. + +The input range can be changed using link:../analogreference[analogReference()], while the resolution can be changed (only for Zero, Due and MKR boards) using link:../../zero-due-mkr-family/analogreadresolution[analogReadResolution()]. + +On ATmega based boards (UNO, Nano, Mini, Mega), it takes about 100 microseconds (0.0001 s) to read an analog input, so the maximum reading rate is about 10,000 times a second. + +[options="header"] +|=================================================== +|Board |Operating voltage |Usable pins |Max resolution +|UNO R3 |5 Volts |A0 to A5 |10 bits +|UNO R4 (Minima, WiFi) |5 Volts |A0 to A5 |14 bits** +|Mini |5 Volts |A0 to A7 |10 bits +|Nano, Nano Every |5 Volts |A0 to A7 |10 bits +|Nano 33 (IoT, BLE, RP2040, ESP32)|3.3 Volts |A0 to A7 |12 bits** +|Mega, Mega2560, MegaADK |5 Volts |A0 to A14 |10 bits +|Micro |5 Volts |A0 to A11* |10 bits +|Leonardo |5 Volts |A0 to A11* |10 bits +|Zero |3.3 Volts |A0 to A5 |12 bits** +|Due |3.3 Volts |A0 to A11 |12 bits** +|GIGA R1 |3.3 Volts |A0 to A11 |16 bits** +|MKR Family boards |3.3 Volts |A0 to A6 |12 bits** +|=================================================== + +*A0 through A5 are labelled on the board, A6 through A11 are respectively available on pins 4, 6, 8, 9, 10, and 12 + +**The default `analogRead()` resolution for these boards is 10 bits, for compatibility. You need to use link:../../zero-due-mkr-family/analogreadresolution[analogReadResolution()] to change it to a higher resolution. -It takes about 100 microseconds (0.0001 s) to read an analog input, so the maximum reading rate is about 10,000 times a second. [%hardbreaks] - [float] === Syntax - `analogRead(pin)` + [float] === Parameters -`pin`: the number of the analog input pin to read from (0 to 5 on most boards, 0 to 7 on the Mini and Nano, 0 to 15 on the Mega) +`pin`: the name of the analog input pin to read from. + [float] === Returns -int(0 to 1023) +The analog reading on the pin. Although it is limited to the resolution of the analog to digital converter (0-1023 for 10 bits or 0-4095 for 12 bits). Data type: `int`. -- // OVERVIEW SECTION ENDS - - // HOW TO USE SECTION STARTS [#howtouse] -- @@ -52,26 +69,24 @@ The code reads the voltage on analogPin and displays it. [source,arduino] ---- -int analogPin = 3; // potentiometer wiper (middle terminal) connected to analog pin 3 - // outside leads to ground and +5V -int val = 0; // variable to store the value read +int analogPin = A3; // potentiometer wiper (middle terminal) connected to analog pin 3 + // outside leads to ground and +5V +int val = 0; // variable to store the value read -void setup() -{ - Serial.begin(9600); // setup serial +void setup() { + Serial.begin(9600); // setup serial } -void loop() -{ - val = analogRead(analogPin); // read the input pin - Serial.println(val); // debug value +void loop() { + val = analogRead(analogPin); // read the input pin + Serial.println(val); // debug value } ---- [%hardbreaks] [float] === Notes and Warnings -If the analog input pin is not connected to anything, the value returned by analogRead() will fluctuate based on a number of factors (e.g. the values of the other analog inputs, how close your hand is to the board, etc.). +If the analog input pin is not connected to anything, the value returned by `analogRead()` will fluctuate based on a number of factors (e.g. the values of the other analog inputs, how close your hand is to the board, etc.). -- // HOW TO USE SECTION ENDS @@ -86,6 +101,6 @@ If the analog input pin is not connected to anything, the value returned by anal [role="language"] * #LANGUAGE# link:../../zero-due-mkr-family/analogreadresolution[analogReadResolution()] -* #LANGUAGE# https://www.arduino.cc/en/Tutorial/AnalogInputPins[Tutorial: Analog Input Pins] +* #EXAMPLE# http://arduino.cc/en/Tutorial/AnalogInputPins[Description of the analog input pins^] -- // SEE ALSO SECTION ENDS diff --git a/Language/Functions/Zero, Due, MKR Family/analogReadResolution.adoc b/Language/Functions/Analog IO/analogReadResolution.adoc similarity index 83% rename from Language/Functions/Zero, Due, MKR Family/analogReadResolution.adoc rename to Language/Functions/Analog IO/analogReadResolution.adoc index fbf41dbf1..8a935374e 100644 --- a/Language/Functions/Zero, Due, MKR Family/analogReadResolution.adoc +++ b/Language/Functions/Analog IO/analogReadResolution.adoc @@ -1,7 +1,7 @@ --- title: analogReadResolution() categories: [ "Functions" ] -subCategories: [ "Zero, Due & MKR Family" ] +subCategories: [ "Analog I/O" ] --- @@ -16,11 +16,12 @@ subCategories: [ "Zero, Due & MKR Family" ] [float] === Description -analogReadResolution() is an extension of the Analog API for the Arduino Due, Zero and MKR Family. +analogReadResolution() is an extension of the Analog API for the Zero, Due, MKR family, Nano 33 (BLE and IoT) and Portenta. Sets the size (in bits) of the value returned by `analogRead()`. It defaults to 10 bits (returns values between 0-1023) for backward compatibility with AVR based boards. -The *Due, Zero and MKR Family* boards have 12-bit ADC capabilities that can be accessed by changing the resolution to 12. This will return values from `analogRead()` between 0 and 4095. +The *Zero, Due, MKR family and Nano 33 (BLE and IoT)* boards have 12-bit ADC capabilities that can be accessed by changing the resolution to 12. This will return values from `analogRead()` between 0 and 4095. + +The *Portenta H7* has a 16 bit ADC, which will allow values between 0 and 65535. [%hardbreaks] @@ -31,7 +32,8 @@ The *Due, Zero and MKR Family* boards have 12-bit ADC capabilities that can be a [float] === Parameters -`bits`: determines the resolution (in bits) of the value returned by the `analogRead()` function. You can set this between 1 and 32. You can set resolutions higher than 12 but values returned by `analogRead()` will suffer approximation. See the note below for details. +`bits`: determines the resolution (in bits) of the value returned by the `analogRead()` function. You can set this between 1 and 32. You can set resolutions higher than the supported 12 or 16 bits, but values returned by `analogRead()` will suffer approximation. See the note below for details. + [float] === Returns @@ -109,7 +111,7 @@ Using a 16 bit resolution (or any resolution *higher* than actual hardware capab === See also [role="example"] -* #EXAMPLE# http://arduino.cc/en/Tutorial/AnalogInputPins[Description of the analog input pins] +* #EXAMPLE# http://arduino.cc/en/Tutorial/AnalogInputPins[Description of the analog input pins^] [role="language"] * #LANGUAGE# link:../../analog-io/analogread[analogRead()] diff --git a/Language/Functions/Analog IO/analogReference.adoc b/Language/Functions/Analog IO/analogReference.adoc index 2db71ee8e..0e44b5881 100644 --- a/Language/Functions/Analog IO/analogReference.adoc +++ b/Language/Functions/Analog IO/analogReference.adoc @@ -19,14 +19,23 @@ subCategories: [ "Analog I/O" ] === Description Configures the reference voltage used for analog input (i.e. the value used as the top of the input range). The options are: -Arduino AVR Boards (Uno, Mega, etc.) +Arduino AVR Boards (Uno, Mega, Leonardo, etc.) * DEFAULT: the default analog reference of 5 volts (on 5V Arduino boards) or 3.3 volts (on 3.3V Arduino boards) -* INTERNAL: an built-in reference, equal to 1.1 volts on the ATmega168 or ATmega328P and 2.56 volts on the ATmega8 (not available on the Arduino Mega) +* INTERNAL: a built-in reference, equal to 1.1 volts on the ATmega168 or ATmega328P and 2.56 volts on the ATmega32U4 and ATmega8 (not available on the Arduino Mega) * INTERNAL1V1: a built-in 1.1V reference (Arduino Mega only) * INTERNAL2V56: a built-in 2.56V reference (Arduino Mega only) * EXTERNAL: the voltage applied to the AREF pin (0 to 5V only) is used as the reference. +Arduino Renesas Boards (UNO R4, Portenta C33) + +* AR_DEFAULT: the default analog reference of 5 volts. +* AR_INTERNAL: A built-in reference, equal to 1.5 Volts on the RA4M1 of the UNO R4 +* AR_INTERNAL_1_5V: A built-in reference, equal to 1.5 V on the R7FA6M5 of the Portenta C33 +* AR_INTERNAL_2_0V: A built-in reference, equal to 2.0 V on the R7FA6M5 of the Portenta C33 +* AR_INTERNAL_2_5V: A built-in reference, equal to 2.5 V on the R7FA6M5 of the Portenta C33 +* AR_EXTERNAL: the voltage applied to the AREF pin (0 to 5V only) is used as the reference. + Arduino SAMD Boards (Zero, etc.) * AR_DEFAULT: the default analog reference of 3.3V @@ -36,10 +45,29 @@ Arduino SAMD Boards (Zero, etc.) * AR_INTERNAL2V23: a built-in 2.23V reference * AR_EXTERNAL: the voltage applied to the AREF pin is used as the reference +Arduino megaAVR Boards (Uno WiFi Rev2) + +* DEFAULT: a built-in 0.55V reference +* INTERNAL: a built-in 0.55V reference +* VDD: Vdd of the ATmega4809. 5V on the Uno WiFi Rev2 +* INTERNAL0V55: a built-in 0.55V reference +* INTERNAL1V1: a built-in 1.1V reference +* INTERNAL1V5: a built-in 1.5V reference +* INTERNAL2V5: a built-in 2.5V reference +* INTERNAL4V3: a built-in 4.3V reference +* EXTERNAL: the voltage applied to the AREF pin (0 to 5V only) is used as the reference + Arduino SAM Boards (Due) * AR_DEFAULT: the default analog reference of 3.3V. This is the only supported option for the Due. +Arduino Mbed OS Nano Boards (Nano 33 BLE), Arduino Mbed OS Edge Boards (Edge Control) + +* AR_VDD: the default 3.3 V reference +* AR_INTERNAL: built-in 0.6 V reference +* AR_INTERNAL1V2: 1.2 V reference (internal 0.6 V reference with 2x gain) +* AR_INTERNAL2V4: 2.4 V reference (internal 0.6 V reference with 4x gain) + [%hardbreaks] @@ -52,6 +80,7 @@ Arduino SAM Boards (Due) === Parameters `type`: which type of reference to use (see list of options in the description). + [float] === Returns Nothing @@ -87,7 +116,7 @@ Alternatively, you can connect the external reference voltage to the AREF pin th === See also [role="example"] -* #EXAMPLE# http://arduino.cc/en/Tutorial/AnalogInputPins[Description of analog input pins] +* #EXAMPLE# http://arduino.cc/en/Tutorial/AnalogInputPins[Description of the analog input pins^] -- // SEE ALSO SECTION ENDS diff --git a/Language/Functions/Analog IO/analogWrite.adoc b/Language/Functions/Analog IO/analogWrite.adoc index 5d9d2749b..36894922e 100644 --- a/Language/Functions/Analog IO/analogWrite.adoc +++ b/Language/Functions/Analog IO/analogWrite.adoc @@ -17,10 +17,34 @@ subCategories: [ "Analog I/O" ] [float] === Description -Writes an analog value (http://arduino.cc/en/Tutorial/PWM[PWM wave]) to a pin. Can be used to light a LED at varying brightnesses or drive a motor at various speeds. After a call to `analogWrite()`, the pin will generate a steady square wave of the specified duty cycle until the next call to `analogWrite()` (or a call to `digitalRead()` or `digitalWrite()`) on the same pin. The frequency of the PWM signal on most pins is approximately 490 Hz. On the Uno and similar boards, pins 5 and 6 have a frequency of approximately 980 Hz. +Writes an analog value (http://arduino.cc/en/Tutorial/PWM[PWM wave]) to a pin. Can be used to light a LED at varying brightnesses or drive a motor at various speeds. After a call to `analogWrite()`, the pin will generate a steady rectangular wave of the specified duty cycle until the next call to `analogWrite()` (or a call to `digitalRead()` or `digitalWrite()`) on the same pin. + +[options="header"] + +|========================================================================================================================= +| Board | PWM Pins +*+ | PWM Frequency +| UNO (R3 and earlier), Nano, Mini | 3, 5, 6, 9, 10, 11 | 490 Hz (pins 5 and 6: 980 Hz) +| UNO R4 (Minima, WiFi) +*+ | 3, 5, 6, 9, 10, 11 | 490 Hz +| Mega | 2 - 13, 44 - 46 | 490 Hz (pins 4 and 13: 980 Hz) +| GIGA R1 +**+ | 2 - 13 | 500 Hz +| Leonardo, Micro, Yún | 3, 5, 6, 9, 10, 11, 13 | 490 Hz (pins 3 and 11: 980 Hz) +| UNO WiFi Rev2, Nano Every | 3, 5, 6, 9, 10 | 976 Hz +| MKR boards +*+ | 0 - 8, 10, A3, A4 | 732 Hz +| MKR1000 WiFi +**+ | 0 - 8, 10, 11, A3, A4 | 732 Hz +| Zero +**+ | 3 - 13, A0, A1 | 732 Hz +| Nano 33 IoT +**+ | 2, 3, 5, 6, 9 - 12, A2, A3, A5 | 732 Hz +| Nano 33 BLE/BLE Sense +****+ | 1 - 13, A0 - A7 | 500 Hz +| Due +***+ | 2-13 | 1000 Hz +| 101 | 3, 5, 6, 9 | pins 3 and 9: 490 Hz, pins 5 and 6: 980 Hz +|========================================================================================================================= + ++*+ These pins are officially supported PWM pins. While some boards have additional pins capable of PWM, using them is recommended only for advanced users that can account for timer availability and potential conflicts with other uses of those pins. + ++**+ In addition to PWM capabilities on the pins noted above, the MKR, Nano 33 IoT, Zero and UNO R4 boards have true analog output when using `analogWrite()` on the `DAC0` (`A0`) pin. + ++***+ In addition to PWM capabilities on the pins noted above, the Due and GIGA R1 boards have true analog output when using `analogWrite()` on pins `DAC0` and `DAC1`. + ++****+ Only 4 different pins can be used at the same time. Enabling PWM on more than 4 pins will abort the running sketch and require resetting the board to upload a new sketch again. + + [%hardbreaks] -On most Arduino boards (those with the ATmega168 or ATmega328P), this function works on pins 3, 5, 6, 9, 10, and 11. On the Arduino Mega, it works on pins 2 - 13 and 44 - 46. Older Arduino boards with an ATmega8 only support `analogWrite()` on pins 9, 10, and 11. -The Arduino DUE supports `analogWrite()` on pins 2 through 13, plus pins DAC0 and DAC1. Unlike the PWM pins, DAC0 and DAC1 are Digital to Analog converters, and act as true analog outputs. + You do not need to call `pinMode()` to set the pin as an output before calling `analogWrite()`. The `analogWrite` function has nothing to do with the analog pins or the `analogRead` function. [%hardbreaks] @@ -33,8 +57,8 @@ The `analogWrite` function has nothing to do with the analog pins or the `analog [float] === Parameters -`pin`: the pin to write to. Allowed data types: int. + -`value`: the duty cycle: between 0 (always off) and 255 (always on). Allowed data types: int +`pin`: the Arduino pin to write to. Allowed data types: `int`. + +`value`: the duty cycle: between 0 (always off) and 255 (always on). Allowed data types: `int`. [float] @@ -62,15 +86,13 @@ int ledPin = 9; // LED connected to digital pin 9 int analogPin = 3; // potentiometer connected to analog pin 3 int val = 0; // variable to store the read value -void setup() -{ - pinMode(ledPin, OUTPUT); // sets the pin as output +void setup() { + pinMode(ledPin, OUTPUT); // sets the pin as output } -void loop() -{ - val = analogRead(analogPin); // read the input pin - analogWrite(ledPin, val / 4); // analogRead values go from 0 to 1023, analogWrite values from 0 to 255 +void loop() { + val = analogRead(analogPin); // read the input pin + analogWrite(ledPin, val / 4); // analogRead values go from 0 to 1023, analogWrite values from 0 to 255 } ---- [%hardbreaks] diff --git a/Language/Functions/Zero, Due, MKR Family/analogWriteResolution.adoc b/Language/Functions/Analog IO/analogWriteResolution.adoc similarity index 95% rename from Language/Functions/Zero, Due, MKR Family/analogWriteResolution.adoc rename to Language/Functions/Analog IO/analogWriteResolution.adoc index 7c6b3e5bb..649eb171c 100644 --- a/Language/Functions/Zero, Due, MKR Family/analogWriteResolution.adoc +++ b/Language/Functions/Analog IO/analogWriteResolution.adoc @@ -1,7 +1,7 @@ --- title: analogWriteResolution() categories: [ "Functions" ] -subCategories: [ "Zero, Due & MKR Family" ] +subCategories: [ "Analog I/O" ] --- @@ -54,6 +54,7 @@ By setting the write resolution to 12 bits, you can use `analogWrite()` with val === Parameters `bits`: determines the resolution (in bits) of the values used in the `analogWrite()` function. The value can range from 1 to 32. If you choose a resolution higher or lower than your board's hardware capabilities, the value used in `analogWrite()` will be either truncated if it's too high or padded with zeros if it's too low. See the note below for details. + [float] === Returns Nothing @@ -75,7 +76,7 @@ Explain Code [source,arduino] ---- -void setup(){ +void setup() { // open a serial connection Serial.begin(9600); // make our digital pin an output @@ -84,7 +85,7 @@ void setup(){ pinMode(13, OUTPUT); } -void loop(){ +void loop() { // read the input on A0 and map it to a PWM pin // with an attached LED int sensorVal = analogRead(A0); @@ -93,9 +94,9 @@ void loop(){ // the default PWM resolution analogWriteResolution(8); - analogWrite(11, map(sensorVal, 0, 1023, 0 ,255)); + analogWrite(11, map(sensorVal, 0, 1023, 0, 255)); Serial.print(" , 8-bit PWM value : "); - Serial.print(map(sensorVal, 0, 1023, 0 ,255)); + Serial.print(map(sensorVal, 0, 1023, 0, 255)); // change the PWM resolution to 12 bits // the full 12 bit resolution is only supported @@ -139,7 +140,7 @@ If you set the `analogWriteResolution()` value to a value lower than your board' * #LANGUAGE# link:../../math/map[map()] [role="example"] -* #EXAMPLE# http://arduino.cc/en/Tutorial/AnalogInputPins[Description of the analog input pins] +* #EXAMPLE# http://arduino.cc/en/Tutorial/AnalogInputPins[Description of the analog input pins^] -- // SEE ALSO SECTION ENDS diff --git a/Language/Functions/Bits and Bytes/bit.adoc b/Language/Functions/Bits and Bytes/bit.adoc index 53a3e4d6c..3aaeda82b 100644 --- a/Language/Functions/Bits and Bytes/bit.adoc +++ b/Language/Functions/Bits and Bytes/bit.adoc @@ -28,11 +28,23 @@ Computes the value of the specified bit (bit 0 is 1, bit 1 is 2, bit 2 is 4, etc [float] === Parameters -`n`: the bit whose value to compute +`n`: the bit whose value to compute. Note that `n` needs to be between 0-31 (32 bit). + [float] === Returns The value of the bit. -- -// OVERVIEW SECTION ENDS \ No newline at end of file +// OVERVIEW SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Functions/Bits and Bytes/bitClear.adoc b/Language/Functions/Bits and Bytes/bitClear.adoc index 33500225e..7c8594c8f 100644 --- a/Language/Functions/Bits and Bytes/bitClear.adoc +++ b/Language/Functions/Bits and Bytes/bitClear.adoc @@ -28,13 +28,57 @@ Clears (writes a 0 to) a bit of a numeric variable. [float] === Parameters -`x`: the numeric variable whose bit to clear +`x`: the numeric variable whose bit to clear. + +`n`: which bit to clear, starting at 0 for the least-significant (rightmost) bit. -`n`: which bit to clear, starting at 0 for the least-significant (rightmost) bit [float] === Returns -Nothing +`x`: the value of the numeric variable after the bit at position `n` is cleared. -- -// OVERVIEW SECTION ENDS \ No newline at end of file +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code +// Describe what the example code is all about and add relevant code +Prints the output of `bitClear(x,n)` on two given integers. The binary representation of 6 is 0110, so when `n=1`, the second bit from the right is set to 0. After this we are left with 0100 in binary, so 4 is returned. + +[source,arduino] +---- +void setup() { + Serial.begin(9600); + while (!Serial) { + ; // wait for serial port to connect. Needed for native USB port only + } + + int x = 6; + int n = 1; + Serial.print(bitClear(x, n)); // print the output of bitClear(x,n) +} + +void loop() { +} +---- +[%hardbreaks] + +-- +// HOW TO USE SECTION ENDS + + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Functions/Bits and Bytes/bitRead.adoc b/Language/Functions/Bits and Bytes/bitRead.adoc index 231efe1f4..53c190c6a 100644 --- a/Language/Functions/Bits and Bytes/bitRead.adoc +++ b/Language/Functions/Bits and Bytes/bitRead.adoc @@ -17,7 +17,7 @@ subCategories: [ "Bits and Bytes" ] [float] === Description -Reads a bit of a number. +Reads a bit of a variable, e.g. `bool`, `int`. Note that `float` & `double` are not supported. You can read the bit of variables up to an `unsigned long long` (64 bits / 8 bytes). [%hardbreaks] @@ -28,14 +28,73 @@ Reads a bit of a number. [float] === Parameters -`x`: the number from which to read - -`n`: which bit to read, starting at 0 for the least-significant (rightmost) bit +`x`: the number from which to read. + +`n`: which bit to read, starting at 0 for the least-significant (rightmost) bit. [float] === Returns -the value of the bit (0 or 1). +The value of the bit (0 or 1). + +[float] +=== Example Code + +This example code demonstrates how to read two variables, one increasing counter, one decreasing counter, and print out both the binary and decimal values of the variables. + +The `readBit()` function loops through each bit of the variable (starting from the rightmost bit), and prints it out. + +[source,arduino] +---- +long negative_var = -0; // +unsigned long long positive_var = 0; + +//predefined sizes when looping through bits +//e.g. long_size is 32 bit (which is 0-31). Therefore, we subtract "1". +const int bool_size = (1 - 1); +const int int_size = (8 - 1); +const int long_size = (32 - 1); + +void setup() { + Serial.begin(9600); +} + +void loop() { + //run readBit function, passing the pos/neg variables + readBit("Positive ", positive_var); + readBit("Negative ", negative_var); + Serial.println(); + + //increase and decrease the variables + negative_var--; + positive_var++; + + delay(1000); +} + +/*this function takes a variable, prints it out bit by bit (starting from the right) +then prints the decimal number for comparison.*/ +void readBit(String direction, long counter) { + Serial.print(direction + "Binary Number: "); + //loop through each bit + for (int b = long_size; b >= 0; b--) { + byte bit = bitRead(counter, b); + Serial.print(bit); + } + Serial.print(" Decimal Number: "); + Serial.println(counter); +} +---- + +-- +// OVERVIEW SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also -- -// OVERVIEW SECTION ENDS \ No newline at end of file +// SEE ALSO SECTION ENDS diff --git a/Language/Functions/Bits and Bytes/bitSet.adoc b/Language/Functions/Bits and Bytes/bitSet.adoc index f16072f07..94c52a797 100644 --- a/Language/Functions/Bits and Bytes/bitSet.adoc +++ b/Language/Functions/Bits and Bytes/bitSet.adoc @@ -12,12 +12,12 @@ subCategories: [ "Bits and Bytes" ] // OVERVIEW SECTION STARTS -Sets (writes a 1 to) a bit of a numeric variable. [#overview] -- [float] === Description +Sets (writes a 1 to) a bit of a numeric variable. [%hardbreaks] @@ -28,13 +28,58 @@ Sets (writes a 1 to) a bit of a numeric variable. [float] === Parameters -`x`: the numeric variable whose bit to set +`x`: the numeric variable whose bit to set. + +`n`: which bit to set, starting at 0 for the least-significant (rightmost) bit. -`n`: which bit to set, starting at 0 for the least-significant (rightmost) bit [float] === Returns -Nothing +`x`: the value of the numeric variable after the bit at position `n` is set. + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code +Prints the output of `bitSet(x,n)` on two given integers. The binary representation of 4 is 0100, so when `n=1`, the second bit from the right is set to 1. After this we are left with 0110 in binary, so 6 is returned. + +[source,arduino] +---- +void setup() { + Serial.begin(9600); + while (!Serial) { + ; // wait for serial port to connect. Needed for native USB port only + } + + int x = 4; + int n = 1; + Serial.print(bitSet(x, n)); // print the output of bitSet(x,n) +} + +void loop() { +} +---- +[%hardbreaks] + +-- +// HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +[role="language"] +* #LANGUAGE# link:../bitclear[bitClear()] -- -// OVERVIEW SECTION ENDS \ No newline at end of file +// SEE ALSO SECTION ENDS diff --git a/Language/Functions/Bits and Bytes/bitWrite.adoc b/Language/Functions/Bits and Bytes/bitWrite.adoc index bdcd6f62b..b0e5ef723 100644 --- a/Language/Functions/Bits and Bytes/bitWrite.adoc +++ b/Language/Functions/Bits and Bytes/bitWrite.adoc @@ -17,7 +17,7 @@ subCategories: [ "Bits and Bytes" ] [float] === Description -Writes a bit of a numeric variable. +Writes to a bit of a variable, e.g. `bool`, `int`, `long`. Note that `float` & `double` are not supported. You can write to a bit of variables up to an `unsigned long` (32 bits / 4 bytes). [%hardbreaks] @@ -28,15 +28,52 @@ Writes a bit of a numeric variable. [float] === Parameters -`x`: the numeric variable to which to write +`x`: the numeric variable to which to write. + +`n`: which bit of the number to write, starting at 0 for the least-significant (rightmost) bit. + +`b`: the value to write to the bit (0 or 1). -`n`: which bit of the number to write, starting at 0 for the least-significant (rightmost) bit - -`b`: the value to write to the bit (0 or 1) [float] === Returns Nothing -- -// OVERVIEW SECTION ENDS \ No newline at end of file +// OVERVIEW SECTION ENDS + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code +Demonstrates the use of bitWrite by printing the value of a variable to the Serial Monitor before and after the use of `bitWrite()`. + + +[source,arduino] +---- +void setup() { + Serial.begin(9600); + while (!Serial) {} // wait for serial port to connect. Needed for native USB port only + byte x = 0b10000000; // the 0b prefix indicates a binary constant + Serial.println(x, BIN); // 10000000 + bitWrite(x, 0, 1); // write 1 to the least significant bit of x + Serial.println(x, BIN); // 10000001 +} + +void loop() {} +---- +[%hardbreaks] +-- +// HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Functions/Bits and Bytes/highByte.adoc b/Language/Functions/Bits and Bytes/highByte.adoc index a30945f09..74fc59123 100644 --- a/Language/Functions/Bits and Bytes/highByte.adoc +++ b/Language/Functions/Bits and Bytes/highByte.adoc @@ -30,9 +30,10 @@ Extracts the high-order (leftmost) byte of a word (or the second lowest byte of === Parameters `x`: a value of any type + [float] === Returns -byte +Data type: `byte`. -- // OVERVIEW SECTION ENDS diff --git a/Language/Functions/Bits and Bytes/lowByte.adoc b/Language/Functions/Bits and Bytes/lowByte.adoc index 9055f6ac4..77c90a772 100644 --- a/Language/Functions/Bits and Bytes/lowByte.adoc +++ b/Language/Functions/Bits and Bytes/lowByte.adoc @@ -30,9 +30,11 @@ Extracts the low-order (rightmost) byte of a variable (e.g. a word). === Parameters `x`: a value of any type + [float] === Returns -byte +Data type: `byte`. + -- // OVERVIEW SECTION ENDS diff --git a/Language/Functions/Characters/isAlpha.adoc b/Language/Functions/Characters/isAlpha.adoc index 80da1686b..e331e0e47 100644 --- a/Language/Functions/Characters/isAlpha.adoc +++ b/Language/Functions/Characters/isAlpha.adoc @@ -1,82 +1,78 @@ ---- -title: "isAlpha()" -categories: [ "Functions" ] -subCategories: [ "Characters" ] ---- - - - - - -= isAlpha(thisChar) - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -Analyse if a char is alpha (that is a letter). Returns true if thisChar contains a letter. -[%hardbreaks] - - -[float] -=== Syntax -[source,arduino] ----- -isAlpha(thisChar) ----- - -[float] -=== Parameters -`thisChar`: variable. *Allowed data types:* char - -[float] -=== Returns -`true`: if thisChar is alpha. - --- -// OVERVIEW SECTION ENDS - - - -// HOW TO USE SECTION STARTS -[#howtouse] --- - -[float] -=== Example Code - -[source,arduino] ----- -if (isAlpha(this)) // tests if this is a letter -{ - Serial.println("The character is a letter"); -} -else -{ - Serial.println("The character is not a letter"); -} - ----- - --- -// HOW TO USE SECTION ENDS - - -// SEE ALSO SECTION -[#see_also] --- - -[float] -=== See also - -[role="language"] -* #LANGUAGE# link:../../../variables/data-types/char[char] -* #LANGUAGE# link:../../../structure/control-structure/if[if (conditional operators)] -* #LANGUAGE# link:../../../structure/control-structure/while[while (conditional operators)] -* #LANGUAGE# link:../../communication/serial/read[read()] - --- -// SEE ALSO SECTION ENDS +--- +title: "isAlpha()" +categories: [ "Functions" ] +subCategories: [ "Characters" ] +--- + + + + + += isAlpha(thisChar) + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Analyse if a char is alpha (that is a letter). Returns true if thisChar contains a letter. +[%hardbreaks] + + +[float] +=== Syntax +`isAlpha(thisChar)` + + +[float] +=== Parameters +`thisChar`: variable. Allowed data types: `char`. + + +[float] +=== Returns +`true`: if thisChar is alpha. + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code + +[source,arduino] +---- +if (isAlpha(myChar)) { // tests if myChar is a letter + Serial.println("The character is a letter"); +} +else { + Serial.println("The character is not a letter"); +} +---- + +-- +// HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +[role="language"] +* #LANGUAGE# link:../../../variables/data-types/char[char] +* #LANGUAGE# link:../../../structure/control-structure/if[if (conditional operators)] +* #LANGUAGE# link:../../../structure/control-structure/while[while (conditional operators)] +* #LANGUAGE# link:../../communication/serial/read[read()] + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Functions/Characters/isAlphaNumeric.adoc b/Language/Functions/Characters/isAlphaNumeric.adoc index 5e7da2c8a..257edd9fc 100644 --- a/Language/Functions/Characters/isAlphaNumeric.adoc +++ b/Language/Functions/Characters/isAlphaNumeric.adoc @@ -1,82 +1,78 @@ ---- -title: "isAlphaNumeric()" -categories: [ "Functions" ] -subCategories: [ "Characters" ] ---- - - - - - -= isAlphaNumeric(thisChar) - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -Analyse if a char is alphanumeric (that is a letter or a numbers). Returns true if thisChar contains either a number or a letter. -[%hardbreaks] - - -[float] -=== Syntax -[source,arduino] ----- -`isAlphaNumeric(thisChar)` ----- - -[float] -=== Parameters -`thisChar`: variable. *Allowed data types:* char - -[float] -=== Returns -`true`: if thisChar is alphanumeric. - --- -// OVERVIEW SECTION ENDS - - - -// HOW TO USE SECTION STARTS -[#howtouse] --- - -[float] -=== Example Code - -[source,arduino] ----- -if (isAlphaNumeric(this)) // tests if this isa letter or a number -{ - Serial.println("The character is alphanumeric"); -} -else -{ - Serial.println("The character is not alphanumeric"); -} - ----- - --- -// HOW TO USE SECTION ENDS - - -// SEE ALSO SECTION -[#see_also] --- - -[float] -=== See also - -[role="language"] -* #LANGUAGE# link:../../../variables/data-types/char[char] -* #LANGUAGE# link:../../../structure/control-structure/if[if (conditional operators)] -* #LANGUAGE# link:../../../structure/control-structure/while[while (conditional operators)] -* #LANGUAGE# link:../../communication/serial/read[read()] - --- -// SEE ALSO SECTION ENDS \ No newline at end of file +--- +title: "isAlphaNumeric()" +categories: [ "Functions" ] +subCategories: [ "Characters" ] +--- + + + + + += isAlphaNumeric(thisChar) + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Analyse if a char is alphanumeric (that is a letter or a numbers). Returns true if thisChar contains either a number or a letter. +[%hardbreaks] + + +[float] +=== Syntax +`isAlphaNumeric(thisChar)` + + +[float] +=== Parameters +`thisChar`: variable. Allowed data types: `char`. + + +[float] +=== Returns +`true`: if thisChar is alphanumeric. + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code + +[source,arduino] +---- +if (isAlphaNumeric(myChar)) { // tests if myChar isa letter or a number + Serial.println("The character is alphanumeric"); +} +else { + Serial.println("The character is not alphanumeric"); +} +---- + +-- +// HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +[role="language"] +* #LANGUAGE# link:../../../variables/data-types/char[char] +* #LANGUAGE# link:../../../structure/control-structure/if[if (conditional operators)] +* #LANGUAGE# link:../../../structure/control-structure/while[while (conditional operators)] +* #LANGUAGE# link:../../communication/serial/read[read()] + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Functions/Characters/isAscii.adoc b/Language/Functions/Characters/isAscii.adoc index d97ef7021..3aad8d047 100644 --- a/Language/Functions/Characters/isAscii.adoc +++ b/Language/Functions/Characters/isAscii.adoc @@ -1,82 +1,78 @@ ---- -title: "isAscii()" -categories: [ "Functions" ] -subCategories: [ "Characters" ] ---- - - - - - -= isAscii(thisChar) - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -Analyse if a char is Ascii. Returns true if thisChar contains an Ascii character. -[%hardbreaks] - - -[float] -=== Syntax -[source,arduino] ----- -`isAscii(thisChar)` ----- - -[float] -=== Parameters -`thisChar`: variable. *Allowed data types:* char - -[float] -=== Returns -`true`: if thisChar is Ascii. - --- -// OVERVIEW SECTION ENDS - - - -// HOW TO USE SECTION STARTS -[#howtouse] --- - -[float] -=== Example Code - -[source,arduino] ----- -if (isAscii(this)) // tests if this is an Ascii character -{ - Serial.println("The character is Ascii"); -} -else -{ - Serial.println("The character is not Ascii"); -} - ----- - --- -// HOW TO USE SECTION ENDS - - -// SEE ALSO SECTION -[#see_also] --- - -[float] -=== See also - -[role="language"] -* #LANGUAGE# link:../../../variables/data-types/char[char] -* #LANGUAGE# link:../../../structure/control-structure/if[if (conditional operators)] -* #LANGUAGE# link:../../../structure/control-structure/while[while (conditional operators)] -* #LANGUAGE# link:../../communication/serial/read[read()] - --- -// SEE ALSO SECTION ENDS \ No newline at end of file +--- +title: "isAscii()" +categories: [ "Functions" ] +subCategories: [ "Characters" ] +--- + + + + + += isAscii(thisChar) + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Analyse if a char is Ascii. Returns true if thisChar contains an Ascii character. +[%hardbreaks] + + +[float] +=== Syntax +`isAscii(thisChar)` + + +[float] +=== Parameters +`thisChar`: variable. Allowed data types: `char`. + + +[float] +=== Returns +`true`: if thisChar is Ascii. + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code + +[source,arduino] +---- +if (isAscii(myChar)) { // tests if myChar is an Ascii character + Serial.println("The character is Ascii"); +} +else { + Serial.println("The character is not Ascii"); +} +---- + +-- +// HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +[role="language"] +* #LANGUAGE# link:../../../variables/data-types/char[char] +* #LANGUAGE# link:../../../structure/control-structure/if[if (conditional operators)] +* #LANGUAGE# link:../../../structure/control-structure/while[while (conditional operators)] +* #LANGUAGE# link:../../communication/serial/read[read()] + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Functions/Characters/isControl.adoc b/Language/Functions/Characters/isControl.adoc index b09c3903c..dc032aa5b 100644 --- a/Language/Functions/Characters/isControl.adoc +++ b/Language/Functions/Characters/isControl.adoc @@ -1,82 +1,78 @@ ---- -title: "isControl()" -categories: [ "Functions" ] -subCategories: [ "Characters" ] ---- - - - - - -= isControl(thisChar) - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -Analyse if a char is a control character. Returns true if thisChar is a control character. -[%hardbreaks] - - -[float] -=== Syntax -[source,arduino] ----- -`isControl(thisChar)` ----- - -[float] -=== Parameters -`thisChar`: variable. *Allowed data types:* char - -[float] -=== Returns -`true`: if thisChar is a control character. - --- -// OVERVIEW SECTION ENDS - - - -// HOW TO USE SECTION STARTS -[#howtouse] --- - -[float] -=== Example Code - -[source,arduino] ----- -if (isControl(this)) // tests if this is a control character -{ - Serial.println("The character is a control character"); -} -else -{ - Serial.println("The character is not a control character"); -} - ----- - --- -// HOW TO USE SECTION ENDS - - -// SEE ALSO SECTION -[#see_also] --- - -[float] -=== See also - -[role="language"] -* #LANGUAGE# link:../../../variables/data-types/char[char] -* #LANGUAGE# link:../../../structure/control-structure/if[if (conditional operators)] -* #LANGUAGE# link:../../../structure/control-structure/while[while (conditional operators)] -* #LANGUAGE# link:../../communication/serial/read[read()] - --- -// SEE ALSO SECTION ENDS \ No newline at end of file +--- +title: "isControl()" +categories: [ "Functions" ] +subCategories: [ "Characters" ] +--- + + + + + += isControl(thisChar) + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Analyse if a char is a control character. Returns true if thisChar is a control character. +[%hardbreaks] + + +[float] +=== Syntax +`isControl(thisChar)` + + +[float] +=== Parameters +`thisChar`: variable. Allowed data types: `char`. + + +[float] +=== Returns +`true`: if thisChar is a control character. + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code + +[source,arduino] +---- +if (isControl(myChar)) { // tests if myChar is a control character + Serial.println("The character is a control character"); +} +else { + Serial.println("The character is not a control character"); +} +---- + +-- +// HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +[role="language"] +* #LANGUAGE# link:../../../variables/data-types/char[char] +* #LANGUAGE# link:../../../structure/control-structure/if[if (conditional operators)] +* #LANGUAGE# link:../../../structure/control-structure/while[while (conditional operators)] +* #LANGUAGE# link:../../communication/serial/read[read()] + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Functions/Characters/isDigit.adoc b/Language/Functions/Characters/isDigit.adoc index 2cb65a831..c26892b1b 100644 --- a/Language/Functions/Characters/isDigit.adoc +++ b/Language/Functions/Characters/isDigit.adoc @@ -1,82 +1,78 @@ ---- -title: "isDigit()" -categories: [ "Functions" ] -subCategories: [ "Characters" ] ---- - - - - - -= isDigit(thisChar) - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -Analyse if a char is a digit (that is a number). Returns true if thisChar is a number. -[%hardbreaks] - - -[float] -=== Syntax -[source,arduino] ----- -isDigit(thisChar) ----- - -[float] -=== Parameters -`thisChar`: variable. *Allowed data types:* char - -[float] -=== Returns -`true`: if thisChar is a number. - --- -// OVERVIEW SECTION ENDS - - - -// HOW TO USE SECTION STARTS -[#howtouse] --- - -[float] -=== Example Code - -[source,arduino] ----- -if (isDigit(this)) // tests if this is a digit -{ - Serial.println("The character is a number"); -} -else -{ - Serial.println("The character is not a number"); -} - ----- - --- -// HOW TO USE SECTION ENDS - - -// SEE ALSO SECTION -[#see_also] --- - -[float] -=== See also - -[role="language"] -* #LANGUAGE# link:../../../variables/data-types/char[char] -* #LANGUAGE# link:../../../structure/control-structure/if[if (conditional operators)] -* #LANGUAGE# link:../../../structure/control-structure/while[while (conditional operators)] -* #LANGUAGE# link:../../communication/serial/read[read()] - --- -// SEE ALSO SECTION ENDS \ No newline at end of file +--- +title: "isDigit()" +categories: [ "Functions" ] +subCategories: [ "Characters" ] +--- + + + + + += isDigit(thisChar) + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Analyse if a char is a digit (that is a number). Returns true if thisChar is a number. +[%hardbreaks] + + +[float] +=== Syntax +`isDigit(thisChar)` + + +[float] +=== Parameters +`thisChar`: variable. Allowed data types: `char`. + + +[float] +=== Returns +`true`: if thisChar is a number. + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code + +[source,arduino] +---- +if (isDigit(myChar)) { // tests if myChar is a digit + Serial.println("The character is a number"); +} +else { + Serial.println("The character is not a number"); +} +---- + +-- +// HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +[role="language"] +* #LANGUAGE# link:../../../variables/data-types/char[char] +* #LANGUAGE# link:../../../structure/control-structure/if[if (conditional operators)] +* #LANGUAGE# link:../../../structure/control-structure/while[while (conditional operators)] +* #LANGUAGE# link:../../communication/serial/read[read()] + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Functions/Characters/isGraph.adoc b/Language/Functions/Characters/isGraph.adoc index ba487741e..237576e88 100644 --- a/Language/Functions/Characters/isGraph.adoc +++ b/Language/Functions/Characters/isGraph.adoc @@ -1,82 +1,77 @@ ---- -title: "isGraph()" -categories: [ "Functions" ] -subCategories: [ "Characters" ] ---- - - - - - -= isGraph(thisChar) - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -Analyse if a char is printable with some content (space is printable but has no content). Returns true if thisChar is printable. -[%hardbreaks] - - -[float] -=== Syntax -[source,arduino] ----- -`isGraph(thisChar)` ----- - -[float] -=== Parameters -`thisChar`: variable. *Allowed data types:* char - -[float] -=== Returns -`true`: if thisChar is printable. - --- -// OVERVIEW SECTION ENDS - - - -// HOW TO USE SECTION STARTS -[#howtouse] --- - -[float] -=== Example Code - -[source,arduino] ----- -if (isGraph(this)) // tests if this is a printable character but not a blank space. -{ - Serial.println("The character is printable"); -} -else -{ - Serial.println("The character is not printable"); -} - ----- - --- -// HOW TO USE SECTION ENDS - - -// SEE ALSO SECTION -[#see_also] --- - -[float] -=== See also - -[role="language"] -* #LANGUAGE# link:../../../variables/data-types/char[char] -* #LANGUAGE# link:../../../structure/control-structure/if[if (conditional operators)] -* #LANGUAGE# link:../../../structure/control-structure/while[while (conditional operators)] -* #LANGUAGE# link:../../communication/serial/read[read()] - --- -// SEE ALSO SECTION ENDS \ No newline at end of file +--- +title: "isGraph()" +categories: [ "Functions" ] +subCategories: [ "Characters" ] +--- + + + + + += isGraph(thisChar) + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Analyse if a char is printable with some content (space is printable but has no content). Returns true if thisChar is printable. +[%hardbreaks] + + +[float] +=== Syntax +`isGraph(thisChar)` + +[float] +=== Parameters +`thisChar`: variable. Allowed data types: `char`. + + +[float] +=== Returns +`true`: if thisChar is printable. + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code + +[source,arduino] +---- +if (isGraph(myChar)) { // tests if myChar is a printable character but not a blank space. + Serial.println("The character is printable"); +} +else { + Serial.println("The character is not printable"); +} +---- + +-- +// HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +[role="language"] +* #LANGUAGE# link:../../../variables/data-types/char[char] +* #LANGUAGE# link:../../../structure/control-structure/if[if (conditional operators)] +* #LANGUAGE# link:../../../structure/control-structure/while[while (conditional operators)] +* #LANGUAGE# link:../../communication/serial/read[read()] + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Functions/Characters/isHexadecimalDigit.adoc b/Language/Functions/Characters/isHexadecimalDigit.adoc index 58f66c4d5..e6e6b6026 100644 --- a/Language/Functions/Characters/isHexadecimalDigit.adoc +++ b/Language/Functions/Characters/isHexadecimalDigit.adoc @@ -1,82 +1,78 @@ ---- -title: "isHexadecimalDigit()" -categories: [ "Functions" ] -subCategories: [ "Characters" ] ---- - - - - - -= isHexadecimalDigit(thisChar) - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -Analyse if a char is an hexadecimal digit (A-F, 0-9). Returns true if thisChar contains an hexadecimal digit. -[%hardbreaks] - - -[float] -=== Syntax -[source,arduino] ----- -`isHexadecimalDigit(thisChar)` ----- - -[float] -=== Parameters -`thisChar`: variable. *Allowed data types:* char - -[float] -=== Returns -`true`: if thisChar is an hexadecimal digit. - --- -// OVERVIEW SECTION ENDS - - - -// HOW TO USE SECTION STARTS -[#howtouse] --- - -[float] -=== Example Code - -[source,arduino] ----- -if (isHexadecimalDigit(this)) // tests if this is an hexadecimal digit -{ - Serial.println("The character is an hexadecimal digit"); -} -else -{ - Serial.println("The character is not an hexadecimal digit"); -} - ----- - --- -// HOW TO USE SECTION ENDS - - -// SEE ALSO SECTION -[#see_also] --- - -[float] -=== See also - -[role="language"] -* #LANGUAGE# link:../../../variables/data-types/char[char] -* #LANGUAGE# link:../../../structure/control-structure/if[if (conditional operators)] -* #LANGUAGE# link:../../../structure/control-structure/while[while (conditional operators)] -* #LANGUAGE# link:../../communication/serial/read[read()] - --- -// SEE ALSO SECTION ENDS +--- +title: "isHexadecimalDigit()" +categories: [ "Functions" ] +subCategories: [ "Characters" ] +--- + + + + + += isHexadecimalDigit(thisChar) + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Analyse if a char is an hexadecimal digit (A-F, 0-9). Returns true if thisChar contains an hexadecimal digit. +[%hardbreaks] + + +[float] +=== Syntax +`isHexadecimalDigit(thisChar)` + + +[float] +=== Parameters +`thisChar`: variable. Allowed data types: `char`. + + +[float] +=== Returns +`true`: if thisChar is an hexadecimal digit. + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code + +[source,arduino] +---- +if (isHexadecimalDigit(myChar)) { // tests if myChar is an hexadecimal digit + Serial.println("The character is an hexadecimal digit"); +} +else { + Serial.println("The character is not an hexadecimal digit"); +} +---- + +-- +// HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +[role="language"] +* #LANGUAGE# link:../../../variables/data-types/char[char] +* #LANGUAGE# link:../../../structure/control-structure/if[if (conditional operators)] +* #LANGUAGE# link:../../../structure/control-structure/while[while (conditional operators)] +* #LANGUAGE# link:../../communication/serial/read[read()] + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Functions/Characters/isLowerCase.adoc b/Language/Functions/Characters/isLowerCase.adoc index e7b0e0bda..8f27e712f 100644 --- a/Language/Functions/Characters/isLowerCase.adoc +++ b/Language/Functions/Characters/isLowerCase.adoc @@ -1,82 +1,78 @@ ---- -title: "isLowerCase()" -categories: [ "Functions" ] -subCategories: [ "Characters" ] ---- - - - - - -= isLowerCase(thisChar) - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -Analyse if a char is lower case (that is a letter in lower case). Returns true if thisChar contains a letter in lower case. -[%hardbreaks] - - -[float] -=== Syntax -[source,arduino] ----- -`isLowerCase(thisChar)` ----- - -[float] -=== Parameters -`thisChar`: variable. *Allowed data types:* char - -[float] -=== Returns -`true`: if thisChar is lower case. - --- -// OVERVIEW SECTION ENDS - - - -// HOW TO USE SECTION STARTS -[#howtouse] --- - -[float] -=== Example Code - -[source,arduino] ----- -if (isLowerCase(this)) // tests if this is a lower case letter -{ - Serial.println("The character is lower case"); -} -else -{ - Serial.println("The character is not lower case"); -} - ----- - --- -// HOW TO USE SECTION ENDS - - -// SEE ALSO SECTION -[#see_also] --- - -[float] -=== See also - -[role="language"] -* #LANGUAGE# link:../../../variables/data-types/char[char] -* #LANGUAGE# link:../../../structure/control-structure/if[if (conditional operators)] -* #LANGUAGE# link:../../../structure/control-structure/while[while (conditional operators)] -* #LANGUAGE# link:../../communication/serial/read[read()] - --- -// SEE ALSO SECTION ENDS +--- +title: "isLowerCase()" +categories: [ "Functions" ] +subCategories: [ "Characters" ] +--- + + + + + += isLowerCase(thisChar) + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Analyse if a char is lower case (that is a letter in lower case). Returns true if thisChar contains a letter in lower case. +[%hardbreaks] + + +[float] +=== Syntax +`isLowerCase(thisChar)` + + +[float] +=== Parameters +`thisChar`: variable. Allowed data types: `char`. + + +[float] +=== Returns +`true`: if thisChar is lower case. + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code + +[source,arduino] +---- +if (isLowerCase(myChar)) { // tests if myChar is a lower case letter + Serial.println("The character is lower case"); +} +else { + Serial.println("The character is not lower case"); +} +---- + +-- +// HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +[role="language"] +* #LANGUAGE# link:../../../variables/data-types/char[char] +* #LANGUAGE# link:../../../structure/control-structure/if[if (conditional operators)] +* #LANGUAGE# link:../../../structure/control-structure/while[while (conditional operators)] +* #LANGUAGE# link:../../communication/serial/read[read()] + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Functions/Characters/isPrintable.adoc b/Language/Functions/Characters/isPrintable.adoc index 71a3a2a72..ecea1307c 100644 --- a/Language/Functions/Characters/isPrintable.adoc +++ b/Language/Functions/Characters/isPrintable.adoc @@ -1,82 +1,78 @@ ---- -title: "isPrintable()" -categories: [ "Functions" ] -subCategories: [ "Characters" ] ---- - - - - - -= isPrintable(thisChar) - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -Analyse if a char is printable (that is any character that produces an output, even a blank space). Returns true if thisChar is printable. -[%hardbreaks] - - -[float] -=== Syntax -[source,arduino] ----- -`isAlpha(thisChar)` ----- - -[float] -=== Parameters -`thisChar`: variable. *Allowed data types:* char - -[float] -=== Returns -`true`: if thisChar is printable. - --- -// OVERVIEW SECTION ENDS - - - -// HOW TO USE SECTION STARTS -[#howtouse] --- - -[float] -=== Example Code - -[source,arduino] ----- -if (isPrintable(this)) // tests if this is printable char -{ - Serial.println("The character is printable"); -} -else -{ - Serial.println("The character is not printable"); -} - ----- - --- -// HOW TO USE SECTION ENDS - - -// SEE ALSO SECTION -[#see_also] --- - -[float] -=== See also - -[role="language"] -* #LANGUAGE# link:../../../variables/data-types/char[char] -* #LANGUAGE# link:../../../structure/control-structure/if[if (conditional operators)] -* #LANGUAGE# link:../../../structure/control-structure/while[while (conditional operators)] -* #LANGUAGE# link:../../communication/serial/read[read()] - --- -// SEE ALSO SECTION ENDS +--- +title: "isPrintable()" +categories: [ "Functions" ] +subCategories: [ "Characters" ] +--- + + + + + += isPrintable(thisChar) + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Analyse if a char is printable (that is any character that produces an output, even a blank space). Returns true if thisChar is printable. +[%hardbreaks] + + +[float] +=== Syntax +`isPrintable(thisChar)` + + +[float] +=== Parameters +`thisChar`: variable. Allowed data types: `char`. + + +[float] +=== Returns +`true`: if thisChar is printable. + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code + +[source,arduino] +---- +if (isPrintable(myChar)) { // tests if myChar is printable char + Serial.println("The character is printable"); +} +else { + Serial.println("The character is not printable"); +} +---- + +-- +// HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +[role="language"] +* #LANGUAGE# link:../../../variables/data-types/char[char] +* #LANGUAGE# link:../../../structure/control-structure/if[if (conditional operators)] +* #LANGUAGE# link:../../../structure/control-structure/while[while (conditional operators)] +* #LANGUAGE# link:../../communication/serial/read[read()] + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Functions/Characters/isPunct.adoc b/Language/Functions/Characters/isPunct.adoc index b4bf4eafe..7f9d159dd 100644 --- a/Language/Functions/Characters/isPunct.adoc +++ b/Language/Functions/Characters/isPunct.adoc @@ -1,82 +1,78 @@ ---- -title: "isPunct()" -categories: [ "Functions" ] -subCategories: [ "Characters" ] ---- - - - - - -= isPunct(thisChar) - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -Analyse if a char is punctuation (that is a comma, a semicolon, an exlamation mark and so on). Returns true if thisChar is punctuation. -[%hardbreaks] - - -[float] -=== Syntax -[source,arduino] ----- -`isPunct(thisChar)` ----- - -[float] -=== Parameters -`thisChar`: variable. *Allowed data types:* char - -[float] -=== Returns -`true`: if thisChar is a punctuation. - --- -// OVERVIEW SECTION ENDS - - - -// HOW TO USE SECTION STARTS -[#howtouse] --- - -[float] -=== Example Code - -[source,arduino] ----- -if (isPunct(this)) // tests if this is a punctuation character -{ - Serial.println("The character is a punctuation"); -} -else -{ - Serial.println("The character is not a punctuation"); -} - ----- - --- -// HOW TO USE SECTION ENDS - - -// SEE ALSO SECTION -[#see_also] --- - -[float] -=== See also - -[role="language"] -* #LANGUAGE# link:../../../variables/data-types/char[char] -* #LANGUAGE# link:../../../structure/control-structure/if[if (conditional operators)] -* #LANGUAGE# link:../../../structure/control-structure/while[while (conditional operators)] -* #LANGUAGE# link:../../communication/serial/read[read()] - --- -// SEE ALSO SECTION ENDS +--- +title: "isPunct()" +categories: [ "Functions" ] +subCategories: [ "Characters" ] +--- + + + + + += isPunct(thisChar) + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Analyse if a char is punctuation (that is a comma, a semicolon, an exclamation mark and so on). Returns true if thisChar is punctuation. +[%hardbreaks] + + +[float] +=== Syntax +`isPunct(thisChar)` + + +[float] +=== Parameters +`thisChar`: variable. Allowed data types: `char`. + + +[float] +=== Returns +`true`: if thisChar is a punctuation. + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code + +[source,arduino] +---- +if (isPunct(myChar)) { // tests if myChar is a punctuation character + Serial.println("The character is a punctuation"); +} +else { + Serial.println("The character is not a punctuation"); +} +---- + +-- +// HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +[role="language"] +* #LANGUAGE# link:../../../variables/data-types/char[char] +* #LANGUAGE# link:../../../structure/control-structure/if[if (conditional operators)] +* #LANGUAGE# link:../../../structure/control-structure/while[while (conditional operators)] +* #LANGUAGE# link:../../communication/serial/read[read()] + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Functions/Characters/isSpace.adoc b/Language/Functions/Characters/isSpace.adoc index fa9cb9b68..89f48954a 100644 --- a/Language/Functions/Characters/isSpace.adoc +++ b/Language/Functions/Characters/isSpace.adoc @@ -1,82 +1,78 @@ ---- -title: "isSpace()" -categories: [ "Functions" ] -subCategories: [ "Characters" ] ---- - - - - - -= isSpace(thisChar) - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -Analyse if a char is the space character. Returns true if thisChar contains the space character. -[%hardbreaks] - - -[float] -=== Syntax -[source,arduino] ----- -`isSpace(thisChar)` ----- - -[float] -=== Parameters -`thisChar`: variable. *Allowed data types:* char - -[float] -=== Returns -`true`: if thisChar is a space. - --- -// OVERVIEW SECTION ENDS - - - -// HOW TO USE SECTION STARTS -[#howtouse] --- - -[float] -=== Example Code - -[source,arduino] ----- -if (isSpace(this)) // tests if this is the space character -{ - Serial.println("The character is a space"); -} -else -{ - Serial.println("The character is not a space"); -} - ----- - --- -// HOW TO USE SECTION ENDS - - -// SEE ALSO SECTION -[#see_also] --- - -[float] -=== See also - -[role="language"] -* #LANGUAGE# link:../../../variables/data-types/char[char] -* #LANGUAGE# link:../../../structure/control-structure/if[if (conditional operators)] -* #LANGUAGE# link:../../../structure/control-structure/while[while (conditional operators)] -* #LANGUAGE# link:../../communication/serial/read[read()] - --- -// SEE ALSO SECTION ENDS +--- +title: "isSpace()" +categories: [ "Functions" ] +subCategories: [ "Characters" ] +--- + + + + + += isSpace(thisChar) + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Analyse if a char is a white-space character. Returns true if the argument is a space, form feed (`'\f'`), newline (`'\n'`), carriage return (`'\r'`), horizontal tab (`'\t'`), or vertical tab (`'\v'`). +[%hardbreaks] + + +[float] +=== Syntax +`isSpace(thisChar)` + + +[float] +=== Parameters +`thisChar`: variable. Allowed data types: `char`. + + +[float] +=== Returns +`true`: if thisChar is a white-space character. + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code + +[source,arduino] +---- +if (isSpace(myChar)) { // tests if myChar is a white-space character + Serial.println("The character is white-space"); +} +else { + Serial.println("The character is not white-space"); +} +---- + +-- +// HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +[role="language"] +* #LANGUAGE# link:../../../variables/data-types/char[char] +* #LANGUAGE# link:../../../structure/control-structure/if[if (conditional operators)] +* #LANGUAGE# link:../../../structure/control-structure/while[while (conditional operators)] +* #LANGUAGE# link:../../communication/serial/read[read()] + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Functions/Characters/isUpperCase.adoc b/Language/Functions/Characters/isUpperCase.adoc index 963995baf..691271f4f 100644 --- a/Language/Functions/Characters/isUpperCase.adoc +++ b/Language/Functions/Characters/isUpperCase.adoc @@ -1,82 +1,74 @@ ---- -title: "isUpperCase()" -categories: [ "Functions" ] -subCategories: [ "Characters" ] ---- - - - - - -= isUpperCase(thisChar) - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -Analyse if a char is upper case (that is a letter in upper case). Returns true if thisChar is upper case. -[%hardbreaks] - - -[float] -=== Syntax -[source,arduino] ----- -`isUpperCase(thisChar)` ----- - -[float] -=== Parameters -`thisChar`: variable. *Allowed data types:* char - -[float] -=== Returns -`true`: if thisChar is upper case. - --- -// OVERVIEW SECTION ENDS - - - -// HOW TO USE SECTION STARTS -[#howtouse] --- - -[float] -=== Example Code - -[source,arduino] ----- -if (isUpperCase(this)) // tests if this is an upeer case letter -{ - Serial.println("The character is upper case"); -} -else -{ - Serial.println("The character is not upper case"); -} - ----- - --- -// HOW TO USE SECTION ENDS - - -// SEE ALSO SECTION -[#see_also] --- - -[float] -=== See also - -[role="language"] -* #LANGUAGE# link:../../../variables/data-types/char[char] -* #LANGUAGE# link:../../../structure/control-structure/if[if (conditional operators)] -* #LANGUAGE# link:../../../structure/control-structure/while[while (conditional operators)] -* #LANGUAGE# link:../../communication/serial/read[read()] - --- -// SEE ALSO SECTION ENDS +--- +title: "isUpperCase()" +categories: [ "Functions" ] +subCategories: [ "Characters" ] +--- + += isUpperCase(thisChar) + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Analyse if a char is upper case (that is, a letter in upper case). Returns true if thisChar is upper case. +[%hardbreaks] + + +[float] +=== Syntax +`isUpperCase(thisChar)` + + +[float] +=== Parameters +`thisChar`: variable. Allowed data types: `char`. + + +[float] +=== Returns +`true`: if thisChar is upper case. + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code + +[source,arduino] +---- +if (isUpperCase(myChar)) { // tests if myChar is an upper case letter + Serial.println("The character is upper case"); +} +else { + Serial.println("The character is not upper case"); +} +---- + +-- +// HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +[role="language"] +* #LANGUAGE# link:../../../variables/data-types/char[char] +* #LANGUAGE# link:../../../structure/control-structure/if[if (conditional operators)] +* #LANGUAGE# link:../../../structure/control-structure/while[while (conditional operators)] +* #LANGUAGE# link:../../communication/serial/read[read()] + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Functions/Characters/isWhitespace.adoc b/Language/Functions/Characters/isWhitespace.adoc index 3eccc0a48..f24b8ab44 100644 --- a/Language/Functions/Characters/isWhitespace.adoc +++ b/Language/Functions/Characters/isWhitespace.adoc @@ -1,82 +1,78 @@ ---- -title: "isWhitespace()" -categories: [ "Functions" ] -subCategories: [ "Characters" ] ---- - - - - - -= isWhitespace(thisChar) - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -Analyse if a char is a white space, that is space, formfeed ('\f'), newline ('\n'), carriage return ('\r'), horizontal tab ('\t'), and vertical tab ('\v')). -Returns true if thisChar contains a white space. -[%hardbreaks] - - -[float] -=== Syntax -[source,arduino] -`isWhitespace(thisChar)` - - -[float] -=== Parameters -`thisChar`: variable. *Allowed data types:* char - -[float] -=== Returns -`true`: if thisChar is a white space. - --- -// OVERVIEW SECTION ENDS - - - -// HOW TO USE SECTION STARTS -[#howtouse] --- - -[float] -=== Example Code - -[source,arduino] ----- -if (isWhitespace(this)) // tests if this is a white space -{ - Serial.println("The character is a white space"); -} -else -{ - Serial.println("The character is not a white space"); -} - ----- - --- -// HOW TO USE SECTION ENDS - - -// SEE ALSO SECTION -[#see_also] --- - -[float] -=== See also - -[role="language"] -* #LANGUAGE# link:../../../variables/data-types/char[char] -* #LANGUAGE# link:../../../structure/control-structure/if[if (conditional operators)] -* #LANGUAGE# link:../../../structure/control-structure/while[while (conditional operators)] -* #LANGUAGE# link:../../communication/serial/read[read()] - --- -// SEE ALSO SECTION ENDS +--- +title: "isWhitespace()" +categories: [ "Functions" ] +subCategories: [ "Characters" ] +--- + + + + + += isWhitespace(thisChar) + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Analyse if a char is a space character. Returns true if the argument is a space or horizontal tab (`'\t'`). +[%hardbreaks] + + +[float] +=== Syntax +`isWhitespace(thisChar)` + + +[float] +=== Parameters +`thisChar`: variable. Allowed data types: `char`. + + +[float] +=== Returns +`true`: if thisChar is a space character. + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code + +[source,arduino] +---- +if (isWhitespace(myChar)) { // tests if myChar is a space character + Serial.println("The character is a space or tab"); +} +else { + Serial.println("The character is not a space or tab"); +} +---- + +-- +// HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +[role="language"] +* #LANGUAGE# link:../../../variables/data-types/char[char] +* #LANGUAGE# link:../../../structure/control-structure/if[if (conditional operators)] +* #LANGUAGE# link:../../../structure/control-structure/while[while (conditional operators)] +* #LANGUAGE# link:../../communication/serial/read[read()] + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Functions/Communication/Print.adoc b/Language/Functions/Communication/Print.adoc new file mode 100644 index 000000000..a6b7a142d --- /dev/null +++ b/Language/Functions/Communication/Print.adoc @@ -0,0 +1,61 @@ +--- +title: Print +categories: [ "Functions" ] +subCategories: [ "Communication" ] +--- + + + + += Print + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +The Print class is an abstract base class that provides a common interface for printing data to different output devices. It defines several methods that allow printing data in different formats. + +Print class is related to several libraries in Arduino that use the printing functionality to interact with devices such as Serial Monitor, LCD Screen, printers, etc. + +Some of the libraries that use the Print class are: + +* link:https://www.arduino.cc/en/Reference/serial[Serial] +* link:https://reference.arduino.cc/reference/en/libraries/liquidcrystal/[LiquidCrystal] +* link:https://www.arduino.cc/en/Reference/Ethernet[Ethernet] +* link:https://reference.arduino.cc/reference/en/libraries/wifi/wificlient/[Wifi] + + +-- +// OVERVIEW SECTION ENDS + + +// FUNCTIONS SECTION STARTS +[#functions] +-- + +''' + +[float] +=== Functions +link:https://www.arduino.cc/reference/en/language/functions/communication/wire/write/[write()] + +link:https://www.arduino.cc/en/Reference/serial/print/[print()] + +link:https://www.arduino.cc/en/Reference/serial/println/[println()] + +''' + +-- +// FUNCTIONS SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Functions/Communication/SPI.adoc b/Language/Functions/Communication/SPI.adoc new file mode 100644 index 000000000..a448778cf --- /dev/null +++ b/Language/Functions/Communication/SPI.adoc @@ -0,0 +1,71 @@ +--- +title: SPI +categories: [ "Functions" ] +subCategories: [ "Communication" ] +--- + + += SPI + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description + + +This library allows you to communicate with SPI devices, with the Arduino as the controller device. This library is bundled with every Arduino platform (avr, megaavr, mbed, samd, sam, arc32), so *you do not need to install* the library separately. + +To use this library + +`#include ` + +To read more about Arduino and SPI, you can visit the https://docs.arduino.cc/learn/communication/spi[Arduino & Serial Peripheral Interface (SPI)] guide. + +-- +// OVERVIEW SECTION ENDS + +// HOW TO USE SECTION STARTS +[#howtouse] +-- +|================================================================================================================================================ +| Boards | Default SPI Pins | Additional SPI Pins | Notes +| UNO R3, UNO R3 SMD, UNO WiFi Rev2, UNO Mini Ltd| 10(CS), 11(COPI), 12(CIPO), 13(SCK) | | SPI pins available on ICSP header +| UNO R4 Minima, UNO R4 WiFi| 10(CS), 11(COPI), 12(CIPO), 13(SCK) | | SPI pins available on ICSP header +| Leonardo, Yún Rev2, Zero| 10(CS), 11(COPI), 12(CIPO), 13(SCK) | | SPI pins available on ICSP header +| Micro | 14(CIPO), 15(SCK), 16(COPI) | | +| Nano boards | 11(COPI), 12(CIPO), 13(SCK) | | +| MKR boards | 8(COPI), 9(SCK), 10(CIPO) | | +| Due | 74(CIPO), 75(MOSI), 76(SCK) | SPI pins available on dedicated SPI header | +| GIGA R1 WiFi | 89(CIPO), 90(COPI), 91(SCK) | 12(CIPO), 11(COPI), 13(SCK), 10(CS) | Note that pin 89,90,91 are located on the SPI header +| Mega 2560 Rev3 | 50(CIPO), 51(COPI), 52(SCK), 53(CS) | | SPI pins available on ICSP header +|================================================================================================================================================ + +-- +// HOW TO USE SECTION ENDS + +// FUNCTIONS SECTION STARTS +[#functions] +-- + +''' + +[float] +=== Functions +link:../spi/spisettings[SPISettings] + +link:../spi/begin[begin()] + +link:../spi/begintransaction[beginTransaction()] + +link:../spi/endtransaction[endTransaction()] + +link:../spi/end[end()] + +link:../spi/setbitorder[setBitOrder()] + +link:../spi/setclockdivider[setClockDivider()] + +link:../spi/setdatamode[setDataMode()] + +link:../spi/transfer[transfer()] + +link:../spi/usinginterrupt[usingInterrupt()] + +''' + +-- +// SEEALSO SECTION ENDS diff --git a/Language/Functions/Communication/SPI/SPISettings.adoc b/Language/Functions/Communication/SPI/SPISettings.adoc new file mode 100644 index 000000000..a0586c8b6 --- /dev/null +++ b/Language/Functions/Communication/SPI/SPISettings.adoc @@ -0,0 +1,43 @@ +--- +title: SPISettings +--- + += SPISettings + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +The `SPISettings` object is used to configure the SPI port for your SPI device. All 3 parameters are combined to a single `SPISettings` object, which is given to `SPI.beginTransaction()`. + +When all of your settings are constants, SPISettings should be used directly in `SPI.beginTransaction()`. See the syntax section below. For constants, this syntax results in smaller and faster code. + +If any of your settings are variables, you may create a SPISettings object to hold the 3 settings. Then you can give the object name to SPI.beginTransaction(). Creating a named SPISettings object may be more efficient when your settings are not constants, especially if the maximum speed is a variable computed or configured, rather than a number you type directly into your sketch. + +[float] +=== Syntax +`SPI.beginTransaction(SPISettings(14000000, MSBFIRST, SPI_MODE0))` +Note: Best if all 3 settings are constants + +`SPISettings mySetting(speedMaximum, dataOrder, dataMode)` +Note: Best when any setting is a variable'' + + +[float] +=== Parameters + +`speedMaximum`: The maximum speed of communication. For a SPI chip rated up to 20 MHz, use 20000000. + +`dataOrder`: MSBFIRST or LSBFIRST + +`dataMode`: SPI_MODE0, SPI_MODE1, SPI_MODE2, or SPI_MODE3 + + +[float] +=== Returns +None. + +-- +// OVERVIEW SECTION ENDS + diff --git a/Language/Functions/Communication/SPI/begin.adoc b/Language/Functions/Communication/SPI/begin.adoc new file mode 100644 index 000000000..757e57c6c --- /dev/null +++ b/Language/Functions/Communication/SPI/begin.adoc @@ -0,0 +1,33 @@ +--- +title: SPI.begin() +--- + += SPI.begin() + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Initializes the SPI bus by setting SCK, MOSI, and SS to outputs, pulling SCK and MOSI low, and SS high. + + +[float] +=== Syntax +`SPI.begin()` + + +[float] +=== Parameters +None. + + +[float] +=== Returns +None. + +-- +// OVERVIEW SECTION ENDS + diff --git a/Language/Functions/Communication/SPI/beginTransaction.adoc b/Language/Functions/Communication/SPI/beginTransaction.adoc new file mode 100644 index 000000000..ae299ca02 --- /dev/null +++ b/Language/Functions/Communication/SPI/beginTransaction.adoc @@ -0,0 +1,33 @@ +--- +title: SPI.beginTransaction() +--- + += SPI.beginTransaction() + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Initializes the SPI bus. Note that calling link:../begin[SPI.begin()] is required before calling this one. + + +[float] +=== Syntax +`SPI.beginTransaction(mySettings)` + + +[float] +=== Parameters +mySettings: the chosen settings (see link:../spisettings[SPISettings]). + + +[float] +=== Returns +None. + +-- +// OVERVIEW SECTION ENDS + diff --git a/Language/Functions/Communication/SPI/end.adoc b/Language/Functions/Communication/SPI/end.adoc new file mode 100644 index 000000000..76eef8025 --- /dev/null +++ b/Language/Functions/Communication/SPI/end.adoc @@ -0,0 +1,33 @@ +--- +title: SPI.end() +--- + += SPI.end() + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Disables the SPI bus (leaving pin modes unchanged). + + +[float] +=== Syntax +`SPI.end()` + + +[float] +=== Parameters +None. + + +[float] +=== Returns +None. + +-- +// OVERVIEW SECTION ENDS + diff --git a/Language/Functions/Communication/SPI/endTransaction.adoc b/Language/Functions/Communication/SPI/endTransaction.adoc new file mode 100644 index 000000000..4bf8ec891 --- /dev/null +++ b/Language/Functions/Communication/SPI/endTransaction.adoc @@ -0,0 +1,33 @@ +--- +title: SPI.endTransaction() +--- + += SPI.endTransaction() + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Stop using the SPI bus. Normally this is called after de-asserting the chip select, to allow other libraries to use the SPI bus. + + +[float] +=== Syntax +`SPI.endTransaction()` + + +[float] +=== Parameters +None. + + +[float] +=== Returns +None. + +-- +// OVERVIEW SECTION ENDS + diff --git a/Language/Functions/Communication/SPI/setBitOrder.adoc b/Language/Functions/Communication/SPI/setBitOrder.adoc new file mode 100644 index 000000000..c67d40c1e --- /dev/null +++ b/Language/Functions/Communication/SPI/setBitOrder.adoc @@ -0,0 +1,35 @@ +--- +title: SPI.setBitOrder() +--- + += SPI.setBitOrder() + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +This function should not be used in new projects. Use link:../spisettings[SPISettings]. with link:../begintransaction[SPI.beginTransaction()]. to configure SPI parameters. + +Sets the order of the bits shifted out of and into the SPI bus, either LSBFIRST (least-significant bit first) or MSBFIRST (most-significant bit first). + + +[float] +=== Syntax +`SPI.setBitOrder(order)` + + +[float] +=== Parameters +order: either LSBFIRST or MSBFIRST + + +[float] +=== Returns +None. + +-- +// OVERVIEW SECTION ENDS + diff --git a/Language/Functions/Communication/SPI/setClockDivider.adoc b/Language/Functions/Communication/SPI/setClockDivider.adoc new file mode 100644 index 000000000..edb835c99 --- /dev/null +++ b/Language/Functions/Communication/SPI/setClockDivider.adoc @@ -0,0 +1,48 @@ +--- +title: SPI.setClockDivider() +--- + += SPI.setClockDivider() + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +This function should not be used in new projects. Use link:../spisettings[SPISettings]. with link:../begintransaction[SPI.beginTransaction()]. to configure SPI parameters. + +Sets the SPI clock divider relative to the system clock. On AVR based boards, the dividers available are 2, 4, 8, 16, 32, 64 or 128. The default setting is SPI_CLOCK_DIV4, which sets the SPI clock to one-quarter the frequency of the system clock (4 Mhz for the boards at 16 MHz). + +*For Arduino Due:* On the Due, the system clock can be divided by values from 1 to 255. The default value is 21, which sets the clock to 4 MHz like other Arduino boards. + + +[float] +=== Syntax +`SPI.setClockDivider(divider)` + + +[float] +=== Parameters + +divider (only AVR boards): + +* SPI_CLOCK_DIV2 +* SPI_CLOCK_DIV4 +* SPI_CLOCK_DIV8 +* SPI_CLOCK_DIV16 +* SPI_CLOCK_DIV32 +* SPI_CLOCK_DIV64 +* SPI_CLOCK_DIV128 + +*chipSelectPin*: peripheral device CS pin (Arduino Due only) +*divider*: a number from 1 to 255 (Arduino Due only) + +[float] +=== Returns +None. + +-- +// OVERVIEW SECTION ENDS + diff --git a/Language/Functions/Communication/SPI/setDataMode.adoc b/Language/Functions/Communication/SPI/setDataMode.adoc new file mode 100644 index 000000000..4089e5e89 --- /dev/null +++ b/Language/Functions/Communication/SPI/setDataMode.adoc @@ -0,0 +1,41 @@ +--- +title: SPI.setDataMode() +--- + += SPI.setDataMode() + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +This function should not be used in new projects. Use link:../spisettings[SPISettings]. with link:../begintransaction[SPI.beginTransaction()]. to configure SPI parameters. + +Sets the SPI data mode: that is, clock polarity and phase. See the Wikipedia article on http://en.wikipedia.org/wiki/Serial_Peripheral_Interface_Bus:[SPI] for details. + +[float] +=== Syntax +`SPI.setDataMode(mode)` + + +[float] +=== Parameters + +mode: + +* SPI_MODE0 +* SPI_MODE1 +* SPI_MODE2 +* SPI_MODE3 + + +chipSelectPin - peripheral device CS pin (Arduino Due only) + +[float] +=== Returns +None. + +-- +// OVERVIEW SECTION ENDS + diff --git a/Language/Functions/Communication/SPI/transfer.adoc b/Language/Functions/Communication/SPI/transfer.adoc new file mode 100644 index 000000000..ff59a3b3c --- /dev/null +++ b/Language/Functions/Communication/SPI/transfer.adoc @@ -0,0 +1,40 @@ +--- +title: SPI.transfer() +--- + += SPI.transfer() + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description + +SPI transfer is based on a simultaneous send and receive: the received data is returned in receivedVal (or receivedVal16). In case of buffer transfers the received data is stored in the buffer in-place (the old data is replaced with the data received). + +[float] +=== Syntax + +`receivedVal = SPI.transfer(val)` + +`receivedVal16 = SPI.transfer16(val16)` + +`SPI.transfer(buffer, size)` + + +[float] +=== Parameters + +* val: the byte to send out over the bus +* val16: the two bytes variable to send out over the bus +* buffer: the array of data to be transferred + + +[float] +=== Returns +The received data. + +-- +// OVERVIEW SECTION ENDS + diff --git a/Language/Functions/Communication/SPI/usingInterrupt.adoc b/Language/Functions/Communication/SPI/usingInterrupt.adoc new file mode 100644 index 000000000..7769ba39d --- /dev/null +++ b/Language/Functions/Communication/SPI/usingInterrupt.adoc @@ -0,0 +1,33 @@ +--- +title: SPI.usingInterrupt() +--- + += SPI.usingInterrupt() + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description + +If your program will perform SPI transactions within an interrupt, call this function to register the interrupt number or name with the SPI library. This allows `SPI.beginTransaction()` to prevent usage conflicts. Note that the interrupt specified in the call to usingInterrupt() will be disabled on a call to `beginTransaction()` and re-enabled in `endTransaction().` + +[float] +=== Syntax + +`SPI.usingInterrupt(interruptNumber)` + + +[float] +=== Parameters + +interruptNumber: the associated interrupt number. + +[float] +=== Returns +None. + +-- +// OVERVIEW SECTION ENDS + diff --git a/Language/Functions/Communication/Serial.adoc b/Language/Functions/Communication/Serial.adoc index 714dee439..9b47ddbff 100644 --- a/Language/Functions/Communication/Serial.adoc +++ b/Language/Functions/Communication/Serial.adoc @@ -4,9 +4,6 @@ categories: [ "Functions" ] subCategories: [ "Communication" ] --- - - - = Serial() @@ -16,16 +13,47 @@ subCategories: [ "Communication" ] [float] === Description -Used for communication between the Arduino board and a computer or other devices. All Arduino boards have at least one serial port (also known as a UART or USART): Serial. It communicates on digital pins 0 (RX) and 1 (TX) as well as with the computer via USB. Thus, if you use these functions, you cannot also use pins 0 and 1 for digital input or output. + +Used for communication between the Arduino board and a computer or other devices. All Arduino boards have at least one serial port (also known as a UART or USART), and some have several. +[options="header"] + +|================================================================================================================================================ +| Board | Serial pins | Serial1 pins | Serial2 pins | Serial3 pins | Serial4 pins +| UNO R3, UNO R3 SMD Mini | 0(RX), 1(TX) | | | | +| Nano (classic) | 0(RX), 1(TX) | | | | +| UNO R4 Minima, UNO R4 WiFi| | 0(RX0), 1(TX0) | | | +| Leonardo, Micro, Yún Rev2 | | 0(RX), 1(TX) | | | +| Uno WiFi Rev.2 | | 0(RX), 1(TX) | | | +| MKR boards | | 13(RX), 14(TX) | | | +| Zero | | 0(RX), 1(TX) | | | +| GIGA R1 WiFi | | 0(RX), 1(TX) | 19(RX1), 18(TX1) | 17(RX2), 16(TX2) | 15(RX3), 14(TX3) +| Due | 0(RX), 1(TX) | 19(RX1), 18(TX1) | 17(RX2), 16(TX2) | 15(RX3), 14(TX3) | +| Mega 2560 Rev3 | 0(RX), 1(TX) | 19(RX1), 18(TX1) | 17(RX2), 16(TX2) | 15(RX3), 14(TX3) | +| Nano 33 IoT | | 0(RX0), 1(TX0) | | | +| Nano RP2040 Connect | | 0(RX0), 1(TX0) | | | +| Nano BLE / BLE Sense | | 0(RX0), 1(TX0) | | | +|================================================================================================================================================ + + +[options="header"] + +The Nano ESP32 board is an exception due to being based on the ESP32 core. Here, `Serial0` refers to `RX0` and `TX0`, while `Serial1` and `Serial2` are additional ports that can be assigned to any free GPIO. + +|================================================================================================================================================ +| Board | Serial0 pins | Serial1 pins | Serial2 pins | Serial3 pins | Serial4 pins +| Nano ESP32 | 0(RX0), 1(TX0) | Any free GPIO | Any free GPIO | | +|================================================================================================================================================ + +You can read more about configuring the Nano ESP32's additional serial ports in https://docs.arduino.cc/tutorials/nano-esp32/cheat-sheet/#uart[this article]. + +[%hardbreaks] +On older boards (Uno, Nano, Mini, and Mega), pins 0 and 1 are used for communication with the computer. Connecting anything to these pins can interfere with that communication, including causing failed uploads to the board. +[%hardbreaks] You can use the Arduino environment's built-in serial monitor to communicate with an Arduino board. Click the serial monitor button in the toolbar and select the same baud rate used in the call to `begin()`. [%hardbreaks] Serial communication on pins TX/RX uses TTL logic levels (5V or 3.3V depending on the board). Don't connect these pins directly to an RS232 serial port; they operate at +/- 12V and can damage your Arduino board. [%hardbreaks] -The *Arduino Mega* has three additional serial ports: `Serial1` on pins 19 (RX) and 18 (TX), `Serial2` on pins 17 (RX) and 16 (TX), `Serial3` on pins 15 (RX) and 14 (TX). To use these pins to communicate with your personal computer, you will need an additional USB-to-serial adaptor, as they are not connected to the Mega's USB-to-serial adaptor. To use them to communicate with an external TTL serial device, connect the TX pin to your device's RX pin, the RX to your device's TX pin, and the ground of your Mega to your device's ground. -[%hardbreaks] -The *Arduino DUE* has three additional 3.3V TTL serial ports: `Serial1` on pins 19 (RX) and 18 (TX); `Serial2` on pins 17 (RX) and 16 (TX), `Serial3` on pins 15 (RX) and 14 (TX). Pins 0 and 1 are also connected to the corresponding pins of the ATmega16U2 USB-to-TTL Serial chip, which is connected to the USB debug port. Additionally, there is a native USB-serial port on the SAM3X chip, SerialUSB'. +To use these extra serial ports to communicate with your personal computer, you will need an additional USB-to-serial adaptor, as they are not connected to the Mega's USB-to-serial adaptor. To use them to communicate with an external TTL serial device, connect the TX pin to your device's RX pin, the RX to your device's TX pin, and the ground of your Mega to your device's ground. [%hardbreaks] -The *Arduino Leonardo* board uses `Serial1` to communicate via TTL (5V) serial on pins 0 (RX) and 1 (TX). `Serial` is reserved for USB CDC communication. For more information, refer to the Leonardo getting started page and hardware page. -- // OVERVIEW SECTION ENDS @@ -39,7 +67,7 @@ The *Arduino Leonardo* board uses `Serial1` to communicate via TTL (5V) serial o [float] === Functions -link:../serial/ifserial[If] (Serial) + +link:../serial/ifserial[if(Serial)] + link:../serial/available[available()] + link:../serial/availableforwrite[availableForWrite()] + link:../serial/begin[begin()] + diff --git a/Language/Functions/Communication/Serial/available.adoc b/Language/Functions/Communication/Serial/available.adoc index 286b5ebc5..14b8ab166 100644 --- a/Language/Functions/Communication/Serial/available.adoc +++ b/Language/Functions/Communication/Serial/available.adoc @@ -11,28 +11,26 @@ title: Serial.available() [float] === Description -Get the number of bytes (characters) available for reading from the serial port. This is data that's already arrived and stored in the serial receive buffer (which holds 64 bytes). `available()` inherits from the Stream utility class. +Get the number of bytes (characters) available for reading from the serial port. This is data that's already arrived and stored in the serial receive buffer (which holds 64 bytes). + +`Serial.available()` inherits from the link:../../stream[Stream] utility class. [%hardbreaks] [float] === Syntax -`Serial.available()` - -_Arduino Mega only:_ - -`Serial1.available()` + -`Serial2.available()` + -`Serial3.available()` +`_Serial_.available()` [float] === Parameters -None +`_Serial_`: serial port object. See the list of available serial ports for each board on the link:https://www.arduino.cc/en/Reference/serial[Serial main page]. + [float] === Returns -The number of bytes available to read . +The number of bytes available to read. + -- // OVERVIEW SECTION ENDS @@ -42,27 +40,26 @@ The number of bytes available to read . [float] === Example Code // Describe what the example code is all about and add relevant code ►►►►► THIS SECTION IS MANDATORY ◄◄◄◄◄ -The following code returns a character received through the serial port. +The following code returns a character received through the serial port. [source,arduino] ---- -int incomingByte = 0; // for incoming serial data +int incomingByte = 0; // for incoming serial data void setup() { - Serial.begin(9600); // opens serial port, sets data rate to 9600 bps + Serial.begin(9600); // opens serial port, sets data rate to 9600 bps } void loop() { - - // reply only when you receive data: - if (Serial.available() > 0) { - // read the incoming byte: - incomingByte = Serial.read(); - - // say what you got: - Serial.print("I received: "); - Serial.println(incomingByte, DEC); - } + // reply only when you receive data: + if (Serial.available() > 0) { + // read the incoming byte: + incomingByte = Serial.read(); + + // say what you got: + Serial.print("I received: "); + Serial.println(incomingByte, DEC); + } } ---- [%hardbreaks] @@ -75,7 +72,6 @@ This code sends data received in one serial port of the Arduino Mega to another. void setup() { Serial.begin(9600); Serial1.begin(9600); - } void loop() { @@ -83,7 +79,6 @@ void loop() { if (Serial.available()) { int inByte = Serial.read(); Serial1.print(inByte, DEC); - } // read from port 1, send to port 0: if (Serial1.available()) { diff --git a/Language/Functions/Communication/Serial/availableForWrite.adoc b/Language/Functions/Communication/Serial/availableForWrite.adoc index f3e84bfac..fe76f5407 100644 --- a/Language/Functions/Communication/Serial/availableForWrite.adoc +++ b/Language/Functions/Communication/Serial/availableForWrite.adoc @@ -20,22 +20,18 @@ Get the number of bytes (characters) available for writing in the serial buffer [float] === Syntax -`Serial.availableForWrite()` - -_Arduino Mega only:_ - -`Serial1.availableForWrite()` + -`Serial2.availableForWrite()` + -`Serial3.availableForWrite()` +`_Serial_.availableForWrite()` [float] === Parameters -Nothing +`_Serial_`: serial port object. See the list of available serial ports for each board on the link:https://www.arduino.cc/en/Reference/serial[Serial main page]. + [float] === Returns The number of bytes available to write. + -- // OVERVIEW SECTION ENDS diff --git a/Language/Functions/Communication/Serial/begin.adoc b/Language/Functions/Communication/Serial/begin.adoc index c60a33e89..ed0bf8270 100644 --- a/Language/Functions/Communication/Serial/begin.adoc +++ b/Language/Functions/Communication/Serial/begin.adoc @@ -14,7 +14,7 @@ title: Serial.begin() [float] === Description -Sets the data rate in bits per second (baud) for serial data transmission. For communicating with the computer, use one of these rates: 300, 600, 1200, 2400, 4800, 9600, 14400, 19200, 28800, 38400, 57600, or 115200. You can, however, specify other rates - for example, to communicate over pins 0 and 1 with a component that requires a particular baud rate. +Sets the data rate in bits per second (baud) for serial data transmission. For communicating with Serial Monitor, make sure to use one of the baud rates listed in the menu at the bottom right corner of its screen. You can, however, specify other rates - for example, to communicate over pins 0 and 1 with a component that requires a particular baud rate. An optional second argument configures the data, parity, and stop bits. The default is 8 data bits, no parity, one stop bit. [%hardbreaks] @@ -22,26 +22,15 @@ An optional second argument configures the data, parity, and stop bits. The defa [float] === Syntax -`Serial.begin(speed)` -`Serial.begin(speed, config)` - -_Arduino Mega only:_ - -`Serial1.begin(speed)` + -`Serial2.begin(speed)` + -`Serial3.begin(speed)` + -`Serial1.begin(speed, config)` + -`Serial2.begin(speed, config)` + -`Serial3.begin(speed, config)` - +`_Serial_.begin(speed)` + +`_Serial_.begin(speed, config)` [float] === Parameters -`speed`: in bits per second (baud) - `long` - -`config`: sets data, parity, and stop bits. Valid values are - +`_Serial_`: serial port object. See the list of available serial ports for each board on the link:https://www.arduino.cc/en/Reference/serial[Serial main page]. + +`speed`: in bits per second (baud). Allowed data types: `long`. + +`config`: sets data, parity, and stop bits. Valid values are: + `SERIAL_5N1` + `SERIAL_6N1` + `SERIAL_7N1` + @@ -50,7 +39,7 @@ _Arduino Mega only:_ `SERIAL_6N2` + `SERIAL_7N2` + `SERIAL_8N2` + -`SERIAL_5E1` + +`SERIAL_5E1`: even parity + `SERIAL_6E1` + `SERIAL_7E1` + `SERIAL_8E1` + @@ -58,14 +47,15 @@ _Arduino Mega only:_ `SERIAL_6E2` + `SERIAL_7E2` + `SERIAL_8E2` + -`SERIAL_5O1` + +`SERIAL_5O1`: odd parity + `SERIAL_6O1` + `SERIAL_7O1` + `SERIAL_8O1` + `SERIAL_5O2` + `SERIAL_6O2` + `SERIAL_7O2` + -`SERIAL_8O2` + +`SERIAL_8O2` + [float] === Returns @@ -103,7 +93,7 @@ void loop() {} // (Serial, Serial1, Serial2, Serial3), // with different baud rates: -void setup(){ +void setup() { Serial.begin(9600); Serial1.begin(38400); Serial2.begin(19200); @@ -119,5 +109,13 @@ void loop() {} [%hardbreaks] Thanks to Jeff Gray for the mega example + +[float] +=== Notes and Warnings +For USB CDC serial ports (e.g. `Serial` on the Leonardo), `Serial.begin()` is irrelevant. You can use any baud rate and configuration for serial communication with these ports. See the list of available serial ports for each board on the link:https://www.arduino.cc/en/Reference/serial[Serial main page]. + +The only `config` value supported for `Serial1` on the Arduino Nano 33 BLE and Nano 33 BLE Sense boards is `SERIAL_8N1`. +[%hardbreaks] + -- // HOW TO USE SECTION ENDS diff --git a/Language/Functions/Communication/Serial/end.adoc b/Language/Functions/Communication/Serial/end.adoc index ccf49c13f..a3b101c79 100644 --- a/Language/Functions/Communication/Serial/end.adoc +++ b/Language/Functions/Communication/Serial/end.adoc @@ -20,22 +20,17 @@ Disables serial communication, allowing the RX and TX pins to be used for genera [float] === Syntax -`Serial.end()` - -_Arduino Mega only:_ - -`Serial1.end()` + -`Serial2.end()` + -`Serial3.end()` + +`_Serial_.end()` [float] === Parameters -Nothing +`_Serial_`: serial port object. See the list of available serial ports for each board on the link:https://www.arduino.cc/en/Reference/serial[Serial main page]. + [float] === Returns Nothing -- -// OVERVIEW SECTION ENDS \ No newline at end of file +// OVERVIEW SECTION ENDS diff --git a/Language/Functions/Communication/Serial/find.adoc b/Language/Functions/Communication/Serial/find.adoc index 3ebbf47ef..9f454de0a 100644 --- a/Language/Functions/Communication/Serial/find.adoc +++ b/Language/Functions/Communication/Serial/find.adoc @@ -14,23 +14,28 @@ title: Serial.find() [float] === Description -Serial.find() reads data from the serial buffer until the target string of given length is found. The function returns true if target string is found, false if it times out. +`Serial.find()` reads data from the serial buffer until the target is found. The function returns `true` if target is found, `false` if it times out. -Serial.find() inherits from the link:../../stream[stream] utility class. +`Serial.find()` inherits from the link:../../stream[stream] utility class. [%hardbreaks] [float] === Syntax -`Serial.find(target)` +`_Serial_.find(target)` + +`_Serial_.find(target, length)` + [float] === Parameters -`target` : the string to search for (char) +`_Serial_`: serial port object. See the list of available serial ports for each board on the link:https://www.arduino.cc/en/Reference/serial[Serial main page]. + +`target`: the string to search for. Allowed data types: `char`. + +`length`: length of the target. Allowed data types: `size_t`. + [float] === Returns -`bool` +Data type: `bool`. -- // OVERVIEW SECTION ENDS diff --git a/Language/Functions/Communication/Serial/findUntil.adoc b/Language/Functions/Communication/Serial/findUntil.adoc index 08a580758..a2e9fc0d6 100644 --- a/Language/Functions/Communication/Serial/findUntil.adoc +++ b/Language/Functions/Communication/Serial/findUntil.adoc @@ -24,35 +24,24 @@ The function returns true if the target string is found, false if it times out. [float] === Syntax -`Serial.findUntil(target, terminal)` +`_Serial_.findUntil(target, terminal)` [float] === Parameters -`target` : the string to search for (char) -`terminal` : the terminal string in the search (char) +`_Serial_`: serial port object. See the list of available serial ports for each board on the link:https://www.arduino.cc/en/Reference/serial[Serial main page]. + +`target`: the string to search for. Allowed data types: `char`. + +`terminal`: the terminal string in the search. Allowed data types: `char`. + [float] === Returns -`bool` +Data type: `bool`. -- // OVERVIEW SECTION ENDS - - -// HOW TO USE SECTION STARTS -[#howtouse] --- - -[float] -=== Notes and Warnings - --- -// HOW TO USE SECTION ENDS - - // SEE ALSO SECTION [#see_also] -- diff --git a/Language/Functions/Communication/Serial/flush.adoc b/Language/Functions/Communication/Serial/flush.adoc index 993902a21..fb7027f6a 100644 --- a/Language/Functions/Communication/Serial/flush.adoc +++ b/Language/Functions/Communication/Serial/flush.adoc @@ -14,26 +14,21 @@ title: Serial.flush() [float] === Description -Waits for the transmission of outgoing serial data to complete. (Prior to Arduino 1.0, this instead removed any buffered incoming serial data.) +Waits for the transmission of outgoing serial data to complete. -`flush()` inherits from the link:../flush[Stream] utility class. +`flush()` inherits from the link:../../stream/streamflush[Stream] utility class. [%hardbreaks] [float] === Syntax -`Serial.flush()` - -_Arduino Mega only:_ - -`Serial1.flush()` + -`Serial2.flush()` + -`Serial3.flush()` +`_Serial_.flush()` [float] === Parameters -Nothing +`_Serial_`: serial port object. See the list of available serial ports for each board on the link:https://www.arduino.cc/en/Reference/serial[Serial main page]. + [float] === Returns diff --git a/Language/Functions/Communication/Serial/getTimeout.adoc b/Language/Functions/Communication/Serial/getTimeout.adoc new file mode 100644 index 000000000..c900bd8ba --- /dev/null +++ b/Language/Functions/Communication/Serial/getTimeout.adoc @@ -0,0 +1,62 @@ +--- +title: Serial.getTimeout() +--- + + + + += Serial.getTimeout() + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +`Serial.getTimeout()` returns the timeout value set by `Serial.setTimeout()`. + +`Serial.getTimeout()` inherits from the link:../../stream[Stream] utility class. +[%hardbreaks] + + +[float] +=== Syntax +`_Serial_.getTimeout()` + + +[float] +=== Parameters +None + + +[float] +=== Returns +The timeout value set by `Serial.setTimeout()`. Data type: `unsigned long`. + +-- +// OVERVIEW SECTION ENDS + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +-- +// HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +[role="language"] +* #LANGUAGE# link:../../stream[stream] +* #LANGUAGE# link:../../stream/streamsettimeout[stream.setTimeout()] +* #LANGUAGE# link:../../stream/streamgettimeout[stream.getTimeout()] + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Functions/Communication/Serial/ifSerial.adoc b/Language/Functions/Communication/Serial/ifSerial.adoc index c690b7f2a..a41c1ec88 100644 --- a/Language/Functions/Communication/Serial/ifSerial.adoc +++ b/Language/Functions/Communication/Serial/ifSerial.adoc @@ -16,35 +16,25 @@ title: if(Serial) === Description Indicates if the specified Serial port is ready. -On the Leonardo, `if (Serial)` indicates whether or not the USB CDC serial connection is open. For all other instances, including `if (Serial1)` on the Leonardo, this will always return true. +On the boards with native USB, `if (Serial)` (or `if(SerialUSB)` on the Due) indicates whether or not the USB CDC serial connection is open. For all other boards, and the non-USB CDC ports, this will always return true. -This was introduced in Arduino IDE 1.0.1. [%hardbreaks] [float] === Syntax -_All boards:_ - `if (Serial)` -_Arduino Leonardo specific:_ - -`if (Serial1)` - -_Arduino Mega specific:_ - -`if (Serial1)` + -`if (Serial2)` + -`if (Serial3)` [float] === Parameters -Nothing +None + [float] === Returns -`bool` : returns true if the specified serial port is available. This will only return false if querying the Leonardo's USB CDC serial connection before it is ready. +Returns true if the specified serial port is available. This will only return false if querying the Leonardo's USB CDC serial connection before it is ready. Data type: `bool`. + -- // OVERVIEW SECTION ENDS @@ -64,7 +54,7 @@ Nothing [source,arduino] ---- void setup() { - //Initialize serial and wait for port to open: + //Initialize serial and wait for port to open: Serial.begin(9600); while (!Serial) { ; // wait for serial port to connect. Needed for native USB @@ -72,9 +62,13 @@ void setup() { } void loop() { - //proceed normally + //proceed normally } ---- +[float] +=== Notes and Warnings +This function adds a delay of 10ms in an attempt to solve "open but not quite" situations. Don't use it in tight loops. + -- // HOW TO USE SECTION ENDS diff --git a/Language/Functions/Communication/Serial/parseFloat.adoc b/Language/Functions/Communication/Serial/parseFloat.adoc index bce4eddb4..6c1f01bcd 100644 --- a/Language/Functions/Communication/Serial/parseFloat.adoc +++ b/Language/Functions/Communication/Serial/parseFloat.adoc @@ -14,7 +14,7 @@ title: Serial.parseFloat() [float] === Description -`Serial.parseFloat()` returns the first valid floating point number from the Serial buffer. Characters that are not digits (or the minus sign) are skipped. `parseFloat()` is terminated by the first character that is not a floating point number. +`Serial.parseFloat()` returns the first valid floating point number from the Serial buffer. `parseFloat()` is terminated by the first character that is not a floating point number. The function terminates if it times out (see link:../settimeout[Serial.setTimeout()]). `Serial.parseFloat()` inherits from the link:../../stream[Stream] utility class. [%hardbreaks] @@ -22,16 +22,26 @@ title: Serial.parseFloat() [float] === Syntax -`Serial.parseFloat()` +`_Serial_.parseFloat()` + +`_Serial_.parseFloat(lookahead)` + +`_Serial_.parseFloat(lookahead, ignore)` [float] === Parameters -Nothing +`_Serial_`: serial port object. See the list of available serial ports for each board on the link:https://www.arduino.cc/en/Reference/serial[Serial main page]. + +`lookahead`: the mode used to look ahead in the stream for a floating point number. Allowed data types: `LookaheadMode`. Allowed `lookahead` values: + +* `SKIP_ALL`: all characters other than a minus sign, decimal point, or digits are ignored when scanning the stream for a floating point number. This is the default mode. +* `SKIP_NONE`: Nothing is skipped, and the stream is not touched unless the first waiting character is valid. +* `SKIP_WHITESPACE`: Only tabs, spaces, line feeds, and carriage returns are skipped. + +`ignore`: used to skip the indicated char in the search. Used for example to skip thousands divider. Allowed data types: `char` + [float] === Returns -`float` +Data type: `float`. -- // OVERVIEW SECTION ENDS diff --git a/Language/Functions/Communication/Serial/parseInt.adoc b/Language/Functions/Communication/Serial/parseInt.adoc index d228b19f5..93c6e1563 100644 --- a/Language/Functions/Communication/Serial/parseInt.adoc +++ b/Language/Functions/Communication/Serial/parseInt.adoc @@ -14,12 +14,13 @@ title: Serial.parseInt() [float] === Description -Looks for the next valid integer in the incoming serial `stream.parseInt()` inherits from the link:../../stream[Stream] utility class. +Looks for the next valid integer in the incoming serial. The function terminates if it times out (see link:../settimeout[Serial.setTimeout()]). + +`Serial.parseInt()` inherits from the link:../../stream[Stream] utility class. In particular: -* Initial characters that are not digits or a minus sign, are skipped; + * Parsing stops when no characters have been read for a configurable time-out value, or a non-digit is read; + * If no valid digits were read when the time-out (see Serial.setTimeout()) occurs, 0 is returned; [%hardbreaks] @@ -27,23 +28,26 @@ In particular: [float] === Syntax -`Serial.parseInt()` -`Serial.parseInt(char skipChar)` - -_Arduino Mega only:_ - -`Serial1.parseInt()` + -`Serial2.parseInt()` + -`Serial3.parseInt()` +`_Serial_.parseInt()` + +`_Serial_.parseInt(lookahead)` + +`_Serial_.parseInt(lookahead, ignore)` [float] === Parameters -`skipChar`: used to skip the indicated char in the search. Used for example to skip thousands divider. +`_Serial_`: serial port object. See the list of available serial ports for each board on the link:https://www.arduino.cc/en/Reference/serial[Serial main page]. + +`lookahead`: the mode used to look ahead in the stream for an integer. Allowed data types: `LookaheadMode`. Allowed `lookahead` values: + +* `SKIP_ALL`: all characters other than digits or a minus sign are ignored when scanning the stream for an integer. This is the default mode. +* `SKIP_NONE`: Nothing is skipped, and the stream is not touched unless the first waiting character is valid. +* `SKIP_WHITESPACE`: Only tabs, spaces, line feeds, and carriage returns are skipped. + +`ignore`: used to skip the indicated char in the search. Used for example to skip thousands divider. Allowed data types: `char` + [float] === Returns -`long` : the next valid integer +The next valid integer. Data type: `long`. -- // OVERVIEW SECTION ENDS diff --git a/Language/Functions/Communication/Serial/peek.adoc b/Language/Functions/Communication/Serial/peek.adoc index f77597b5a..557c729af 100644 --- a/Language/Functions/Communication/Serial/peek.adoc +++ b/Language/Functions/Communication/Serial/peek.adoc @@ -14,28 +14,25 @@ title: Serial.peek() [float] === Description -Returns the next byte (character) of incoming serial data without removing it from the internal serial buffer. That is, successive calls to `peek()` will return the same character, as will the next call to `read()`. `peek()` inherits from the link:../../stream[Stream] utility class. +Returns the next byte (character) of incoming serial data without removing it from the internal serial buffer. That is, successive calls to `peek()` will return the same character, as will the next call to `read()`. + +`Serial.peek()` inherits from the link:../../stream[Stream] utility class. [%hardbreaks] [float] === Syntax -`Serial.peek()` - -_Arduino Mega only:_ - -`Serial1.peek()` + -`Serial2.peek()` + -`Serial3.peek()` +`_Serial_.peek()` [float] === Parameters -Nothing +`_Serial_`: serial port object. See the list of available serial ports for each board on the link:https://www.arduino.cc/en/Reference/serial[Serial main page]. + [float] === Returns -The first byte of incoming serial data available (or -1 if no data is available) - `int` +The first byte of incoming serial data available (or -1 if no data is available). Data type: `int`. -- // OVERVIEW SECTION ENDS diff --git a/Language/Functions/Communication/Serial/print.adoc b/Language/Functions/Communication/Serial/print.adoc index 46a617de5..8f09302a0 100644 --- a/Language/Functions/Communication/Serial/print.adoc +++ b/Language/Functions/Communication/Serial/print.adoc @@ -16,24 +16,25 @@ title: Serial.print() === Description Prints data to the serial port as human-readable ASCII text. This command can take many forms. Numbers are printed using an ASCII character for each digit. Floats are similarly printed as ASCII digits, defaulting to two decimal places. Bytes are sent as a single character. Characters and strings are sent as is. For example- -* `Serial.print(78) gives "78"` + -* `Serial.print(1.23456) gives "1.23"` + -* `Serial.print('N') gives "N"` + -* `Serial.print("Hello world.") gives "Hello world."` +* `_Serial_.print(78)` gives "78" + +* `_Serial_.print(1.23456)` gives "1.23" + +* `_Serial_.print('N')` gives "N" + +* `_Serial_.print("Hello world.")` gives "Hello world." + An optional second parameter specifies the base (format) to use; permitted values are `BIN(binary, or base 2)`, `OCT(octal, or base 8)`, `DEC(decimal, or base 10)`, `HEX(hexadecimal, or base 16)`. For floating point numbers, this parameter specifies the number of decimal places to use. For example- -* `Serial.print(78, BIN) gives "1001110"` + -* `Serial.print(78, OCT) gives "116"` + -* `Serial.print(78, DEC) gives "78"` + -* `Serial.print(78, HEX) gives "4E"` + -* `Serial.print(1.23456, 0) gives "1"` + -* `Serial.print(1.23456, 2) gives "1.23"` + -* `Serial.print(1.23456, 4) gives "1.2346"` +* `_Serial_.print(78, BIN)` gives "1001110" + +* `_Serial_.print(78, OCT)` gives "116" + +* `_Serial_.print(78, DEC)` gives "78" + +* `_Serial_.print(78, HEX)` gives "4E" + +* `_Serial_.print(1.23456, 0)` gives "1" + +* `_Serial_.print(1.23456, 2)` gives "1.23" + +* `_Serial_.print(1.23456, 4)` gives "1.2346" -You can pass flash-memory based strings to Serial.print() by wrapping them with link:../../../../variables/utilities/progmem[F()]. For example: +You can pass flash-memory based strings to `_Serial_.print()` by wrapping them with link:../../../../variables/utilities/progmem[F()]. For example: -`Serial.print(F(“Hello World”))` +`Serial.print(F("Hello World"))` To send data without conversion to its representation as characters, use link:../write[Serial.write()]. [%hardbreaks] @@ -41,17 +42,19 @@ To send data without conversion to its representation as characters, use link:.. [float] === Syntax -`Serial.print(val)` + -`Serial.print(val, format)` +`_Serial_.print(val)` + +`_Serial_.print(val, format)` [float] === Parameters -`val`: the value to print - any data type +`_Serial_`: serial port object. See the list of available serial ports for each board on the link:https://www.arduino.cc/en/Reference/serial[Serial main page]. + +`val`: the value to print. Allowed data types: any data type. + [float] === Returns -`size_t`: `print()` returns the number of bytes written, though reading that number is optional. +`print()` returns the number of bytes written, though reading that number is optional. Data type: `size_t`. -- // OVERVIEW SECTION ENDS @@ -71,16 +74,16 @@ To send data without conversion to its representation as characters, use link:.. [source,arduino] ---- /* -Uses a for loop to print numbers in various formats. + Uses a for loop to print numbers in various formats. */ void setup() { - Serial.begin(9600); // open the serial port at 9600 bps: + Serial.begin(9600); // open the serial port at 9600 bps: } void loop() { // print labels Serial.print("NO FORMAT"); // prints a label - Serial.print("\t"); // prints a tab + Serial.print("\t"); // prints a tab Serial.print("DEC"); Serial.print("\t"); @@ -97,7 +100,7 @@ void loop() { for (int x = 0; x < 64; x++) { // only part of the ASCII chart, change to suit // print it out in many formats: Serial.print(x); // print as an ASCII-encoded decimal - same as "DEC" - Serial.print("\t\t"); // prints two tabs to accomodate the label lenght + Serial.print("\t\t"); // prints two tabs to accommodate the label length Serial.print(x, DEC); // print as an ASCII-encoded decimal Serial.print("\t"); // prints a tab @@ -119,7 +122,7 @@ void loop() { [float] === Notes and Warnings -As of version 1.0, serial transmission is asynchronous; `Serial.print()` will return before any characters are transmitted. +For information on the asyncronicity of `_Serial_.print()`, see the Notes and Warnings section of the link:../write#howtouse[Serial.write() reference page]. -- // HOW TO USE SECTION ENDS diff --git a/Language/Functions/Communication/Serial/println.adoc b/Language/Functions/Communication/Serial/println.adoc index 4185a2fb9..49dc2aaa1 100644 --- a/Language/Functions/Communication/Serial/println.adoc +++ b/Language/Functions/Communication/Serial/println.adoc @@ -20,19 +20,21 @@ Prints data to the serial port as human-readable ASCII text followed by a carria [float] === Syntax -`Serial.println(val)` + -`Serial.println(val, format)` +`_Serial_.println(val)` + +`_Serial_.println(val, format)` [float] === Parameters -`val`: the value to print - any data type +`_Serial_`: serial port object. See the list of available serial ports for each board on the link:https://www.arduino.cc/en/Reference/serial[Serial main page]. + +`val`: the value to print. Allowed data types: any data type. + +`format`: specifies the number base (for integral data types) or number of decimal places (for floating point types). -`format`: specifies the number base (for integral data types) or number of decimal places (for floating point types) [float] === Returns -`size_t`: `println()` returns the number of bytes written, though reading that number is optional +`println()` returns the number of bytes written, though reading that number is optional. Data type: `size_t`. + -- // OVERVIEW SECTION ENDS @@ -76,7 +78,13 @@ void loop() { // delay 10 milliseconds before the next reading: delay(10); +} ---- +[%hardbreaks] + +[float] +=== Notes and Warnings +For information on the asyncronicity of `Serial.println()`, see the Notes and Warnings section of the link:../write#howtouse[Serial.write() reference page]. -- // HOW TO USE SECTION ENDS diff --git a/Language/Functions/Communication/Serial/read.adoc b/Language/Functions/Communication/Serial/read.adoc index c9ae16af4..b721f2322 100644 --- a/Language/Functions/Communication/Serial/read.adoc +++ b/Language/Functions/Communication/Serial/read.adoc @@ -14,28 +14,25 @@ title: Serial.read() [float] === Description -Reads incoming serial data. read() inherits from the link:../../stream[Stream] utility class. +Reads incoming serial data. + +`Serial.read()` inherits from the link:../../stream[Stream] utility class. [%hardbreaks] [float] === Syntax -`Serial.read()` - -_Arduino Mega only:_ - -`Serial1.read()` + -`Serial2.read()` + -`Serial3.read()` +`_Serial_.read()` [float] === Parameters -Nothing +`_Serial_`: serial port object. See the list of available serial ports for each board on the link:https://www.arduino.cc/en/Reference/serial[Serial main page]. + [float] === Returns -The first byte of incoming serial data available (or -1 if no data is available) - `int`. +The first byte of incoming serial data available (or -1 if no data is available). Data type: `int`. -- // OVERVIEW SECTION ENDS @@ -54,23 +51,22 @@ The first byte of incoming serial data available (or -1 if no data is available) [source,arduino] ---- -int incomingByte = 0; // for incoming serial data +int incomingByte = 0; // for incoming serial data void setup() { - Serial.begin(9600); // opens serial port, sets data rate to 9600 bps + Serial.begin(9600); // opens serial port, sets data rate to 9600 bps } void loop() { - - // send data only when you receive data: - if (Serial.available() > 0) { - // read the incoming byte: - incomingByte = Serial.read(); - - // say what you got: - Serial.print("I received: "); - Serial.println(incomingByte, DEC); - } + // send data only when you receive data: + if (Serial.available() > 0) { + // read the incoming byte: + incomingByte = Serial.read(); + + // say what you got: + Serial.print("I received: "); + Serial.println(incomingByte, DEC); + } } ---- diff --git a/Language/Functions/Communication/Serial/readBytes.adoc b/Language/Functions/Communication/Serial/readBytes.adoc index dbd25f35e..eee28340b 100644 --- a/Language/Functions/Communication/Serial/readBytes.adoc +++ b/Language/Functions/Communication/Serial/readBytes.adoc @@ -24,18 +24,19 @@ title: Serial.readBytes() [float] === Syntax -`Serial.readBytes(buffer, length)` +`_Serial_.readBytes(buffer, length)` [float] === Parameters -`buffer`: the buffer to store the bytes in (`char[]` or `byte[]`) +`_Serial_`: serial port object. See the list of available serial ports for each board on the link:https://www.arduino.cc/en/Reference/serial[Serial main page]. + +`buffer`: the buffer to store the bytes in. Allowed data types: array of `char` or `byte`. + +`length`: the number of bytes to read. Allowed data types: `int`. -`length` : the number of bytes to read (`int`) [float] === Returns -The number of bytes placed in the buffer (`size_t`) +The number of bytes placed in the buffer. Data type: `size_t`. -- // OVERVIEW SECTION ENDS diff --git a/Language/Functions/Communication/Serial/readBytesUntil.adoc b/Language/Functions/Communication/Serial/readBytesUntil.adoc index b5eca10d9..50775c471 100644 --- a/Language/Functions/Communication/Serial/readBytesUntil.adoc +++ b/Language/Functions/Communication/Serial/readBytesUntil.adoc @@ -14,9 +14,9 @@ title: Serial.readBytesUntil() [float] === Description -Serial.readBytesUntil() reads characters from the serial buffer into an array. The function terminates if the terminator character is detected, the determined length has been read, or it times out (see link:../settimeout[Serial.setTimeout()]). The function returns the characters up to the last character before the supplied terminator. The terminator itself is not returned in the buffer. +Serial.readBytesUntil() reads characters from the serial buffer into an array. The function terminates (checks being done in this order) if the determined length has been read, if it times out (see link:../settimeout[Serial.setTimeout()]), or if the terminator character is detected (in which case the function returns the characters up to the last character before the supplied terminator). The terminator itself is not returned in the buffer. -`Serial.readBytesUntil()` returns the number of characters read into the buffer. A 0 means no valid data was found. +`Serial.readBytesUntil()` returns the number of characters read into the buffer. A 0 means that the `length` parameter \<= 0, a time out occurred before any other input, or a termination character was found before any other input. `Serial.readBytesUntil()` inherits from the link:../../stream[Stream] utility class. [%hardbreaks] @@ -24,25 +24,38 @@ Serial.readBytesUntil() reads characters from the serial buffer into an array. T [float] === Syntax -`Serial.readBytesUntil(character, buffer, length)` +`_Serial_.readBytesUntil(character, buffer, length)` [float] === Parameters -`character` : the character to search for (`char`) +`_Serial_`: serial port object. See the list of available serial ports for each board on the link:https://www.arduino.cc/en/Reference/serial[Serial main page]. + +`character`: the character to search for. Allowed data types: `char`. + +`buffer`: the buffer to store the bytes in. Allowed data types: array of `char` or `byte`. + +`length`: the number of bytes to read. Allowed data types: `int`. -`buffer`: the buffer to store the bytes in (`char[]` or `byte[]`) - -`length` : the number of bytes to read (`int`) [float] === Returns -`size_t` +Data type: `size_t`. -- // OVERVIEW SECTION ENDS +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Notes and Warnings +The terminator character is discarded from the serial buffer, unless the number of characters read and copied into the buffer equals `length`. +[%hardbreaks] + +-- +// HOW TO USE SECTION ENDS + + // SEE ALSO SECTION [#see_also] -- @@ -52,7 +65,7 @@ Serial.readBytesUntil() reads characters from the serial buffer into an array. T [role="language"] * #LANGUAGE# link:../../stream[Stream] -* #LANGUAGE# link:../../stream/streamreadbytesuntil[Stream.readByteUntil()] +* #LANGUAGE# link:../../stream/streamreadbytesuntil[Stream.readBytesUntil()] -- // SEE ALSO SECTION ENDS diff --git a/Language/Functions/Communication/Serial/readString.adoc b/Language/Functions/Communication/Serial/readString.adoc index acb736da4..496787c8e 100644 --- a/Language/Functions/Communication/Serial/readString.adoc +++ b/Language/Functions/Communication/Serial/readString.adoc @@ -14,30 +14,69 @@ title: Serial.readString() [float] === Description -`Serial.readString()` reads characters from the serial buffer into a string. The function terminates if it times out (see link:../settimeout[setTimeout()]). - -This function is part of the Stream class, and is called by any class that inherits from it (Wire, Serial, etc). See the link:../../stream[Stream class] main page for more information. +`Serial.readString()` reads characters from the serial buffer into a String. The function terminates if it times out (see link:../settimeout[setTimeout()]). +`Serial.readString()` inherits from the link:../../stream[Stream] utility class. [%hardbreaks] [float] === Syntax -`Serial.readString()` +`_Serial_.readString()` [float] === Parameters -Nothing +`_Serial_`: serial port object. See the list of available serial ports for each board on the link:https://www.arduino.cc/en/Reference/serial[Serial main page]. + [float] === Returns -A String read from the serial buffer +A `String` read from the serial buffer + -- // OVERVIEW SECTION ENDS +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code +Demonstrate Serial.readString() + +[source,arduino] +---- +void setup() { + Serial.begin(9600); +} + +void loop() { + Serial.println("Enter data:"); + while (Serial.available() == 0) {} //wait for data available + String teststr = Serial.readString(); //read until timeout + teststr.trim(); // remove any \r \n whitespace at the end of the String + if (teststr == "red") { + Serial.println("A primary color"); + } else { + Serial.println("Something else"); + } +} +---- +[%hardbreaks] + + +[float] +=== Notes and Warnings +The function does not terminate early if the data contains end of line characters. The returned `String` may contain carriage return and/or line feed characters if they were received. +[%hardbreaks] + +-- +// HOW TO USE SECTION ENDS + + // SEE ALSO SECTION [#see_also] -- @@ -46,7 +85,7 @@ A String read from the serial buffer === See also [role="language"] -* #LANGUAGE# link:../../serial[Serial] +* #LANGUAGE# link:https://www.arduino.cc/en/Reference/serial[Serial] * #LANGUAGE# link:../begin[begin()] * #LANGUAGE# link:../end[end()] * #LANGUAGE# link:../available[available()] @@ -60,4 +99,4 @@ A String read from the serial buffer * #LANGUAGE# link:../parsefloat[parseFloat()] -- -// SEE ALSO SECTION ENDS \ No newline at end of file +// SEE ALSO SECTION ENDS diff --git a/Language/Functions/Communication/Serial/readStringUntil.adoc b/Language/Functions/Communication/Serial/readStringUntil.adoc index fdbe1bc3c..54f24540f 100644 --- a/Language/Functions/Communication/Serial/readStringUntil.adoc +++ b/Language/Functions/Communication/Serial/readStringUntil.adoc @@ -14,30 +14,46 @@ title: Serial.readStringUntil() [float] === Description -`readStringUntil()` reads characters from the serial buffer into a string. The function terminates if it times out (see link:../settimeout[setTimeout()]). - -This function is part of the Stream class, and is called by any class that inherits from it (Wire, Serial, etc). See the link:../../stream[Stream class] main page for more information. +`readStringUntil()` reads characters from the serial buffer into a String. The function terminates if it times out (see link:../settimeout[setTimeout()]). +`Serial.readStringUntil()` inherits from the link:../../stream[Stream] utility class. [%hardbreaks] [float] === Syntax -`Serial.readStringUntil(terminator)` +`_Serial_.readStringUntil(terminator)` [float] === Parameters -`terminator` : the character to search for (`char`) +`_Serial_`: serial port object. See the list of available serial ports for each board on the link:https://www.arduino.cc/en/Reference/serial[Serial main page]. + +`terminator`: the character to search for. Allowed data types: `char`. + [float] === Returns -The entire String read from the serial buffer, until the terminator character is detected +The entire `String` read from the serial buffer, up to the terminator character. +If the terminator character can't be found, or if there is no data before the terminator character, it will return `NULL`. -- // OVERVIEW SECTION ENDS +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Notes and Warnings +The terminator character is discarded from the serial buffer. +If the terminator character can't be found, all read characters will be discarded. +[%hardbreaks] + +-- +// HOW TO USE SECTION ENDS + + // SEE ALSO SECTION [#see_also] -- @@ -46,7 +62,7 @@ The entire String read from the serial buffer, until the terminator character is === See also [role="language"] -* #LANGUAGE# link:../../serial[Serial] +* #LANGUAGE# link:https://www.arduino.cc/en/Reference/serial[Serial] * #LANGUAGE# link:../begin[begin()] * #LANGUAGE# link:../end[end()] * #LANGUAGE# link:../available[available()] @@ -60,4 +76,4 @@ The entire String read from the serial buffer, until the terminator character is * #LANGUAGE# link:../../stream/streamparsefloat[stream.parseFloat()] -- -// SEE ALSO SECTION ENDS \ No newline at end of file +// SEE ALSO SECTION ENDS diff --git a/Language/Functions/Communication/Serial/serialEvent.adoc b/Language/Functions/Communication/Serial/serialEvent.adoc index d45b3b6bc..80475fe00 100644 --- a/Language/Functions/Communication/Serial/serialEvent.adoc +++ b/Language/Functions/Communication/Serial/serialEvent.adoc @@ -1,5 +1,5 @@ --- -title: Serial.serialEvent() +title: serialEvent() --- @@ -14,9 +14,9 @@ title: Serial.serialEvent() [float] === Description -Called when data is available. Use `Serial.read()` to capture this data. +Called at the end of link:../../../../structure/sketch/loop[`loop()`] when data is available. Use `Serial.read()` to capture this data. -NB : Currently, `serialEvent()` is not compatible with the Esplora, Leonardo, or Micro +*Please note:* most modern boards do not support this method. See "Notes and Warnings" further below this article. [%hardbreaks] @@ -25,30 +25,34 @@ NB : Currently, `serialEvent()` is not compatible with the Esplora, Leonardo, or [source,arduino] ---- -void serialEvent(){ -//statements +void serialEvent() { + //statements } ---- -Arduino Mega only: + +The Mega 2560 R3 and Due boards have additional serial ports which can be accessed by adding the corresponding number at the end of the function. + [source,arduino] ---- -void serialEvent1(){ -//statements +void serialEvent1() { + //statements } -void serialEvent2(){ -//statements +void serialEvent2() { + //statements } -void serialEvent3(){ -//statements +void serialEvent3() { + //statements } ---- + [float] === Parameters `statements`: any valid statements + [float] === Returns Nothing @@ -57,6 +61,21 @@ Nothing // OVERVIEW SECTION ENDS +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Notes and Warnings +Please note that `serialEvent()` *does not work* on any modern Arduino boards. The only recognized boards to have support as of 2023/12/06 are the *UNO R3*, *Nano*, *Mega 2560 R3* and *Due*. + +Instead, you can use the link:../available[`available()`] method. Examples in this page demonstrates how to read serial data only when it is available, similarly to how `Serial.event()` is implemented. +[%hardbreaks] + +-- +// HOW TO USE SECTION ENDS + + // SEE ALSO SECTION [#see_also] -- @@ -65,7 +84,7 @@ Nothing === See also [role="example"] -* #EXAMPLE# http://arduino.cc/en/Tutorial/SerialEvent[SerialEvent Tutorial] +* #EXAMPLE# http://arduino.cc/en/Tutorial/SerialEvent[Serial Event^] [role="language"] * #LANGUAGE# link:../begin[begin()] @@ -79,4 +98,4 @@ Nothing * #LANGUAGE# link:../write[write()] -- -// SEE ALSO SECTION ENDS \ No newline at end of file +// SEE ALSO SECTION ENDS diff --git a/Language/Functions/Communication/Serial/setTimeout.adoc b/Language/Functions/Communication/Serial/setTimeout.adoc index 82aefb4ea..41d5f224c 100644 --- a/Language/Functions/Communication/Serial/setTimeout.adoc +++ b/Language/Functions/Communication/Serial/setTimeout.adoc @@ -14,7 +14,7 @@ title: Serial.setTimeout() [float] === Description -`Serial.setTimeout()` sets the maximum milliseconds to wait for serial data when using link:../readbytesuntil[serial.readBytesUntil()] or link:../readbytes[serial.readBytes()]. It defaults to 1000 milliseconds. +`Serial.setTimeout()` sets the maximum milliseconds to wait for serial data. It defaults to 1000 milliseconds. `Serial.setTimeout()` inherits from the link:../../stream[Stream] utility class. [%hardbreaks] @@ -22,11 +22,14 @@ title: Serial.setTimeout() [float] === Syntax -`Serial.setTimeout(time)` +`_Serial_.setTimeout(time)` + [float] === Parameters -`time` : timeout duration in milliseconds (`long`). +`_Serial_`: serial port object. See the list of available serial ports for each board on the link:https://www.arduino.cc/en/Reference/serial[Serial main page]. + +`time`: timeout duration in milliseconds. Allowed data types: `long`. + [float] === Returns @@ -36,6 +39,29 @@ Nothing // OVERVIEW SECTION ENDS +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Notes and Warnings +Serial functions that use the timeout value set via `_Serial_.setTimeout()`: + +* `_Serial_.find()` +* `_Serial_.findUntil()` +* `_Serial_.parseInt()` +* `_Serial_.parseFloat()` +* `_Serial_.readBytes()` +* `_Serial_.readBytesUntil()` +* `_Serial_.readString()` +* `_Serial_.readStringUntil()` + +[%hardbreaks] + +-- +// HOW TO USE SECTION ENDS + + // SEE ALSO SECTION [#see_also] -- diff --git a/Language/Functions/Communication/Serial/write.adoc b/Language/Functions/Communication/Serial/write.adoc index 79c7427d0..cfcd0b944 100644 --- a/Language/Functions/Communication/Serial/write.adoc +++ b/Language/Functions/Communication/Serial/write.adoc @@ -2,9 +2,6 @@ title: Serial.write() --- - - - = write() @@ -20,28 +17,23 @@ Writes binary data to the serial port. This data is sent as a byte or series of [float] === Syntax -`Serial.write(val)` + -`Serial.write(str)` + -`Serial.write(buf, len)` - -_Arduino Mega also supports:_ - -`Serial1`, `Serial2`, `Serial3` (in place of `Serial`) +`_Serial_.write(val)` + +`_Serial_.write(str)` + +`_Serial_.write(buf, len)` [float] === Parameters -`val`: a value to send as a single byte +`_Serial_`: serial port object. See the list of available serial ports for each board on the link:https://www.arduino.cc/en/Reference/serial[Serial main page]. + +`val`: a value to send as a single byte. + +`str`: a string to send as a series of bytes. + +`buf`: an array to send as a series of bytes. + +`len`: the number of bytes to be sent from the array. -`str`: a string to send as a series of bytes - -`buf`: an array to send as a series of bytes [float] === Returns -`size_t` - -`write()` will return the number of bytes written, though reading that number is optional +`write()` will return the number of bytes written, though reading that number is optional. Data type: `size_t`. -- // OVERVIEW SECTION ENDS @@ -59,16 +51,21 @@ _Arduino Mega also supports:_ [source,arduino] ---- -void setup(){ +void setup() { Serial.begin(9600); } -void loop(){ +void loop() { Serial.write(45); // send a byte with the value 45 - int bytesSent = Serial.write(“hello”); //send the string “hello” and return the length of the string. + int bytesSent = Serial.write("hello"); //send the string "hello" and return the length of the string. } ---- +[%hardbreaks] + +[float] +=== Notes and Warnings +Serial transmission is asynchronous. If there is enough empty space in the transmit buffer, `Serial.write()` will return before any characters are transmitted over serial. If the transmit buffer is full then `Serial.write()` will block until there is enough space in the buffer. To avoid blocking calls to `Serial.write()`, you can first check the amount of free space in the transmit buffer using link:../availableforwrite[availableForWrite()]. -- // HOW TO USE SECTION ENDS diff --git a/Language/Functions/Communication/Stream/streamAvailable.adoc b/Language/Functions/Communication/Stream/streamAvailable.adoc index 371fb683d..867180620 100644 --- a/Language/Functions/Communication/Stream/streamAvailable.adoc +++ b/Language/Functions/Communication/Stream/streamAvailable.adoc @@ -15,7 +15,7 @@ title: Stream.available() === Description `available()` gets the number of bytes available in the stream. This is only for bytes that have already arrived. -This function is part of the Stream class, and is called by any class that inherits from it (Wire, Serial, etc). See the link:../../stream[Stream class] main page for more information. +This function is part of the Stream class, and can be called by any class that inherits from it (Wire, Serial, etc). See the link:../../stream[Stream class] main page for more information. [%hardbreaks] @@ -26,11 +26,12 @@ This function is part of the Stream class, and is called by any class that inher [float] === Parameters -`stream` : an instance of a class that inherits from Stream. +`stream`: an instance of a class that inherits from Stream. + [float] === Returns -`int` : the number of bytes available to read +The number of bytes available to read. Data type: `int`. -- -// OVERVIEW SECTION ENDS \ No newline at end of file +// OVERVIEW SECTION ENDS diff --git a/Language/Functions/Communication/Stream/streamFind.adoc b/Language/Functions/Communication/Stream/streamFind.adoc index c8f2de836..99c41c2b5 100644 --- a/Language/Functions/Communication/Stream/streamFind.adoc +++ b/Language/Functions/Communication/Stream/streamFind.adoc @@ -14,26 +14,28 @@ title: Stream.find() [float] === Description -`find()` reads data from the stream until the target string of given length is found The function returns true if target string is found, false if timed out. +`find()` reads data from the stream until the target is found. The function returns true if target is found, false if timed out (see link:../streamsettimeout[Stream.setTimeout()]). -This function is part of the Stream class, and is called by any class that inherits from it (Wire, Serial, etc). See the link:../../stream[stream class] main page for more information. +This function is part of the Stream class, and can be called by any class that inherits from it (Wire, Serial, etc). See the link:../../stream[stream class] main page for more information. [%hardbreaks] [float] === Syntax -`stream.find(target)` +`stream.find(target)` + +`stream.find(target, length)` [float] === Parameters -`stream` : an instance of a class that inherits from Stream. +`stream`: an instance of a class that inherits from Stream. + +`target`: the string to search for. Allowed data types: `char`. + +`length`: length of the target. Allowed data types: `size_t`. -`target` : the string to search for (char) [float] === Returns -`bool` +Data type: `bool`. -- -// OVERVIEW SECTION ENDS \ No newline at end of file +// OVERVIEW SECTION ENDS diff --git a/Language/Functions/Communication/Stream/streamFindUntil.adoc b/Language/Functions/Communication/Stream/streamFindUntil.adoc index 9447096df..a16f61f78 100644 --- a/Language/Functions/Communication/Stream/streamFindUntil.adoc +++ b/Language/Functions/Communication/Stream/streamFindUntil.adoc @@ -14,11 +14,11 @@ title: Stream.findUntil() [float] === Description -`findUntil()` reads data from the stream until the target string of given length or terminator string is found. +`findUntil()` reads data from the stream until the target string of given length or terminator string is found, or it times out (see link:../streamsettimeout[Stream.setTimeout()]). -The function returns true if target string is found, false if timed out +The function returns `true` if target string is found, `false` if timed out. -This function is part of the Stream class, and is called by any class that inherits from it (Wire, Serial, etc). See the #LANGUAGE# link:../../stream[Stream class] main page for more information. +This function is part of the Stream class, and can be called by any class that inherits from it (Wire, Serial, etc). See the link:../../stream[Stream class] main page for more information. [%hardbreaks] @@ -29,11 +29,14 @@ This function is part of the Stream class, and is called by any class that inher [float] === Parameters -`stream.findUntil(target, terminal)` +`stream`: an instance of a class that inherits from Stream. + +`target`: the string to search for. Allowed data types: `char`. + +`terminal`: the terminal string in the search. Allowed data types: `char`. + [float] === Returns -`bool` +Data type: `bool`. -- -// OVERVIEW SECTION ENDS \ No newline at end of file +// OVERVIEW SECTION ENDS diff --git a/Language/Functions/Communication/Stream/streamFlush.adoc b/Language/Functions/Communication/Stream/streamFlush.adoc index 498fef16d..c37052a46 100644 --- a/Language/Functions/Communication/Stream/streamFlush.adoc +++ b/Language/Functions/Communication/Stream/streamFlush.adoc @@ -16,7 +16,7 @@ title: Stream.flush() === Description `flush()` clears the buffer once all outgoing characters have been sent. -This function is part of the Stream class, and is called by any class that inherits from it (Wire, Serial, etc). See the link:../../stream[stream class] main page for more information. +This function is part of the Stream class, and can be called by any class that inherits from it (Wire, Serial, etc). See the link:../../stream[stream class] main page for more information. [%hardbreaks] @@ -27,11 +27,12 @@ This function is part of the Stream class, and is called by any class that inher [float] === Parameters -`stream` : an instance of a class that inherits from Stream. +`stream`: an instance of a class that inherits from Stream. + [float] === Returns Nothing -- -// OVERVIEW SECTION ENDS \ No newline at end of file +// OVERVIEW SECTION ENDS diff --git a/Language/Functions/Communication/Stream/streamGetTimeout.adoc b/Language/Functions/Communication/Stream/streamGetTimeout.adoc new file mode 100644 index 000000000..0323f6d53 --- /dev/null +++ b/Language/Functions/Communication/Stream/streamGetTimeout.adoc @@ -0,0 +1,44 @@ +--- +title: Stream.getTimeout() +--- + + + + += getTimeout() + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +`getTimeout()` returns the timeout value set by `setTimeout()`. This function is part of the Stream class, and can be called by any class that inherits from it (Wire, Serial, etc). See the link:../../stream[Stream class] main page for more information. +[%hardbreaks] + + +[float] +=== Syntax +`stream.getTimeout()` + + +[float] +=== Parameters +None + + +[float] +=== Returns +The timeout value set by `stream.setTimeout()`. Data type: `unsigned long`. + +-- +// OVERVIEW SECTION ENDS + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +-- +// HOW TO USE SECTION ENDS diff --git a/Language/Functions/Communication/Stream/streamParseFloat.adoc b/Language/Functions/Communication/Stream/streamParseFloat.adoc index 40324ce62..71fcd977a 100644 --- a/Language/Functions/Communication/Stream/streamParseFloat.adoc +++ b/Language/Functions/Communication/Stream/streamParseFloat.adoc @@ -14,26 +14,34 @@ title: Stream.parseFloat() [float] === Description -`parseFloat()` returns the first valid floating point number from the current position. Initial characters that are not digits (or the minus sign) are skipped. `parseFloat()` is terminated by the first character that is not a floating point number. +`parseFloat()` returns the first valid floating point number from the current position. `parseFloat()` is terminated by the first character that is not a floating point number. The function terminates if it times out (see link:../streamsettimeout[Stream.setTimeout()]). -This function is part of the Stream class, and is called by any class that inherits from it (Wire, Serial, etc). See the link:../../stream[Stream class] main page for more informatio +This function is part of the Stream class, and can be called by any class that inherits from it (Wire, Serial, etc). See the link:../../stream[Stream class] main page for more information. [%hardbreaks] [float] === Syntax -`stream.parseFloat(list)` +`stream.parseFloat()` + +`stream.parseFloat(lookahead)` + +`stream.parseFloat(lookahead, ignore)` [float] === Parameters -`stream` : an instance of a class that inherits from Stream. +`stream` : an instance of a class that inherits from Stream. + +`lookahead`: the mode used to look ahead in the stream for a floating point number. Allowed data types: `LookaheadMode`. Allowed `lookahead` values: + +* `SKIP_ALL`: all characters other than a minus sign, decimal point, or digits are ignored when scanning the stream for a floating point number. This is the default mode. +* `SKIP_NONE`: Nothing is skipped, and the stream is not touched unless the first waiting character is valid. +* `SKIP_WHITESPACE`: Only tabs, spaces, line feeds, and carriage returns are skipped. + +`ignore`: used to skip the indicated char in the search. Used for example to skip thousands divider. Allowed data types: `char` -`list` : the stream to check for floats (`char`) [float] === Returns -`float` +Data type: `float`. -- -// OVERVIEW SECTION ENDS \ No newline at end of file +// OVERVIEW SECTION ENDS diff --git a/Language/Functions/Communication/Stream/streamParseInt.adoc b/Language/Functions/Communication/Stream/streamParseInt.adoc index ac284be6f..244148496 100644 --- a/Language/Functions/Communication/Stream/streamParseInt.adoc +++ b/Language/Functions/Communication/Stream/streamParseInt.adoc @@ -14,35 +14,39 @@ title: Stream.parseInt() [float] === Description -`parseInt()` returns the first valid (long) integer number from the current position. Initial characters that are not integers (or the minus sign) are skipped. +`parseInt()` returns the first valid (long) integer number from the current position. In particular: -* Initial characters that are not digits or a minus sign, are skipped; + * Parsing stops when no characters have been read for a configurable time-out value, or a non-digit is read; + * If no valid digits were read when the time-out (see link:../streamsettimeout[Stream.setTimeout()]) occurs, 0 is returned; -This function is part of the Stream class, and is called by any class that inherits from it (Wire, Serial, etc). See the link:../../stream[Stream class] main page for more information. +This function is part of the Stream class, and can be called by any class that inherits from it (Wire, Serial, etc). See the link:../../stream[Stream class] main page for more information. [%hardbreaks] [float] === Syntax -`stream.parseInt(list)` +`stream.parseInt()` + +`stream.parseInt(lookahead)` + +`stream.parseInt(lookahead, ignore)` -`stream.parseInt(''list', char skipchar')` [float] === Parameters -`stream` : an instance of a class that inherits from Stream. +`stream` : an instance of a class that inherits from Stream. + +`lookahead`: the mode used to look ahead in the stream for an integer. Allowed data types: `LookaheadMode`. Allowed `lookahead` values: -`list` : the stream to check for ints (`char`) +* `SKIP_ALL`: all characters other than digits or a minus sign are ignored when scanning the stream for an integer. This is the default mode. +* `SKIP_NONE`: Nothing is skipped, and the stream is not touched unless the first waiting character is valid. +* `SKIP_WHITESPACE`: Only tabs, spaces, line feeds, and carriage returns are skipped. + +`ignore`: used to skip the indicated char in the search. Used for example to skip thousands divider. Allowed data types: `char` -`skipChar`: used to skip the indicated char in the search. Used for example to skip thousands divider. [float] === Returns -`long` +Data type: `long`. -- -// OVERVIEW SECTION ENDS \ No newline at end of file +// OVERVIEW SECTION ENDS diff --git a/Language/Functions/Communication/Stream/streamPeek.adoc b/Language/Functions/Communication/Stream/streamPeek.adoc index cc1e3f6dd..1ed33a1bd 100644 --- a/Language/Functions/Communication/Stream/streamPeek.adoc +++ b/Language/Functions/Communication/Stream/streamPeek.adoc @@ -16,7 +16,7 @@ title: Stream.peek() === Description Read a byte from the file without advancing to the next one. That is, successive calls to `peek()` will return the same value, as will the next call to `read()`. -This function is part of the Stream class, and is called by any class that inherits from it (Wire, Serial, etc). See the link:../../stream[Stream class] main page for more information. +This function is part of the Stream class, and can be called by any class that inherits from it (Wire, Serial, etc). See the link:../../stream[Stream class] main page for more information. [%hardbreaks] @@ -27,7 +27,8 @@ This function is part of the Stream class, and is called by any class that inher [float] === Parameters -`stream` : an instance of a class that inherits from Stream. +`stream`: an instance of a class that inherits from Stream. + [float] === Returns @@ -43,9 +44,5 @@ The next byte (or character), or -1 if none is available. [#howtouse] -- -[float] -=== Example Code -// Describe what the example code is all about and add relevant code ►►►►► THIS SECTION IS MANDATORY ◄◄◄◄◄ - -- -// HOW TO USE SECTION ENDS \ No newline at end of file +// HOW TO USE SECTION ENDS diff --git a/Language/Functions/Communication/Stream/streamRead.adoc b/Language/Functions/Communication/Stream/streamRead.adoc index c08e24fc7..6a932782b 100644 --- a/Language/Functions/Communication/Stream/streamRead.adoc +++ b/Language/Functions/Communication/Stream/streamRead.adoc @@ -16,7 +16,7 @@ title: Stream.read() === Description `read()` reads characters from an incoming stream to the buffer. -This function is part of the Stream class, and is called by any class that inherits from it (Wire, Serial, etc). See the link:../../stream[stream class] main page for more information. +This function is part of the Stream class, and can be called by any class that inherits from it (Wire, Serial, etc). See the link:../../stream[stream class] main page for more information. [%hardbreaks] @@ -27,11 +27,12 @@ This function is part of the Stream class, and is called by any class that inher [float] === Parameters -`stream` : an instance of a class that inherits from Stream. +`stream`: an instance of a class that inherits from Stream. + [float] === Returns The first byte of incoming data available (or -1 if no data is available). -- -// OVERVIEW SECTION ENDS \ No newline at end of file +// OVERVIEW SECTION ENDS diff --git a/Language/Functions/Communication/Stream/streamReadBytes.adoc b/Language/Functions/Communication/Stream/streamReadBytes.adoc index 84c8cc756..fd24d1a85 100644 --- a/Language/Functions/Communication/Stream/streamReadBytes.adoc +++ b/Language/Functions/Communication/Stream/streamReadBytes.adoc @@ -18,7 +18,7 @@ title: Stream.readBytes() `readBytes()` returns the number of bytes placed in the buffer. A 0 means no valid data was found. -This function is part of the Stream class, and is called by any class that inherits from it (Wire, Serial, etc). See the link:../../stream[Stream class] main page for more information. +This function is part of the Stream class, and can be called by any class that inherits from it (Wire, Serial, etc). See the link:../../stream[Stream class] main page for more information. [%hardbreaks] @@ -29,15 +29,14 @@ This function is part of the Stream class, and is called by any class that inher [float] === Parameters -`stream` : an instance of a class that inherits from Stream. +`stream`: an instance of a class that inherits from Stream. + +`buffer`: the buffer to store the bytes in. Allowed data types: array of `char` or `byte`. + +`length`: the number of bytes to read. Allowed data types: `int`. -`buffer` : the buffer to store the bytes in (`char[]` or `byte[]`) - -`length` : the number of bytes to `read(int)` [float] === Returns -The number of bytes placed in the buffer (`size_t`) +The number of bytes placed in the buffer. Data type: `size_t`. -- // OVERVIEW SECTION ENDS diff --git a/Language/Functions/Communication/Stream/streamReadBytesUntil.adoc b/Language/Functions/Communication/Stream/streamReadBytesUntil.adoc index 5c8b24148..e417058be 100644 --- a/Language/Functions/Communication/Stream/streamReadBytesUntil.adoc +++ b/Language/Functions/Communication/Stream/streamReadBytesUntil.adoc @@ -14,11 +14,11 @@ title: Stream.readBytesUntil() [float] === Description -`readBytesUntil()` reads characters from a stream into a buffer. The function terminates if the terminator character is detected, the determined length has been read, or it times out (see link:../streamsettimeout[setTimeout()]). +`readBytesUntil()` reads characters from a stream into a buffer. The function terminates if the terminator character is detected, the determined length has been read, or it times out (see link:../streamsettimeout[setTimeout()]). The function returns the characters up to the last character before the supplied terminator. The terminator itself is not returned in the buffer. -`readBytesUntil()` returns the number of bytes placed in the buffer. A 0 means no valid data was found. +`readBytesUntil()` returns the number of bytes placed in the buffer. A 0 means the terminator character can't be found or there is no data before it. -This function is part of the Stream class, and is called by any class that inherits from it (Wire, Serial, etc). See the link:../../stream[Stream class] main page for more information. +This function is part of the Stream class, and can be called by any class that inherits from it (Wire, Serial, etc). See the link:../../stream[Stream class] main page for more information. [%hardbreaks] @@ -29,17 +29,28 @@ This function is part of the Stream class, and is called by any class that inher [float] === Parameters -`stream` : an instance of a class that inherits from Stream. +`stream`: an instance of a class that inherits from Stream. + +`character`: the character to search for. Allowed data types: `char`. + +`buffer`: the buffer to store the bytes in. Allowed data types: array of `char` or `byte`. + +`length`: the number of bytes to read. Allowed data types: `int`. -`character` : the character to search for (`char`) - -`buffer`: the buffer to store the bytes in (`char[]` or `byte[]`) - -`length : the number of bytes to `read(int)` [float] === Returns -The number of bytes placed in the buffer. +The number of bytes (excluding the terminator character) placed in the buffer if the terminator character has been found. -- // OVERVIEW SECTION ENDS + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Notes and Warnings +The terminator character is discarded from the stream. +[%hardbreaks] + +-- +// HOW TO USE SECTION ENDS diff --git a/Language/Functions/Communication/Stream/streamReadString.adoc b/Language/Functions/Communication/Stream/streamReadString.adoc index 71ca98875..b941ca660 100644 --- a/Language/Functions/Communication/Stream/streamReadString.adoc +++ b/Language/Functions/Communication/Stream/streamReadString.adoc @@ -16,7 +16,7 @@ title: Stream.readString() === Description `readString()` reads characters from a stream into a String. The function terminates if it times out (see link:../streamsettimeout[setTimeout()]). -This function is part of the Stream class, and is called by any class that inherits from it (Wire, Serial, etc). See the link:../../stream[Stream class] main page for more information. +This function is part of the Stream class, and can be called by any class that inherits from it (Wire, Serial, etc). See the link:../../stream[Stream class] main page for more information. [%hardbreaks] @@ -27,7 +27,8 @@ This function is part of the Stream class, and is called by any class that inher [float] === Parameters -Nothing +`stream`: an instance of a class that inherits from Stream. + [float] === Returns diff --git a/Language/Functions/Communication/Stream/streamReadStringUntil.adoc b/Language/Functions/Communication/Stream/streamReadStringUntil.adoc index 1a0832121..fea1400ab 100644 --- a/Language/Functions/Communication/Stream/streamReadStringUntil.adoc +++ b/Language/Functions/Communication/Stream/streamReadStringUntil.adoc @@ -16,22 +16,39 @@ title: Stream.readStringUntil() === Description `readStringUntil()` reads characters from a stream into a String. The function terminates if the terminator character is detected or it times out (see link:../streamsettimeout[setTimeout()]). -This function is part of the Stream class, and is called by any class that inherits from it (Wire, Serial, etc). See the link:../../stream[Stream class] main page for more information. +This function is part of the Stream class, and can be called by any class that inherits from it (Wire, Serial, etc). See the link:../../stream[Stream class] main page for more information. [%hardbreaks] [float] === Syntax -`stream.readString(terminator)` +`stream.readStringUntil(terminator)` [float] === Parameters -`terminator` : the character to search for (`char`) +`stream`: an instance of a class that inherits from Stream. + +`terminator`: the character to search for. Allowed data types: `char`. + [float] === Returns -The entire String read from a stream, until the terminator character is detected. +The entire String read from a stream, up to the terminator character. +If the terminator character can't be found, or if there is no data before the terminator character, it will return `NULL`. -- // OVERVIEW SECTION ENDS + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Notes and Warnings +The terminator character is discarded from the stream. +If the terminator character can't be found, all read characters will be discarded. +[%hardbreaks] + +-- +// HOW TO USE SECTION ENDS diff --git a/Language/Functions/Communication/Stream/streamSetTimeout.adoc b/Language/Functions/Communication/Stream/streamSetTimeout.adoc index 39d623506..556a6494f 100644 --- a/Language/Functions/Communication/Stream/streamSetTimeout.adoc +++ b/Language/Functions/Communication/Stream/streamSetTimeout.adoc @@ -14,7 +14,7 @@ title: Stream.setTimeout() [float] === Description -`setTimeout()` sets the maximum milliseconds to wait for stream data, it defaults to 1000 milliseconds. This function is part of the Stream class, and is called by any class that inherits from it (Wire, Serial, etc). See the #LANGUAGE# link:../../stream[Stream class] main page for more information. +`setTimeout()` sets the maximum milliseconds to wait for stream data, it defaults to 1000 milliseconds. This function is part of the Stream class, and can be called by any class that inherits from it (Wire, Serial, etc). See the link:../../stream[Stream class] main page for more information. [%hardbreaks] @@ -25,12 +25,36 @@ title: Stream.setTimeout() [float] === Parameters -`stream` : an instance of a class that inherits from Stream. -`time` : timeout duration in milliseconds (`long`). +`stream`: an instance of a class that inherits from Stream. + +`time`: timeout duration in milliseconds. Allowed data types: `long`. + [float] === Returns Nothing -- -// OVERVIEW SECTION ENDS \ No newline at end of file +// OVERVIEW SECTION ENDS + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Notes and Warnings +Stream functions that use the timeout value set via `setTimeout()`: + +* `find()` +* `findUntil()` +* `parseInt()` +* `parseFloat()` +* `readBytes()` +* `readBytesUntil()` +* `readString()` +* `readStringUntil()` + +[%hardbreaks] + +-- +// HOW TO USE SECTION ENDS diff --git a/Language/Functions/Communication/Wire.adoc b/Language/Functions/Communication/Wire.adoc new file mode 100644 index 000000000..50ee777b7 --- /dev/null +++ b/Language/Functions/Communication/Wire.adoc @@ -0,0 +1,78 @@ +--- +title: Wire +categories: [ "Functions" ] +subCategories: [ "Communication" ] +--- + + += Wire + + +//OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description + + +This library allows you to communicate with I2C devices, a feature that is present on all Arduino boards. I2C is a very common protocol, primarily used for reading/sending data to/from external I2C components. To learn more, visit link:https://docs.arduino.cc/learn/communication/wire[this article for Arduino & I2C]. + +Due to the hardware design and various architectural differences, the I2C pins are located in different places. The pin map just below highlights the default pins, as well as additional ports available on certain boards. + + +|================================================================================================================================================ +| Board | I2C Default | I2C1 | I2C2 | Notes +| UNO R3, UNO R3 SMD, UNO Mini Ltd | A4(SDA), A5(SCL) | | | I2C also available on the SDA / SCL pins (digital header). +| UNO R4 Minima, UNO R4 WiFi | A4(SDA), A5(SCL) | Qwiic: D27(SDA), D26(SCL) | | I2C also available on the SDA / SCL pins (digital header). +| UNO WiFi Rev2, Zero | 20(SDA), 21(SCL) | | | +| Leonardo, Micro, Yùn Rev2 | D2(SDA), D3(SCL) | | | +| Nano boards | A4(SDA), A5(SCL) | | | +| MKR boards | D11(SDA), D12(SCL) | | | +| GIGA R1 WiFi | 20(SDA), 21(SCL) | D102(SDA1), D101 (SCL1) | D9(SDA2), D8 (SCL2) | Use `Wire1.begin()` for I2C1, and `Wire2.begin()` for I2C2. +| Due | 20(SDA), 21(SCL) | D70(SDA1), D71(SCL1) | | Use `Wire1.begin()` for I2C1 +| Mega 2560 Rev3 | D20(SDA), D21(SCL) | | | +|================================================================================================================================================ + + +This library inherits from the Stream functions, making it consistent with other read/write libraries. Because of this, `send()` and `receive()` have been replaced with `read()` and `write()`. + +Recent versions of the Wire library can use timeouts to prevent a lockup in the face of certain problems on the bus, but this is not enabled by default (yet) in current versions. It is recommended to always enable these timeouts when using the Wire library. See the Wire.setWireTimeout function for more details. + +*Note:* There are both 7 and 8-bit versions of I2C addresses. 7 bits identify the device, and the eighth bit determines if it's being written to or read from. The Wire library uses 7 bit addresses throughout. If you have a datasheet or sample code that uses 8-bit address, you'll want to drop the low bit (i.e. shift the value one bit to the right), yielding an address between 0 and 127. However the addresses from 0 to 7 are not used because are reserved so the first address that can be used is 8. Please note that a pull-up resistor is needed when connecting SDA/SCL pins. Please refer to the examples for more information. MEGA 2560 board has pull-up resistors on pins 20 and 21 onboard. + +*The Wire library implementation uses a 32 byte buffer, therefore any communication should be within this limit. Exceeding bytes in a single transmission will just be dropped.* + +To use this library: + +`#include ` + +-- +// OVERVIEW SECTION ENDS + +//FUNCTION SECTION STARTS +[#functions] +-- + +''' +[float] +=== Functions +link:../wire/begin[begin()] + +link:../wire/end[end()] + +link:../wire/requestfrom[requestFrom()] + +link:../wire/begintransmission[beginTransmission()] + +link:../wire/endtransmission[endTransmission()] + +link:../wire/write[write()] + +link:../wire/available[available()] + +link:../wire/read[read()] + +link:../wire/setclock[setClock()] + +link:../wire/onreceive[onReceive()] + +link:../wire/onrequest[onRequest()] + +link:../wire/setwiretimeout[setWireTimeout()] + +link:../wire/clearwiretimeoutflag[clearWireTimeoutFlag()] + +link:../wire/getwiretimeoutflag[getWireTimeoutFlag()] + +''' + +-- +// FUNCTION SECTION ENDS diff --git a/Language/Functions/Communication/Wire/available.adoc b/Language/Functions/Communication/Wire/available.adoc new file mode 100644 index 000000000..db375e9ee --- /dev/null +++ b/Language/Functions/Communication/Wire/available.adoc @@ -0,0 +1,30 @@ +--- +title: available() +--- + += available + +//OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +This function returns the number of bytes available for retrieval with `read()`. This function should be called on a controller device after a call to `requestFrom()` or on a peripheral inside the `onReceive()` handler. `available()` inherits from the Stream utility class. + +[float] +=== Syntax +`Wire.available()` + +[float] +=== Parameters + +None. + +[float] +=== Returns + +The number of bytes available for reading. + +-- +//OVERVIEW SECTION STARTS \ No newline at end of file diff --git a/Language/Functions/Communication/Wire/begin.adoc b/Language/Functions/Communication/Wire/begin.adoc new file mode 100644 index 000000000..cbd0dea14 --- /dev/null +++ b/Language/Functions/Communication/Wire/begin.adoc @@ -0,0 +1,31 @@ +--- +title: begin() +--- += begin + +//OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description + +This function initializes the Wire library and join the I2C bus as a controller or a peripheral. This function should normally be called only once. + +[float] +=== Syntax + +`Wire.begin()` + +`Wire.begin(address)` + +[float] +=== Parameters +* _address_: the 7-bit slave address (optional); if not specified, join the bus as a controller device. + +[float] +=== Returns +None. +-- + +//OVERVIEW SECTION ENDS \ No newline at end of file diff --git a/Language/Functions/Communication/Wire/beginTransmission.adoc b/Language/Functions/Communication/Wire/beginTransmission.adoc new file mode 100644 index 000000000..ffc686af5 --- /dev/null +++ b/Language/Functions/Communication/Wire/beginTransmission.adoc @@ -0,0 +1,28 @@ +--- +title: beginTransmission() +--- + += beginTransmission + +//OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +This function begins a transmission to the I2C peripheral device with the given address. Subsequently, queue bytes for transmission with the `write()` function and transmit them by calling `endTransmission()`. + +[float] +=== Syntax + +`Wire.beginTransmission(address)` + +[float] +=== Parameters +* _address_: the 7-bit address of the device to transmit to. + +[float] +=== Returns +None. +-- +//OVERVIEW SECTION ENDS diff --git a/Language/Functions/Communication/Wire/clearWireTimeoutFlag.adoc b/Language/Functions/Communication/Wire/clearWireTimeoutFlag.adoc new file mode 100644 index 000000000..66bb41466 --- /dev/null +++ b/Language/Functions/Communication/Wire/clearWireTimeoutFlag.adoc @@ -0,0 +1,37 @@ +--- +title: clearWireTimeoutFlag() +--- += clearWireTimeoutFlag + +//OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description + +Clears the timeout flag. + +Timeouts might not be enabled by default. See the documentation for `Wire.setWireTimeout()` for more information on how to configure timeouts and how they work. + + +[float] +=== Syntax + +`Wire.clearTimeout()` + +[float] +=== Parameters +None. + +[float] +=== Returns +None. + +[float] +=== Portability Notes +This function was not available in the original version of the Wire library and might still not be available on all platforms. Code that needs to be portable across platforms and versions can use the `WIRE_HAS_TIMEOUT` macro, which is only defined when `Wire.setWireTimeout()`, `Wire.getWireTimeoutFlag()` and `Wire.clearWireTimeout()` are all available. + +-- + +//OVERVIEW SECTION ENDS \ No newline at end of file diff --git a/Language/Functions/Communication/Wire/end.adoc b/Language/Functions/Communication/Wire/end.adoc new file mode 100644 index 000000000..74871fba4 --- /dev/null +++ b/Language/Functions/Communication/Wire/end.adoc @@ -0,0 +1,31 @@ +--- +title: end() +--- += end + +//OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description + +Disable the Wire library, reversing the effect of `Wire.begin()`. To use the Wire library again after this, call `Wire.begin()` again. + +*Note:* This function was not available in the original version of the Wire library and might still not be available on all platforms. Code that needs to be portable across platforms and versions can use the `WIRE_HAS_END` macro, which is only defined when `Wire.end()` is available. + +[float] +=== Syntax + +`Wire.end()` + +[float] +=== Parameters +None. + +[float] +=== Returns +None. +-- + +//OVERVIEW SECTION ENDS \ No newline at end of file diff --git a/Language/Functions/Communication/Wire/endTransmission.adoc b/Language/Functions/Communication/Wire/endTransmission.adoc new file mode 100644 index 000000000..5687ed70a --- /dev/null +++ b/Language/Functions/Communication/Wire/endTransmission.adoc @@ -0,0 +1,34 @@ +--- +title: endTransmission() +--- + += endTransmission + +//OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +This function ends a transmission to a peripheral device that was begun by `beginTransmission()` and transmits the bytes that were queued by `write()`. The `endTransmission()` method accepts a boolean argument changing its behavior for compatibility with certain I2C devices. If true, `endTransmission()` sends a stop message after transmission, releasing the I2C bus. If false, `endTransmission()` sends a restart message after transmission. The bus will not be released, which prevents another controller device from transmitting between messages. This allows one controller device to send multiple transmissions while in control. The default value is true. + +[float] +=== Syntax +`Wire.endTransmission()` +`Wire.endTransmission(stop)` + +[float] +=== Parameters + +* _stop_: true or false. True will send a stop message, releasing the bus after transmission. False will send a restart, keeping the connection active. +[float] +=== Returns + +* _0_: success. +* _1_: data too long to fit in transmit buffer. +* _2_: received NACK on transmit of address. +* _3_: received NACK on transmit of data. +* _4_: other error. +* _5_: timeout +-- +//OVERVIEW SECTION ENDS diff --git a/Language/Functions/Communication/Wire/getWireTimeoutFlag.adoc b/Language/Functions/Communication/Wire/getWireTimeoutFlag.adoc new file mode 100644 index 000000000..c50449a63 --- /dev/null +++ b/Language/Functions/Communication/Wire/getWireTimeoutFlag.adoc @@ -0,0 +1,37 @@ +--- +title: getWireTimeoutFlag() +--- += getWireTimeoutFlag + +//OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description + +Checks whether a timeout has occurred since the last time the flag was cleared. + +This flag is set is set whenever a timeout occurs and cleared when `Wire.clearWireTimeoutFlag()` is called, or when the timeout is changed using `Wire.setWireTimeout()`. + + +[float] +=== Syntax + +`Wire.getWireTimeoutFlag()` + +[float] +=== Parameters +None. + +[float] +=== Returns +* bool: The current value of the flag + +[float] +=== Portability Notes +This function was not available in the original version of the Wire library and might still not be available on all platforms. Code that needs to be portable across platforms and versions can use the `WIRE_HAS_TIMEOUT` macro, which is only defined when `Wire.setWireTimeout()`, `Wire.getWireTimeoutFlag()` and `Wire.clearWireTimeout()` are all available. + +-- + +//OVERVIEW SECTION ENDS diff --git a/Language/Functions/Communication/Wire/onReceive.adoc b/Language/Functions/Communication/Wire/onReceive.adoc new file mode 100644 index 000000000..2ca8d60dd --- /dev/null +++ b/Language/Functions/Communication/Wire/onReceive.adoc @@ -0,0 +1,30 @@ +--- +title: onReceive() +--- + += onReceive + +//OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description + +This function registers a function to be called when a peripheral device receives a transmission from a controller device. + +[float] +=== Syntax +`Wire.onReceive(handler)` + +[float] +=== Parameters + +* _handler_: the function to be called when the peripheral device receives data; this should take a single int parameter (the number of bytes read from the controller device) and return nothing. + +[float] +=== Returns + +None. +-- +//OVERVIEW SECTION ENDS diff --git a/Language/Functions/Communication/Wire/onRequest.adoc b/Language/Functions/Communication/Wire/onRequest.adoc new file mode 100644 index 000000000..3b56c9a8d --- /dev/null +++ b/Language/Functions/Communication/Wire/onRequest.adoc @@ -0,0 +1,30 @@ +--- +title: onRequest() +--- + += onRequest + +//OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +This function registers a function to be called when a controller device requests data from a peripheral device. + +[float] +=== Syntax +`Wire.onRequest(handler)` + +[float] +=== Parameters + +* _handler_: the function to be called, takes no parameters and returns nothing. + +[float] +=== Returns + +None. + +-- +//OVERVIEW SECTION ENDS \ No newline at end of file diff --git a/Language/Functions/Communication/Wire/read.adoc b/Language/Functions/Communication/Wire/read.adoc new file mode 100644 index 000000000..73f56240f --- /dev/null +++ b/Language/Functions/Communication/Wire/read.adoc @@ -0,0 +1,54 @@ +--- +title: read() +--- + += read + +//OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +This function reads a byte that was transmitted from a peripheral device to a controller device after a call to `requestFrom()` or was transmitted from a controller device to a peripheral device. `read()` inherits from the Stream utility class. + +[float] +=== Syntax +`Wire.read()` + +[float] +=== Parameters + +None. + +[float] +=== Returns + +The next byte received. + +[float] +=== Example + +``` +#include + +void setup() { + Wire.begin(); // Join I2C bus (address is optional for controller device) + Serial.begin(9600); // Start serial for output +} + +void loop() { + Wire.requestFrom(2, 6); // Request 6 bytes from slave device number two + + // Slave may send less than requested + while(Wire.available()) { + char c = Wire.read(); // Receive a byte as character + Serial.print(c); // Print the character + } + + delay(500); +} +``` + +-- +//OVERVIEW SECTION ENDS \ No newline at end of file diff --git a/Language/Functions/Communication/Wire/requestFrom.adoc b/Language/Functions/Communication/Wire/requestFrom.adoc new file mode 100644 index 000000000..342dc54da --- /dev/null +++ b/Language/Functions/Communication/Wire/requestFrom.adoc @@ -0,0 +1,33 @@ +--- +title: requestFrom() +--- + += requestFrom + +// OVERVIEW SECTION STARTS +[#overview] + +-- + +[float] +=== Description +This function is used by the controller device to request bytes from a peripheral device. The bytes may then be retrieved with the `available()` and `read()` functions. The `requestFrom()` method accepts a boolean argument changing its behavior for compatibility with certain I2C devices. If true, `requestFrom()` sends a stop message after the request, releasing the I2C bus. If false, `requestFrom()` sends a restart message after the request. The bus will not be released, which prevents another master device from requesting between messages. This allows one master device to send multiple requests while in control. The default value is true. + +[float] +=== Syntax +`Wire.requestFrom(address, quantity)` + +`Wire.requestFrom(address, quantity, stop)` + +[float] +=== Parameters +* _address_: the 7-bit slave address of the device to request bytes from. +* _quantity_: the number of bytes to request. +* _stop_: true or false. true will send a stop message after the request, releasing the bus. False will continually send a restart after the request, keeping the connection active. + +[float] +=== Returns +* _byte_ : the number of bytes returned from the peripheral device. + +-- +//OVERVIEW SECTION ENDS \ No newline at end of file diff --git a/Language/Functions/Communication/Wire/setClock.adoc b/Language/Functions/Communication/Wire/setClock.adoc new file mode 100644 index 000000000..f47de0c20 --- /dev/null +++ b/Language/Functions/Communication/Wire/setClock.adoc @@ -0,0 +1,28 @@ +--- +title: setClock() +--- + += setClock + +//OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +This function modifies the clock frequency for I2C communication. I2C peripheral devices have no minimum working clock frequency, however 100KHz is usually the baseline. + +[float] +=== Syntax +`Wire.setClock(clockFrequency)` + +[float] +=== Parameters +* _clockFrequency_: the value (in Hertz) of the desired communication clock. Accepted values are 100000 (standard mode) and 400000 (fast mode). Some processors also support 10000 (low speed mode), 1000000 (fast mode plus) and 3400000 (high speed mode). Please refer to the specific processor documentation to make sure the desired mode is supported. + +[float] +=== Returns + +None. +-- +//OVERVIEW SECTION ENDS \ No newline at end of file diff --git a/Language/Functions/Communication/Wire/setWireTimeout.adoc b/Language/Functions/Communication/Wire/setWireTimeout.adoc new file mode 100644 index 000000000..3cfe18b8e --- /dev/null +++ b/Language/Functions/Communication/Wire/setWireTimeout.adoc @@ -0,0 +1,105 @@ +--- +title: setWireTimeout() +--- += setWireTimeout + +//OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description + +Sets the timeout for Wire transmissions in master mode. + +*Note:* these timeouts are almost always an indication of an underlying problem, such as misbehaving devices, noise, insufficient shielding, or other electrical problems. These timeouts will prevent your sketch from locking up, but not solve these problems. In such situations there will often (also) be data corruption which doesn't result in a timeout or other error and remains undetected. So when a timeout happens, it is likely that some data previously read or written is also corrupted. Additional measures might be needed to more reliably detect such issues (e.g. checksums or reading back written values) and recover from them (e.g. full system reset). This timeout and such additional measures should be seen as a last line of defence, when possible the underlying cause should be fixed instead. + +[float] +=== Syntax + +`Wire.setWireTimeout(timeout, reset_on_timeout)` + +`Wire.setWireTimeout()` + +[float] +=== Parameters +* `timeout a timeout`: timeout in microseconds, if zero then timeout checking is disabled +* `reset_on_timeout`: if true then Wire hardware will be automatically reset on timeout + +When this function is called without parameters, a default timeout is configured that should be sufficient to prevent lockups in a typical single-master configuration. + +[float] +=== Returns +None. + +[float] +=== Example Code + +``` +#include + +void setup() { + Wire.begin(); // join i2c bus (address optional for master) + #if defined(WIRE_HAS_TIMEOUT) + Wire.setWireTimeout(3000 /* us */, true /* reset_on_timeout */); + #endif +} + +byte x = 0; + +void loop() { + /* First, send a command to the other device */ + Wire.beginTransmission(8); // transmit to device #8 + Wire.write(123); // send command + byte error = Wire.endTransmission(); // run transaction + if (error) { + Serial.println("Error occurred when writing"); + if (error == 5) + Serial.println("It was a timeout"); + } + + delay(100); + + /* Then, read the result */ + #if defined(WIRE_HAS_TIMEOUT) + Wire.clearWireTimeoutFlag(); + #endif + byte len = Wire.requestFrom(8, 1); // request 1 byte from device #8 + if (len == 0) { + Serial.println("Error occurred when reading"); + #if defined(WIRE_HAS_TIMEOUT) + if (Wire.getWireTimeoutFlag()) + Serial.println("It was a timeout"); + #endif + } + + delay(100); +} +``` + +[float] +=== Notes and Warnings + +How this timeout is implemented might vary between different platforms, but typically a timeout condition is triggered when waiting for (some part of) the transaction to complete (e.g. waiting for the bus to become available again, waiting for an ACK bit, or maybe waiting for the entire transaction to be completed). + +When such a timeout condition occurs, the transaction is aborted and `endTransmission()` or `requestFrom()` will return an error code or zero bytes respectively. While this will not resolve the bus problem by itself (i.e. it does not remove a short-circuit), it will at least prevent blocking potentially indefinitely and allow your software to detect and maybe solve this condition. + +If `reset_on_timeout` was set to true and the platform supports this, the Wire hardware is also reset, which can help to clear any incorrect state inside the Wire hardware module. For example, on the AVR platform, this can be required to restart communications after a noise-induced timeout. + +When a timeout is triggered, a flag is set that can be queried with `getWireTimeoutFlag()` and must be cleared manually using `clearWireTimeoutFlag()` (and is also cleared when `setWireTimeout()` is called). + +Note that this timeout can also trigger while waiting for clock stretching or waiting for a second master to complete its transaction. So make sure to adapt the timeout to accommodate for those cases if needed. A typical timeout would be 25ms (which is the maximum clock stretching allowed by the SMBus protocol), but (much) shorter values will usually also work. + + +[float] +=== Portability Notes + +This function was not available in the original version of the Wire library and might still not be available on all platforms. Code that needs to be portable across platforms and versions can use the `WIRE_HAS_TIMEOUT` macro, which is only defined when `Wire.setWireTimeout()`, `Wire.getWireTimeoutFlag()` and `Wire.clearWireTimeout()` are all available. + +When this timeout feature was introduced on the AVR platform, it was initially kept disabled by default for compatibility, expecting it to become enabled at a later point. This means the default value of the timeout can vary between (versions of) platforms. The default timeout settings are available from the `WIRE_DEFAULT_TIMEOUT` and `WIRE_DEFAULT_RESET_WITH_TIMEOUT` macro. + +If you require the timeout to be disabled, it is recommended you disable it by default using `setWireTimeout(0)`, even though that is currently the default. + +-- + +//OVERVIEW SECTION ENDS diff --git a/Language/Functions/Communication/Wire/write.adoc b/Language/Functions/Communication/Wire/write.adoc new file mode 100644 index 000000000..3bd29962d --- /dev/null +++ b/Language/Functions/Communication/Wire/write.adoc @@ -0,0 +1,61 @@ +--- +title: write() +--- + += write + +//OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +This function writes data from a peripheral device in response to a request from a controller device, or queues bytes for transmission from a controller to peripheral device (in-between calls to `beginTransmission()` and `endTransmission()`). + +[float] +=== Syntax +`Wire.write(value)` +`Wire.write(string)` +`Wire.write(data, length)` + +[float] +=== Parameters +* _value_: a value to send as a single byte. +* _string_: a string to send as a series of bytes. +* _data_: an array of data to send as bytes. +* _length_: the number of bytes to transmit. + +[float] +=== Returns + +The number of bytes written (reading this number is optional). +[float] +=== Example + +``` +#include + +byte val = 0; + +void setup() { + Wire.begin(); // Join I2C bus +} + +void loop() { + Wire.beginTransmission(44); // Transmit to device number 44 (0x2C) + + Wire.write(val); // Sends value byte + Wire.endTransmission(); // Stop transmitting + + val++; // Increment value + + // if reached 64th position (max) + if(val == 64) { + val = 0; // Start over from lowest value + } + + delay(500); +} +``` +-- +//OVERVIEW SECTION ENDS diff --git a/Language/Functions/Communication/stream.adoc b/Language/Functions/Communication/stream.adoc index 18f78bec0..7258a219e 100644 --- a/Language/Functions/Communication/stream.adoc +++ b/Language/Functions/Communication/stream.adoc @@ -1,5 +1,5 @@ --- -title: stream +title: Stream categories: [ "Functions" ] subCategories: [ "Communication" ] --- @@ -22,8 +22,8 @@ Stream defines the reading functions in Arduino. When using any core functionali Some of the libraries that rely on Stream include : -* link:../serial[Serial] -* link:https://www.arduino.cc/en/Reference/Wire[Wire] +* link:https://www.arduino.cc/en/Reference/serial[Serial] +* link:https://www.arduino.cc/en/Reference/wire[Wire] * link:https://www.arduino.cc/en/Reference/Ethernet[Ethernet] * link:https://www.arduino.cc/en/Reference/SD[SD] @@ -58,3 +58,14 @@ link:../stream/streamsettimeout[setTimeout()] -- // FUNCTIONS SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Functions/Digital IO/digitalRead.adoc b/Language/Functions/Digital IO/digitalRead.adoc index ceafcc0b6..01b4f3c5a 100644 --- a/Language/Functions/Digital IO/digitalRead.adoc +++ b/Language/Functions/Digital IO/digitalRead.adoc @@ -28,7 +28,8 @@ Reads the value from a specified digital pin, either `HIGH` or `LOW`. [float] === Parameters -`pin`: the number of the digital pin you want to read +`pin`: the Arduino pin number you want to read + [float] === Returns @@ -49,31 +50,29 @@ Reads the value from a specified digital pin, either `HIGH` or `LOW`. // Describe what the example code is all about and add relevant code ►►►►► THIS SECTION IS MANDATORY ◄◄◄◄◄ Sets pin 13 to the same value as pin 7, declared as an input. -//[source,arduino] +[source,arduino] ---- -int ledPin = 13; // LED connected to digital pin 13 -int inPin = 7; // pushbutton connected to digital pin 7 -int val = 0; // variable to store the read value - -void setup() -{ - pinMode(ledPin, OUTPUT); // sets the digital pin 13 as output - pinMode(inPin, INPUT); // sets the digital pin 7 as input +int ledPin = 13; // LED connected to digital pin 13 +int inPin = 7; // pushbutton connected to digital pin 7 +int val = 0; // variable to store the read value + +void setup() { + pinMode(ledPin, OUTPUT); // sets the digital pin 13 as output + pinMode(inPin, INPUT); // sets the digital pin 7 as input } -void loop() -{ - val = digitalRead(inPin); // read the input pin - digitalWrite(ledPin, val); // sets the LED to the button's value +void loop() { + val = digitalRead(inPin); // read the input pin + digitalWrite(ledPin, val); // sets the LED to the button's value } ---- [%hardbreaks] [float] === Notes and Warnings -If the pin isn't connected to anything, digitalRead() can return either HIGH or LOW (and this can change randomly). +If the pin isn't connected to anything, `digitalRead()` can return either `HIGH` or `LOW` (and this can change randomly). -The analog input pins can be used as digital pins, referred to as A0, A1, etc. +The analog input pins can be used as digital pins, referred to as A0, A1, etc. The exception is the Arduino Nano, Pro Mini, and Mini's A6 and A7 pins, which can only be used as analog inputs. -- // HOW TO USE SECTION ENDS @@ -87,7 +86,7 @@ The analog input pins can be used as digital pins, referred to as A0, A1, etc. === See also [role="example"] -* #EXAMPLE# Tutorial: (http://arduino.cc/en/Tutorial/DigitalPins[Digital Pins]) +* #EXAMPLE# http://arduino.cc/en/Tutorial/DigitalPins[Description of the digital pins^] -- // SEE ALSO SECTION ENDS diff --git a/Language/Functions/Digital IO/digitalWrite.adoc b/Language/Functions/Digital IO/digitalWrite.adoc index 32fcbcaae..d2bc38aad 100644 --- a/Language/Functions/Digital IO/digitalWrite.adoc +++ b/Language/Functions/Digital IO/digitalWrite.adoc @@ -22,7 +22,7 @@ Write a `HIGH` or a `LOW` value to a digital pin. If the pin has been configured as an `OUTPUT` with `pinMode()`, its voltage will be set to the corresponding value: 5V (or 3.3V on 3.3V boards) for `HIGH`, 0V (ground) for `LOW`. [%hardbreaks] -If the pin is configured as an `INPUT`, `digitalWrite()` will enable (`HIGH`) or disable (`LOW`) the internal pullup on the input pin. It is recommended to set the `pinMode()` to `INPUT_PULLUP` to enable the internal pull-up resistor. See the digital pins tutorial for more information. +If the pin is configured as an `INPUT`, `digitalWrite()` will enable (`HIGH`) or disable (`LOW`) the internal pullup on the input pin. It is recommended to set the `pinMode()` to `INPUT_PULLUP` to enable the internal pull-up resistor. See the http://arduino.cc/en/Tutorial/DigitalPins[Digital Pins^] tutorial for more information. [%hardbreaks] If you do not set the `pinMode()` to `OUTPUT`, and connect an LED to a pin, when calling `digitalWrite(HIGH)`, the LED may appear dim. Without explicitly setting `pinMode()`, `digitalWrite()` will have enabled the internal pull-up resistor, which acts like a large current-limiting resistor. @@ -35,9 +35,9 @@ If you do not set the `pinMode()` to `OUTPUT`, and connect an LED to a pin, when [float] === Parameters -`pin`: the pin number +`pin`: the Arduino pin number. + +`value`: `HIGH` or `LOW`. -`value`: `HIGH` or `LOW` [float] === Returns @@ -58,26 +58,24 @@ Nothing // Describe what the example code is all about and add relevant code ►►►►► THIS SECTION IS MANDATORY ◄◄◄◄◄ The code makes the digital pin 13 an `OUTPUT` and toggles it by alternating between `HIGH` and `LOW` at one second pace. -//[source,arduino] +[source,arduino] ---- -void setup() -{ - pinMode(13, OUTPUT); // sets the digital pin 13 as output +void setup() { + pinMode(13, OUTPUT); // sets the digital pin 13 as output } -void loop() -{ - digitalWrite(13, HIGH); // sets the digital pin 13 on - delay(1000); // waits for a second - digitalWrite(13, LOW); // sets the digital pin 13 off - delay(1000); // waits for a second +void loop() { + digitalWrite(13, HIGH); // sets the digital pin 13 on + delay(1000); // waits for a second + digitalWrite(13, LOW); // sets the digital pin 13 off + delay(1000); // waits for a second } ---- [%hardbreaks] [float] === Notes and Warnings -The analog input pins can be used as digital pins, referred to as A0, A1, etc. +The analog input pins can be used as digital pins, referred to as A0, A1, etc. The exception is the Arduino Nano, Pro Mini, and Mini's A6 and A7 pins, which can only be used as analog inputs. -- // HOW TO USE SECTION ENDS @@ -91,7 +89,7 @@ The analog input pins can be used as digital pins, referred to as A0, A1, etc. === See also [role="example"] -* #EXAMPLE# http://arduino.cc/en/Tutorial/DigitalPins[Tutorial: Digital Pins] +* #EXAMPLE# http://arduino.cc/en/Tutorial/DigitalPins[Description of the digital pins^] -- // SEE ALSO SECTION ENDS diff --git a/Language/Functions/Digital IO/pinMode.adoc b/Language/Functions/Digital IO/pinMode.adoc index 9cff325a4..46daae777 100644 --- a/Language/Functions/Digital IO/pinMode.adoc +++ b/Language/Functions/Digital IO/pinMode.adoc @@ -17,9 +17,9 @@ subCategories: [ "Digital I/O" ] [float] === Description -Configures the specified pin to behave either as an input or an output. See the description of (http://arduino.cc/en/Tutorial/DigitalPins[digital pins]) for details on the functionality of the pins. +Configures the specified pin to behave either as an input or an output. See the http://arduino.cc/en/Tutorial/DigitalPins[Digital Pins] page for details on the functionality of the pins. [%hardbreaks] -As of Arduino 1.0.1, it is possible to enable the internal pullup resistors with the mode INPUT_PULLUP. Additionally, the INPUT mode explicitly disables the internal pullups. +It is possible to enable the internal pullup resistors with the mode `INPUT_PULLUP`. Additionally, the `INPUT` mode explicitly disables the internal pullups. [%hardbreaks] @@ -27,13 +27,12 @@ As of Arduino 1.0.1, it is possible to enable the internal pullup resistors with === Syntax `pinMode(pin, mode)` + [float] === Parameters -`pin`: the number of the pin whose mode you wish to set - -`mode`: `INPUT`, `OUTPUT`, or `INPUT_PULLUP`. (see the (http://arduino.cc/en/Tutorial/DigitalPins[digital pins]) page for a more complete description of the functionality.) +`pin`: the Arduino pin number to set the mode of. + +`mode`: `INPUT`, `OUTPUT`, or `INPUT_PULLUP`. See the http://arduino.cc/en/Tutorial/DigitalPins[Digital Pins] page for a more complete description of the functionality. -//Check how to add links [float] === Returns @@ -53,19 +52,17 @@ Nothing === Example Code The code makes the digital pin 13 `OUTPUT` and Toggles it `HIGH` and `LOW` -//[source,arduino] +[source,arduino] ---- -void setup() -{ - pinMode(13, OUTPUT); // sets the digital pin 13 as output +void setup() { + pinMode(13, OUTPUT); // sets the digital pin 13 as output } -void loop() -{ - digitalWrite(13, HIGH); // sets the digital pin 13 on - delay(1000); // waits for a second - digitalWrite(13, LOW); // sets the digital pin 13 off - delay(1000); // waits for a second +void loop() { + digitalWrite(13, HIGH); // sets the digital pin 13 on + delay(1000); // waits for a second + digitalWrite(13, LOW); // sets the digital pin 13 off + delay(1000); // waits for a second } ---- [%hardbreaks] @@ -86,7 +83,7 @@ The analog input pins can be used as digital pins, referred to as A0, A1, etc. === See also [role="example"] -* #EXAMPLE# http://arduino.cc/en/Tutorial/DigitalPins[Description of the pins on an Arduino board^] +* #EXAMPLE# http://arduino.cc/en/Tutorial/DigitalPins[Description of the digital pins^] -- // SEE ALSO SECTION ENDS diff --git a/Language/Functions/External Interrupts/attachInterrupt.adoc b/Language/Functions/External Interrupts/attachInterrupt.adoc index 99cbd9767..05fa3b70c 100644 --- a/Language/Functions/External Interrupts/attachInterrupt.adoc +++ b/Language/Functions/External Interrupts/attachInterrupt.adoc @@ -4,10 +4,6 @@ categories: [ "Functions" ] subCategories: [ "External Interrupts" ] --- - - - - = attachInterrupt() @@ -19,19 +15,25 @@ subCategories: [ "External Interrupts" ] === Description *Digital Pins With Interrupts* -The first parameter to attachInterrupt is an interrupt number. Normally you should use digitalPinToInterrupt(pin) to translate the actual digital pin to the specific interrupt number. For example, if you connect to pin 3, use digitalPinToInterrupt(3) as the first parameter to attachInterrupt. +The first parameter to `attachInterrupt()` is an interrupt number. Normally you should use `digitalPinToInterrupt(pin)` to translate the actual digital pin to the specific interrupt number. For example, if you connect to pin 3, use `digitalPinToInterrupt(3)` as the first parameter to `attachInterrupt()`. [options="header"] |=================================================== -|Board |Digital Pins Usable For Interrupts -|Uno, Nano, Mini, other 328-based |2, 3 -|Uno WiFi Rev.2 |all digital pins -|Mega, Mega2560, MegaADK |2, 3, 18, 19, 20, 21 -|Micro, Leonardo, other 32u4-based |0, 1, 2, 3, 7 -|Zero |all digital pins, except 4 -|MKR Family boards |0, 1, 4, 5, 6, 7, 8, 9, A1, A2 -|Due |all digital pins -|101 |all digital pins (Only pins 2, 5, 7, 8, 10, 11, 12, 13 work with *CHANGE*) +|Board |Digital Pins Usable For Interrupts| Notes +|Uno Rev3, Nano, Mini, other 328-based |2, 3| +|UNO R4 Minima, UNO R4 WiFi |2, 3| +|Uno WiFi Rev2, Nano Every |All digital pins| +|Mega, Mega2560, MegaADK |2, 3, 18, 19, 20, 21 |(*pins 20 & 21* are not available to use for interrupts while they are used for I2C communication; they also have external pull-ups that cannot be disabled) +|Micro, Leonardo |0, 1, 2, 3, 7| +|Zero |0-3, 5-13, A0-A5| Pin 4 cannot be used as an interrupt. +|MKR Family boards |0, 1, 4, 5, 6, 7, 8, 9, A1, A2| +|Nano 33 IoT |2, 3, 9, 10, 11, 13, A1, A5, A7| +|Nano 33 BLE, Nano 33 BLE Sense (rev 1 & 2) |all pins| +|Nano RP2040 Connect |0-13, A0-A5| +|Nano ESP32 |all pins| +|GIGA R1 WiFi |all pins| +|Due |all digital pins| +|101 |all digital pins | (Only pins 2, 5, 7, 8, 10, 11, 12, 13 work with *CHANGE*)) |=================================================== [%hardbreaks] @@ -40,20 +42,20 @@ The first parameter to attachInterrupt is an interrupt number. Normally you shou === Notes and Warnings *Note* + -Inside the attached function, `delay()` won't work and the value returned by `millis()` will not increment. Serial data received while in the function may be lost. You should declare as volatile any variables that you modify within the attached function. See the section on ISRs below for more information. +Inside the attached function, `delay()` won't work and the value returned by `millis()` will not increment. Serial data received while in the function may be lost. You should declare as `volatile` any variables that you modify within the attached function. See the section on ISRs below for more information. [%hardbreaks] [float] == Using Interrupts -Interrupts are useful for making things happen automatically in microcontroller programs, and can help solve timing problems. Good tasks for using an interrupt may include reading a rotary encoder, or monitoring user input. +Interrupts are useful for making things happen automatically in microcontroller programs and can help solve timing problems. Good tasks for using an interrupt may include reading a rotary encoder, or monitoring user input. -If you wanted to insure that a program always caught the pulses from a rotary encoder, so that it never misses a pulse, it would make it very tricky to write a program to do anything else, because the program would need to constantly poll the sensor lines for the encoder, in order to catch pulses when they occurred. Other sensors have a similar interface dynamic too, such as trying to read a sound sensor that is trying to catch a click, or an infrared slot sensor (photo-interrupter) trying to catch a coin drop. In all of these situations, using an interrupt can free the microcontroller to get some other work done while not missing the input. +If you wanted to ensure that a program always caught the pulses from a rotary encoder, so that it never misses a pulse, it would make it very tricky to write a program to do anything else, because the program would need to constantly poll the sensor lines for the encoder, in order to catch pulses when they occurred. Other sensors have a similar interface dynamic too, such as trying to read a sound sensor that is trying to catch a click, or an infrared slot sensor (photo-interrupter) trying to catch a coin drop. In all of these situations, using an interrupt can free the microcontroller to get some other work done while not missing the input. [float] == About Interrupt Service Routines ISRs are special kinds of functions that have some unique limitations most other functions do not have. An ISR cannot have any parameters, and they shouldn't return anything. -Generally, an ISR should be as short and fast as possible. If your sketch uses multiple ISRs, only one can run at a time, other interrupts will be executed after the current one finishes in an order that depends on the priority they have. millis() relies on interrupts to count, so it will never increment inside an ISR. Since delay() requires interrupts to work, it will not work if called inside an ISR. micros() works initially, but will start behaving erratically after 1-2 ms. delayMicroseconds() does not use any counter, so it will work as normal. +Generally, an ISR should be as short and fast as possible. If your sketch uses multiple ISRs, only one can run at a time, other interrupts will be executed after the current one finishes in an order that depends on the priority they have. `millis()` relies on interrupts to count, so it will never increment inside an ISR. Since `delay()` requires interrupts to work, it will not work if called inside an ISR. `micros()` works initially but will start behaving erratically after 1-2 ms. `delayMicroseconds()` does not use any counter, so it will work as normal. Typically global variables are used to pass data between an ISR and the main program. To make sure variables shared between an ISR and the main program are updated correctly, declare them as `volatile`. @@ -61,15 +63,15 @@ For more information on interrupts, see http://gammon.com.au/interrupts[Nick Gam [float] === Syntax -`attachInterrupt(digitalPinToInterrupt(pin), ISR, mode);` (recommended) + -`attachInterrupt(interrupt, ISR, mode);` (not recommended) + -`attachInterrupt(pin, ISR, mode);` (not recommended Arduino Due, Zero, MKR1000, 101 only) +`attachInterrupt(digitalPinToInterrupt(pin), ISR, mode)` (recommended) + +`attachInterrupt(interrupt, ISR, mode)` (not recommended) + +`attachInterrupt(pin, ISR, mode)` (Not recommended. Additionally, this syntax only works on Arduino SAMD Boards, Uno WiFi Rev2, Due, and 101.) [float] === Parameters -`interrupt`: the number of the interrupt (`int`) + -`pin`: the pin number _(Arduino Due, Zero, MKR1000 only)_ + +`interrupt`: the number of the interrupt. Allowed data types: `int`. + +`pin`: the Arduino pin number. + `ISR`: the ISR to call when the interrupt occurs; this function must take no parameters and return nothing. This function is sometimes referred to as an interrupt service routine. + `mode`: defines when the interrupt should be triggered. Four constants are predefined as valid values: + @@ -78,10 +80,11 @@ For more information on interrupts, see http://gammon.com.au/interrupts[Nick Gam * *RISING* to trigger when the pin goes from low to high, + * *FALLING* for when the pin goes from high to low. + -The Due, Zero and MKR1000 boards allows also: + +The Due, Zero and MKR1000 boards allow also: + * *HIGH* to trigger the interrupt whenever the pin is high. + [float] === Returns Nothing @@ -121,11 +124,11 @@ void blink() { [float] === Interrupt Numbers -Normally you should use digitalPinToInterrupt(pin), rather than place an interrupt number directly into your sketch. The specific pins with interrupts, and their mapping to interrupt number varies on each type of board. Direct use of interrupt numbers may seem simple, but it can cause compatibility trouble when your sketch is run on a different board. +Normally you should use `digitalPinToInterrupt(pin)`, rather than place an interrupt number directly into your sketch. The specific pins with interrupts and their mapping to interrupt number varies for each type of board. Direct use of interrupt numbers may seem simple, but it can cause compatibility trouble when your sketch runs on a different board. However, older sketches often have direct interrupt numbers. Often number 0 (for digital pin 2) or number 1 (for digital pin 3) were used. The table below shows the available interrupt pins on various boards. -Note that in the table below, the interrupt numbers refer to the number to be passed to attachInterrupt(). For historical reasons, this numbering does not always correspond directly to the interrupt numbering on the atmega chip (e.g. int.0 corresponds to INT4 on the Atmega2560 chip). +Note that in the table below, the interrupt numbers refer to the number to be passed to `attachInterrupt()`. For historical reasons, this numbering does not always correspond directly to the interrupt numbering on the ATmega chip (e.g. int.0 corresponds to INT4 on the ATmega2560 chip). [options="header"] |=================================================== @@ -134,8 +137,19 @@ Note that in the table below, the interrupt numbers refer to the number to be pa |Mega2560 | 2 | 3 | 21 | 20 | 19 | 18 |32u4 based (e.g Leonardo, Micro) | 3 | 2 | 0 | 1 | 7 | |=================================================== -For Uno WiFiRev.2, Due, Zero, MKR Family and 101 boards the *interrupt number = pin number*. +For Uno WiFi Rev2, Due, Zero, MKR Family and 101 boards the *interrupt number = pin number*. -- // HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Functions/External Interrupts/detachInterrupt.adoc b/Language/Functions/External Interrupts/detachInterrupt.adoc index ddd26f082..84fa30978 100644 --- a/Language/Functions/External Interrupts/detachInterrupt.adoc +++ b/Language/Functions/External Interrupts/detachInterrupt.adoc @@ -23,14 +23,16 @@ Turns off the given interrupt. [float] === Syntax -`detachInterrupt()` + -`detachInterrupt(pin)` (Arduino Due only) +- `detachInterrupt(digitalPinToInterrupt(pin))` (recommended) + +- `detachInterrupt(interrupt)` (not recommended) + +- `detachInterrupt(pin)` (Not recommended. Additionally, this only works on a specific set of boards.) + [float] === Parameters -`interrupt`: the number of the interrupt to disable (see link:../attachinterrupt[attachInterrupt()] for more details). +`interrupt`: the number of the interrupt to disable (see link:../attachinterrupt[attachInterrupt()] for more details). + +`pin`: the Arduino pin number of the interrupt to disable -`pin`: the pin number of the interrupt to disable (Arduino Due only) [float] === Returns @@ -38,3 +40,14 @@ Nothing -- // OVERVIEW SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Functions/External Interrupts/digitalPinToInterrupt.adoc b/Language/Functions/External Interrupts/digitalPinToInterrupt.adoc new file mode 100644 index 000000000..a5077725f --- /dev/null +++ b/Language/Functions/External Interrupts/digitalPinToInterrupt.adoc @@ -0,0 +1,92 @@ +--- +title: digitalPinToInterrupt() +categories: [ "Functions" ] +subCategories: [ "External Interrupts" ] +--- + + + + + += digitalPinToInterrupt() + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +The `digitalPinToInterrupt()` function takes a pin as an argument, and returns the same pin *if* it can be used as an interrupt. For example, `digitalPinToInterrupt(4)` on an Arduino UNO will not work, as interrupts are only supported on pins 2,3. + +See link:../../external-interrupts/attachinterrupt[attachInterrupt()] for a full list of supported interrupt pins on all boards. + +[%hardbreaks] + + +[float] +=== Syntax +`digitalPinToInterrupt(pin)` + + +[float] +=== Parameters +- `pin` - the pin we want to use for an interrupt. + + +[float] +=== Returns +- The pin to interrupt (e.g. `2`)+ +- If pin is not available for interrupt, returns `-1`. + +-- +// OVERVIEW SECTION ENDS + + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code +// Describe what the example code is all about and add relevant code ►►►►► THIS SECTION IS MANDATORY ◄◄◄◄◄ +This example checks if a pin can be used as an interrupt. + +[source,arduino] +---- +int pin = 2; + +void setup() { + Serial.begin(9600); + int checkPin = digitalPinToInterrupt(pin); + + if (checkPin == -1) { + Serial.println("Not a valid interrupt pin!"); + } else { + Serial.println("Valid interrupt pin."); + } +} + +void loop() { +} +---- + +-- +// HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +[role="language"] +* #LANGUAGE# link:../../external-interrupts/attachinterrupt[attachInterrupts()] +* #LANGUAGE# link:../../external-interrupts/detachinterrupt[detachInterrupts()] + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Functions/Interrupts/interrupts.adoc b/Language/Functions/Interrupts/interrupts.adoc index a6690d044..2158aeed6 100644 --- a/Language/Functions/Interrupts/interrupts.adoc +++ b/Language/Functions/Interrupts/interrupts.adoc @@ -17,7 +17,7 @@ subCategories: [ "Interrupts" ] [float] === Description -Re-enables interrupts (after they've been disabled by link:../nointerrupts[nointerrupts()]. Interrupts allow certain important tasks to happen in the background and are enabled by default. Some functions will not work while interrupts are disabled, and incoming communication may be ignored. Interrupts can slightly disrupt the timing of code, however, and may be disabled for particularly critical sections of code. +Re-enables interrupts (after they've been disabled by link:../nointerrupts[noInterrupts()]. Interrupts allow certain important tasks to happen in the background and are enabled by default. Some functions will not work while interrupts are disabled, and incoming communication may be ignored. Interrupts can slightly disrupt the timing of code, however, and may be disabled for particularly critical sections of code. [%hardbreaks] @@ -28,7 +28,8 @@ Re-enables interrupts (after they've been disabled by link:../nointerrupts[noint [float] === Parameters -Nothing +None + [float] === Returns @@ -53,8 +54,7 @@ The code enables Interrupts. ---- void setup() {} -void loop() -{ +void loop() { noInterrupts(); // critical, time-sensitive code here interrupts(); diff --git a/Language/Functions/Interrupts/noInterrupts.adoc b/Language/Functions/Interrupts/noInterrupts.adoc index 3202a9dd5..b925094d7 100644 --- a/Language/Functions/Interrupts/noInterrupts.adoc +++ b/Language/Functions/Interrupts/noInterrupts.adoc @@ -17,7 +17,7 @@ subCategories: [ "Interrupts" ] [float] === Description -Disables interrupts (you can re-enable them with `interrupts()`). Interrupts allow certain important tasks to happen in the background and are enabled by default. Some functions will not work while interrupts are disabled, and incoming communication may be ignored. Interrupts can slightly disrupt the timing of code, however, and may be disabled for particularly critical sections of code. +Disables interrupts (you can re-enable them with link:../interrupts[`interrupts()`]). Interrupts allow certain important tasks to happen in the background and are enabled by default. Some functions will not work while interrupts are disabled, and incoming communication may be ignored. Interrupts can slightly disrupt the timing of code, however, and may be disabled for particularly critical sections of code. [%hardbreaks] @@ -28,7 +28,8 @@ Disables interrupts (you can re-enable them with `interrupts()`). Interrupts all [float] === Parameters -Nothing +None + [float] === Returns @@ -53,14 +54,31 @@ The code shows how to enable interrupts. ---- void setup() {} -void loop() -{ +void loop() { noInterrupts(); // critical, time-sensitive code here interrupts(); // other code here } ---- +[%hardbreaks] + + +[float] +=== Notes and Warnings +Note that disabling interrupts on the Arduino boards with native USB capabilities (e.g., link:https://docs.arduino.cc/hardware/leonardo[Leonardo^]) will make the board +not appear in the Port menu, since this disables its USB capability. -- // HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Functions/Math/abs.adoc b/Language/Functions/Math/abs.adoc index 602943701..5e575abb2 100644 --- a/Language/Functions/Math/abs.adoc +++ b/Language/Functions/Math/abs.adoc @@ -25,14 +25,15 @@ Calculates the absolute value of a number. === Syntax `abs(x)` + [float] === Parameters `x`: the number + [float] === Returns -`x`: if x is greater than or equal to 0. - +`x`: if x is greater than or equal to 0. + `-x`: if x is less than 0. -- @@ -44,20 +45,68 @@ Calculates the absolute value of a number. // HOW TO USE SECTION STARTS [#howtouse] -- +[float] +=== Example Code +// Describe what the example code is all about and add relevant code ►►►►► THIS SECTION IS MANDATORY ◄◄◄◄◄ +Prints the absolute value of variable `x` to the Serial Monitor. +[source,arduino] +---- +void setup() { + Serial.begin(9600); + while (!Serial) { + ; // wait for serial port to connect. Needed for native USB port only + } + int x = 42; + Serial.print("The absolute value of "); + Serial.print(x); + Serial.print(" is "); + Serial.println(abs(x)); + x = -42; + Serial.print("The absolute value of "); + Serial.print(x); + Serial.print(" is "); + Serial.println(abs(x)); +} + +void loop() { +} +---- +[%hardbreaks] [float] === Notes and Warnings Because of the way the abs() function is implemented, avoid using other functions inside the brackets, it may lead to incorrect results. [source,arduino] ---- -abs(a++); // avoid this - yields incorrect results +abs(a++); // avoid this - yields incorrect results -abs(a); // use this instead - -a++; // keep other math outside the function +// use this instead: +abs(a); +a++; // keep other math outside the function ---- [%hardbreaks] -- // HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +[role="language"] +* #LANGUAGE# link:../constrain[constrain()] +* #LANGUAGE# link:../map[map()] +* #LANGUAGE# link:../max[max()] +* #LANGUAGE# link:../min[min()] +* #LANGUAGE# link:../pow[pow()] +* #LANGUAGE# link:../sq[sq()] +* #LANGUAGE# link:../sqrt[sqrt()] + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Functions/Math/constrain.adoc b/Language/Functions/Math/constrain.adoc index 8e369f2e6..7abb8f2f4 100644 --- a/Language/Functions/Math/constrain.adoc +++ b/Language/Functions/Math/constrain.adoc @@ -28,17 +28,16 @@ Constrains a number to be within a range. [float] === Parameters -`x`: the number to constrain, all data types -`a`: the lower end of the range, all data types -`b`: the upper end of the range, all data types +`x`: the number to constrain Allowed data types: all data types. + +`a`: the lower end of the range. Allowed data types: all data types. + +`b`: the upper end of the range. Allowed data types: all data types. + [float] === Returns -x: if x is between a and b - -a: if x is less than a - -b: if x is greater than b +x: if x is between a and b. + +a: if x is less than a. + +b: if x is greater than b. -- // OVERVIEW SECTION ENDS @@ -57,8 +56,46 @@ The code limits the sensor values to between 10 to 150. [source,arduino] ---- -sensVal = constrain(sensVal, 10, 150); // limits range of sensor values to between 10 and 150 +sensVal = constrain(sensVal, 10, 150); // limits range of sensor values to between 10 and 150 +---- + +[float] +=== Notes and Warnings +Because of the way the `constrain()` function is implemented, avoid using other functions inside the brackets, it may lead to incorrect results. + +This code will yield incorrect results: +[source,arduino] +---- +int constrainedInput = constrain(Serial.parseInt(), minimumValue, maximumValue); // avoid this +---- + +Use this instead: +[source,arduino] +---- +int input = Serial.parseInt(); // keep other operations outside the constrain function +int constrainedInput = constrain(input, minimumValue, maximumValue); ---- +[%hardbreaks] -- // HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +[role="language"] +* #LANGUAGE# link:../abs[abs()] +* #LANGUAGE# link:../map[map()] +* #LANGUAGE# link:../max[max()] +* #LANGUAGE# link:../min[min()] +* #LANGUAGE# link:../pow[pow()] +* #LANGUAGE# link:../sq[sq()] +* #LANGUAGE# link:../sqrt[sqrt()] + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Functions/Math/map.adoc b/Language/Functions/Math/map.adoc index a65a01edb..ee97cf762 100644 --- a/Language/Functions/Math/map.adoc +++ b/Language/Functions/Math/map.adoc @@ -42,19 +42,16 @@ The `map()` function uses integer math so will not generate fractions, when the [float] === Parameters -`value`: the number to map +`value`: the number to map. + +`fromLow`: the lower bound of the value's current range. + +`fromHigh`: the upper bound of the value's current range. + +`toLow`: the lower bound of the value's target range. + +`toHigh`: the upper bound of the value's target range. -`fromLow`: the lower bound of the value's current range - -`fromHigh`: the upper bound of the value's current range - -`toLow`: the lower bound of the value's target range - -`toHigh`: the upper bound of the value's target range [float] === Returns -The mapped value. +The mapped value. Data type: `long`. -- // OVERVIEW SECTION ENDS @@ -76,8 +73,7 @@ The mapped value. /* Map an analog value to 8 bits (0 to 255) */ void setup() {} -void loop() -{ +void loop() { int val = analogRead(0); val = map(val, 0, 1023, 0, 255); analogWrite(9, val); @@ -92,11 +88,35 @@ For the mathematically inclined, here's the whole function [source,arduino] ---- -long map(long x, long in_min, long in_max, long out_min, long out_max) -{ +long map(long x, long in_min, long in_max, long out_min, long out_max) { return (x - in_min) * (out_max - out_min) / (in_max - in_min) + out_min; } ---- +[float] +=== Notes & Warnings + +As previously mentioned, the map() function uses integer math. So fractions might get suppressed due to this. For example, fractions like 3/2, 4/3, 5/4 will all be returned as 1 from the map() function, despite their different actual values. So if your project requires precise calculations (e.g. voltage accurate to 3 decimal places), please consider avoiding map() and implementing the calculations manually in your code yourself. + -- // HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +[role="language"] +* #LANGUAGE# link:../abs[abs()] +* #LANGUAGE# link:../constrain[constrain()] +* #LANGUAGE# link:../max[max()] +* #LANGUAGE# link:../min[min()] +* #LANGUAGE# link:../pow[pow()] +* #LANGUAGE# link:../sq[sq()] +* #LANGUAGE# link:../sqrt[sqrt()] + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Functions/Math/max.adoc b/Language/Functions/Math/max.adoc index ccb68c043..1ea570a59 100644 --- a/Language/Functions/Math/max.adoc +++ b/Language/Functions/Math/max.adoc @@ -28,8 +28,9 @@ Calculates the maximum of two numbers. [float] === Parameters -`x`: the first number, any data type -`y`: the second number, any data type +`x`: the first number. Allowed data types: any data type. + +`y`: the second number. Allowed data types: any data type. + [float] === Returns @@ -53,7 +54,7 @@ The code ensures that sensVal is at least 20. [source,arduino] ---- sensVal = max(sensVal, 20); // assigns sensVal to the larger of sensVal or 20 - // (effectively ensuring that it is at least 20) + // (effectively ensuring that it is at least 20) ---- [%hardbreaks] @@ -64,11 +65,33 @@ Perhaps counter-intuitively, `max()` is often used to constrain the lower end of Because of the way the `max()` function is implemented, avoid using other functions inside the brackets, it may lead to incorrect results [source,arduino] ---- -max(a--, 0); // avoid this - yields incorrect results +max(a--, 0); // avoid this - yields incorrect results -max(a, 0); // use this instead - -a--; // keep other math outside the function +// use this instead: +max(a, 0); +a--; // keep other math outside the function ---- -- // HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +[role="language"] +* #LANGUAGE# link:../abs[abs()] +* #LANGUAGE# link:../constrain[constrain()] +* #LANGUAGE# link:../map[map()] +* #LANGUAGE# link:../min[min()] +* #LANGUAGE# link:../pow[pow()] +* #LANGUAGE# link:../sq[sq()] +* #LANGUAGE# link:../sqrt[sqrt()] + + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Functions/Math/min.adoc b/Language/Functions/Math/min.adoc index 76acf159d..fc8c663c8 100644 --- a/Language/Functions/Math/min.adoc +++ b/Language/Functions/Math/min.adoc @@ -28,9 +28,9 @@ Calculates the minimum of two numbers. [float] === Parameters -`x`: the first number, any data type +`x`: the first number. Allowed data types: any data type. + +`y`: the second number. Allowed data types: any data type. -`y`: the second number, any data type [float] === Returns @@ -53,8 +53,8 @@ The code ensures that it never gets above 100. [source,arduino] ---- -sensVal = min(sensVal, 100); // assigns sensVal to the smaller of sensVal or 100 - // ensuring that it never gets above 100. +sensVal = min(sensVal, 100); // assigns sensVal to the smaller of sensVal or 100 + // ensuring that it never gets above 100. ---- [%hardbreaks] @@ -65,11 +65,31 @@ Perhaps counter-intuitively, `max()` is often used to constrain the lower end of Because of the way the `min()` function is implemented, avoid using other functions inside the brackets, it may lead to incorrect results [source,arduino] ---- -min(a++, 100); // avoid this - yields incorrect results +min(a++, 100); // avoid this - yields incorrect results min(a, 100); -a++; // use this instead - keep other math outside the function +a++; // use this instead - keep other math outside the function ---- -- // HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +[role="language"] +* #LANGUAGE# link:../abs[abs()] +* #LANGUAGE# link:../constrain[constrain()] +* #LANGUAGE# link:../map[map()] +* #LANGUAGE# link:../max[max()] +* #LANGUAGE# link:../pow[pow()] +* #LANGUAGE# link:../sq[sq()] +* #LANGUAGE# link:../sqrt[sqrt()] + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Functions/Math/pow.adoc b/Language/Functions/Math/pow.adoc index bf22a9ecf..feda5a6d9 100644 --- a/Language/Functions/Math/pow.adoc +++ b/Language/Functions/Math/pow.adoc @@ -17,7 +17,7 @@ subCategories: [ "Math" ] [float] === Description -Calculates the value of a number raised to a power. `Pow()` can be used to raise a number to a fractional power. This is useful for generating exponential mapping of values or curves. +Calculates the value of a number raised to a power. `pow()` can be used to raise a number to a fractional power. This is useful for generating exponential mapping of values or curves. [%hardbreaks] @@ -28,13 +28,13 @@ Calculates the value of a number raised to a power. `Pow()` can be used to raise [float] === Parameters -`base`: the number (`float`) +`base`: the number. Allowed data types: `float`. + +`exponent`: the power to which the base is raised. Allowed data types: `float`. -`exponent`: the power to which the base is raised (`float`) [float] === Returns -The result of the exponentiation. (`double`) +The result of the exponentiation. Data type: `double`. -- // OVERVIEW SECTION ENDS @@ -47,7 +47,13 @@ The result of the exponentiation. (`double`) [float] === Example Code // Describe what the example code is all about and add relevant code ►►►►► THIS SECTION IS MANDATORY ◄◄◄◄◄ -See the (http://arduino.cc/playground/Main/Fscale[fscale]) function in the code library. +Calculate the value of x raised to the power of y: +[source,arduino] +---- +z = pow(x, y); +---- +See the (http://arduino.cc/playground/Main/Fscale[fscale]) sketch for a more complex example of the use of `pow()`. +[%hardbreaks] -- // HOW TO USE SECTION ENDS @@ -60,9 +66,15 @@ See the (http://arduino.cc/playground/Main/Fscale[fscale]) function in the code [float] === See also -[role="definition"] -* #DEFINITION# link:../../../variables/data-types/float[float] -* #DEFENITION# link:../../../variables/data-types/double[double] +[role="language"] +* #LANGUAGE# link:../abs[abs()] +* #LANGUAGE# link:../constrain[constrain()] +* #LANGUAGE# link:../map[map()] +* #LANGUAGE# link:../max[max()] +* #LANGUAGE# link:../min[min()] +* #LANGUAGE# link:../sq[sq()] +* #LANGUAGE# link:../sqrt[sqrt()] + -- // SEE ALSO SECTION ENDS diff --git a/Language/Functions/Math/sq.adoc b/Language/Functions/Math/sq.adoc index 759fec4f0..ac403498d 100644 --- a/Language/Functions/Math/sq.adoc +++ b/Language/Functions/Math/sq.adoc @@ -28,11 +28,58 @@ Calculates the square of a number: the number multiplied by itself. [float] === Parameters -`x`: the number, any data type +`x`: the number. Allowed data types: any data type. + [float] === Returns -The square of the number. (double) +The square of the number. Data type: `double`. + +-- +// OVERVIEW SECTION ENDS + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Notes and Warnings +Because of the way the `sq()` function is implemented, avoid using other functions inside the brackets, it may lead to incorrect results. + +This code will yield incorrect results: +[source,arduino] +---- +int inputSquared = sq(Serial.parseInt()); // avoid this +---- + +Use this instead: +[source,arduino] +---- +int input = Serial.parseInt(); // keep other operations outside the sq function +int inputSquared = sq(input); +---- +[%hardbreaks] + +-- +// HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +[role="language"] +* #LANGUAGE# link:../abs[abs()] +* #LANGUAGE# link:../constrain[constrain()] +* #LANGUAGE# link:../map[map()] +* #LANGUAGE# link:../max[max()] +* #LANGUAGE# link:../min[min()] +* #LANGUAGE# link:../pow[pow()] +* #LANGUAGE# link:../sqrt[sqrt()] -- -// OVERVIEW SECTION ENDS \ No newline at end of file +// SEE ALSO SECTION ENDS diff --git a/Language/Functions/Math/sqrt.adoc b/Language/Functions/Math/sqrt.adoc index fbb6940ee..00f601091 100644 --- a/Language/Functions/Math/sqrt.adoc +++ b/Language/Functions/Math/sqrt.adoc @@ -28,11 +28,32 @@ Calculates the square root of a number. [float] === Parameters -`x`: the number, any data type +`x`: the number. Allowed data types: any data type. + [float] === Returns -The number's square root. (double) +The number's square root. Data type: `double`. + +-- +// OVERVIEW SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +[role="language"] +* #LANGUAGE# link:../abs[abs()] +* #LANGUAGE# link:../constrain[constrain()] +* #LANGUAGE# link:../map[map()] +* #LANGUAGE# link:../max[max()] +* #LANGUAGE# link:../min[min()] +* #LANGUAGE# link:../pow[pow()] +* #LANGUAGE# link:../sq[sq()] -- -// OVERVIEW SECTION ENDS \ No newline at end of file +// SEE ALSO SECTION ENDS diff --git a/Language/Functions/Random Numbers/random.adoc b/Language/Functions/Random Numbers/random.adoc index 39d7e2550..c7c76903e 100644 --- a/Language/Functions/Random Numbers/random.adoc +++ b/Language/Functions/Random Numbers/random.adoc @@ -29,13 +29,13 @@ The random function generates pseudo-random numbers. [float] === Parameters -`min` - lower bound of the random value, inclusive (optional) +`min`: lower bound of the random value, inclusive (optional). + +`max`: upper bound of the random value, exclusive. -`max` - upper bound of the random value, exclusive [float] === Returns -A random number between min and max-1 (`long`) . +A random number between min and max-1. Data type: `long`. -- // OVERVIEW SECTION ENDS @@ -56,7 +56,7 @@ The code generates random numbers and displays them. ---- long randNumber; -void setup(){ +void setup() { Serial.begin(9600); // if analog input pin 0 is unconnected, random analog @@ -90,3 +90,14 @@ The `max` parameter should be chosen according to the data type of the variable -- // HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Functions/Random Numbers/randomSeed.adoc b/Language/Functions/Random Numbers/randomSeed.adoc index 814c7bacf..13ee2ad5e 100644 --- a/Language/Functions/Random Numbers/randomSeed.adoc +++ b/Language/Functions/Random Numbers/randomSeed.adoc @@ -25,12 +25,15 @@ Conversely, it can occasionally be useful to use pseudo-random sequences that re [%hardbreaks] - +[float] +=== Syntax +`randomSeed(seed)` [float] === Parameters -`seed` - number to initialize the pseudo-random sequence (unsigned long). +`seed`: non-zero number to initialize the pseudo-random sequence. Allowed data types: `unsigned long`. + [float] === Returns @@ -49,24 +52,39 @@ Nothing [float] === Example Code // Describe what the example code is all about and add relevant code ►►►►► THIS SECTION IS MANDATORY ◄◄◄◄◄ -The code explanation required. +The code generates a pseudo-random number and sends the generated number to the serial port. [source,arduino] ---- long randNumber; -void setup(){ +void setup() { Serial.begin(9600); randomSeed(analogRead(0)); } -void loop(){ +void loop() { randNumber = random(300); Serial.println(randNumber); - delay(50); } ---- +[%hardbreaks] + +[float] +=== Notes and Warnings +If the `seed` is 0, `randomSeed(seed)` will have no effect. -- // HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Functions/Time/delay.adoc b/Language/Functions/Time/delay.adoc index c5eb71f74..b47fc9ec3 100644 --- a/Language/Functions/Time/delay.adoc +++ b/Language/Functions/Time/delay.adoc @@ -28,7 +28,8 @@ Pauses the program for the amount of time (in milliseconds) specified as paramet [float] === Parameters -`ms`: the number of milliseconds to pause (`unsigned long`) +`ms`: the number of milliseconds to pause. Allowed data types: `unsigned long`. + [float] === Returns @@ -51,28 +52,26 @@ The code pauses the program for one second before toggling the output pin. [source,arduino] ---- -int ledPin = 13; // LED connected to digital pin 13 +int ledPin = 13; // LED connected to digital pin 13 -void setup() -{ - pinMode(ledPin, OUTPUT); // sets the digital pin as output +void setup() { + pinMode(ledPin, OUTPUT); // sets the digital pin as output } -void loop() -{ - digitalWrite(ledPin, HIGH); // sets the LED on - delay(1000); // waits for a second - digitalWrite(ledPin, LOW); // sets the LED off - delay(1000); // waits for a second +void loop() { + digitalWrite(ledPin, HIGH); // sets the LED on + delay(1000); // waits for a second + digitalWrite(ledPin, LOW); // sets the LED off + delay(1000); // waits for a second } ---- [%hardbreaks] [float] === Notes and Warnings -While it is easy to create a blinking LED with the `delay()` function, and many sketches use short delays for such tasks as switch debouncing, the use of `delay()` in a sketch has significant drawbacks. No other reading of sensors, mathematical calculations, or pin manipulation can go on during the delay function, so in effect, it brings most other activity to a halt. For alternative approaches to controlling timing see the link:../millis[millis()] function and the sketch sited below. More knowledgeable programmers usually avoid the use of `delay()` for timing of events longer than 10's of milliseconds unless the Arduino sketch is very simple. +While it is easy to create a blinking LED with the `delay()` function and many sketches use short delays for such tasks as switch debouncing, the use of `delay()` in a sketch has significant drawbacks. No other reading of sensors, mathematical calculations, or pin manipulation can go on during the delay function, so in effect, it brings most other activity to a halt. For alternative approaches to controlling timing see the link:http://arduino.cc/en/Tutorial/BlinkWithoutDelay[Blink Without Delay] sketch, which loops, polling the link:../millis[millis()] function until enough time has elapsed. More knowledgeable programmers usually avoid the use of `delay()` for timing of events longer than 10's of milliseconds unless the Arduino sketch is very simple. -Certain things do go on while the delay() function is controlling the Atmega chip however, because the delay function does not disable interrupts. Serial communication that appears at the RX pin is recorded, PWM (link:../../analog-io/analogwrite[analogWrite]) values and pin states are maintained, and link:../../external-interrupts/attachinterrupt[interrupts] will work as they should. +Certain things do go on while the delay() function is controlling the Atmega chip, however, because the delay function does not disable interrupts. Serial communication that appears at the RX pin is recorded, PWM (link:../../analog-io/analogwrite[analogWrite]) values and pin states are maintained, and link:../../external-interrupts/attachinterrupt[interrupts] will work as they should. -- // HOW TO USE SECTION ENDS @@ -86,7 +85,7 @@ Certain things do go on while the delay() function is controlling the Atmega chi === See also [role="example"] -* #EXAMPLE# http://arduino.cc/en/Tutorial/BlinkWithoutDelay[Blink Without Delay] +* #EXAMPLE# http://arduino.cc/en/Tutorial/BlinkWithoutDelay[Blink Without Delay^] -- // SEE ALSO SECTION ENDS diff --git a/Language/Functions/Time/delayMicroseconds.adoc b/Language/Functions/Time/delayMicroseconds.adoc index 542aaf509..7b57914da 100644 --- a/Language/Functions/Time/delayMicroseconds.adoc +++ b/Language/Functions/Time/delayMicroseconds.adoc @@ -17,9 +17,9 @@ subCategories: [ "Time" ] [float] === Description -Pauses the program for the amount of time (in microseconds) specified as parameter. There are a thousand microseconds in a millisecond, and a million microseconds in a second. +Pauses the program for the amount of time (in microseconds) specified by the parameter. There are a thousand microseconds in a millisecond and a million microseconds in a second. -Currently, the largest value that will produce an accurate delay is 16383. This could change in future Arduino releases. For delays longer than a few thousand microseconds, you should use `delay()` instead. +Currently, the largest value that will produce an accurate delay is 16383; larger values can produce an extremely short delay. This could change in future Arduino releases. For delays longer than a few thousand microseconds, you should use `delay()` instead. [%hardbreaks] @@ -30,7 +30,8 @@ Currently, the largest value that will produce an accurate delay is 16383. This [float] === Parameters -`us`: the number of microseconds to pause (`unsigned int`) +`us`: the number of microseconds to pause. Allowed data types: `unsigned int`. + [float] === Returns @@ -49,32 +50,39 @@ Nothing [float] === Example Code // Describe what the example code is all about and add relevant code ►►►►► THIS SECTION IS MANDATORY ◄◄◄◄◄ -The code configures pin number 8 to work as an output pin. It sends a train of pulses of approximately 100 microseconds period. The approximation is due to execution of the other instructions in the code. +The code configures pin number 8 to work as an output pin. It sends a train of pulses of approximately 100 microseconds period. The approximation is due to execution of the other instructions in the code. [source,arduino] ---- -int outPin = 8; // digital pin 8 +int outPin = 8; // digital pin 8 -void setup() -{ - pinMode(outPin, OUTPUT); // sets the digital pin as output +void setup() { + pinMode(outPin, OUTPUT); // sets the digital pin as output } -void loop() -{ - digitalWrite(outPin, HIGH); // sets the pin on - delayMicroseconds(50); // pauses for 50 microseconds - digitalWrite(outPin, LOW); // sets the pin off - delayMicroseconds(50); // pauses for 50 microseconds +void loop() { + digitalWrite(outPin, HIGH); // sets the pin on + delayMicroseconds(50); // pauses for 50 microseconds + digitalWrite(outPin, LOW); // sets the pin off + delayMicroseconds(50); // pauses for 50 microseconds } ---- [%hardbreaks] [float] === Notes and Warnings -This function works very accurately in the range 3 microseconds and up. We cannot assure that delayMicroseconds will perform precisely for smaller delay-times. - -As of Arduino 0018, delayMicroseconds() no longer disables interrupts. +This function works very accurately in the range 3 microseconds and up to 16383. We cannot assure that delayMicroseconds will perform precisely for smaller delay-times. Larger delay times may actually delay for an extremely brief time. -- // HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Functions/Time/micros.adoc b/Language/Functions/Time/micros.adoc index 64798d8c1..22fc13962 100644 --- a/Language/Functions/Time/micros.adoc +++ b/Language/Functions/Time/micros.adoc @@ -17,7 +17,7 @@ subCategories: [ "Time" ] [float] === Description -Returns the number of microseconds since the Arduino board began running the current program. This number will overflow (go back to zero), after approximately 70 minutes. On 16 MHz Arduino boards (e.g. Duemilanove and Nano), this function has a resolution of four microseconds (i.e. the value returned is always a multiple of four). On 8 MHz Arduino boards (e.g. the LilyPad), this function has a resolution of eight microseconds. +Returns the number of microseconds since the Arduino board began running the current program. This number will overflow (go back to zero), after approximately 70 minutes. On the boards from the Arduino Portenta family this function has a resolution of one microsecond on all cores. On 16 MHz Arduino boards (e.g. Duemilanove and Nano), this function has a resolution of four microseconds (i.e. the value returned is always a multiple of four). On 8 MHz Arduino boards (e.g. the LilyPad), this function has a resolution of eight microseconds. [%hardbreaks] @@ -28,11 +28,12 @@ Returns the number of microseconds since the Arduino board began running the cur [float] === Parameters -Nothing +None + [float] === Returns -Returns the number of microseconds since the Arduino board began running the current program.(unsigned long) +Returns the number of microseconds since the Arduino board began running the current program. Data type: `unsigned long`. -- // OVERVIEW SECTION ENDS @@ -53,15 +54,15 @@ The code returns the number of microseconds since the Arduino board began. ---- unsigned long time; -void setup(){ +void setup() { Serial.begin(9600); } -void loop(){ +void loop() { Serial.print("Time: "); time = micros(); - Serial.println(time); //prints time since program started - delay(1000); // wait a second so as not to send massive amounts of data + Serial.println(time); //prints time since program started + delay(1000); // wait a second so as not to send massive amounts of data } ---- [%hardbreaks] @@ -72,3 +73,14 @@ There are 1,000 microseconds in a millisecond and 1,000,000 microseconds in a se -- // HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Functions/Time/millis.adoc b/Language/Functions/Time/millis.adoc index 0c08e10ad..cecb109dd 100644 --- a/Language/Functions/Time/millis.adoc +++ b/Language/Functions/Time/millis.adoc @@ -4,20 +4,15 @@ categories: [ "Functions" ] subCategories: [ "Time" ] --- - - - - = millis() - // OVERVIEW SECTION STARTS [#overview] -- [float] === Description -Returns the number of milliseconds since the Arduino board began running the current program. This number will overflow (go back to zero), after approximately 50 days. +Returns the number of milliseconds passed since the Arduino board began running the current program. This number will overflow (go back to zero), after approximately 50 days. [%hardbreaks] @@ -28,11 +23,12 @@ Returns the number of milliseconds since the Arduino board began running the cur [float] === Parameters -Nothing +None + [float] === Returns -Number of milliseconds since the program started (unsigned long) +Number of milliseconds passed since the program started. Data type: `unsigned long`. -- // OVERVIEW SECTION ENDS @@ -47,28 +43,32 @@ Number of milliseconds since the program started (unsigned long) [float] === Example Code // Describe what the example code is all about and add relevant code ►►►►► THIS SECTION IS MANDATORY ◄◄◄◄◄ -The code reads the milllisecond since the Arduino board began. +This example code prints on the serial port the number of milliseconds passed since the Arduino board started running the code itself. [source,arduino] ---- -unsigned long time; +unsigned long myTime; -void setup(){ +void setup() { Serial.begin(9600); } -void loop(){ +void loop() { Serial.print("Time: "); - time = millis(); + myTime = millis(); - Serial.println(time); //prints time since program started - delay(1000); // wait a second so as not to send massive amounts of data + Serial.println(myTime); // prints time since program started + delay(1000); // wait a second so as not to send massive amounts of data } ---- [%hardbreaks] [float] === Notes and Warnings -Please note that the return value for millis() is an unsigned long, logic errors may occur if a programmer tries to do arithmetic with smaller data types such as int's. Even signed long may encounter errors as its maximum value is half that of its unsigned counterpart. + +* The return value for millis() is of type `unsigned long`, logic errors may occur if a programmer tries to do arithmetic with smaller data types such as `int`. Even signed `long` may encounter errors as its maximum value is half that of its unsigned counterpart. +* millis() is incremented (for 16 MHz AVR chips and some others) every 1.024 milliseconds, then incrementing by 2 (rather than 1) every 41 or 42 ticks, to pull it back into synch; thus some millis() values are skipped. For accurate timing over short intervals, consider using micros(). +* millis() will wrap around to 0 after about 49 days (micros in about 71 minutes). +* Reconfiguration of the microcontroller's timers may result in inaccurate `millis()` readings. The "Arduino AVR Boards" and "Arduino megaAVR Boards" cores use Timer0 to generate `millis()`. The "Arduino ARM (32-bits) Boards" and "Arduino SAMD (32-bits ARM Cortex-M0+) Boards" cores use the SysTick timer. -- // HOW TO USE SECTION ENDS @@ -82,7 +82,7 @@ Please note that the return value for millis() is an unsigned long, logic errors === See also [role="example"] -* #EXAMPLE# http://arduino.cc/en/Tutorial/BlinkWithoutDelay[Blink Without Delay] +* #EXAMPLE# http://arduino.cc/en/Tutorial/BlinkWithoutDelay[Blink Without Delay^] -- // SEE ALSO SECTION ENDS diff --git a/Language/Functions/Trigonometry/cos.adoc b/Language/Functions/Trigonometry/cos.adoc index 07c6e86b1..f9f9fdc1c 100644 --- a/Language/Functions/Trigonometry/cos.adoc +++ b/Language/Functions/Trigonometry/cos.adoc @@ -28,11 +28,12 @@ Calculates the cosine of an angle (in radians). The result will be between -1 an [float] === Parameters -`rad`: The angle in Radians (float). +`rad`: The angle in radians. Allowed data types: `float`. + [float] === Returns -The cos of the angle (`double`). +The cos of the angle. Data type: `double`. -- // OVERVIEW SECTION ENDS diff --git a/Language/Functions/Trigonometry/sin.adoc b/Language/Functions/Trigonometry/sin.adoc index 3d3237848..0cc7fd95b 100644 --- a/Language/Functions/Trigonometry/sin.adoc +++ b/Language/Functions/Trigonometry/sin.adoc @@ -28,11 +28,12 @@ Calculates the sine of an angle (in radians). The result will be between -1 and [float] === Parameters -`rad`: The angle in Radians (`float`). +`rad`: The angle in radians. Allowed data types: `float`. + [float] === Returns -The sine of the angle (`double`). +The sine of the angle. Data type: `double`. -- // OVERVIEW SECTION ENDS diff --git a/Language/Functions/Trigonometry/tan.adoc b/Language/Functions/Trigonometry/tan.adoc index 277db9ff2..193730123 100644 --- a/Language/Functions/Trigonometry/tan.adoc +++ b/Language/Functions/Trigonometry/tan.adoc @@ -28,11 +28,12 @@ Calculates the tangent of an angle (in radians). The result will be between nega [float] === Parameters -`rad`: The angle in Radians (`float`). +`rad`: The angle in radians. Allowed data types: `float`. + [float] === Returns -The tangent of the angle (`double`). +The tangent of the angle. Data type: `double`. -- // OVERVIEW SECTION ENDS diff --git a/Language/Functions/USB/Keyboard.adoc b/Language/Functions/USB/Keyboard.adoc index 80c4b0b30..6773f0e69 100644 --- a/Language/Functions/USB/Keyboard.adoc +++ b/Language/Functions/USB/Keyboard.adoc @@ -24,13 +24,30 @@ The library supports the use of modifier keys. Modifier keys change the behavior -- // OVERVIEW SECTION ENDS +[float] +=== Compatible Hardware +HID is supported on the following boards: +[options="header"] +|================================================================================================= +| Board | Supported Pins +| link:https://docs.arduino.cc/hardware/leonardo[Leonardo] | All digital & analog pins +| link:https://docs.arduino.cc/hardware/micro[Micro] | All digital & analog pins +| link:https://docs.arduino.cc/hardware/due[Due] | All digital & analog pins +| link:https://docs.arduino.cc/hardware/zero[Zero] | All digital & analog pins +| link:https://docs.arduino.cc/hardware/uno-r4-minima[UNO R4 Minima] | All digital & analog pins +| link:https://docs.arduino.cc/hardware/uno-r4-wifi[UNO R4 WiFi] | All digital & analog pins +| link:https://docs.arduino.cc/hardware/giga-r1-wifi[Giga R1] | All digital & analog pins +| link:https://docs.arduino.cc/hardware/nano-esp32[Nano ESP32] | All digital & analog pins +| link:https://docs.arduino.cc/#mkr-family[MKR Family] | All digital & analog pins +|================================================================================================= + [float] === Notes and Warnings These core libraries allow the 32u4 and SAMD based boards (Leonardo, Esplora, Zero, Due and MKR Family) to appear as a native Mouse and/or Keyboard to a connected computer. [%hardbreaks] -*A word of caution on using the Mouse and Keyboard libraries*: if the Mouse or Keyboard library is constantly running, it will be difficult to program your board. Functions such as `Mouse.move()` and `Keyboard.print()` will move your cursor or send keystrokes to a connected computer and should only be called when you are ready to handle them. It is recommended to use a control system to turn this functionality on, like a physical switch or only responding to specific input you can control. +*A word of caution on using the Mouse and Keyboard libraries*: if the Mouse or Keyboard library is constantly running, it will be difficult to program your board. Functions such as `Mouse.move()` and `Keyboard.print()` will move your cursor or send keystrokes to a connected computer and should only be called when you are ready to handle them. It is recommended to use a control system to turn this functionality on, like a physical switch or only responding to specific input you can control. Refer to the Mouse and Keyboard examples for some ways to handle this. [%hardbreaks] -When using the Mouse or Keyboard library, it may be best to test your output first using `Serial.print()`. This way, you can be sure you know what values are being reported. Refer to the Mouse and Keyboard examples for some ways to handle this. +When using the Mouse or Keyboard library, it may be best to test your output first using link:../../communication/serial/print[Serial.print()]. This way, you can be sure you know what values are being reported. // FUNCTIONS SECTION STARTS @@ -64,11 +81,11 @@ link:../keyboard/keyboardwrite[Keyboard.write()] === See also [role="example"] -* #EXAMPLE# http://www.arduino.cc/en/Tutorial/KeyboardAndMouseControl[KeyboardAndMouseControl]: Demonstrates the Mouse and Keyboard commands in one program. -* #EXAMPLE# http://www.arduino.cc/en/Tutorial/KeyboardMessage[KeyboardMessage]: Sends a text string when a button is pressed. -* #EXAMPLE# http://www.arduino.cc/en/Tutorial/KeyboardLogout[KeyboardLogout]: Logs out the current user with key commands -* #EXAMPLE# http://www.arduino.cc/en/Tutorial/KeyboardSerial[KeyboardSerial]: Reads a byte from the serial port, and sends back a keystroke. -* #EXAMPLE# http://www.arduino.cc/en/Tutorial/KeyboardReprogram[KeyboardReprogram]: opens a new window in the Arduino IDE and reprograms the board with a simple blink program +* #EXAMPLE# http://www.arduino.cc/en/Tutorial/KeyboardAndMouseControl[KeyboardAndMouseControl^]: Demonstrates the Mouse and Keyboard commands in one program. +* #EXAMPLE# http://www.arduino.cc/en/Tutorial/KeyboardMessage[KeyboardMessage^]: Sends a text string when a button is pressed. +* #EXAMPLE# http://www.arduino.cc/en/Tutorial/KeyboardLogout[KeyboardLogout^]: Logs out the current user with key commands +* #EXAMPLE# http://www.arduino.cc/en/Tutorial/KeyboardSerial[KeyboardSerial^]: Reads a byte from the serial port, and sends back a keystroke. +* #EXAMPLE# http://www.arduino.cc/en/Tutorial/KeyboardReprogram[KeyboardReprogram^]: opens a new window in the Arduino IDE and reprograms the board with a simple blink program -- // SEE ALSO SECTION ENDS diff --git a/Language/Functions/USB/Keyboard/keyboardBegin.adoc b/Language/Functions/USB/Keyboard/keyboardBegin.adoc index 39f0c5e4d..52e352203 100644 --- a/Language/Functions/USB/Keyboard/keyboardBegin.adoc +++ b/Language/Functions/USB/Keyboard/keyboardBegin.adoc @@ -20,12 +20,29 @@ When used with a Leonardo or Due board, `Keyboard.begin()` starts emulating a ke [float] === Syntax -`Keyboard.begin()` +`Keyboard.begin()` + +`Keyboard.begin(layout)` [float] === Parameters -Nothing +`layout`: the keyboard layout to use. This parameter is optional and defaults to `KeyboardLayout_en_US`. + + +[float] +=== Keyboard layouts +Currently, the library supports the following national keyboard layouts: + +* `KeyboardLayout_da_DK`: Denmark +* `KeyboardLayout_de_DE`: Germany +* `KeyboardLayout_en_US`: USA +* `KeyboardLayout_es_ES`: Spain +* `KeyboardLayout_fr_FR`: France +* `KeyboardLayout_hu_HU`: Hungary +* `KeyboardLayout_it_IT`: Italy +* `KeyboardLayout_pt_PT`: Portugal +* `KeyboardLayout_sv_SE`: Sweden + [float] === Returns @@ -60,11 +77,17 @@ void setup() { void loop() { //if the button is pressed - if(digitalRead(2)==LOW){ + if (digitalRead(2) == LOW) { //Send the message Keyboard.print("Hello!"); } } ---- -// HOW TO USE SECTION ENDS \ No newline at end of file + +[float] +=== Notes and Warnings +Custom layouts can be created by copying and modifying an existing layout. See the instructions in the Keyboard library's KeyboardLayout.h file. + +-- +// HOW TO USE SECTION ENDS diff --git a/Language/Functions/USB/Keyboard/keyboardEnd.adoc b/Language/Functions/USB/Keyboard/keyboardEnd.adoc index 4dc0fc7b4..134ebdc0b 100644 --- a/Language/Functions/USB/Keyboard/keyboardEnd.adoc +++ b/Language/Functions/USB/Keyboard/keyboardEnd.adoc @@ -25,7 +25,8 @@ Stops the keyboard emulation to a connected computer. To start keyboard emulatio [float] === Parameters -Nothing +None + [float] === Returns @@ -60,7 +61,7 @@ void setup() { } void loop() { - //do nothing + //do nothing } ---- diff --git a/Language/Functions/USB/Keyboard/keyboardModifiers.adoc b/Language/Functions/USB/Keyboard/keyboardModifiers.adoc index 15976a8cf..3ecd403df 100644 --- a/Language/Functions/USB/Keyboard/keyboardModifiers.adoc +++ b/Language/Functions/USB/Keyboard/keyboardModifiers.adoc @@ -1,11 +1,11 @@ --- -title: Keyboard Modifiers +title: Keyboard Modifiers and Special Keys --- -= Keyboard Modifiers += Keyboard modifiers and special keys // OVERVIEW SECTION STARTS @@ -14,56 +14,165 @@ title: Keyboard Modifiers [float] === Description -The `Keyboard.write()` and `Keyboard.press()` and `Keyboard.release()` commands don’t work with every possible ASCII character, only those that correspond to a key on the keyboard. For example, backspace works, but many of the other non-printable characters produce unpredictable results. For capital letters (and other keys), what’s sent is shift plus the character (i.e. the equivalent of pressing both of those keys on the keyboard). -[%hardbreaks] -A modifier key is a special key on a computer keyboard that modifies the normal action of another key when the two are pressed in combination. -[%hardbreaks] -For more on ASCII values and the characters or functions they represent, see http://www.asciitable.com/[asciitable.com] -[%hardbreaks] -For multiple key presses use link:../keyboardpress[Keyboard.press]() -[%hardbreaks] -The Leonardo's definitions for modifier keys are listed below: +When given a printable ASCII character as an argument, the functions `Keyboard.write()`, `Keyboard.press()` and `Keyboard.release()` simulate actuations on the corresponding keys. These functions can also handle ASCII characters that require pressing a key in combination with Shift or, on international keyboards, AltGr. For example: +[source,arduino] +---- +Keyboard.write('a'); // press and release the 'A' key +Keyboard.write('A'); // press Shift and 'A', then release both +---- +A typical keyboard, however, has many keys that do not match a printable ASCII character. In order to simulate those keys, the library provides a set of macros that can be passed as arguments to `Keyboard.write()`, `Keyboard.press()` and `Keyboard.release()`. For example, the key combination Shift+F2 can be generated by: +[source,arduino] +---- +Keyboard.press(KEY_LEFT_SHIFT); // press and hold Shift +Keyboard.press(KEY_F2); // press and hold F2 +Keyboard.releaseAll(); // release both +---- +Note that, in order to press multiple keys simultaneously, one has to use link:../keyboardpress[`Keyboard.press()`] rather than link:../keyboardwrite[`Keyboard.write()`], as the latter just “hits” the keys (it presses and immediately releases them). [%hardbreaks] +The available macros are listed below: + +[float] +=== Keyboard modifiers +These keys are meant to modify the normal action of another key when the two are pressed in combination. + +|=== +|Key |Hexadecimal value |Decimal value |Notes + +|KEY_LEFT_CTRL |0x80 |128 | +|KEY_LEFT_SHIFT |0x81 |129 | +|KEY_LEFT_ALT |0x82 |130 |Option (⌥) on Mac +|KEY_LEFT_GUI |0x83 |131 |OS logo, Command (⌘) on Mac +|KEY_RIGHT_CTRL |0x84 |132 | +|KEY_RIGHT_SHIFT |0x85 |133 | +|KEY_RIGHT_ALT |0x86 |134 |also AltGr, Option (⌥) on Mac +|KEY_RIGHT_GUI |0x87 |135 |OS logo, Command (⌘) on Mac +|=== + +[float] +=== Special keys +These are all the keys that do not match a printable ASCII character and are not modifiers. + +[float] +==== Within the alphanumeric cluster + +|=== +|Key |Hexadecimal value |Decimal value + +|KEY_TAB |0xB3 |179 +|KEY_CAPS_LOCK |0xC1 |193 +|KEY_BACKSPACE |0xB2 |178 +|KEY_RETURN |0xB0 |176 +|KEY_MENU |0xED |237 +|=== + +[float] +==== Navigation cluster + +|=== +|Key |Hexadecimal value |Decimal value +|KEY_INSERT |0xD1 |209 +|KEY_DELETE |0xD4 |212 +|KEY_HOME |0xD2 |210 +|KEY_END |0xD5 |213 +|KEY_PAGE_UP |0xD3 |211 +|KEY_PAGE_DOWN |0xD6 |214 +|KEY_UP_ARROW |0xDA |218 +|KEY_DOWN_ARROW |0xD9 |217 +|KEY_LEFT_ARROW |0xD8 |216 +|KEY_RIGHT_ARROW |0xD7 |215 +|=== + +[float] +==== Numeric keypad + +|=== +|Key |Hexadecimal value |Decimal value + +|KEY_NUM_LOCK |0xDB |219 +|KEY_KP_SLASH |0xDC |220 +|KEY_KP_ASTERISK |0xDD |221 +|KEY_KP_MINUS |0xDE |222 +|KEY_KP_PLUS |0xDF |223 +|KEY_KP_ENTER |0xE0 |224 +|KEY_KP_1 |0xE1 |225 +|KEY_KP_2 |0xE2 |226 +|KEY_KP_3 |0xE3 |227 +|KEY_KP_4 |0xE4 |228 +|KEY_KP_5 |0xE5 |229 +|KEY_KP_6 |0xE6 |230 +|KEY_KP_7 |0xE7 |231 +|KEY_KP_8 |0xE8 |232 +|KEY_KP_9 |0xE9 |233 +|KEY_KP_0 |0xEA |234 +|KEY_KP_DOT |0xEB |235 +|=== + +[float] +==== Escape and function keys +The library can simulate function keys up to F24. |=== |Key |Hexadecimal value |Decimal value -|KEY_LEFT_CTRL |0x80 |128 -|KEY_LEFT_SHIFT |0x81 |129 -|KEY_LEFT_ALT |0x82 |130 -|KEY_LEFT_GUI |0x83 |131 -|KEY_RIGHT_CTRL |0x84 |132 -|KEY_RIGHT_SHIFT |0x85 |133 -|KEY_RIGHT_ALT |0x86 |134 -|KEY_RIGHT_GUI |0x87 |135 -|KEY_UP_ARROW |0xDA |218 -|KEY_DOWN_ARROW |0xD9 |217 -|KEY_LEFT_ARROW |0xD8 |216 -|KEY_RIGHT_ARROW |0xD7 |215 -|KEY_BACKSPACE |0xB2 |178 -|KEY_TAB |0xB3 |179 -|KEY_RETURN |0xB0 |176 -|KEY_ESC |0xB1 |177 -|KEY_INSERT |0xD1 |209 -|KEY_DELETE |0xD4 |212 -|KEY_PAGE_UP |0xD3 |211 -|KEY_PAGE_DOWN |0xD6 |214 -|KEY_HOME |0xD2 |210 -|KEY_END |0xD5 |213 -|KEY_CAPS_LOCK |0xC1 |193 -|KEY_F1 |0xC2 |194 -|KEY_F2 |0xC3 |195 -|KEY_F3 |0xC4 |196 -|KEY_F4 |0xC5 |197 -|KEY_F5 |0xC6 |198 -|KEY_F6 |0xC7 |199 -|KEY_F7 |0xC8 |200 -|KEY_F8 |0xC9 |201 -|KEY_F9 |0xCA |202 -|KEY_F10 |0xCB |203 -|KEY_F11 |0xCC |204 -|KEY_F12 |0xCD |205 +|KEY_ESC |0xB1 |177 +|KEY_F1 |0xC2 |194 +|KEY_F2 |0xC3 |195 +|KEY_F3 |0xC4 |196 +|KEY_F4 |0xC5 |197 +|KEY_F5 |0xC6 |198 +|KEY_F6 |0xC7 |199 +|KEY_F7 |0xC8 |200 +|KEY_F8 |0xC9 |201 +|KEY_F9 |0xCA |202 +|KEY_F10 |0xCB |203 +|KEY_F11 |0xCC |204 +|KEY_F12 |0xCD |205 +|KEY_F13 |0xF0 |240 +|KEY_F14 |0xF1 |241 +|KEY_F15 |0xF2 |242 +|KEY_F16 |0xF3 |243 +|KEY_F17 |0xF4 |244 +|KEY_F18 |0xF5 |245 +|KEY_F19 |0xF6 |246 +|KEY_F20 |0xF7 |247 +|KEY_F21 |0xF8 |248 +|KEY_F22 |0xF9 |249 +|KEY_F23 |0xFA |250 +|KEY_F24 |0xFB |251 +|=== + +[float] +==== Function control keys +These are three keys that sit above the navigation cluster. + +|=== +|Key |Hexadecimal value |Decimal value |Notes + +|KEY_PRINT_SCREEN |0xCE |206 |Print Screen or PrtSc / SysRq +|KEY_SCROLL_LOCK |0xCF |207 | +|KEY_PAUSE |0xD0 |208 |Pause / Break +|=== + +[float] +==== International keyboard layouts + +Some national layouts define extra keys. For example, the Swedish and Danish layouts define `KEY_A_RING` as `0xB7`, which is the key to the right of “P”, labeled “Å” on those layouts and “{”/“[” on the US layout. In order to use those definitions, one has to include the proper Keyboard_*.h file. For example: + +[source,arduino] +---- +#include +#include // extra key definitions from Swedish layout + +void setup() { + Keyboard.begin(KeyboardLayout_sv_SE); // use the Swedish layout + Keyboard.write(KEY_A_RING); +} + +void loop() {} // do-nothing loop +---- + +For the list of layout-specific key definitions, see the respective Keyboard_*.h file within the library sources. -- -// OVERVIEW SECTION ENDS \ No newline at end of file +// OVERVIEW SECTION ENDS diff --git a/Language/Functions/USB/Keyboard/keyboardPress.adoc b/Language/Functions/USB/Keyboard/keyboardPress.adoc index ec22ca15a..a20a84da4 100644 --- a/Language/Functions/USB/Keyboard/keyboardPress.adoc +++ b/Language/Functions/USB/Keyboard/keyboardPress.adoc @@ -22,16 +22,17 @@ It is necessary to call link:../keyboardbegin[Keyboard.begin()] before using `pr [float] === Syntax -`Keyboard.press()` +`Keyboard.press(key)` [float] === Parameters -`char` : the key to press +`key`: the key to press. Allowed data types: `char`. + [float] === Returns -`size_t` : number of key presses sent. +Number of key presses sent. Data type: `size_t`. -- // OVERVIEW SECTION ENDS @@ -79,6 +80,7 @@ void loop() { Keyboard.releaseAll(); // wait for new window to open: delay(1000); +} ---- -- diff --git a/Language/Functions/USB/Keyboard/keyboardPrint.adoc b/Language/Functions/USB/Keyboard/keyboardPrint.adoc index 620f3fee5..f93530145 100644 --- a/Language/Functions/USB/Keyboard/keyboardPrint.adoc +++ b/Language/Functions/USB/Keyboard/keyboardPrint.adoc @@ -14,7 +14,7 @@ title: Keyboard.print() [float] === Description -Sends a keystroke to a connected computer. +Sends one or more keystrokes to a connected computer. `Keyboard.print()` must be called after initiating link:../keyboardbegin[Keyboard.begin()]. [%hardbreaks] @@ -25,13 +25,16 @@ Sends a keystroke to a connected computer. `Keyboard.print(character)` + `Keyboard.print(characters)` + [float] === Parameters -`character` : a char or int to be sent to the computer as a keystroke characters : a string to be sent to the computer as a keystroke. +`character`: a char or int to be sent to the computer as a keystroke. + +`characters`: a string to be sent to the computer as keystrokes. + [float] === Returns -`size_t` : number of bytes sent. +Number of keystrokes sent. Data type: `size_t`. -- // OVERVIEW SECTION ENDS @@ -62,7 +65,7 @@ void setup() { void loop() { //if the button is pressed - if(digitalRead(2)==LOW){ + if (digitalRead(2) == LOW) { //Send the message Keyboard.print("Hello!"); } diff --git a/Language/Functions/USB/Keyboard/keyboardPrintln.adoc b/Language/Functions/USB/Keyboard/keyboardPrintln.adoc index 3641bb837..062b9c92f 100644 --- a/Language/Functions/USB/Keyboard/keyboardPrintln.adoc +++ b/Language/Functions/USB/Keyboard/keyboardPrintln.adoc @@ -14,7 +14,7 @@ title: Keyboard.println() [float] === Description -Sends a keystroke to a connected computer, followed by a newline and carriage return. +Sends one or more keystrokes to a connected computer, followed by a keystroke on the Enter key. `Keyboard.println()` must be called after initiating link:../keyboardbegin[Keyboard.begin()]. [%hardbreaks] @@ -23,18 +23,19 @@ Sends a keystroke to a connected computer, followed by a newline and carriage re [float] === Syntax `Keyboard.println()` + -`Keyboard.println(character)`+ +`Keyboard.println(character)` + `Keyboard.println(characters)` + [float] === Parameters -`character` : a char or int to be sent to the computer as a keystroke, followed by newline and carriage return. +`character`: a char or int to be sent to the computer as a keystroke, followed by Enter. + +`characters`: a string to be sent to the computer as keystrokes, followed by Enter. -`characters` : a string to be sent to the computer as a keystroke, followed by a newline and carriage return. [float] === Returns -`size_t` : number of bytes sent +Number of keystrokes sent. Data type: `size_t`. -- // OVERVIEW SECTION ENDS @@ -63,7 +64,7 @@ void setup() { void loop() { //if the button is pressed - if(digitalRead(2)==LOW){ + if (digitalRead(2) == LOW) { //Send the message Keyboard.println("Hello!"); } diff --git a/Language/Functions/USB/Keyboard/keyboardRelease.adoc b/Language/Functions/USB/Keyboard/keyboardRelease.adoc index 0769ec306..643e7de8e 100644 --- a/Language/Functions/USB/Keyboard/keyboardRelease.adoc +++ b/Language/Functions/USB/Keyboard/keyboardRelease.adoc @@ -25,11 +25,12 @@ Lets go of the specified key. See link:../keyboardpress[Keyboard.press()] for mo [float] === Parameters -`key` : the key to release. `char` +`key`: the key to release. Allowed data types: `char`. + [float] === Returns -`size_t` : the number of keys released +The number of keys released. Data type: `size_t`. -- // OVERVIEW SECTION ENDS diff --git a/Language/Functions/USB/Keyboard/keyboardReleaseAll.adoc b/Language/Functions/USB/Keyboard/keyboardReleaseAll.adoc index ce826c472..8952a280f 100644 --- a/Language/Functions/USB/Keyboard/keyboardReleaseAll.adoc +++ b/Language/Functions/USB/Keyboard/keyboardReleaseAll.adoc @@ -25,7 +25,8 @@ Lets go of all keys currently pressed. See link:../keyboardpress[Keyboard.press( [float] === Parameters -Nothing +None + [float] === Returns diff --git a/Language/Functions/USB/Keyboard/keyboardWrite.adoc b/Language/Functions/USB/Keyboard/keyboardWrite.adoc index daa38e626..6ff2155a7 100644 --- a/Language/Functions/USB/Keyboard/keyboardWrite.adoc +++ b/Language/Functions/USB/Keyboard/keyboardWrite.adoc @@ -16,7 +16,7 @@ title: Keyboard.write() === Description Sends a keystroke to a connected computer. This is similar to pressing and releasing a key on your keyboard. You can send some ASCII characters or the additional link:../keyboardmodifiers[keyboard modifiers and special keys]. -Only ASCII characters that are on the keyboard are supported. For example, ASCII 8 (backspace) would work, but ASCII 25 (Substitution) would not. When sending capital letters, Keyboard.write() sends a shift command plus the desired character, just as if typing on a keyboard. If sending a numeric type, it sends it as an ASCII character (ex. Keyboard.write(97) will send 'a'). +Only ASCII characters that are on the keyboard are supported. For example, ASCII 8 (backspace) would work, but ASCII 25 (Substitution) would not. When sending capital letters, `Keyboard.write()` sends a shift command plus the desired character, just as if typing on a keyboard. If sending a numeric type, it sends it as an ASCII character (ex. Keyboard.write(97) will send 'a'). For a complete list of ASCII characters, see http://www.asciitable.com/[ASCIITable.com]. [%hardbreaks] @@ -29,7 +29,7 @@ For a complete list of ASCII characters, see http://www.asciitable.com/[ASCIITab [float] === Parameters -`character` : a char or int to be sent to the computer. Can be sent in any notation that's acceptable for a char. For example, all of the below are acceptable and send the same value, 65 or ASCII A: +`character`: a char or int to be sent to the computer. Can be sent in any notation that's acceptable for a char. For example, all of the below are acceptable and send the same value, 65 or ASCII A: [source,arduino] ---- Keyboard.write(65); // sends ASCII value 65, or A @@ -38,9 +38,10 @@ Keyboard.write(0x41); // same thing in hexadecimal Keyboard.write(0b01000001); // same thing in binary (weird choice, but it works) ---- + [float] === Returns -`size_t` : number of bytes sent. +Number of bytes sent. Data type: `size_t`. -- // OVERVIEW SECTION ENDS @@ -71,7 +72,7 @@ void setup() { void loop() { //if the button is pressed - if(digitalRead(2)==LOW){ + if (digitalRead(2) == LOW) { //Send an ASCII 'A', Keyboard.write(65); } diff --git a/Language/Functions/USB/Mouse.adoc b/Language/Functions/USB/Mouse.adoc index cde0e0920..b4a8400b8 100644 --- a/Language/Functions/USB/Mouse.adoc +++ b/Language/Functions/USB/Mouse.adoc @@ -23,14 +23,30 @@ The mouse functions enable 32u4 or SAMD micro based boards to control cursor mov -- // OVERVIEW SECTION ENDS +[float] +=== Compatible Hardware +HID is supported on the following boards: +[options="header"] +|================================================================================================= +| Board | Supported Pins +| link:https://docs.arduino.cc/hardware/leonardo[Leonardo] | All digital & analog pins +| link:https://docs.arduino.cc/hardware/micro[Micro] | All digital & analog pins +| link:https://docs.arduino.cc/hardware/due[Due] | All digital & analog pins +| link:https://docs.arduino.cc/hardware/zero[Zero] | All digital & analog pins +| link:https://docs.arduino.cc/hardware/uno-r4-minima[UNO R4 Minima] | All digital & analog pins +| link:https://docs.arduino.cc/hardware/uno-r4-wifi[UNO R4 WiFi] | All digital & analog pins +| link:https://docs.arduino.cc/hardware/giga-r1-wifi[Giga R1] | All digital & analog pins +| link:https://docs.arduino.cc/hardware/nano-esp32[Nano ESP32] | All digital & analog pins +| link:https://docs.arduino.cc/#mkr-family[MKR Family] | All digital & analog pins +|================================================================================================= [float] === Notes and Warnings These core libraries allow the 32u4 and SAMD based boards (Leonardo, Esplora, Zero, Due and MKR Family) to appear as a native Mouse and/or Keyboard to a connected computer. [%hardbreaks] -*A word of caution on using the Mouse and Keyboard libraries*: if the Mouse or Keyboard library is constantly running, it will be difficult to program your board. Functions such as `Mouse.move()` and `Keyboard.print()` will move your cursor or send keystrokes to a connected computer and should only be called when you are ready to handle them. It is recommended to use a control system to turn this functionality on, like a physical switch or only responding to specific input you can control. +*A word of caution on using the Mouse and Keyboard libraries*: if the Mouse or Keyboard library is constantly running, it will be difficult to program your board. Functions such as `Mouse.move()` and `Keyboard.print()` will move your cursor or send keystrokes to a connected computer and should only be called when you are ready to handle them. It is recommended to use a control system to turn this functionality on, like a physical switch or only responding to specific input you can control. Refer to the Mouse and Keyboard examples for some ways to handle this. [%hardbreaks] -When using the Mouse or Keyboard library, it may be best to test your output first using `Serial.print()`. This way, you can be sure you know what values are being reported. Refer to the Mouse and Keyboard examples for some ways to handle this. +When using the Mouse or Keyboard library, it may be best to test your output first using link:../../communication/serial/print[Serial.print()]. This way, you can be sure you know what values are being reported. [%hardbreaks] // FUNCTIONS SECTION STARTS [#functions] @@ -62,10 +78,9 @@ link:../mouse/mouseispressed[Mouse.isPressed()] === See also [role="example"] -* #EXAMPLE# http://www.arduino.cc/en/Tutorial/KeyboardAndMouseControl[KeyboardAndMouseControl]: Demonstrates the Mouse and Keyboard commands in one program. -* #EXAMPLE# http://www.arduino.cc/en/Tutorial/ButtonMouseControl[ButtonMouseControl]: Control cursor movement with 5 pushbuttons. -* #EXAMPLE# http://www.arduino.cc/en/Tutorial/JoystickMouseControl[JoystickMouseControl]: Controls a computer's cursor movement with a Joystick when a button is pressed. +* #EXAMPLE# http://www.arduino.cc/en/Tutorial/KeyboardAndMouseControl[KeyboardAndMouseControl^]: Demonstrates the Mouse and Keyboard commands in one program. +* #EXAMPLE# http://www.arduino.cc/en/Tutorial/ButtonMouseControl[ButtonMouseControl^]: Control cursor movement with 5 pushbuttons. +* #EXAMPLE# http://www.arduino.cc/en/Tutorial/JoystickMouseControl[JoystickMouseControl^]: Controls a computer's cursor movement with a Joystick when a button is pressed. -- // SEE ALSO SECTION ENDS - diff --git a/Language/Functions/USB/Mouse/mouseBegin.adoc b/Language/Functions/USB/Mouse/mouseBegin.adoc index f4820aa74..e9ca794f5 100644 --- a/Language/Functions/USB/Mouse/mouseBegin.adoc +++ b/Language/Functions/USB/Mouse/mouseBegin.adoc @@ -26,7 +26,8 @@ Begins emulating the mouse connected to a computer. `begin()` must be called bef [float] === Parameters -Nothing +None + [float] === Returns @@ -51,17 +52,15 @@ Nothing ---- #include -void setup(){ - pinMode(2, INPUT); +void setup() { + pinMode(2, INPUT); } -void loop(){ - +void loop() { //initiate the Mouse library when button is pressed - if(digitalRead(2) == HIGH){ - Mouse.begin(); - } - + if (digitalRead(2) == HIGH) { + Mouse.begin(); + } } ---- @@ -86,4 +85,3 @@ void loop(){ -- // SEE ALSO SECTION ENDS - diff --git a/Language/Functions/USB/Mouse/mouseClick.adoc b/Language/Functions/USB/Mouse/mouseClick.adoc index f54a532c2..37f8c2652 100644 --- a/Language/Functions/USB/Mouse/mouseClick.adoc +++ b/Language/Functions/USB/Mouse/mouseClick.adoc @@ -22,18 +22,19 @@ Sends a momentary click to the computer at the location of the cursor. This is t [float] === Syntax -`Mouse.click();` + -`Mouse.click(button);` +`Mouse.click()` + +`Mouse.click(button)` [float] === Parameters -`button`: which mouse button to press - `char` +`button`: which mouse button to press. Allowed data types: `char`. * `MOUSE_LEFT` (default) * `MOUSE_RIGHT` * `MOUSE_MIDDLE` + [float] === Returns Nothing @@ -57,15 +58,15 @@ Nothing ---- #include -void setup(){ - pinMode(2,INPUT); +void setup() { + pinMode(2, INPUT); //initiate the Mouse library Mouse.begin(); } -void loop(){ +void loop() { //if the button is pressed, send a left mouse click - if(digitalRead(2) == HIGH){ + if (digitalRead(2) == HIGH) { Mouse.click(); } } @@ -95,4 +96,4 @@ When you use the `Mouse.click()` command, the Arduino takes over your mouse! Mak * #LANGUAGE# link:../mouseispressed[Mouse.isPressed()] -- -// SEE ALSO SECTION ENDS \ No newline at end of file +// SEE ALSO SECTION ENDS diff --git a/Language/Functions/USB/Mouse/mouseEnd.adoc b/Language/Functions/USB/Mouse/mouseEnd.adoc index b9514d673..89943fa9e 100644 --- a/Language/Functions/USB/Mouse/mouseEnd.adoc +++ b/Language/Functions/USB/Mouse/mouseEnd.adoc @@ -25,7 +25,8 @@ Stops emulating the mouse connected to a computer. To start control, use link:.. [float] === Parameters -Nothing +None + [float] === Returns @@ -50,21 +51,20 @@ Nothing ---- #include -void setup(){ - pinMode(2,INPUT); +void setup() { + pinMode(2, INPUT); //initiate the Mouse library Mouse.begin(); } -void loop(){ +void loop() { //if the button is pressed, send a left mouse click //then end the Mouse emulation - if(digitalRead(2) == HIGH){ + if (digitalRead(2) == HIGH) { Mouse.click(); Mouse.end(); } } - ---- -- diff --git a/Language/Functions/USB/Mouse/mouseIsPressed.adoc b/Language/Functions/USB/Mouse/mouseIsPressed.adoc index d27db64ad..4f265d51a 100644 --- a/Language/Functions/USB/Mouse/mouseIsPressed.adoc +++ b/Language/Functions/USB/Mouse/mouseIsPressed.adoc @@ -27,17 +27,16 @@ Checks the current status of all mouse buttons, and reports if any are pressed o === Parameters When there is no value passed, it checks the status of the left mouse button. -`button`: which mouse button to check - `char` +`button`: which mouse button to check. Allowed data types: `char`. * `MOUSE_LEFT (default)` - * `MOUSE_RIGHT` - * `MOUSE_MIDDLE` + [float] === Returns -`bool` : reports whether a button is pressed or not. +Reports whether a button is pressed or not. Data type: `bool`. -- // OVERVIEW SECTION ENDS @@ -58,32 +57,32 @@ When there is no value passed, it checks the status of the left mouse button. ---- #include -void setup(){ +void setup() { //The switch that will initiate the Mouse press - pinMode(2,INPUT); + pinMode(2, INPUT); //The switch that will terminate the Mouse press - pinMode(3,INPUT); + pinMode(3, INPUT); //Start serial communication with the computer - Serial1.begin(9600); + Serial.begin(9600); //initiate the Mouse library Mouse.begin(); } -void loop(){ +void loop() { //a variable for checking the button's state - int mouseState=0; + int mouseState = 0; //if the switch attached to pin 2 is closed, press and hold the left mouse button and save the state ina variable - if(digitalRead(2) == HIGH){ + if (digitalRead(2) == HIGH) { Mouse.press(); - mouseState=Mouse.isPressed(); + mouseState = Mouse.isPressed(); } //if the switch attached to pin 3 is closed, release the left mouse button and save the state in a variable - if(digitalRead(3) == HIGH){ + if (digitalRead(3) == HIGH) { Mouse.release(); - mouseState=Mouse.isPressed(); + mouseState = Mouse.isPressed(); } //print out the current mouse button state - Serial1.println(mouseState); + Serial.println(mouseState); delay(10); } ---- diff --git a/Language/Functions/USB/Mouse/mouseMove.adoc b/Language/Functions/USB/Mouse/mouseMove.adoc index 461caa10e..f4214f85a 100644 --- a/Language/Functions/USB/Mouse/mouseMove.adoc +++ b/Language/Functions/USB/Mouse/mouseMove.adoc @@ -20,16 +20,16 @@ Moves the cursor on a connected computer. The motion onscreen is always relative [float] === Syntax -`Mouse.move(xVal, yPos, wheel);` +`Mouse.move(xVal, yVal, wheel)` [float] === Parameters -`xVal`: amount to move along the x-axis - `signed char` +`xVal`: amount to move along the x-axis. Allowed data types: `signed char`. + +`yVal`: amount to move along the y-axis. Allowed data types: `signed char`. + +`wheel`: amount to move scroll wheel. Allowed data types: `signed char`. -`yVal`: amount to move along the y-axis - `signed char` -`wheel`: amount to move scroll wheel - `signed char` [float] === Returns Nothing @@ -57,31 +57,27 @@ const int xAxis = A1; //analog sensor for X axis const int yAxis = A2; // analog sensor for Y axis int range = 12; // output range of X or Y movement -int responseDelay = 2; // response delay of the mouse, in ms -int threshold = range/4; // resting threshold -int center = range/2; // resting position value -int minima[] = { - 1023, 1023}; // actual analogRead minima for {x, y} -int maxima[] = { - 0,0}; // actual analogRead maxima for {x, y} -int axis[] = { - xAxis, yAxis}; // pin numbers for {x, y} +int responseDelay = 2; // response delay of the mouse, in ms +int threshold = range / 4; // resting threshold +int center = range / 2; // resting position value +int minima[] = {1023, 1023}; // actual analogRead minima for {x, y} +int maxima[] = {0, 0}; // actual analogRead maxima for {x, y} +int axis[] = {xAxis, yAxis}; // pin numbers for {x, y} int mouseReading[2]; // final mouse readings for {x, y} void setup() { - Mouse.begin(); + Mouse.begin(); } void loop() { - -// read and scale the two axes: + // read and scale the two axes: int xReading = readAxis(0); int yReading = readAxis(1); -// move the mouse: - Mouse.move(xReading, yReading, 0); - delay(responseDelay); + // move the mouse: + Mouse.move(xReading, yReading, 0); + delay(responseDelay); } /* @@ -90,13 +86,13 @@ void loop() { */ int readAxis(int axisNumber) { - int distance = 0; // distance from center of the output range + int distance = 0; // distance from center of the output range // read the analog input: int reading = analogRead(axis[axisNumber]); -// of the current reading exceeds the max or min for this axis, -// reset the max or min: + // of the current reading exceeds the max or min for this axis, + // reset the max or min: if (reading < minima[axisNumber]) { minima[axisNumber] = reading; } @@ -107,14 +103,14 @@ int readAxis(int axisNumber) { // map the reading from the analog input range to the output range: reading = map(reading, minima[axisNumber], maxima[axisNumber], 0, range); - // if the output reading is outside from the - // rest position threshold, use it: + // if the output reading is outside from the + // rest position threshold, use it: if (abs(reading - center) > threshold) { distance = (reading - center); } // the Y axis needs to be inverted in order to - // map the movemment correctly: + // map the movement correctly: if (axisNumber == 1) { distance = -distance; } diff --git a/Language/Functions/USB/Mouse/mousePress.adoc b/Language/Functions/USB/Mouse/mousePress.adoc index a4738ecd8..51d371ba1 100644 --- a/Language/Functions/USB/Mouse/mousePress.adoc +++ b/Language/Functions/USB/Mouse/mousePress.adoc @@ -24,20 +24,19 @@ Before using `Mouse.press()`, you need to start communication with link:../mouse [float] === Syntax -`Mouse.press();` + +`Mouse.press()` + `Mouse.press(button)` [float] === Parameters -`button`: which mouse button to press - `char` +`button`: which mouse button to press. Allowed data types: `char`. * `MOUSE_LEFT (default)` - * `MOUSE_RIGHT` - * `MOUSE_MIDDLE` + [float] === Returns Nothing @@ -61,22 +60,22 @@ Nothing ---- #include -void setup(){ +void setup() { //The switch that will initiate the Mouse press - pinMode(2,INPUT); + pinMode(2, INPUT); //The switch that will terminate the Mouse press - pinMode(3,INPUT); + pinMode(3, INPUT); //initiate the Mouse library Mouse.begin(); } -void loop(){ +void loop() { //if the switch attached to pin 2 is closed, press and hold the left mouse button - if(digitalRead(2) == HIGH){ + if (digitalRead(2) == HIGH) { Mouse.press(); } //if the switch attached to pin 3 is closed, release the left mouse button - if(digitalRead(3) == HIGH){ + if (digitalRead(3) == HIGH) { Mouse.release(); } } diff --git a/Language/Functions/USB/Mouse/mouseRelease.adoc b/Language/Functions/USB/Mouse/mouseRelease.adoc index a92b9fa3c..bfa720c1c 100644 --- a/Language/Functions/USB/Mouse/mouseRelease.adoc +++ b/Language/Functions/USB/Mouse/mouseRelease.adoc @@ -14,25 +14,25 @@ title: Mouse.release() [float] === Description -Sends a message that a previously pressed button (invoked through link:../mousepress[Mouse.press()]) is released. Mouse.release() defaults to the left button. +Sends a message that a previously pressed button (invoked through link:../mousepress[Mouse.press()]) is released. `Mouse.release()` defaults to the left button. [%hardbreaks] [float] === Syntax -`Mouse.release();` + -`Mouse.release(button);` +`Mouse.release()` + +`Mouse.release(button)` + [float] === Parameters -`button`: which mouse button to press - char +`button`: which mouse button to press. Allowed data types: `char`. * `MOUSE_LEFT` (default) - * `MOUSE_RIGHT` - * `MOUSE_MIDDLE` + [float] === Returns Nothing @@ -56,22 +56,22 @@ Nothing ---- #include -void setup(){ +void setup() { //The switch that will initiate the Mouse press - pinMode(2,INPUT); + pinMode(2, INPUT); //The switch that will terminate the Mouse press - pinMode(3,INPUT); + pinMode(3, INPUT); //initiate the Mouse library Mouse.begin(); } -void loop(){ +void loop() { //if the switch attached to pin 2 is closed, press and hold the left mouse button - if(digitalRead(2) == HIGH){ + if (digitalRead(2) == HIGH) { Mouse.press(); } //if the switch attached to pin 3 is closed, release the left mouse button - if(digitalRead(3) == HIGH){ + if (digitalRead(3) == HIGH) { Mouse.release(); } } diff --git a/Language/Functions/Zero, Due, MKR Family/.gitkeep b/Language/Functions/Zero, Due, MKR Family/.gitkeep deleted file mode 100644 index e69de29bb..000000000 diff --git a/Language/Structure/.DS_Store b/Language/Structure/.DS_Store deleted file mode 100644 index 5008ddfcf..000000000 Binary files a/Language/Structure/.DS_Store and /dev/null differ diff --git a/Language/Structure/Arithmetic Operators/addition.adoc b/Language/Structure/Arithmetic Operators/addition.adoc index 690256e75..ac1573e9b 100644 --- a/Language/Structure/Arithmetic Operators/addition.adoc +++ b/Language/Structure/Arithmetic Operators/addition.adoc @@ -1,89 +1,89 @@ ---- -title: "+" -title_expanded: "addition" -categories: [ "Structure" ] -subCategories: [ "Arithmetic Operators" ] ---- - - - - - -= + Addition - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -*Addition* is one of the four primary arithmetic operations. The operator `+` (plus) operates on two operands to produce the sum. -[%hardbreaks] - - -[float] -=== Syntax -[source,arduino] ----- -sum = operand1 + operand2; ----- - -[float] -=== Parameters -`sum` : variable. *Allowed data types:* int, float, double, byte, short, long + -`operand1` : variable or constant. *Allowed data types:* int, float, double, byte, short, long + -`operand2` : variable or constant. *Allowed data types:* int, float, double, byte, short, long -[%hardbreaks] --- -// OVERVIEW SECTION ENDS - - - - -// HOW TO USE SECTION STARTS -[#howtouse] --- - -[float] -=== Example Code - -[source,arduino] ----- -int a = 5, b = 10, c = 0; -c = a + b; // the variable 'c' gets a value of 15 after this statement is executed ----- -[%hardbreaks] - -[float] -=== Notes and Warnings -1. The addition operation can overflow if the result is larger than that which can be stored in the data type (e.g. adding 1 to an integer with the value 32,767 gives -32,768). - -2. If one of the numbers (operands) are of the type float or of type double, floating point math will be used for the calculation. - -3. If the operands are of float / double data type and the variable that stores the sum is an integer, then only the integral part is stored and the fractional part of the number is lost. - -[source,arduino] ----- -float a = 5.5, b = 6.6; -int c = 0; -c = a + b; // the variable 'c' stores a value of 12 only as opposed to the expected sum of 12.1 ----- -[%hardbreaks] --- -// HOW TO USE SECTION ENDS - - - - -// SEE ALSO SECTION -[#see_also] --- - -[float] -=== See also - -[role="language"] - --- -// SEE ALSO SECTION ENDS +--- +title: "+" +title_expanded: "addition" +categories: [ "Structure" ] +subCategories: [ "Arithmetic Operators" ] +--- + + + + + += + Addition + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +*Addition* is one of the four primary arithmetic operations. The operator `+` (plus) operates on two operands to produce the sum. +[%hardbreaks] + + +[float] +=== Syntax +`sum = operand1 + operand2;` + +[float] +=== Parameters +`sum`: variable. Allowed data types: `int`, `float`, `double`, `byte`, `short`, `long`. + +`operand1`: variable or constant. Allowed data types: `int`, `float`, `double`, `byte`, `short`, `long`. + +`operand2`: variable or constant. Allowed data types: `int`, `float`, `double`, `byte`, `short`, `long`. + +-- +// OVERVIEW SECTION ENDS + + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code + +[source,arduino] +---- +int a = 5; +int b = 10; +int c = 0; +c = a + b; // the variable 'c' gets a value of 15 after this statement is executed +---- +[%hardbreaks] + +[float] +=== Notes and Warnings +1. The addition operation can overflow if the result is larger than that which can be stored in the data type (e.g. adding 1 to an integer with the value 32,767 gives -32,768). + +2. If one of the numbers (operands) are of the type float or of type double, floating point math will be used for the calculation. + +3. If the operands are of float / double data type and the variable that stores the sum is an integer, then only the integral part is stored and the fractional part of the number is lost. + +[source,arduino] +---- +float a = 5.5; +float b = 6.6; +int c = 0; +c = a + b; // the variable 'c' stores a value of 12 only as opposed to the expected sum of 12.1 +---- +[%hardbreaks] +-- +// HOW TO USE SECTION ENDS + + + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +[role="language"] + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Structure/Arithmetic Operators/assignment.adoc b/Language/Structure/Arithmetic Operators/assignment.adoc index fe782fa9c..0d1b00141 100644 --- a/Language/Structure/Arithmetic Operators/assignment.adoc +++ b/Language/Structure/Arithmetic Operators/assignment.adoc @@ -1,70 +1,70 @@ ---- -title: "=" -title_expanded: "assignment operator" -categories: [ "Structure" ] -subCategories: [ "Arithmetic Operators" ] ---- - - - - - -= = Assignment (single equal sign) - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -The single equal sign `=` in the C programming language is called the assignment operator. It has a different meaning than in algebra class where it indicated an equation or equality. The assignment operator tells the microcontroller to evaluate whatever value or expression is on the right side of the equal sign, and store it in the variable to the left of the equal sign. -[%hardbreaks] - --- -// OVERVIEW SECTION ENDS - - - - -// HOW TO USE SECTION STARTS -[#howtouse] --- - -[float] -=== Example Code - - - -[source,arduino] ----- -int sensVal; // declare an integer variable named sensVal -sensVal = analogRead(0); // store the (digitized) input voltage at analog pin 0 in SensVal ----- -[%hardbreaks] - -[float] -=== Notes and Warnings -1. The variable on the left side of the assignment operator ( = sign ) needs to be able to hold the value stored in it. If it is not large enough to hold a value, the value stored in the variable will be incorrect. - -2. Don't confuse the assignment operator [ = ] (single equal sign) with the comparison operator [ == ] (double equal signs), which evaluates whether two expressions are equal. -[%hardbreaks] - --- -// HOW TO USE SECTION ENDS - -// SEE ALSO SECTION STARTS -[#see_also] --- - -[float] -=== See also - -[role="language"] -* #LANGUAGE# link:../../control-structure/if[if (conditional operators)] -* #LANGUAGE# link:../../../variables/data-types/char[char] -* #LANGUAGE# link:../../../variables/data-types/int[int] -* #LANGUAGE# link:../../../variables/data-types/long[long] - --- -// SEE ALSO SECTION ENDS +--- +title: "=" +title_expanded: "assignment operator" +categories: [ "Structure" ] +subCategories: [ "Arithmetic Operators" ] +--- + + + + + += = Assignment (single equal sign) + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +The single equal sign `=` in the C++ programming language is called the assignment operator. It has a different meaning than in algebra class where it indicated an equation or equality. The assignment operator tells the microcontroller to evaluate whatever value or expression is on the right side of the equal sign, and store it in the variable to the left of the equal sign. +[%hardbreaks] + +-- +// OVERVIEW SECTION ENDS + + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code + + + +[source,arduino] +---- +int sensVal; // declare an integer variable named sensVal +sensVal = analogRead(0); // store the (digitized) input voltage at analog pin 0 in SensVal +---- +[%hardbreaks] + +[float] +=== Notes and Warnings +1. The variable on the left side of the assignment operator ( = sign ) needs to be able to hold the value stored in it. If it is not large enough to hold a value, the value stored in the variable will be incorrect. + +2. Don't confuse the assignment operator [ = ] (single equal sign) with the comparison operator [ == ] (double equal signs), which evaluates whether two expressions are equal. +[%hardbreaks] + +-- +// HOW TO USE SECTION ENDS + +// SEE ALSO SECTION STARTS +[#see_also] +-- + +[float] +=== See also + +[role="language"] +* #LANGUAGE# link:../../control-structure/if[if (conditional operators)] +* #LANGUAGE# link:../../../variables/data-types/char[char] +* #LANGUAGE# link:../../../variables/data-types/int[int] +* #LANGUAGE# link:../../../variables/data-types/long[long] + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Structure/Arithmetic Operators/division.adoc b/Language/Structure/Arithmetic Operators/division.adoc index c8b6148ff..12ae3b8bb 100644 --- a/Language/Structure/Arithmetic Operators/division.adoc +++ b/Language/Structure/Arithmetic Operators/division.adoc @@ -1,86 +1,86 @@ ---- -title: "/" -title_expanded: "division" -categories: [ "Structure" ] -subCategories: [ "Arithmetic Operators" ] ---- - - - - - -= / Division - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -*Division* is one of the four primary arithmetic operations. The operator `/` (slash) operates on two operands to produce the result. -[%hardbreaks] - - -[float] -=== Syntax -[source,arduino] ----- -result = numerator / denominator; ----- - -[float] -=== Parameters -`result` : variable. *Allowed data types:* int, float, double, byte, short, long + -`numerator` : variable or constant. *Allowed data types:* int, float, double, byte, short, long + -`denominator` : *non zero* variable or constant. *Allowed data types:* int, float, double, byte, short, long -[%hardbreaks] - --- -// OVERVIEW SECTION ENDS - - - - -// HOW TO USE SECTION STARTS -[#howtouse] --- - -[float] -=== Example Code - -[source,arduino] ----- -int a = 50, b = 10, c = 0; -c = a / b; // the variable 'c' gets a value of 5 after this statement is executed ----- -[%hardbreaks] - -[float] -=== Notes and Warnings -1. If one of the numbers (operands) are of the type float or of type double, floating point math will be used for the calculation. - -2. If the operands are of float / double data type and the variable that stores the sum is an integer, then only the integral part is stored and the fractional part of the number is lost. - -[source,arduino] ----- -float a = 55.5, b = 6.6; -int c = 0; -c = a / b; // the variable 'c' stores a value of 8 only as opposed to the expected result of 8.409 ----- -[%hardbreaks] - --- -// HOW TO USE SECTION ENDS - -// SEE ALSO SECTION STARTS -[#see_also] --- - -[float] -=== See also - -[role="language"] - --- -// SEE ALSO SECTION ENDS +--- +title: "/" +title_expanded: "division" +categories: [ "Structure" ] +subCategories: [ "Arithmetic Operators" ] +--- + + + + + += / Division + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +*Division* is one of the four primary arithmetic operations. The operator `/` (slash) operates on two operands to produce the result. +[%hardbreaks] + + +[float] +=== Syntax +`result = numerator / denominator;` + + +[float] +=== Parameters +`result`: variable. Allowed data types: `int`, `float`, `double`, `byte`, `short`, `long`. + +`numerator`: variable or constant. Allowed data types: `int`, `float`, `double`, `byte`, `short`, `long`. + +`denominator`: *non zero* variable or constant. Allowed data types: `int`, `float`, `double`, `byte`, `short`, `long`. + +-- +// OVERVIEW SECTION ENDS + + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code + +[source,arduino] +---- +int a = 50; +int b = 10; +int c = 0; +c = a / b; // the variable 'c' gets a value of 5 after this statement is executed +---- +[%hardbreaks] + +[float] +=== Notes and Warnings +1. If one of the numbers (operands) are of the type float or of type double, floating point math will be used for the calculation. + +2. If the operands are of float / double data type and the variable that stores the result is an integer, then only the integral part is stored and the fractional part of the number is lost. + +[source,arduino] +---- +float a = 55.5; +float b = 6.6; +int c = 0; +c = a / b; // the variable 'c' stores a value of 8 only as opposed to the expected result of 8.409 +---- +[%hardbreaks] + +-- +// HOW TO USE SECTION ENDS + +// SEE ALSO SECTION STARTS +[#see_also] +-- + +[float] +=== See also + +[role="language"] + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Structure/Arithmetic Operators/multiplication.adoc b/Language/Structure/Arithmetic Operators/multiplication.adoc index 7821acf53..6cc778fbf 100644 --- a/Language/Structure/Arithmetic Operators/multiplication.adoc +++ b/Language/Structure/Arithmetic Operators/multiplication.adoc @@ -1,91 +1,91 @@ ---- -title: "*" -title_expanded: "multiplication" -categories: [ "Structure" ] -subCategories: [ "Arithmetic Operators" ] ---- - - - - - -= * Multiplication - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -*Multiplication* is one of the four primary arithmetic operations. The operator `*` (asterisk) operates on two operands to produce the product. -[%hardbreaks] - - -[float] -=== Syntax -[source,arduino] ----- -product = operand1 * operand2; ----- - -[float] -=== Parameters -`product` : variable. *Allowed data types:* int, float, double, byte, short, long + -`operand1` : variable or constant. *Allowed data types:* int, float, double, byte, short, long + -`operand2` : variable or constant. *Allowed data types:* int, float, double, byte, short, long -[%hardbreaks] - --- -// OVERVIEW SECTION ENDS - - - - -// HOW TO USE SECTION STARTS -[#howtouse] --- - -[float] -=== Example Code - -[source,arduino] ----- -int a = 5, b = 10, c = 0; -c = a * b; // the variable 'c' gets a value of 50 after this statement is executed ----- -[%hardbreaks] - -[float] -=== Notes and Warnings -1. The multiplication operation can overflow if the result is bigger than that which can be stored in the data type. - -2. If one of the numbers (operands) are of the type float or of type double, floating point math will be used for the calculation. - -3. If the operands are of float / double data type and the variable that stores the product is an integer, then only the integral part is stored and the fractional part of the number is lost. - -[source,arduino] ----- -float a = 5.5, b = 6.6; -int c = 0; -c = a * b; // the variable 'c' stores a value of 36 only as opposed to the expected product of 36.3 ----- -[%hardbreaks] - --- -// HOW TO USE SECTION ENDS - - - - -// SEE ALSO SECTION STARTS -[#see_also] --- - -[float] -=== See also - -[role="language"] - --- -// SEE ALSO SECTION ENDS +--- +title: "*" +title_expanded: "multiplication" +categories: [ "Structure" ] +subCategories: [ "Arithmetic Operators" ] +--- + + + + + += * Multiplication + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +*Multiplication* is one of the four primary arithmetic operations. The operator `*` (asterisk) operates on two operands to produce the product. +[%hardbreaks] + + +[float] +=== Syntax +`product = operand1 * operand2;` + + +[float] +=== Parameters +`product`: variable. Allowed data types: `int`, `float`, `double`, `byte`, `short`, `long`. + +`operand1`: variable or constant. Allowed data types: `int`, `float`, `double`, `byte`, `short`, `long`. + +`operand2`: variable or constant. Allowed data types: `int`, `float`, `double`, `byte`, `short`, `long`. + +-- +// OVERVIEW SECTION ENDS + + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code + +[source,arduino] +---- +int a = 5; +int b = 10; +int c = 0; +c = a * b; // the variable 'c' gets a value of 50 after this statement is executed +---- +[%hardbreaks] + +[float] +=== Notes and Warnings +1. The multiplication operation can overflow if the result is bigger than that which can be stored in the data type. + +2. If one of the numbers (operands) are of the type float or of type double, floating point math will be used for the calculation. + +3. If the operands are of float / double data type and the variable that stores the product is an integer, then only the integral part is stored and the fractional part of the number is lost. + +[source,arduino] +---- +float a = 5.5; +float b = 6.6; +int c = 0; +c = a * b; // the variable 'c' stores a value of 36 only as opposed to the expected product of 36.3 +---- +[%hardbreaks] + +-- +// HOW TO USE SECTION ENDS + + + + +// SEE ALSO SECTION STARTS +[#see_also] +-- + +[float] +=== See also + +[role="language"] + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Structure/Arithmetic Operators/remainder.adoc b/Language/Structure/Arithmetic Operators/remainder.adoc index 3b922c9c3..a6715a1ad 100644 --- a/Language/Structure/Arithmetic Operators/remainder.adoc +++ b/Language/Structure/Arithmetic Operators/remainder.adoc @@ -24,17 +24,13 @@ subCategories: [ "Arithmetic Operators" ] [float] === Syntax -[source,arduino] ----- -remainder = dividend % divisor; ----- +`remainder = dividend % divisor;` [float] === Parameters -`remainder` : variable. *Allowed data types:* int, float, double + -`dividend` : variable or constant. *Allowed data types:* int + -`divisor` : *non zero* variable or constant. *Allowed data types:* int -[%hardbreaks] +`remainder`: variable. Allowed data types: `int`, `float`, `double`. + +`dividend`: variable or constant. Allowed data types: `int`. + +`divisor`: *non zero* variable or constant. Allowed data types: `int`. -- // OVERVIEW SECTION ENDS @@ -51,12 +47,12 @@ remainder = dividend % divisor; [source,arduino] ---- int x = 0; -x = 7 % 5; // x now contains 2 -x = 9 % 5; // x now contains 4 -x = 5 % 5; // x now contains 0 -x = 4 % 5; // x now contains 4 -x = -4 % 5; // x now contains -4 -x = 4 % -5; // x now contains 4 +x = 7 % 5; // x now contains 2 +x = 9 % 5; // x now contains 4 +x = 5 % 5; // x now contains 0 +x = 4 % 5; // x now contains 4 +x = -4 % 5; // x now contains -4 +x = 4 % -5; // x now contains 4 ---- [source,arduino] @@ -68,10 +64,9 @@ int i = 0; void setup() {} -void loop() -{ +void loop() { values[i] = analogRead(0); - i = (i + 1) % 10; // remainder operator rolls over variable + i = (i + 1) % 10; // remainder operator rolls over variable } ---- [%hardbreaks] diff --git a/Language/Structure/Arithmetic Operators/subtraction.adoc b/Language/Structure/Arithmetic Operators/subtraction.adoc index ebcc8b44c..2644f5269 100644 --- a/Language/Structure/Arithmetic Operators/subtraction.adoc +++ b/Language/Structure/Arithmetic Operators/subtraction.adoc @@ -1,91 +1,91 @@ ---- -title: "-" -title_expanded: "subtraction" -categories: [ "Structure" ] -subCategories: [ "Arithmetic Operators" ] ---- - - - - - -= - Subtraction - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -*Subtraction* is one of the four primary arithmetic operations. The operator `-` (minus) operates on two operands to produce the difference of the second from the first. -[%hardbreaks] - - -[float] -=== Syntax -[source,arduino] ----- -difference = operand1 - operand2; ----- - -[float] -=== Parameters -`difference` : variable. *Allowed data types:* int, float, double, byte, short, long + -`operand1` : variable or constant. *Allowed data types:* int, float, double, byte, short, long + -`operand2` : variable or constant. *Allowed data types:* int, float, double, byte, short, long -[%hardbreaks] - --- -// OVERVIEW SECTION ENDS - - - - -// HOW TO USE SECTION STARTS -[#howtouse] --- - -[float] -=== Example Code - -[source,arduino] ----- -int a = 5, b = 10, c = 0; -c = a - b; // the variable 'c' gets a value of -5 after this statement is executed ----- -[%hardbreaks] - -[float] -=== Notes and Warnings -1. The subtraction operation can overflow if the result is smaller than that which can be stored in the data type (e.g. subtracting 1 from an integer with the value -32,768 gives 32,767). - -2. If one of the numbers (operands) are of the type float or of type double, floating point math will be used for the calculation. - -3. If the operands are of float / double data type and the variable that stores the difference is an integer, then only the integral part is stored and the fractional part of the number is lost. - -[source,arduino] ----- -float a = 5.5, b = 6.6; -int c = 0; -c = a - b; // the variable 'c' stores a value of -1 only as opposed to the expected difference of -1.1 ----- -[%hardbreaks] - --- -// HOW TO USE SECTION ENDS - - - - -// SEE ALSO SECTION STARTS -[#see_also] --- - -[float] -=== See also - -[role="language"] - --- -// SEE ALSO SECTION ENDS +--- +title: "-" +title_expanded: "subtraction" +categories: [ "Structure" ] +subCategories: [ "Arithmetic Operators" ] +--- + + + + + += - Subtraction + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +*Subtraction* is one of the four primary arithmetic operations. The operator `-` (minus) operates on two operands to produce the difference of the second from the first. +[%hardbreaks] + + +[float] +=== Syntax +`difference = operand1 - operand2;` + + +[float] +=== Parameters +`difference`: variable. Allowed data types: `int`, `float`, `double`, `byte`, `short`, `long`. + +`operand1`: variable or constant. Allowed data types: `int`, `float`, `double`, `byte`, `short`, `long`. + +`operand2`: variable or constant. Allowed data types: `int`, `float`, `double`, `byte`, `short`, `long`. + +-- +// OVERVIEW SECTION ENDS + + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code + +[source,arduino] +---- +int a = 5; +int b = 10; +int c = 0; +c = a - b; // the variable 'c' gets a value of -5 after this statement is executed +---- +[%hardbreaks] + +[float] +=== Notes and Warnings +1. The subtraction operation can overflow if the result is smaller than that which can be stored in the data type (e.g. subtracting 1 from an integer with the value -32,768 gives 32,767). + +2. If one of the numbers (operands) are of the type float or of type double, floating point math will be used for the calculation. + +3. If the operands are of float / double data type and the variable that stores the difference is an integer, then only the integral part is stored and the fractional part of the number is lost. + +[source,arduino] +---- +float a = 5.5; +float b = 6.6; +int c = 0; +c = a - b; // the variable 'c' stores a value of -1 only as opposed to the expected difference of -1.1 +---- +[%hardbreaks] + +-- +// HOW TO USE SECTION ENDS + + + + +// SEE ALSO SECTION STARTS +[#see_also] +-- + +[float] +=== See also + +[role="language"] + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Structure/Bitwise Operators/bitshiftLeft.adoc b/Language/Structure/Bitwise Operators/bitshiftLeft.adoc index 94c455422..5a4c97a5a 100644 --- a/Language/Structure/Bitwise Operators/bitshiftLeft.adoc +++ b/Language/Structure/Bitwise Operators/bitshiftLeft.adoc @@ -1,123 +1,121 @@ ---- -title: "<<" -title_expanded: bitshift left -categories: [ "Structure" ] -subCategories: [ "Bitwise Operators" ] ---- - - - - - -= << Bitshift Left - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -The left shift operator `<<` causes the bits of the left operand to be shifted *left* by the number of positions specified by the right operand. -[%hardbreaks] - - -[float] -=== Syntax -[source,arduino] ----- -variable << number_of_bits; ----- - -[float] -=== Parameters -`variable`: *Allowed data types:* byte, int, long + -`number_of_bits`: a number that is < = 32. *Allowed data types:* int - --- -// OVERVIEW SECTION ENDS - - - -// HOW TO USE SECTION STARTS -[#howtouse] --- - -[float] -=== Example Code - -[source,arduino] ----- -int a = 5; // binary: 0000000000000101 -int b = a << 3; // binary: 0000000000101000, or 40 in decimal ----- -[%hardbreaks] - -[float] -=== Notes and Warnings -When you shift a value x by y bits (x << y), the leftmost y bits in x are lost, literally shifted out of existence: - -[source,arduino] ----- -int x = 5; // binary: 0000000000000101 -int y = 14; -int result = x << y; // binary: 0100000000000000 - the first 1 in 101 was discarded ----- - -If you are certain that none of the ones in a value are being shifted into oblivion, a simple way to think of the left-shift operator is that it multiplies the left operand by 2 raised to the right operand power. For example, to generate powers of 2, the following expressions can be employed: - -[source,arduino] ----- - Operation Result - --------- ------ - 1 << 0 1 - 1 << 1 2 - 1 << 2 4 - 1 << 3 8 - ... - 1 << 8 256 - 1 << 9 512 - 1 << 10 1024 - ... ----- - -The following example can be used to print out the value of a received byte to the serial monitor, using the left shift operator to move along the byte from bottom(LSB) to top (MSB), and print out its Binary value: - -[source,arduino] ----- -// Prints out Binary value (1 or 0) of byte -void printOut1(int c) { - for (int bits = 7; bits > -1; bits--) { - // Compare bits 7-0 in byte - if (c & (1 << bits)) { - Serial.print ("1"); - } - else { - Serial.print ("0"); - } - } -} ----- -[%hardbreaks] - --- -// HOW TO USE SECTION ENDS - - - - -//SEE ALSO SECTION STARTS -[#see_also] --- - -[float] -=== See also - -[role="language"] - -[role="example"] -* #EXAMPLE# https://www.arduino.cc/playground/Code/BitMath[BitMath Tutorial^] - --- -//SEE ALSO SECTION ENDS - +--- +title: "<<" +title_expanded: bitshift left +categories: [ "Structure" ] +subCategories: [ "Bitwise Operators" ] +--- + + + + + += << Bitshift Left + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +The left shift operator `<<` causes the bits of the left operand to be shifted *left* by the number of positions specified by the right operand. +[%hardbreaks] + + +[float] +=== Syntax +`variable << number_of_bits;` + + +[float] +=== Parameters +`variable`: Allowed data types: `byte`, `int`, `long`. + +`number_of_bits`: a number that is < = 32. Allowed data types: `int`. + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code + +[source,arduino] +---- +int a = 5; // binary: 0000000000000101 +int b = a << 3; // binary: 0000000000101000, or 40 in decimal +---- +[%hardbreaks] + +[float] +=== Notes and Warnings +When you shift a value x by y bits (x << y), the leftmost y bits in x are lost, literally shifted out of existence: + +[source,arduino] +---- +int x = 5; // binary: 0000000000000101 +int y = 14; +int result = x << y; // binary: 0100000000000000 - the first 1 in 101 was discarded +---- + +If you are certain that none of the ones in a value are being shifted into oblivion, a simple way to think of the left-shift operator is that it multiplies the left operand by 2 raised to the right operand power. For example, to generate powers of 2, the following expressions can be employed: + +[source,arduino] +---- + Operation Result + --------- ------ + 1 << 0 1 + 1 << 1 2 + 1 << 2 4 + 1 << 3 8 + ... + 1 << 8 256 + 1 << 9 512 + 1 << 10 1024 + ... +---- + +The following example can be used to print out the value of a received byte to the serial monitor, using the left shift operator to move along the byte from bottom(LSB) to top (MSB), and print out its Binary value: + +[source,arduino] +---- +// Prints out Binary value (1 or 0) of byte +void printOut1(int c) { + for (int bits = 7; bits > -1; bits--) { + // Compare bits 7-0 in byte + if (c & (1 << bits)) { + Serial.print("1"); + } + else { + Serial.print("0"); + } + } +} +---- +[%hardbreaks] + +-- +// HOW TO USE SECTION ENDS + + + + +//SEE ALSO SECTION STARTS +[#see_also] +-- + +[float] +=== See also + +[role="language"] + +[role="example"] +* #EXAMPLE# https://www.arduino.cc/playground/Code/BitMath[BitMath Tutorial^] + +-- +//SEE ALSO SECTION ENDS + diff --git a/Language/Structure/Bitwise Operators/bitshiftRight.adoc b/Language/Structure/Bitwise Operators/bitshiftRight.adoc index a340c3e07..444665f96 100644 --- a/Language/Structure/Bitwise Operators/bitshiftRight.adoc +++ b/Language/Structure/Bitwise Operators/bitshiftRight.adoc @@ -1,99 +1,104 @@ ---- -title: ">>" -title_expanded: bitshift right -categories: [ "Structure" ] -subCategories: [ "Bitwise Operators" ] ---- - - - - - -= >> Bitshift Right - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -The right shift operator `>>` causes the bits of the left operand to be shifted *right* by the number of positions specified by the right operand. -[%hardbreaks] - - -[float] -=== Syntax -[source,arduino] ----- -variable >> number_of_bits; ----- - -[float] -=== Parameters -`variable`: *Allowed data types:* byte, int, long + -`number_of_bits`: a number that is < = 32. *Allowed data types:* int - --- -// OVERVIEW SECTION ENDS - - - -// HOW TO USE SECTION STARTS -[#howtouse] --- - -[float] -=== Example Code - -[source,arduino] ----- -int a = 40; // binary: 0000000000101000 -int b = a >> 3; // binary: 0000000000000101, or 5 in decimal ----- -[%hardbreaks] - -[float] -=== Notes and Warnings -When you shift x right by y bits (x >> y), and the highest bit in x is a 1, the behavior depends on the exact data type of x. If x is of type int, the highest bit is the sign bit, determining whether x is negative or not, as we have discussed above. In that case, the sign bit is copied into lower bits, for esoteric historical reasons: - -[source,arduino] ----- -int x = -16; // binary: 1111111111110000 -int y = 3; -int result = x >> y; // binary: 1111111111111110 ----- -This behavior, called sign extension, is often not the behavior you want. Instead, you may wish zeros to be shifted in from the left. It turns out that the right shift rules are different for unsigned int expressions, so you can use a typecast to suppress ones being copied from the left: - -[source,arduino] ----- -int x = -16; // binary: 1111111111110000 -int y = 3; -int result = (unsigned int)x >> y; // binary: 0001111111111110 ----- -If you are careful to avoid sign extension, you can use the right-shift operator `>>` as a way to divide by powers of 2. For example: - -[source,arduino] ----- -int x = 1000; -int y = x >> 3; // integer division of 1000 by 8, causing y = 125. ----- - --- -// HOW TO USE SECTION ENDS - - -// SEE ALSO SECTION -[#see_also] --- - -[float] -=== See also - -[role="language"] - -[role="example"] -* #EXAMPLE# http://www.arduino.cc/playground/Code/BitMath[BitMath Tutorial^] - --- -// SEE ALSO SECTION ENDS \ No newline at end of file +--- +title: ">>" +title_expanded: bitshift right +categories: [ "Structure" ] +subCategories: [ "Bitwise Operators" ] +--- + + + + + += >> Bitshift Right + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +The right shift operator `>>` causes the bits of the left operand to be shifted *right* by the number of positions specified by the right operand. +[%hardbreaks] + + +[float] +=== Syntax +`variable >> number_of_bits;` + + +[float] +=== Parameters +`variable`: Allowed data types: any integer type (`byte`, `short`, `int`, `long`, `unsigned short`...). + +`number_of_bits`: a positive number smaller than the bit-width of `variable`. Allowed data types: `int`. + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code + +[source,arduino] +---- +int a = 40; // binary: 0000000000101000 +int b = a >> 3; // binary: 0000000000000101, decimal: 5 +---- +[%hardbreaks] + +[float] +=== Notes and Warnings +When you shift `x` right by `y` bits (`x >> y`), the `y` rightmost bits of `x` “fall off” and are discarded. If `x` has an unsigned type (e.g. `unsigned int`), the `y` leftmost bits of the result are filled with zeroes. If `x` has a signed type (e.g. `int`), its leftmost bit is the sign bit, which determines whether it is positive or negative. In this case, the `y` leftmost bits of the result are filled with copies of the sign bit. This behavior, called “sign extension”, ensures the result has the same sign as `x`. + +[source,arduino] +---- +int x = -16; // binary: 1111111111110000 +int y = 3; +int result = x >> y; // binary: 1111111111111110, decimal: -2 +---- +This may not be the behavior you want. If you instead want zeros to be shifted in from the left, you can use a typecast to suppress sign extension: + +[source,arduino] +---- +int x = -16; // binary: 1111111111110000 +int y = 3; +int result = (unsigned int)x >> y; // binary: 0001111111111110, decimal: 8190 +---- +Sign extension causes the right-shift operator `>>` to perform a division by powers of 2, even with negative numbers. For example: + +[source,arduino] +---- +int x = -1000; +int y = x >> 3; // integer division of -1000 by 8, causing y = -125. +---- +But be aware of the rounding with negative numbers: +[source,arduino] +---- +int x = -1001; +int y = x >> 3; // division by shifting always rounds down, causing y = -126 +int z = x / 8; // division operator rounds towards zero, causing z = -125 +---- + +-- +// HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +[role="language"] + +[role="example"] +* #EXAMPLE# http://www.arduino.cc/playground/Code/BitMath[BitMath Tutorial^] + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Structure/Bitwise Operators/bitwiseAnd.adoc b/Language/Structure/Bitwise Operators/bitwiseAnd.adoc index 75a1f9dc8..eb8a2067b 100644 --- a/Language/Structure/Bitwise Operators/bitwiseAnd.adoc +++ b/Language/Structure/Bitwise Operators/bitwiseAnd.adoc @@ -1,83 +1,83 @@ ---- -title: "&" -title_expanded: bitwise and -categories: [ "Structure" ] -subCategories: [ "Bitwise Operators" ] ---- - - - - - -= & Bitwise AND - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -The bitwise AND operator in C++ is a single ampersand `&`, used between two other integer expressions. Bitwise AND operates on each bit position of the surrounding expressions independently, according to this rule: if both input bits are 1, the resulting output is 1, otherwise the output is 0. -[%hardbreaks] - -Another way of expressing this is: - - 0 0 1 1 operand1 - 0 1 0 1 operand2 - ---------- - 0 0 0 1 (operand1 & operand2) - returned result -[%hardbreaks] - -In Arduino, the type int is a 16-bit value, so using & between two int expressions causes 16 simultaneous AND operations to occur. -[%hardbreaks] - --- -// OVERVIEW SECTION ENDS - - - -// HOW TO USE SECTION STARTS -[#howtouse] --- - -[float] -=== Example Code -In a code fragment like: - -[source,arduino] ----- -int a = 92; // in binary: 0000000001011100 -int b = 101; // in binary: 0000000001100101 -int c = a & b; // result: 0000000001000100, or 68 in decimal. ----- -Each of the 16 bits in a and b are processed by using the bitwise AND, and all 16 resulting bits are stored in c, resulting in the value 01000100 in binary, which is 68 in decimal. -[%hardbreaks] - -One of the most common uses of bitwise AND is to select a particular bit (or bits) from an integer value, often called masking. See below for an example - -[source,arduino] ----- -PORTD = PORTD & B00000011; // clear out bits 2 - 7, leave pins 0 and 1 untouched (xx & 11 == xx) ----- - --- -// HOW TO USE SECTION ENDS - - -// SEE ALSO SECTION -[#see_also] --- - -[float] -=== See also - - -[role="language"] -* #LANGUAGE# link:../../boolean-operators/logicaland[&& Logical AND] - -[role="example"] -* #EXAMPLE# https://www.arduino.cc/playground/Code/BitMath[BitMath Tutorial^] - --- -// SEE ALSO SECTION ENDS +--- +title: "&" +title_expanded: bitwise and +categories: [ "Structure" ] +subCategories: [ "Bitwise Operators" ] +--- + + + + + += & Bitwise AND + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +The bitwise AND operator in C++ is a single ampersand `&`, used between two other integer expressions. Bitwise AND operates on each bit position of the surrounding expressions independently, according to this rule: if both input bits are 1, the resulting output is 1, otherwise the output is 0. +[%hardbreaks] + +Another way of expressing this is: + + 0 0 1 1 operand1 + 0 1 0 1 operand2 + ---------- + 0 0 0 1 (operand1 & operand2) - returned result +[%hardbreaks] + +In Arduino, the type int is a 16-bit value, so using & between two int expressions causes 16 simultaneous AND operations to occur. +[%hardbreaks] + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code +In a code fragment like: + +[source,arduino] +---- +int a = 92; // in binary: 0000000001011100 +int b = 101; // in binary: 0000000001100101 +int c = a & b; // result: 0000000001000100, or 68 in decimal. +---- +Each of the 16 bits in a and b are processed by using the bitwise AND, and all 16 resulting bits are stored in c, resulting in the value 01000100 in binary, which is 68 in decimal. +[%hardbreaks] + +One of the most common uses of bitwise AND is to select a particular bit (or bits) from an integer value, often called masking. See below for an example (AVR architecture specific). + +[source,arduino] +---- +PORTD = PORTD & 0b00000011; // clear out bits 2 - 7, leave pins PD0 and PD1 untouched (xx & 11 == xx) +---- + +-- +// HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + + +[role="language"] +* #LANGUAGE# link:../../boolean-operators/logicaland[&& Logical AND] + +[role="example"] +* #EXAMPLE# https://www.arduino.cc/playground/Code/BitMath[BitMath Tutorial^] + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Structure/Bitwise Operators/bitwiseNot.adoc b/Language/Structure/Bitwise Operators/bitwiseNot.adoc index 93b27ffa4..7a35ec1a2 100644 --- a/Language/Structure/Bitwise Operators/bitwiseNot.adoc +++ b/Language/Structure/Bitwise Operators/bitwiseNot.adoc @@ -1,76 +1,76 @@ ---- -title: "~" -title_expanded: bitwise not -categories: [ "Structure" ] -subCategories: [ "Bitwise Operators" ] ---- - - - - - -= ~ Bitwise NOT - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -The bitwise NOT operator in C++ is the tilde character `~`. Unlike & and |, the bitwise NOT operator is applied to a single operand to its right. Bitwise NOT changes each bit to its opposite: 0 becomes 1, and 1 becomes 0. -[%hardbreaks] - -In other words: - - 0 1 operand1 - ----- - 1 0 ~operand1 -[%hardbreaks] --- -// OVERVIEW SECTION ENDS - - - -// HOW TO USE SECTION STARTS -[#howtouse] --- - -[float] -=== Example Code - -[source,arduino] ----- -int a = 103; // binary: 0000000001100111 -int b = ~a; // binary: 1111111110011000 = -104 ----- -[%hardbreaks] - -[float] -=== Notes and Warnings -You might be surprised to see a negative number like -104 as the result of this operation. This is because the highest bit in an int variable is the so-called sign bit. If the highest bit is 1, the number is interpreted as negative. This encoding of positive and negative numbers is referred to as two's complement. For more information, see the Wikipedia article on http://en.wikipedia.org/wiki/Twos_complement[two's complement^]. - -As an aside, it is interesting to note that for any integer x, ~x is the same as -x-1. - -At times, the sign bit in a signed integer expression can cause some unwanted surprises. -[%hardbreaks] - --- -// HOW TO USE SECTION ENDS - - - -// SEE ALSO BEGINS -[#see_also] --- - -[float] -=== See also - -[role="language"] - -[role="example"] -* #EXAMPLE# https://www.arduino.cc/playground/Code/BitMath[BitMath Tutorial^] - --- -//SEE ALSO SECTION ENDS +--- +title: "~" +title_expanded: bitwise not +categories: [ "Structure" ] +subCategories: [ "Bitwise Operators" ] +--- + + + + + += ~ Bitwise NOT + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +The bitwise NOT operator in C++ is the tilde character `~`. Unlike & and |, the bitwise NOT operator is applied to a single operand to its right. Bitwise NOT changes each bit to its opposite: 0 becomes 1, and 1 becomes 0. +[%hardbreaks] + +In other words: + + 0 1 operand1 + ----- + 1 0 ~operand1 +[%hardbreaks] +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code + +[source,arduino] +---- +int a = 103; // binary: 0000000001100111 +int b = ~a; // binary: 1111111110011000 = -104 +---- +[%hardbreaks] + +[float] +=== Notes and Warnings +You might be surprised to see a negative number like -104 as the result of this operation. This is because the highest bit in an int variable is the so-called sign bit. If the highest bit is 1, the number is interpreted as negative. This encoding of positive and negative numbers is referred to as two's complement. For more information, see the Wikipedia article on http://en.wikipedia.org/wiki/Twos_complement[two's complement^]. + +As an aside, it is interesting to note that for any integer x, ~x is the same as -x - 1. + +At times, the sign bit in a signed integer expression can cause some unwanted surprises. +[%hardbreaks] + +-- +// HOW TO USE SECTION ENDS + + + +// SEE ALSO BEGINS +[#see_also] +-- + +[float] +=== See also + +[role="language"] + +[role="example"] +* #EXAMPLE# https://www.arduino.cc/playground/Code/BitMath[BitMath Tutorial^] + +-- +//SEE ALSO SECTION ENDS diff --git a/Language/Structure/Bitwise Operators/bitwiseOr.adoc b/Language/Structure/Bitwise Operators/bitwiseOr.adoc index d0f6e0a24..c0297fea7 100644 --- a/Language/Structure/Bitwise Operators/bitwiseOr.adoc +++ b/Language/Structure/Bitwise Operators/bitwiseOr.adoc @@ -1,79 +1,81 @@ ---- -title: "|" -title_expanded: bitwise or -categories: [ "Structure" ] -subCategories: [ "Bitwise Operators" ] ---- - - - - - -= | Bitwise OR - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -The bitwise OR operator in C++ is the vertical bar symbol, |. Like the & operator, | operates independently each bit in its two surrounding integer expressions, but what it does is different (of course). The bitwise OR of two bits is 1 if either or both of the input bits is 1, otherwise it is 0. -[%hardbreaks] - -In other words: - - 0 0 1 1 operand1 - 0 1 0 1 operand2 - ---------- - 0 1 1 1 (operand1 | operand2) - returned result -[%hardbreaks] - --- -// OVERVIEW SECTION ENDS - - - -// HOW TO USE SECTION STARTS -[#howtouse] --- - -[float] -=== Example Code - -[source,arduino] ----- -int a = 92; // in binary: 0000000001011100 -int b = 101; // in binary: 0000000001100101 -int c = a | b; // result: 0000000001111101, or 125 in decimal. ----- -[%hardbreaks] - -One of the most common uses of the Bitwise OR is to set multiple bits in a bit-packed number. - -[source,arduino] ----- -DDRD = DDRD | B11111100; // set direction bits for pins 2 to 7, leave 0 and 1 untouched (xx | 00 == xx) -// same as pinMode(pin, OUTPUT) for pins 2 to 7 ----- - --- -// HOW TO USE SECTION ENDS - - -// SEE ALSO SECTION -[#see_also] --- - -[float] -=== See also - - -[role="language"] -* #LANGUAGE# link:../../boolean-operators/logicalor[|| Logical OR] - -[role="example"] -* #EXAMPLE# https://www.arduino.cc/playground/Code/BitMath[BitMath Tutorial^] - --- -// SEE ALSO SECTION ENDS \ No newline at end of file +--- +title: "|" +title_expanded: bitwise or +categories: [ "Structure" ] +subCategories: [ "Bitwise Operators" ] +--- + + + + + += | Bitwise OR + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +The bitwise OR operator in C++ is the vertical bar symbol, |. Like the & operator, | operates independently each bit in its two surrounding integer expressions, but what it does is different (of course). The bitwise OR of two bits is 1 if either or both of the input bits is 1, otherwise it is 0. +[%hardbreaks] + +In other words: + + 0 0 1 1 operand1 + 0 1 0 1 operand2 + ---------- + 0 1 1 1 (operand1 | operand2) - returned result +[%hardbreaks] + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code + +[source,arduino] +---- +int a = 92; // in binary: 0000000001011100 +int b = 101; // in binary: 0000000001100101 +int c = a | b; // result: 0000000001111101, or 125 in decimal. +---- +[%hardbreaks] + +One of the most common uses of the Bitwise OR is to set multiple bits in a bit-packed number. + +[source,arduino] +---- +// Note: This code is AVR architecture specific +// set direction bits for pins 2 to 7, leave PD0 and PD1 untouched (xx | 00 == xx) +// same as pinMode(pin, OUTPUT) for pins 2 to 7 on Uno or Nano +DDRD = DDRD | 0b11111100; +---- + +-- +// HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + + +[role="language"] +* #LANGUAGE# link:../../boolean-operators/logicalor[|| Logical OR] + +[role="example"] +* #EXAMPLE# https://www.arduino.cc/playground/Code/BitMath[BitMath Tutorial^] + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Structure/Bitwise Operators/bitwiseXor.adoc b/Language/Structure/Bitwise Operators/bitwiseXor.adoc index 56ea46a81..995040657 100644 --- a/Language/Structure/Bitwise Operators/bitwiseXor.adoc +++ b/Language/Structure/Bitwise Operators/bitwiseXor.adoc @@ -1,85 +1,85 @@ ---- -title: "^" -title_expanded: bitwise xor -categories: [ "Structure" ] -subCategories: [ "Bitwise Operators" ] ---- - - - - - -= ^ Bitwise XOR - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -There is a somewhat unusual operator in C++ called bitwise EXCLUSIVE OR, also known as bitwise XOR. (In English this is usually pronounced "eks-or".) The bitwise XOR operator is written using the caret symbol `^`. A bitwise XOR operation results in a 1 only if the input bits are different, else it results in a 0. -[%hardbreaks] - -Precisely, - - 0 0 1 1 operand1 - 0 1 0 1 operand2 - ---------- - 0 1 1 0 (operand1 ^ operand2) - returned result -[%hardbreaks] - --- -// OVERVIEW SECTION ENDS - - - -// HOW TO USE SECTION STARTS -[#howtouse] --- - -[float] -=== Example Code - -[source,arduino] ----- -int x = 12; // binary: 1100 -int y = 10; // binary: 1010 -int z = x ^ y; // binary: 0110, or decimal 6 ----- -[%hardbreaks] - -The ^ operator is often used to toggle (i.e. change from 0 to 1, or 1 to 0) some of the bits in an integer expression. In a bitwise XOR operation if there is a 1 in the mask bit, that bit is inverted; if there is a 0, the bit is not inverted and stays the same. Below is a program to blink digital pin 5. - -[source,arduino] ----- -// Blink_Pin_5 -// demo for Exclusive OR -void setup(){ -DDRD = DDRD | B00100000; // set digital pin five as OUTPUT -Serial.begin(9600); -} - -void loop(){ -PORTD = PORTD ^ B00100000; // invert bit 5 (digital pin 5), leave others untouched -delay(100); -} ----- - - --- -// HOW TO USE SECTION ENDS - - -// SEE ALSO SECTION -[#see_also] --- - -[float] -=== See also - -[role="example"] -* #EXAMPLE# https://www.arduino.cc/playground/Code/BitMath[BitMath Tutorial^] - --- -// SEE ALSO SECTION ENDS +--- +title: "^" +title_expanded: bitwise xor +categories: [ "Structure" ] +subCategories: [ "Bitwise Operators" ] +--- + + + + + += ^ Bitwise XOR + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +There is a somewhat unusual operator in C++ called bitwise EXCLUSIVE OR, also known as bitwise XOR. (In English this is usually pronounced "eks-or".) The bitwise XOR operator is written using the caret symbol `^`. A bitwise XOR operation results in a 1 only if the input bits are different, else it results in a 0. +[%hardbreaks] + +Precisely, + + 0 0 1 1 operand1 + 0 1 0 1 operand2 + ---------- + 0 1 1 0 (operand1 ^ operand2) - returned result +[%hardbreaks] + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code + +[source,arduino] +---- +int x = 12; // binary: 1100 +int y = 10; // binary: 1010 +int z = x ^ y; // binary: 0110, or decimal 6 +---- +[%hardbreaks] + +The ^ operator is often used to toggle (i.e. change from 0 to 1, or 1 to 0) some of the bits in an integer expression. In a bitwise XOR operation if there is a 1 in the mask bit, that bit is inverted; if there is a 0, the bit is not inverted and stays the same. + +[source,arduino] +---- +// Note: This code uses registers specific to AVR microcontrollers (Uno, Nano, Leonardo, Mega, etc.) +// it will not compile for other architectures +void setup() { + DDRB = DDRB | 0b00100000; // set PB5 (pin 13 on Uno/Nano, pin 9 on Leonardo/Micro, pin 11 on Mega) as OUTPUT + Serial.begin(9600); +} + +void loop() { + PORTB = PORTB ^ 0b00100000; // invert PB5, leave others untouched + delay(100); +} +---- + + +-- +// HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +[role="example"] +* #EXAMPLE# https://www.arduino.cc/playground/Code/BitMath[BitMath Tutorial^] + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Structure/Boolean Operators/logicalAnd.adoc b/Language/Structure/Boolean Operators/logicalAnd.adoc index 8bbbf351a..b46a749cf 100644 --- a/Language/Structure/Boolean Operators/logicalAnd.adoc +++ b/Language/Structure/Boolean Operators/logicalAnd.adoc @@ -1,64 +1,64 @@ ---- -title: "&&" -title_expanded: logical and -categories: [ "Structure" ] -subCategories: [ "Boolean Operators" ] ---- - - - - - -= && Logical AND - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -*Logical AND* results in `true` *only* if both operands are `true`. -[%hardbreaks] - --- -// OVERVIEW SECTION ENDS - - - -// HOW TO USE SECTION STARTS -[#howtouse] --- - -[float] -=== Example Code -This operator can be used inside the condition of an link:../../control-structure/if[if] statement. - -[source,arduino] ----- -if (digitalRead(2) == HIGH && digitalRead(3) == HIGH) { // if BOTH the switches read HIGH - // statements -} ----- -[%hardbreaks] - -[float] -=== Notes and Warnings -Make sure you don't mistake the boolean AND operator, && (double ampersand) for the bitwise AND operator & (single ampersand). They are entirely different beasts. - --- -// HOW TO USE SECTION ENDS - - -// SEE ALSO SECTION -[#see_also] --- - -[float] -=== See also - -[role="language"] -* #LANGUAGE# link:../../bitwise-operators/bitwiseand[& (Bitwise AND)] - --- -// SEE ALSO SECTION ENDS \ No newline at end of file +--- +title: "&&" +title_expanded: logical and +categories: [ "Structure" ] +subCategories: [ "Boolean Operators" ] +--- + + + + + += && Logical AND + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +*Logical AND* results in `true` *only* if both operands are `true`. +[%hardbreaks] + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code +This operator can be used inside the condition of an link:../../control-structure/if[if] statement. + +[source,arduino] +---- +if (digitalRead(2) == HIGH && digitalRead(3) == HIGH) { // if BOTH the switches read HIGH + // statements +} +---- +[%hardbreaks] + +[float] +=== Notes and Warnings +Make sure you don't mistake the boolean AND operator, && (double ampersand) for the bitwise AND operator & (single ampersand). They are entirely different beasts. + +-- +// HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +[role="language"] +* #LANGUAGE# link:../../bitwise-operators/bitwiseand[& (Bitwise AND)] + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Structure/Boolean Operators/logicalNot.adoc b/Language/Structure/Boolean Operators/logicalNot.adoc index 79009031f..47a29c012 100644 --- a/Language/Structure/Boolean Operators/logicalNot.adoc +++ b/Language/Structure/Boolean Operators/logicalNot.adoc @@ -1,72 +1,72 @@ ---- -title: "!" -title_expanded: logical not -categories: [ "Structure" ] -subCategories: [ "Boolean Operators" ] ---- - - - - - -= ! Logical NOT - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -*Logical NOT* results in a `true` if the operand is `false` and vice versa. -[%hardbreaks] - --- -// OVERVIEW SECTION ENDS - - - -// HOW TO USE SECTION STARTS -[#howtouse] --- - -[float] -=== Example Code -This operator can be used inside the condition of an link:../../control-structure/if/[if] statement. - -[source,arduino] ----- -if (!x) { // if x is not true - // statements -} ----- - -It can be used to invert the boolean value. -[source,arduino] ----- -x = !y; // the inverted value of y is stored in x ----- - - -[%hardbreaks] - -[float] -=== Notes and Warnings -The bitwise not ~ (tilde) looks much different than the boolean not ! (exclamation point or "bang" as the programmers say) but you still have to be sure which one you want where. - --- -// HOW TO USE SECTION ENDS - - -// SEE ALSO SECTION -[#see_also] --- - -[float] -=== See also - -[role="language"] -* #LANGUAGE# link:../../bitwise-operators/bitwisenot[~ Bitwise NOT] - --- -// SEE ALSO SECTION ENDS +--- +title: "!" +title_expanded: logical not +categories: [ "Structure" ] +subCategories: [ "Boolean Operators" ] +--- + + + + + += ! Logical NOT + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +*Logical NOT* results in a `true` if the operand is `false` and vice versa. +[%hardbreaks] + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code +This operator can be used inside the condition of an link:../../control-structure/if[if] statement. + +[source,arduino] +---- +if (!x) { // if x is not true + // statements +} +---- + +It can be used to invert the boolean value. +[source,arduino] +---- +x = !y; // the inverted value of y is stored in x +---- + + +[%hardbreaks] + +[float] +=== Notes and Warnings +The bitwise not ~ (tilde) looks much different than the boolean not ! (exclamation point or "bang" as the programmers say) but you still have to be sure which one you want where. + +-- +// HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +[role="language"] +* #LANGUAGE# link:../../bitwise-operators/bitwisenot[~ Bitwise NOT] + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Structure/Boolean Operators/logicalOr.adoc b/Language/Structure/Boolean Operators/logicalOr.adoc index d876fd062..5032e7aae 100644 --- a/Language/Structure/Boolean Operators/logicalOr.adoc +++ b/Language/Structure/Boolean Operators/logicalOr.adoc @@ -1,66 +1,66 @@ ---- -title: "||" -title_expanded: logical or -categories: [ "Structure" ] -subCategories: [ "Boolean Operators" ] ---- - - - - - -= || Logical OR - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -*Logical OR* results in a `true` if either of the two operands is `true`. -[%hardbreaks] - --- -// OVERVIEW SECTION ENDS - - - -// HOW TO USE SECTION STARTS -[#howtouse] --- - -[float] -=== Example Code -This operator can be used inside the condition of an link:../../control-structure/if[if] statement. - -[source,arduino] ----- -if (x > 0 || y > 0) { // if either x or y is greater than zero - // statements -} ----- - -[%hardbreaks] - -[float] -=== Notes and Warnings -Do not confuse the boolean || (double pipe) operator with the bitwise OR operator | (single pipe). -[%hardbreaks] - --- -// HOW TO USE SECTION ENDS - - -// SEE ALSO SECTION -[#see_also] --- - -[float] -=== See also - -[role="language"] -* #LANGUAGE# link:../../bitwise-operators/bitwiseor[| Bitwise OR] - --- -// SEE ALSO SECTION ENDS \ No newline at end of file +--- +title: "||" +title_expanded: logical or +categories: [ "Structure" ] +subCategories: [ "Boolean Operators" ] +--- + + + + + += || Logical OR + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +*Logical OR* results in a `true` if either of the two operands is `true`. +[%hardbreaks] + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code +This operator can be used inside the condition of an link:../../control-structure/if[if] statement. + +[source,arduino] +---- +if (x > 0 || y > 0) { // if either x or y is greater than zero + // statements +} +---- + +[%hardbreaks] + +[float] +=== Notes and Warnings +Do not confuse the boolean || (double pipe) operator with the bitwise OR operator | (single pipe). +[%hardbreaks] + +-- +// HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +[role="language"] +* #LANGUAGE# link:../../bitwise-operators/bitwiseor[| Bitwise OR] + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Structure/Comparison Operators/equalTo.adoc b/Language/Structure/Comparison Operators/equalTo.adoc index c9f11bd72..23058df15 100644 --- a/Language/Structure/Comparison Operators/equalTo.adoc +++ b/Language/Structure/Comparison Operators/equalTo.adoc @@ -24,15 +24,13 @@ Compares the variable on the left with the value or variable on the right of the [float] === Syntax -[source,arduino] ----- -x == y; // is true if x is equal to y and it is false if x is not equal to y ----- +`x == y; // is true if x is equal to y and it is false if x is not equal to y` + [float] === Parameters -`x`: variable. *Allowed data types:* int, float, double, byte, short, long + -`y`: variable or constant. *Allowed data types:* int, float, double, byte, short, long +`x`: variable. Allowed data types: `int`, `float`, `double`, `byte`, `short`, `long`. + +`y`: variable or constant. Allowed data types: `int`, `float`, `double`, `byte`, `short`, `long`. -- // OVERVIEW SECTION ENDS @@ -48,9 +46,8 @@ x == y; // is true if x is equal to y and it is false if x is not equal to y [source,arduino] ---- -if (x==y) // tests if x is equal to y -{ -// do something only if the comparison result is true +if (x == y) { // tests if x is equal to y + // do something only if the comparison result is true } ---- [%hardbreaks] @@ -71,4 +68,3 @@ if (x==y) // tests if x is equal to y -- // SEE ALSO SECTION ENDS - diff --git a/Language/Structure/Comparison Operators/greaterThan.adoc b/Language/Structure/Comparison Operators/greaterThan.adoc index 3ccb945f7..378c516c4 100644 --- a/Language/Structure/Comparison Operators/greaterThan.adoc +++ b/Language/Structure/Comparison Operators/greaterThan.adoc @@ -24,15 +24,13 @@ Compares the variable on the left with the value or variable on the right of the [float] === Syntax -[source,arduino] ----- -x > y; // is true if x is bigger than y and it is false if x is equal or smaller than y ----- +`x > y; // is true if x is bigger than y and it is false if x is equal or smaller than y` + [float] === Parameters -`x`: variable. *Allowed data types:* int, float, double, byte, short, long + -`y`: variable or constant. *Allowed data types:* int, float, double, byte, short, long +`x`: variable. Allowed data types: `int`, `float`, `double`, `byte`, `short`, `long`. + +`y`: variable or constant. Allowed data types: `int`, `float`, `double`, `byte`, `short`, `long`. -- // OVERVIEW SECTION ENDS @@ -48,16 +46,15 @@ x > y; // is true if x is bigger than y and it is false if x is equal or small [source,arduino] ---- -if (x>y) // tests if x is greater (bigger) than y -{ -// do something only if the comparison result is true +if (x > y) { // tests if x is greater (bigger) than y + // do something only if the comparison result is true } ---- [%hardbreaks] [float] === Notes and Warnings -Positive numbers are greater than negative numbers. +Positive numbers are greater than negative numbers. [%hardbreaks] -- diff --git a/Language/Structure/Comparison Operators/greaterThanOrEqualTo.adoc b/Language/Structure/Comparison Operators/greaterThanOrEqualTo.adoc index 029725ddb..1520d172f 100644 --- a/Language/Structure/Comparison Operators/greaterThanOrEqualTo.adoc +++ b/Language/Structure/Comparison Operators/greaterThanOrEqualTo.adoc @@ -24,15 +24,13 @@ Compares the variable on the left with the value or variable on the right of the [float] === Syntax -[source,arduino] ----- -x >= y; // is true if x is bigger than or equal to y and it is false if x is smaller than y ----- +`x >= y; // is true if x is bigger than or equal to y and it is false if x is smaller than y` + [float] === Parameters -`x`: variable. *Allowed data types:* int, float, double, byte, short, long + -`y`: variable or constant. *Allowed data types:* int, float, double, byte, short, long +`x`: variable. Allowed data types: `int`, `float`, `double`, `byte`, `short`, `long`. + +`y`: variable or constant. Allowed data types: `int`, `float`, `double`, `byte`, `short`, `long`. -- // OVERVIEW SECTION ENDS @@ -48,16 +46,15 @@ x >= y; // is true if x is bigger than or equal to y and it is false if x is s [source,arduino] ---- -if (x>=y) // tests if x is greater (bigger) than or equal to y -{ -// do something only if the comparison result is true +if (x >= y) { // tests if x is greater (bigger) than or equal to y + // do something only if the comparison result is true } ---- [%hardbreaks] [float] === Notes and Warnings -Positive numbers are greater than negative numbers. +Positive numbers are greater than negative numbers. [%hardbreaks] -- diff --git a/Language/Structure/Comparison Operators/lessThan.adoc b/Language/Structure/Comparison Operators/lessThan.adoc index 0f9402560..9e0ad052b 100644 --- a/Language/Structure/Comparison Operators/lessThan.adoc +++ b/Language/Structure/Comparison Operators/lessThan.adoc @@ -24,15 +24,13 @@ Compares the variable on the left with the value or variable on the right of the [float] === Syntax -[source,arduino] ----- -x < y; // is true if x is smaller than y and it is false if x is equal or bigger than y ----- +`x < y; // is true if x is smaller than y and it is false if x is equal or bigger than y` + [float] === Parameters -`x`: variable. *Allowed data types:* int, float, double, byte, short, long + -`y`: variable or constant. *Allowed data types:* int, float, double, byte, short, long +`x`: variable. Allowed data types: `int`, `float`, `double`, `byte`, `short`, `long`. + +`y`: variable or constant. Allowed data types: `int`, `float`, `double`, `byte`, `short`, `long`. -- // OVERVIEW SECTION ENDS @@ -48,16 +46,15 @@ x < y; // is true if x is smaller than y and it is false if x is equal or bigg [source,arduino] ---- -if (x threshold){ // bail out on sensor detect - x = 0; - break; - } - delay(50); -} ----- - --- -// HOW TO USE SECTION ENDS - - - -// SEE ALSO SECTION BEGINS -[#see_also] --- - -[float] -=== See also - -[role="language"] - --- -// SEE ALSO SECTION ENDS +--- +title: break +categories: [ "Structure" ] +subCategories: [ "Control Structure" ] +--- + + + + + += break + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +[%hardbreaks] +`break` is used to exit from a `link:../for[for]`, `link:../while[while]` or `link:../dowhile[do...while]` loop, bypassing the normal loop condition. It is also used to exit from a `link:../switchcase[switch case]` statement. +[%hardbreaks] + +-- +// OVERVIEW SECTION ENDS + + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- +[float] +=== Example Code +In the following code, the control exits the link:../for[`for`] loop when the sensor value exceeds the threshold. +[source,arduino] +---- +int threshold = 40; +for (int x = 0; x < 255; x++) { + analogWrite(PWMpin, x); + sens = analogRead(sensorPin); + if (sens > threshold) { // bail out on sensor detect + x = 0; + break; + } + delay(50); +} +---- + +-- +// HOW TO USE SECTION ENDS + + + +// SEE ALSO SECTION BEGINS +[#see_also] +-- + +[float] +=== See also + +[role="language"] + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Structure/Control Structure/continue.adoc b/Language/Structure/Control Structure/continue.adoc index dc3626679..9c7a368e4 100644 --- a/Language/Structure/Control Structure/continue.adoc +++ b/Language/Structure/Control Structure/continue.adoc @@ -1,66 +1,65 @@ ---- -title: continue -categories: [ "Structure" ] -subCategories: [ "Control Structure" ] ---- - - - - - -= continue - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -[%hardbreaks] -The `continue` statement skips the rest of the current iteration of a loop (link:../for[for], link:../while[while], or link:../dowhile[do...while]). It continues by checking the conditional expression of the loop, and proceeding with any subsequent iterations. -[%hardbreaks] - --- -// OVERVIEW SECTION ENDS - - - - -// HOW TO USE SECTION STARTS -[#howtouse] --- - -[float] -=== Example Code -The following code writes the value of 0 to 255 to the `PWMpin`, but skips the values in the range of 41 to 119. -[source,arduino] ----- -for (x = 0; x <= 255; x ++) -{ - if (x > 40 && x < 120){ // create jump in values - continue; - } - - analogWrite(PWMpin, x); - delay(50); -} ----- - - --- -// HOW TO USE SECTION ENDS - - - -// SEE ALSO SECTION BEGINS -[#see_also] --- - -[float] -=== See also - -[role="language"] - --- -// SEE ALSO SECTION ENDS +--- +title: continue +categories: [ "Structure" ] +subCategories: [ "Control Structure" ] +--- + + + + + += continue + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +[%hardbreaks] +The `continue` statement skips the rest of the current iteration of a loop (`link:../for[for]`, `link:../while[while]`, or `link:../dowhile[do...while]`). It continues by checking the conditional expression of the loop, and proceeding with any subsequent iterations. +[%hardbreaks] + +-- +// OVERVIEW SECTION ENDS + + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code +The following code writes the value of 0 to 255 to the `PWMpin`, but skips the values in the range of 41 to 119. +[source,arduino] +---- +for (int x = 0; x <= 255; x ++) { + if (x > 40 && x < 120) { // create jump in values + continue; + } + + analogWrite(PWMpin, x); + delay(50); +} +---- + + +-- +// HOW TO USE SECTION ENDS + + + +// SEE ALSO SECTION BEGINS +[#see_also] +-- + +[float] +=== See also + +[role="language"] + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Structure/Control Structure/doWhile.adoc b/Language/Structure/Control Structure/doWhile.adoc index d62864d77..033d32b9c 100644 --- a/Language/Structure/Control Structure/doWhile.adoc +++ b/Language/Structure/Control Structure/doWhile.adoc @@ -1,72 +1,78 @@ ---- -title: do...while -categories: [ "Structure" ] -subCategories: [ "Control Structure" ] ---- - - - - - -= do...while loop - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -[%hardbreaks] -The `do...while` loop works in the same manner as the link:../while[while] loop, with the exception that the condition is tested at the end of the loop, so the do loop will always run at least once. - -[float] -=== Syntax -[source,arduino] ----- -do -{ - // statement block -} while (condition); ----- -The `condition` is a boolean expression that evaluates to `true` or `false`. - --- -// OVERVIEW SECTION ENDS - - - - -// HOW TO USE SECTION STARTS -[#howtouse] --- - -[float] -=== Example Code - -[source,arduino] ----- -do -{ - delay(50); // wait for sensors to stabilize - x = readSensors(); // check the sensors - -} while (x < 100); ----- - - --- -// HOW TO USE SECTION ENDS - - -// SEE ALSO SECTION BEGINS -[#see_also] --- - -[float] -=== See also - -[role="language"] - --- -// SEE ALSO SECTION ENDS \ No newline at end of file +--- +title: do...while +categories: [ "Structure" ] +subCategories: [ "Control Structure" ] +--- + + + + + += do...while loop + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +[%hardbreaks] +The `do...while` loop works in the same manner as the `link:../while[while]` loop, with the exception that the condition is tested at the end of the loop, so the do loop will always run at least once. + +[float] +=== Syntax +[source,arduino] +---- +do { + // statement block +} while (condition); +---- + + +[float] +=== Parameters +`condition`: a boolean expression that evaluates to `link:../../../variables/constants/truefalse[true]` or `link:../../../variables/constants/truefalse[false]`. + +-- +// OVERVIEW SECTION ENDS + + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code + +[source,arduino] +---- +// initialize x and i with a value of 0 +int x = 0; +int i = 0; + +do { + delay(50); // wait for sensors to stabilize + x = readSensors(); // check the sensors + i++; // increase i by 1 +} while (i < 100); // repeat 100 times +---- + + +-- +// HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION BEGINS +[#see_also] +-- + +[float] +=== See also + +[role="language"] + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Structure/Control Structure/else.adoc b/Language/Structure/Control Structure/else.adoc index 8ac37de85..769e9d965 100644 --- a/Language/Structure/Control Structure/else.adoc +++ b/Language/Structure/Control Structure/else.adoc @@ -4,10 +4,6 @@ categories: [ "Structure" ] subCategories: [ "Control Structure" ] --- - - - - = if...else @@ -17,31 +13,29 @@ subCategories: [ "Control Structure" ] [float] === Description -The `if...else` allows greater control over the flow of code than the basic link:../if[if] statement, by allowing multiple tests to be grouped together. An `else` clause (if at all exists) will be executed if the condition in the `if` statement results in `false`. The `else` can proceed another `if` test, so that multiple, mutually exclusive tests can be run at the same time. +The `if...else` allows greater control over the flow of code than the basic `link:../if[if]` statement, by allowing multiple tests to be grouped. An `else` clause (if at all exists) will be executed if the condition in the `if` statement results in `false`. The `else` can proceed another `if` test, so that multiple, mutually exclusive tests can be run at the same time. [%hardbreaks] Each test will proceed to the next one until a true test is encountered. When a true test is found, its associated block of code is run, and the program then skips to the line following the entire if/else construction. If no test proves to be true, the default `else` block is executed, if one is present, and sets the default behavior. [%hardbreaks] -Note that an `else if` block may be used with or without a terminating `else` block and vice versa. An unlimited number of such `else if` branches is allowed. +Note that an `else if` block may be used with or without a terminating `else` block and vice versa. An unlimited number of such `else if` branches are allowed. [float] === Syntax [source,arduino] ---- -if (condition1) -{ +if (condition1) { // do Thing A } -else if (condition2) -{ +else if (condition2) { // do Thing B } -else -{ +else { // do Thing C } ---- + -- // OVERVIEW SECTION ENDS @@ -55,17 +49,14 @@ else Below is an extract from a code for temperature sensor system [source,arduino] ---- -if (temperature >= 70) -{ - //Danger! Shut down the system +if (temperature >= 70) { + // Danger! Shut down the system. } -else if (temperature >= 60 && temperature < 70) -{ - //Warning! User attention required +else if (temperature >= 60) { // 60 <= temperature < 70 + // Warning! User attention required. } -else -{ - //Safe! Continue usual tasks... +else { // temperature < 60 + // Safe! Continue usual tasks. } ---- @@ -84,4 +75,4 @@ else [role="language"] -- -// SEE ALSO SECTION ENDS \ No newline at end of file +// SEE ALSO SECTION ENDS diff --git a/Language/Structure/Control Structure/for.adoc b/Language/Structure/Control Structure/for.adoc index ce68a1383..3ddf86d4f 100644 --- a/Language/Structure/Control Structure/for.adoc +++ b/Language/Structure/Control Structure/for.adoc @@ -1,115 +1,118 @@ ---- -title: for -categories: [ "Structure" ] -subCategories: [ "Control Structure" ] ---- - - - - - -= for loop - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -The `for` statement is used to repeat a block of statements enclosed in curly braces. An increment counter is usually used to increment and terminate the loop. The `for` statement is useful for any repetitive operation, and is often used in combination with arrays to operate on collections of data/pins. -[%hardbreaks] - - -[float] -=== Syntax -[source,arduino] ----- -for (initialization; condition; increment) { - //statement(s); -} ----- - -The *initialization* happens first and exactly once. Each time through the loop, the *condition* is tested; if it's `true`, the statement block, and the *increment* is executed, then the *condition* is tested again. When the *condition* becomes `false`, the loop ends. -[%hardbreaks] - --- -// OVERVIEW SECTION ENDS - - - - -// HOW TO USE SECTION STARTS -[#howtouse] --- - -[float] -=== Example Code -[source,arduino] ----- -// Dim an LED using a PWM pin -int PWMpin = 10; // LED in series with 470 ohm resistor on pin 10 - -void setup() -{ - // no setup needed -} - -void loop() -{ - for (int i=0; i <= 255; i++){ - analogWrite(PWMpin, i); - delay(10); - } -} ----- -[%hardbreaks] - -[float] -=== Notes and Warnings -The C `for` loop is much more flexible than `for` loops found in some other computer languages, including BASIC. Any or all of the three header elements may be omitted, although the semicolons are required. Also the statements for initialization, condition, and increment can be any valid C statements with unrelated variables, and use any C datatypes including floats. These types of unusual `for` statements may provide solutions to some rare programming problems. -[%hardbreaks] - -For example, using a multiplication in the increment line will generate a logarithmic progression: - -[source,arduino] ----- -for(int x = 2; x < 100; x = x * 1.5){ -println(x); -} ----- - -Generates: 2,3,4,6,9,13,19,28,42,63,94 -[%hardbreaks] - -Another example, fade an LED up and down with one `for` loop: - -[source,arduino] ----- -void loop() -{ - int x = 1; - for (int i = 0; i > -1; i = i + x){ - analogWrite(PWMpin, i); - if (i == 255) x = -1; // switch direction at peak - delay(10); - } -} ----- - - --- -// HOW TO USE SECTION ENDS - - -// SEE ALSO SECTION BEGINS -[#see_also] --- - -[float] -=== See also - -[role="language"] - --- -// SEE ALSO SECTION ENDS \ No newline at end of file +--- +title: for +categories: [ "Structure" ] +subCategories: [ "Control Structure" ] +--- + + + + + += for loop + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +The `for` statement is used to repeat a block of statements enclosed in curly braces. An increment counter is usually used to increment and terminate the loop. The `for` statement is useful for any repetitive operation, and is often used in combination with arrays to operate on collections of data/pins. +[%hardbreaks] + + +[float] +=== Syntax +[source,arduino] +---- +for (initialization; condition; increment) { + // statement(s); +} +---- + + +[float] +=== Parameters +`initialization`: happens first and exactly once. + +`condition`: each time through the loop, `condition` is tested; if it's `link:../../../variables/constants/truefalse[true]`, the statement block, and the *increment* is executed, then the *condition* is tested again. When the *condition* becomes `link:../../../variables/constants/truefalse[false]`, the loop ends. + +`increment`: executed each time through the loop when `condition` is link:../../../variables/constants/truefalse[`true`]. + +-- +// OVERVIEW SECTION ENDS + + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code +[source,arduino] +---- +// Brighten an LED using a PWM pin +int PWMpin = 10; // LED in series with 470 ohm resistor from pin 10 to ground + +void setup() { + // no setup needed +} + +void loop() { + for (int i = 0; i <= 255; i++) { + analogWrite(PWMpin, i); + delay(10); + } +} +---- +[%hardbreaks] + +[float] +=== Notes and Warnings +The pass:[C++] `for` loop is much more flexible than `for` loops found in some other computer languages, including BASIC. Any or all of the three header elements may be omitted, although the semicolons are required. Also the statements for initialization, condition, and increment can be any valid pass:[C++] statements with unrelated variables, and use any pass:[C++] datatypes including floats. These types of unusual `for` statements may provide solutions to some rare programming problems. +[%hardbreaks] + +For example, using a multiplication in the increment line will generate a logarithmic progression: + +[source,arduino] +---- +for (int x = 2; x < 100; x = x * 1.5) { + println(x); +} +---- + +Generates: 2,3,4,6,9,13,19,28,42,63,94 +[%hardbreaks] + +Another example, fade an LED up and down with one `for` loop: + +[source,arduino] +---- +void loop() { + int x = 1; + for (int i = 0; i > -1; i = i + x) { + analogWrite(PWMpin, i); + if (i == 255) { + x = -1; // switch direction at peak + } + delay(10); + } +} +---- + + +-- +// HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION BEGINS +[#see_also] +-- + +[float] +=== See also + +[role="language"] + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Structure/Control Structure/goto.adoc b/Language/Structure/Control Structure/goto.adoc index 34b1a6be3..57de782cf 100644 --- a/Language/Structure/Control Structure/goto.adoc +++ b/Language/Structure/Control Structure/goto.adoc @@ -1,83 +1,86 @@ ---- -title: goto -categories: [ "Structure" ] -subCategories: [ "Control Structure" ] ---- - - - - - -= goto - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -Transfers program flow to a labeled point in the program -[%hardbreaks] - - -[float] -=== Syntax -[source,arduino] ----- -label: - -goto label; // sends program flow to the label ----- - --- -// OVERVIEW SECTION ENDS - - - - -// HOW TO USE SECTION STARTS -[#howtouse] --- - -[float] -=== Example Code - -[source,arduino] ----- -for(byte r = 0; r < 255; r++){ - for(byte g = 255; g > 0; g--){ - for(byte b = 0; b < 255; b++){ - if (analogRead(0) > 250){ goto bailout;} - // more statements ... - } - } -} - -bailout: ----- -[%hardbreaks] - -[float] -=== Notes and Warnings -The use of `goto` is discouraged in C programming, and some authors of C programming books claim that the `goto` statement is never necessary, but used judiciously, it can simplify certain programs. The reason that many programmers frown upon the use of goto is that with the unrestrained use of `goto` statements, it is easy to create a program with undefined program flow, which can never be debugged. - -With that said, there are instances where a `goto` statement can come in handy, and simplify coding. One of these situations is to break out of deeply nested link:../for[for] loops, or link:../if[if] logic blocks, on a certain condition. -[%hardbreaks] - --- -// HOW TO USE SECTION ENDS - - - - -// SEE ALSO SECTION BEGINS -[#see_also] --- - -[float] -=== See also -[role="language"] - --- -// SEE ALSO SECTION ENDS +--- +title: goto +categories: [ "Structure" ] +subCategories: [ "Control Structure" ] +--- + + + + + += goto + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Transfers program flow to a labeled point in the program +[%hardbreaks] + + +[float] +=== Syntax +[source,arduino] +---- +label: + +goto label; // sends program flow to the label +---- + +-- +// OVERVIEW SECTION ENDS + + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code + +[source,arduino] +---- +for (byte r = 0; r < 255; r++) { + for (byte g = 255; g > 0; g--) { + for (byte b = 0; b < 255; b++) { + if (analogRead(0) > 250) { + goto bailout; + } + // more statements ... + } + } +} + +bailout: +// more statements ... +---- +[%hardbreaks] + +[float] +=== Notes and Warnings +The use of `goto` is discouraged in C++ programming, and some authors of C++ programming books claim that the `goto` statement is never necessary, but used judiciously, it can simplify certain programs. The reason that many programmers frown upon the use of goto is that with the unrestrained use of `goto` statements, it is easy to create a program with undefined program flow, which can never be debugged. + +With that said, there are instances where a `goto` statement can come in handy, and simplify coding. One of these situations is to break out of deeply nested link:../for[for] loops, or link:../if[if] logic blocks, on a certain condition. +[%hardbreaks] + +-- +// HOW TO USE SECTION ENDS + + + + +// SEE ALSO SECTION BEGINS +[#see_also] +-- + +[float] +=== See also +[role="language"] + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Structure/Control Structure/if.adoc b/Language/Structure/Control Structure/if.adoc index 225a189dc..45ad2da20 100644 --- a/Language/Structure/Control Structure/if.adoc +++ b/Language/Structure/Control Structure/if.adoc @@ -1,95 +1,107 @@ ---- -title: if...else -categories: [ "Structure" ] -subCategories: [ "Control Structure" ] ---- - - - - - -= if (conditional) and ==, !=, <, > (comparison operators) - - -// OVERVIEW SECTION STARTS -[#overview] --- -[float] -=== Description -The `if` statement checks for a condition and executes the proceeding statement or set of statements if the condition is 'true'. -[%hardbreaks] - -[float] -=== Syntax -[source,arduino] ----- -if (condition) -{ - //statement(s) -} ----- - -[float] -=== Parameters -condition: a boolean expression i.e., can be `true` or `false` - -[float] -=== Example Code - -The brackets may be omitted after an if statement. If this is done, the next line (defined by the semicolon) becomes the only conditional statement. -[%hardbreaks] - -[source,arduino] ----- -if (x > 120) digitalWrite(LEDpin, HIGH); - -if (x > 120) -digitalWrite(LEDpin, HIGH); - -if (x > 120){ digitalWrite(LEDpin, HIGH); } - -if (x > 120){ - digitalWrite(LEDpin1, HIGH); - digitalWrite(LEDpin2, HIGH); -} // all are correct ----- -[%hardbreaks] - - -[float] -=== Notes and Warnings -The statements being evaluated inside the parentheses require the use of one or more operators shown below. -[%hardbreaks] - -*Comparison Operators:* - - x == y (x is equal to y) - x != y (x is not equal to y) - x < y (x is less than y) - x > y (x is greater than y) - x <= y (x is less than or equal to y) - x >= y (x is greater than or equal to y) - - -Beware of accidentally using the single equal sign (e.g. `if (x = 10)` ). The single equal sign is the assignment operator, and sets `x` to 10 (puts the value 10 into the variable `x`). Instead use the double equal sign (e.g. `if (x == 10)` ), which is the comparison operator, and tests _whether_ `x` is equal to 10 or not. The latter statement is only true if `x` equals 10, but the former statement will always be true. - -This is because C evaluates the statement `if (x=10)` as follows: 10 is assigned to `x` (remember that the single equal sign is the (http://arduino.cc/en/Reference/Assignment[assignment operator^])), so `x` now contains 10. Then the 'if' conditional evaluates 10, which always evaluates to `TRUE`, since any non-zero number evaluates to TRUE. Consequently, `if (x = 10)` will always evaluate to `TRUE`, which is not the desired result when using an 'if' statement. Additionally, the variable `x` will be set to 10, which is also not a desired action. -[%hardbreaks] - --- -// HOW TO USE SECTION ENDS - - - - -// SEE ALSO SECTION BEGINS -[#see_also] --- - -[float] -=== See also - -[role="language"] - --- -// SEE ALSO SECTION ENDS +--- +title: if +categories: [ "Structure" ] +subCategories: [ "Control Structure" ] +--- + + + + + += if + + +// OVERVIEW SECTION STARTS +[#overview] +-- +[float] +=== Description +The `if` statement checks for a condition and executes the following statement or set of statements if the condition is 'true'. +[%hardbreaks] + +[float] +=== Syntax +[source,arduino] +---- +if (condition) { + //statement(s) +} +---- + + +[float] +=== Parameters +`condition`: a boolean expression (i.e., can be `true` or `false`). + +-- +// OVERVIEW SECTION ENDS + + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code + +The brackets may be omitted after an if statement. If this is done, the next line (defined by the semicolon) becomes the only conditional statement. +[%hardbreaks] + +[source,arduino] +---- +if (x > 120) digitalWrite(LEDpin, HIGH); + +if (x > 120) +digitalWrite(LEDpin, HIGH); + +if (x > 120) {digitalWrite(LEDpin, HIGH);} + +if (x > 120) { + digitalWrite(LEDpin1, HIGH); + digitalWrite(LEDpin2, HIGH); +} +// all are correct +---- +[%hardbreaks] + + +[float] +=== Notes and Warnings +The statements being evaluated inside the parentheses require the use of one or more operators shown below. +[%hardbreaks] + +*Comparison Operators:* + + x == y (x is equal to y) + x != y (x is not equal to y) + x < y (x is less than y) + x > y (x is greater than y) + x <= y (x is less than or equal to y) + x >= y (x is greater than or equal to y) + + +Beware of accidentally using the single equal sign (e.g. `if (x = 10)` ). The single equal sign is the assignment operator, and sets `x` to 10 (puts the value 10 into the variable `x`). Instead use the double equal sign (e.g. `if (x == 10)` ), which is the comparison operator, and tests _whether_ `x` is equal to 10 or not. The latter statement is only true if `x` equals 10, but the former statement will always be true. + +This is because C++ evaluates the statement `if (x=10)` as follows: 10 is assigned to `x` (remember that the single equal sign is the (http://arduino.cc/en/Reference/Assignment[assignment operator^])), so `x` now contains 10. Then the 'if' conditional evaluates 10, which always evaluates to `TRUE`, since any non-zero number evaluates to TRUE. Consequently, `if (x = 10)` will always evaluate to `TRUE`, which is not the desired result when using an 'if' statement. Additionally, the variable `x` will be set to 10, which is also not a desired action. +[%hardbreaks] + +-- +// HOW TO USE SECTION ENDS + + + + +// SEE ALSO SECTION BEGINS +[#see_also] +-- + +[float] +=== See also + +[role="language"] +* #LANGUAGE# link:../else[else] + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Structure/Control Structure/return.adoc b/Language/Structure/Control Structure/return.adoc index 51f5626fe..abd53be57 100644 --- a/Language/Structure/Control Structure/return.adoc +++ b/Language/Structure/Control Structure/return.adoc @@ -1,95 +1,90 @@ ---- -title: return -categories: [ "Structure" ] -subCategories: [ "Control Structure" ] ---- - - - - - -= return - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -Terminate a function and return a value from a function to the calling function, if desired. -[%hardbreaks] - - -[float] -=== Syntax -[source,arduino] ----- -return; - -return value; // both forms are valid ----- - - -[float] -=== Parameters -`value': any variable or constant type - --- -// OVERVIEW SECTION ENDS - - - - -// HOW TO USE SECTION STARTS -[#howtouse] --- - -[float] -=== Example Code -A function to compare a sensor input to a threshold - -[source,arduino] ----- - int checkSensor(){ - if (analogRead(0) > 400) { - return 1; - } - else{ - return 0; - } -} ----- - -The return keyword is handy to test a section of code without having to "comment out" large sections of possibly buggy code. -[source,arduino] ----- -void loop(){ - -// brilliant code idea to test here - -return; - -// the rest of a dysfunctional sketch here -// this code will never be executed -} ----- -[%hardbreaks] - --- -// HOW TO USE SECTION ENDS - - - - - -// SEE ALSO SECTION BEGINS -[#see_also] --- - -[float] -=== See also -[role="language"] - --- -// SEE ALSO SECTION ENDS +--- +title: return +categories: [ "Structure" ] +subCategories: [ "Control Structure" ] +--- + + + + + += return + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Terminate a function and return a value from a function to the calling function, if desired. +[%hardbreaks] + + +[float] +=== Syntax +`return;` + +`return value;` + + +[float] +=== Parameters +`value`: Allowed data types: any variable or constant type. + +-- +// OVERVIEW SECTION ENDS + + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code +A function to compare a sensor input to a threshold + +[source,arduino] +---- +int checkSensor() { + if (analogRead(0) > 400) { + return 1; + } + else { + return 0; + } +} +---- + +The return keyword is handy to test a section of code without having to "comment out" large sections of possibly buggy code. +[source,arduino] +---- +void loop() { + // brilliant code idea to test here + + return; + + // the rest of a dysfunctional sketch here + // this code will never be executed +} +---- +[%hardbreaks] + +-- +// HOW TO USE SECTION ENDS + + + + + +// SEE ALSO SECTION BEGINS +[#see_also] +-- + +[float] +=== See also +[role="language"] + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Structure/Control Structure/switchCase.adoc b/Language/Structure/Control Structure/switchCase.adoc index 88335ad17..7b2fad04d 100644 --- a/Language/Structure/Control Structure/switchCase.adoc +++ b/Language/Structure/Control Structure/switchCase.adoc @@ -1,99 +1,104 @@ ---- -title: switch...case -categories: [ "Structure" ] -subCategories: [ "Control Structure" ] ---- - - - - - -= switch...case statement - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -Like link:../if[if] statements, link:../switchcase[switch case] controls the flow of programs by allowing programmers to specify different code that should be executed in various conditions. In particular, a switch statement compares the value of a variable to the values specified in case statements. When a case statement is found whose value matches that of the variable, the code in that case statement is run. -[%hardbreaks] - -The link:../break[break] keyword exits the switch statement, and is typically used at the end of each case. Without a break statement, the switch statement will continue executing the following expressions ("falling-through") until a break, or the end of the switch statement is reached. -[%hardbreaks] - - -[float] -=== Syntax -[source,arduino] ----- -switch (var) { - case label1: - // statements - break; - case label2: - // statements - break; - default: - // statements -} ----- - - -[float] -=== Parameters -`var`: a variable whose value to compare with various cases. *Allowed data types:* int, char + -`label1`, `label2`: constants. *Allowed data types:* int, char - -[float] -=== Returns -Nothing - --- -// OVERVIEW SECTION ENDS - - - - -// HOW TO USE SECTION STARTS -[#howtouse] --- - -[float] -=== Example Code - -[source,arduino] ----- - switch (var) { - case 1: - //do something when var equals 1 - break; - case 2: - //do something when var equals 2 - break; - default: - // if nothing else matches, do the default - // default is optional - break; - } - ----- -[%hardbreaks] - --- -// HOW TO USE SECTION ENDS - - - - -// SEE ALSO SECTIN BEGINS -[#see_also] --- - -[float] -=== See also -[role="language"] - --- -// SEE ALSO SECTION ENDS +--- +title: switch...case +categories: [ "Structure" ] +subCategories: [ "Control Structure" ] +--- + + + + + += switch...case statement + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Like link:../if[if] statements, link:../switchcase[switch case] controls the flow of programs by allowing programmers to specify different code that should be executed in various conditions. In particular, a switch statement compares the value of a variable to the values specified in case statements. When a case statement is found whose value matches that of the variable, the code in that case statement is run. +[%hardbreaks] + +The link:../break[break] keyword exits the switch statement, and is typically used at the end of each case. Without a break statement, the switch statement will continue executing the following expressions ("falling-through") until a break, or the end of the switch statement is reached. +[%hardbreaks] + + +[float] +=== Syntax +[source,arduino] +---- +switch (var) { + case label1: + // statements + break; + case label2: + // statements + break; + default: + // statements + break; +} +---- + + +[float] +=== Parameters +`var`: an *integer* variable whose value to compare with various cases. Any integer data type is allowed*, such as `byte`, `char`, `int`, `long`. +`label1`, `label2`: constants. Any integer data type here is also allowed. + +*You can also use the `bool` data type when you specify just two switch cases. + +Note that you can also use negative values as input. + +[float] +=== Returns +Nothing + +-- +// OVERVIEW SECTION ENDS + + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code + +[source,arduino] +---- +switch (var) { + case 1: + // do something when var equals 1 + break; + case 2: + // do something when var equals 2 + break; + default: + // if nothing else matches, do the default + // default is optional + break; +} + +---- +[%hardbreaks] + +-- +// HOW TO USE SECTION ENDS + + + + +// SEE ALSO SECTION BEGINS +[#see_also] +-- + +[float] +=== See also +[role="language"] + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Structure/Control Structure/while.adoc b/Language/Structure/Control Structure/while.adoc index fce5e5102..09b25192c 100644 --- a/Language/Structure/Control Structure/while.adoc +++ b/Language/Structure/Control Structure/while.adoc @@ -1,73 +1,77 @@ ---- -title: while -categories: [ "Structure" ] -subCategories: [ "Control Structure" ] ---- - - - - - -= while loop - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -[%hardbreaks] -A `while` loop will loop continuously, and infinitely, until the expression inside the parenthesis, () becomes false. Something must change the tested variable, or the while loop will never exit. This could be in your code, such as an incremented variable, or an external condition, such as testing a sensor. - -[float] -=== Syntax -[source,arduino] ----- -while(condition){ - // statement(s) -} ----- -The `condition` is a boolean expression that evaluates to `true` or `false`. - --- -// OVERVIEW SECTION ENDS - - - - -// HOW TO USE SECTION STARTS -[#howtouse] --- - -[float] -=== Example Code - -[source,arduino] ----- -var = 0; -while(var < 200){ - // do something repetitive 200 times - var++; -} ----- - --- -// HOW TO USE SECTION ENDS - - - -// SEE ALSO SECTION BEGINS -[#see_also] --- - -[float] -=== See also - -[role="language"] - -[role="example"] -* #EXAMPLE# https://arduino.cc/en/Tutorial/WhileLoop[While Loop Tutorial^] - --- -// SEE ALSO SECTION ENDS \ No newline at end of file +--- +title: while +categories: [ "Structure" ] +subCategories: [ "Control Structure" ] +--- + + + + + += while loop + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +[%hardbreaks] +A `while` loop will loop continuously, and infinitely, until the expression inside the parenthesis, () becomes false. Something must change the tested variable, or the while loop will never exit. This could be in your code, such as an incremented variable, or an external condition, such as testing a sensor. + +[float] +=== Syntax +[source,arduino] +---- +while (condition) { + // statement(s) +} +---- + + +[float] +=== Parameters +`condition`: a boolean expression that evaluates to `true` or `false`. + +-- +// OVERVIEW SECTION ENDS + + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code + +[source,arduino] +---- +var = 0; +while (var < 200) { + // do something repetitive 200 times + var++; +} +---- + +-- +// HOW TO USE SECTION ENDS + + + +// SEE ALSO SECTION BEGINS +[#see_also] +-- + +[float] +=== See also + +[role="language"] + +[role="example"] +* #EXAMPLE# https://www.arduino.cc/en/Tutorial/BuiltInExamples/WhileStatementConditional[While Loop^] + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Structure/Further Syntax/blockComment.adoc b/Language/Structure/Further Syntax/blockComment.adoc index 89271c234..62c0a8f40 100644 --- a/Language/Structure/Further Syntax/blockComment.adoc +++ b/Language/Structure/Further Syntax/blockComment.adoc @@ -1,81 +1,81 @@ ---- -title: "/* */" -title_expanded: block comment -categories: [ "Structure" ] -subCategories: [ "Further Syntax" ] ---- - - - - - -= /* */ Block Comment - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -*Comments* are lines in the program that are used to inform yourself or others about the way the program works. They are ignored by the compiler, and not exported to the processor, so they don't take up any space in the microcontroller's flash memory. Comments' only purpose is to help you understand (or remember), or to inform others about how your program works. -[%hardbreaks] - -The beginning of a *block comment* or a *multi-line comment* is marked by the symbol `/\*` and the symbol `*/` marks its end. This type of a comment is called so as this can extend over more than one line; once the compiler reads the `/\*` it ignores whatever follows unitl it enounters a `*/`. - -// NOTE TO THE EDITOR: The '\' before the '*' in certain places are to escape the '*' from making the text bolder. -// In places were '\' is not used before '*', it is not actually required. --- -// OVERVIEW SECTION ENDS - - - - -// HOW TO USE SECTION STARTS -[#howtouse] --- - -[float] -=== Example Code -[source,arduino] ----- -/* This is a valid comment */ - -/* - Blink - Turns on an LED on for one second, then off for one second, repeatedly. - - This example code is in the public domain. - (Another valid comment) -*/ - -/* - if (gwb == 0){ // single line comment is OK inside a multi-line comment - x = 3; /* but not another multi-line comment - this is invalid */ - } -// don't forget the "closing" comment - they have to be balanced! -*/ ----- -[%hardbreaks] - -[float] -=== Notes and Warnings -When experimenting with code, "commenting out" parts of your program is a convenient way to remove lines that may be buggy. This leaves the lines in the code, but turns them into comments, so the compiler just ignores them. This can be especially useful when trying to locate a problem, or when a program refuses to compile and the compiler error is cryptic or unhelpful. -[%hardbreaks] - --- -// HOW TO USE SECTION ENDS - - - - -// SEE ALSO SECTION BEGINS -[#see_also] --- - -[float] -=== See also -[role="language"] - --- -// SEE ALSO SECTION ENDS \ No newline at end of file +--- +title: "/* */" +title_expanded: block comment +categories: [ "Structure" ] +subCategories: [ "Further Syntax" ] +--- + + + + + += /* */ Block Comment + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +*Comments* are lines in the program that are used to inform yourself or others about the way the program works. They are ignored by the compiler, and not exported to the processor, so they don't take up any space in the microcontroller's flash memory. Comments' only purpose is to help you understand (or remember), or to inform others about how your program works. +[%hardbreaks] + +The beginning of a *block comment* or a *multi-line comment* is marked by the symbol `/\*` and the symbol `*/` marks its end. This type of comment is called so as this can extend over more than one line; once the compiler reads the `/\*` it ignores whatever follows until it encounters a `*/`. + +// NOTE TO THE EDITOR: The '\' before the '*' in certain places are to escape the '*' from making the text bolder. +// In places were '\' is not used before '*', it is not actually required. +-- +// OVERVIEW SECTION ENDS + + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code +[source,arduino] +---- +/* This is a valid comment */ + +/* + Blink + Turns on an LED on for one second, then off for one second, repeatedly. + + This example code is in the public domain. + (Another valid comment) +*/ + +/* + if (gwb == 0) { // single line comment is OK inside a multi-line comment + x = 3; /* but not another multi-line comment - this is invalid */ + } +// don't forget the "closing" comment - they have to be balanced! +*/ +---- +[%hardbreaks] + +[float] +=== Notes and Warnings +When experimenting with code, "commenting out" parts of your program is a convenient way to remove lines that may be buggy. This leaves the lines in the code, but turns them into comments, so the compiler just ignores them. This can be especially useful when trying to locate a problem, or when a program refuses to compile and the compiler error is cryptic or unhelpful. +[%hardbreaks] + +-- +// HOW TO USE SECTION ENDS + + + + +// SEE ALSO SECTION BEGINS +[#see_also] +-- + +[float] +=== See also +[role="language"] + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Structure/Further Syntax/curlyBraces.adoc b/Language/Structure/Further Syntax/curlyBraces.adoc index 172d4dc91..9bafb7fdc 100644 --- a/Language/Structure/Further Syntax/curlyBraces.adoc +++ b/Language/Structure/Further Syntax/curlyBraces.adoc @@ -17,10 +17,10 @@ subCategories: [ "Further Syntax" ] [float] === Description -Curly braces (also referred to as just "braces" or as "curly brackets") are a major part of the C programming language. They are used in several different constructs, outlined below, and this can sometimes be confusing for beginners. + +Curly braces (also referred to as just "braces" or as "curly brackets") are a major part of the C++ programming language. They are used in several different constructs, outlined below, and this can sometimes be confusing for beginners. + An opening curly brace `{` must always be followed by a closing curly brace `}`. This is a condition that is often referred to as the braces being balanced. The Arduino IDE (Integrated Development Environment) includes a convenient feature to check the balance of curly braces. Just select a brace, or even click the insertion point immediately following a brace, and its logical companion will be highlighted. [%hardbreaks] -Beginners programmers, and programmers coming to C from the BASIC language often find using braces confusing or daunting. After all, the same curly braces replace the RETURN statement in a subroutine (function), the ENDIF statement in a conditional and the NEXT statement in a FOR loop. +Beginner programmers, and programmers coming to C++ from the BASIC language often find using braces confusing or daunting. After all, the same curly braces replace the RETURN statement in a subroutine (function), the ENDIF statement in a conditional and the NEXT statement in a FOR loop. [%hardbreaks] Unbalanced braces can often lead to cryptic, impenetrable compiler errors that can sometimes be hard to track down in a large program. Because of their varied usages, braces are also incredibly important to the syntax of a program and moving a brace one or two lines will often dramatically affect the meaning of a program. [%hardbreaks] @@ -45,8 +45,8 @@ The main uses of curly braces are listed in the examples below. [source,arduino] ---- -void myfunction(datatype argument){ - statements(s) +void myfunction(datatype argument) { + // any statement(s) } ---- [%hardbreaks] @@ -57,19 +57,16 @@ void myfunction(datatype argument){ [source,arduino] ---- -while (boolean expression) -{ - statement(s) +while (boolean expression) { + // any statement(s) } -do -{ - statement(s) +do { + // any statement(s) } while (boolean expression); -for (initialisation; termination condition; incrementing expr) -{ - statement(s) +for (initialisation; termination condition; incrementing expr) { + // any statement(s) } ---- [%hardbreaks] @@ -82,18 +79,15 @@ for (initialisation; termination condition; incrementing expr) [source,arduino] ---- -if (boolean expression) -{ - statement(s) +if (boolean expression) { + // any statement(s) } -else if (boolean expression) -{ - statement(s) +else if (boolean expression) { + // any statement(s) } -else -{ - statement(s) +else { + // any statement(s) } ---- [%hardbreaks] @@ -112,4 +106,4 @@ else [role="language"] -- -// SEE ALSO SECTION ENDS \ No newline at end of file +// SEE ALSO SECTION ENDS diff --git a/Language/Structure/Further Syntax/define.adoc b/Language/Structure/Further Syntax/define.adoc index e65b03114..c04df008f 100644 --- a/Language/Structure/Further Syntax/define.adoc +++ b/Language/Structure/Further Syntax/define.adoc @@ -1,94 +1,94 @@ ---- -title: "#define" -title_expanded: define -categories: [ "Structure" ] -subCategories: [ "Further Syntax" ] ---- - - - - - -= #define - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -`#define` is a useful C component that allows the programmer to give a name to a constant value before the program is compiled. Defined constants in arduino don't take up any program memory space on the chip. The compiler will replace references to these constants with the defined value at compile time. -[%hardbreaks] - -This can have some unwanted side effects though, if for example, a constant name that had been #defined is included in some other constant or variable name. In that case the text would be replaced by the #defined number (or text). -[%hardbreaks] - -In general, the link:../../../variables/variable-scope\--qualifiers/const[const] keyword is preferred for defining constants and should be used instead of #define. -[%hardbreaks] - -[float] -=== Syntax -[source,arduino] ----- -#define constantName value ----- -Note that the # is necessary. -[%hardbreaks] - --- -// OVERVIEW SECTION ENDS - - - - -// HOW TO USE SECTION STARTS -[#howtouse] --- - -[float] -=== Example Code - -[source,arduino] ----- -#define ledPin 3 -// The compiler will replace any mention of ledPin with the value 3 at compile time. ----- -[%hardbreaks] - -[float] -=== Notes and Warnings -There is no semicolon after the #define statement. If you include one, the compiler will throw cryptic errors further down the page. - -[source,arduino] ----- -#define ledPin 3; // this is an error ----- - -Similarly, including an equal sign after the #define statement will also generate a cryptic compiler error further down the page. - -[source,arduino] ----- -#define ledPin = 3 // this is also an error ----- -[%hardbreaks] - --- -// HOW TO USE SECTION ENDS - - - - -// SEE ALSO SECTION BEGINS -[#see_also] --- - -[float] -=== See also - -[role="language"] -* #LANGUAGE# link:../../../variables/variable-scope\--qualifiers/const[const] -* #LANGUAGE# link:../../../variables/constants/constants[Constants] - --- -// SEE ALSO SECTION ENDS +--- +title: "#define" +title_expanded: define +categories: [ "Structure" ] +subCategories: [ "Further Syntax" ] +--- + + + + + += #define + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +`#define` is a useful C++ component that allows the programmer to give a name to a constant value before the program is compiled. Defined constants in arduino don't take up any program memory space on the chip. The compiler will replace references to these constants with the defined value at compile time. +[%hardbreaks] + +This can have some unwanted side effects though, if for example, a constant name that had been #defined is included in some other constant or variable name. In that case the text would be replaced by the #defined number (or text). +[%hardbreaks] + +In general, the `link:../../../variables/variable-scope-qualifiers/const[const]` keyword is preferred for defining constants and should be used instead of `#define`. +[%hardbreaks] + +[float] +=== Syntax +`#define constantName value` + + +[float] +=== Parameters +`constantName`: the name of the macro to define. + +`value`: the value to assign to the macro. + +-- +// OVERVIEW SECTION ENDS + + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code + +[source,arduino] +---- +#define ledPin 3 +// The compiler will replace any mention of ledPin with the value 3 at compile time. +---- +[%hardbreaks] + +[float] +=== Notes and Warnings +There is no semicolon after the #define statement. If you include one, the compiler will throw cryptic errors further down the page. + +[source,arduino] +---- +#define ledPin 3; // this is an error +---- + +Similarly, including an equal sign after the #define statement will also generate a cryptic compiler error further down the page. + +[source,arduino] +---- +#define ledPin = 3 // this is also an error +---- +[%hardbreaks] + +-- +// HOW TO USE SECTION ENDS + + + + +// SEE ALSO SECTION BEGINS +[#see_also] +-- + +[float] +=== See also + +[role="language"] +* #LANGUAGE# link:../../../variables/variable-scope-qualifiers/const[const] + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Structure/Further Syntax/include.adoc b/Language/Structure/Further Syntax/include.adoc index 6421dde13..478a1ab28 100644 --- a/Language/Structure/Further Syntax/include.adoc +++ b/Language/Structure/Further Syntax/include.adoc @@ -1,70 +1,97 @@ ---- -title: "#include" -title_expanded: include -categories: [ "Structure" ] -subCategories: [ "Further Syntax" ] ---- - - - - - -= #include - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -`#include` is used to include outside libraries in your sketch. This gives the programmer access to a large group of standard C libraries (groups of pre-made functions), and also libraries written especially for Arduino. -[%hardbreaks] - -The main reference page for AVR C libraries (AVR is a reference to the Atmel chips on which the Arduino is based) is http://www.nongnu.org/avr-libc/user-manual/modules.html[here^]. -[%hardbreaks] - -Note that `#include`, similar to link:../define[`#define`], has no semicolon terminator, and the compiler will yield cryptic error messages if you add one. -[%hardbreaks] - --- -// OVERVIEW SECTION ENDS - - - - -// HOW TO USE SECTION STARTS -[#howtouse] --- - -[float] -=== Example Code -This example includes a library that is used to put data into the program space _flash_ instead of _ram_. This saves the ram space for dynamic memory needs and makes large lookup tables more practical. - - -[source,arduino] ----- -#include - -prog_uint16_t myConstants[] PROGMEM = {0, 21140, 702 , 9128, 0, 25764, 8456, -0,0,0,0,0,0,0,0,29810,8968,29762,29762,4500}; ----- - - --- -// HOW TO USE SECTION ENDS - - - -// SEE ALSO SECTION BEGINS -[#see_also] --- - -[float] -=== See also - -[role="language"] - - --- -// SEE ALSO SECTION ENDS \ No newline at end of file +--- +title: "#include" +title_expanded: include +categories: [ "Structure" ] +subCategories: [ "Further Syntax" ] +--- + + + + + += #include + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +`#include` is used to include outside libraries in your sketch. This gives the programmer access to a large group of standard C libraries (groups of pre-made functions), and also libraries written especially for Arduino. +[%hardbreaks] + +The main reference page for AVR C libraries (AVR is a reference to the Atmel chips on which the Arduino is based) is http://www.nongnu.org/avr-libc/user-manual/modules.html[here^]. +[%hardbreaks] + +Note that `#include`, similar to `link:../define[#define]`, has no semicolon terminator, and the compiler will yield cryptic error messages if you add one. +[%hardbreaks] + + +[float] +=== Syntax +`#include ` + +`#include "LocalFile.h"` + + +[float] +=== Parameters +`LibraryFile.h`: when the angle brackets syntax is used, the libraries paths will be searched for the file. + +`LocalFile.h`: When the double quotes syntax is used, the folder of the file using the `#include` directive will be searched for the specified file, then the libraries paths if it was not found in the local path. Use this syntax for header files in the sketch's folder. + +-- +// OVERVIEW SECTION ENDS + + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code +This example includes the Servo library so that its functions may be used to control a Servo motor. + + +[source,arduino] +---- +#include + +Servo myservo; // create servo object to control a servo + +void setup() { + myservo.attach(9); // attaches the servo on pin 9 to the servo object +} + +void loop() { + for (int pos = 0; pos <= 180; pos += 1) { // goes from 0 degrees to 180 degrees + // in steps of 1 degree + myservo.write(pos); // tell servo to go to position in variable 'pos' + delay(15); // waits 15ms for the servo to reach the position + } + for (int pos = 180; pos >= 0; pos -= 1) { // goes from 180 degrees to 0 degrees + myservo.write(pos); // tell servo to go to position in variable 'pos' + delay(15); // waits 15ms for the servo to reach the position + } +} +---- + + +-- +// HOW TO USE SECTION ENDS + + + +// SEE ALSO SECTION BEGINS +[#see_also] +-- + +[float] +=== See also + +[role="language"] + + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Structure/Further Syntax/semicolon.adoc b/Language/Structure/Further Syntax/semicolon.adoc index 74e379e29..6a9a1d2ba 100644 --- a/Language/Structure/Further Syntax/semicolon.adoc +++ b/Language/Structure/Further Syntax/semicolon.adoc @@ -1,64 +1,64 @@ ---- -title: ";" -title_expanded: semicolon -categories: [ "Structure" ] -subCategories: [ "Further Syntax" ] ---- - - - - - -= ; Semicolon - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -Used to end a statement. -[%hardbreaks] - --- -// OVERVIEW SECTION ENDS - - - - -// HOW TO USE SECTION STARTS -[#howtouse] --- - -[float] -=== Example Code - -[source,arduino] ----- -int a = 13; ----- -[%hardbreaks] - -[float] -=== Notes and Warnings -Forgetting to end a line in a semicolon will result in a compiler error. The error text may be obvious, and refer to a missing semicolon, or it may not. If an impenetrable or seemingly illogical compiler error comes up, one of the first things to check is a missing semicolon, in the immediate vicinity, preceding the line at which the compiler complained. -[%hardbreaks] - --- -// HOW TO USE SECTION ENDS - - - - -// SEE ALSO SECTION BEGINS -[#see_also] --- - -[float] -=== See also - -[role="language"] - --- -// SEE ALSO SECTION ENDS +--- +title: ";" +title_expanded: semicolon +categories: [ "Structure" ] +subCategories: [ "Further Syntax" ] +--- + + + + + += ; Semicolon + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Used to end a statement. +[%hardbreaks] + +-- +// OVERVIEW SECTION ENDS + + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code + +[source,arduino] +---- +int a = 13; +---- +[%hardbreaks] + +[float] +=== Notes and Warnings +Forgetting to end a line in a semicolon will result in a compiler error. The error text may be obvious, and refer to a missing semicolon, or it may not. If an impenetrable or seemingly illogical compiler error comes up, one of the first things to check is a missing semicolon, in the immediate vicinity, preceding the line at which the compiler complained. +[%hardbreaks] + +-- +// HOW TO USE SECTION ENDS + + + + +// SEE ALSO SECTION BEGINS +[#see_also] +-- + +[float] +=== See also + +[role="language"] + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Structure/Further Syntax/singleLineComment.adoc b/Language/Structure/Further Syntax/singleLineComment.adoc index 7e5615936..9946e3865 100644 --- a/Language/Structure/Further Syntax/singleLineComment.adoc +++ b/Language/Structure/Further Syntax/singleLineComment.adoc @@ -1,72 +1,70 @@ ---- -title: "//" -title_expanded: single line comment -categories: [ "Structure" ] -subCategories: [ "Further Syntax" ] ---- - - - - - -= // Single Line Comment - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -*Comments* are lines in the program that are used to inform yourself or others about the way the program works. They are ignored by the compiler, and not exported to the processor, so they don't take up any space in the microcontroller's flash memory. Comments' only purpose is to help you understand (or remember), or to inform others about how your program works. -[%hardbreaks] - -A *single line comment* begins with `//` (two adjacent slashes). This comment ends automatically at the end of a line. whatever follows `//` till the end of a line will be ignored by the compiler. --- -// OVERVIEW SECTION ENDS - - - - -// HOW TO USE SECTION STARTS -[#howtouse] --- - -[float] -=== Example Code -There are two different ways of marking a line as a comment: - -[source,arduino] ----- -// Pin 13 has an LED connected on most Arduino boards. -// give it a name: -int led = 13; - - -digitalWrite(led, HIGH); // turn the LED on (HIGH is the voltage level) ----- -[%hardbreaks] - -[float] -=== Notes and Warnings -When experimenting with code, "commenting out" parts of your program is a convenient way to remove lines that may be buggy. This leaves the lines in the code, but turns them into comments, so the compiler just ignores them. This can be especially useful when trying to locate a problem, or when a program refuses to compile and the compiler error is cryptic or unhelpful. -[%hardbreaks] - - --- -// HOW TO USE SECTION ENDS - - - - -// SEE ALSO SECTION BEGINS -[#see_also] --- - -[float] -=== See also - -[role="language"] - --- -// SEE ALSO SECTION ENDS +--- +title: "//" +title_expanded: single line comment +categories: [ "Structure" ] +subCategories: [ "Further Syntax" ] +--- + + + + + += // Single Line Comment + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +*Comments* are lines in the program that are used to inform yourself or others about the way the program works. They are ignored by the compiler, and not exported to the processor, so they don't take up any space in the microcontroller's flash memory. Comments' only purpose is to help you understand (or remember), or to inform others about how your program works. +[%hardbreaks] + +A *single line comment* begins with `//` (two adjacent slashes). This comment ends automatically at the end of a line. Whatever follows `//` till the end of a line will be ignored by the compiler. +-- +// OVERVIEW SECTION ENDS + + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code +There are two different ways of marking a line as a comment: + +[source,arduino] +---- +// pin 13 has an LED connected on most Arduino boards. +// give it a name: +int led = 13; +digitalWrite(led, HIGH); // turn the LED on (HIGH is the voltage level) +---- +[%hardbreaks] + +[float] +=== Notes and Warnings +When experimenting with code, "commenting out" parts of your program is a convenient way to remove lines that may be buggy. This leaves the lines in the code, but turns them into comments, so the compiler just ignores them. This can be especially useful when trying to locate a problem, or when a program refuses to compile and the compiler error is cryptic or unhelpful. +[%hardbreaks] + + +-- +// HOW TO USE SECTION ENDS + + + + +// SEE ALSO SECTION BEGINS +[#see_also] +-- + +[float] +=== See also + +[role="language"] + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Structure/Pointer Access Operators/dereference.adoc b/Language/Structure/Pointer Access Operators/dereference.adoc index bbddef9ac..b59831358 100644 --- a/Language/Structure/Pointer Access Operators/dereference.adoc +++ b/Language/Structure/Pointer Access Operators/dereference.adoc @@ -1,70 +1,71 @@ ---- -title: "*" -title_expanded: dereference operator -categories: [ "Structure" ] -subCategories: [ "Pointer Access Operators" ] ---- - - - - - -= * Dereference Operator - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -Dereferencing is one of the features specifically for use with pointers. The asterisk operator `*` is used for this purpose. If `p` is a pointer, then `*p` represents the value contained in the address pointed by `p`. -[%hardbreaks] - --- -// OVERVIEW SECTION ENDS - - - -// HOW TO USE SECTION STARTS -[#howtouse] --- - -[float] -=== Example Code - -[source,arduino] ----- -int *p; // declare a pointer to an int data type -int i = 5, result = 0; -p = &i; // now 'p' contains the address of 'i' -result = *p; // 'result' gets the value at the address pointed by 'p' - // i.e., it gets the value of 'i' which is 5 ----- -[%hardbreaks] - -[float] -=== Notes and Warnings -Pointers are one of the complicated subjects for beginners in learning C, and it is possible to write the vast majority of Arduino sketches without ever encountering pointers. However for manipulating certain data structures, the use of pointers can simplify the code, and and knowledge of manipulating pointers is handy to have in one's toolkit. -[%hardbreaks] - --- -// HOW TO USE SECTION ENDS - - - - -// SEE ALSO SECTION BEGINS -[#see_also] --- - -[float] -=== See also - -[role="language"] - -[role="definition"] -* #DEFINITION# https://en.wikipedia.org/wiki/Pointer_%28computer_programming%29[Pointers^] - --- -// SEE ALSO SECTION ENDS +--- +title: "*" +title_expanded: dereference operator +categories: [ "Structure" ] +subCategories: [ "Pointer Access Operators" ] +--- + + + + + += * Dereference Operator + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Dereferencing is one of the features specifically for use with pointers. The asterisk operator `*` is used for this purpose. If `p` is a pointer, then `*p` represents the value contained in the address pointed by `p`. +[%hardbreaks] + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code + +[source,arduino] +---- +int *p; // declare a pointer to an int data type +int i = 5; +int result = 0; +p = &i; // now 'p' contains the address of 'i' +result = *p; // 'result' gets the value at the address pointed by 'p' + // i.e., it gets the value of 'i' which is 5 +---- +[%hardbreaks] + +[float] +=== Notes and Warnings +Pointers are one of the complicated subjects for beginners in learning C, and it is possible to write the vast majority of Arduino sketches without ever encountering pointers. However for manipulating certain data structures, the use of pointers can simplify the code, and knowledge of manipulating pointers is handy to have in one's toolkit. +[%hardbreaks] + +-- +// HOW TO USE SECTION ENDS + + + + +// SEE ALSO SECTION BEGINS +[#see_also] +-- + +[float] +=== See also + +[role="language"] + +[role="definition"] +* #DEFINITION# https://en.wikipedia.org/wiki/Pointer_%28computer_programming%29[Pointers^] + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Structure/Pointer Access Operators/reference.adoc b/Language/Structure/Pointer Access Operators/reference.adoc index 2babbb06f..eaf220b23 100644 --- a/Language/Structure/Pointer Access Operators/reference.adoc +++ b/Language/Structure/Pointer Access Operators/reference.adoc @@ -1,71 +1,72 @@ ---- -title: "&" -title_expanded: reference operator -categories: [ "Structure" ] -subCategories: [ "Pointer Access Operators" ] ---- - - - - - -= & Reference Operator - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -Referencing is one of the features specifically for use with pointers. The ampersand operator `&` is used for this purpose. If `x` is a variable, then `&x` represents the address of the variable `x`. -[%hardbreaks] - --- -// OVERVIEW SECTION ENDS - - - -// HOW TO USE SECTION STARTS -[#howtouse] --- - -[float] -=== Example Code - -[source,arduino] ----- -int *p; // declare a pointer to an int data type -int i = 5, result = 0; -p = &i; // now 'p' contains the address of 'i' -result = *p; // 'result' gets the value at the address pointed by 'p' - // i.e., it gets the value of 'i' which is 5 ----- -[%hardbreaks] - -[float] -=== Notes and Warnings -Pointers are one of the complicated subjects for beginners in learning C, and it is possible to write the vast majority of Arduino sketches without ever encountering pointers. However for manipulating certain data structures, the use of pointers can simplify the code, and knowledge of manipulating pointers is handy to have in one's toolkit. -[%hardbreaks] - - --- -// HOW TO USE SECTION ENDS - - - - -// SEE ALSO SECTION BEGINS -[#see_also] --- - -[float] -=== See also - -[role="language"] - -[role="definition"] -* #DEFINITION# https://en.wikipedia.org/wiki/Pointer_%28computer_programming%29[Pointers^] - --- -// SEE ALSO SECTION ENDS +--- +title: "&" +title_expanded: reference operator +categories: [ "Structure" ] +subCategories: [ "Pointer Access Operators" ] +--- + + + + + += & Reference Operator + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Referencing is one of the features specifically for use with pointers. The ampersand operator `&` is used for this purpose. If `x` is a variable, then `&x` represents the address of the variable `x`. +[%hardbreaks] + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code + +[source,arduino] +---- +int *p; // declare a pointer to an int data type +int i = 5; +int result = 0; +p = &i; // now 'p' contains the address of 'i' +result = *p; // 'result' gets the value at the address pointed by 'p' + // i.e., it gets the value of 'i' which is 5 +---- +[%hardbreaks] + +[float] +=== Notes and Warnings +Pointers are one of the complicated subjects for beginners in learning C, and it is possible to write the vast majority of Arduino sketches without ever encountering pointers. However for manipulating certain data structures, the use of pointers can simplify the code, and knowledge of manipulating pointers is handy to have in one's toolkit. +[%hardbreaks] + + +-- +// HOW TO USE SECTION ENDS + + + + +// SEE ALSO SECTION BEGINS +[#see_also] +-- + +[float] +=== See also + +[role="language"] + +[role="definition"] +* #DEFINITION# https://en.wikipedia.org/wiki/Pointer_%28computer_programming%29[Pointers^] + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Structure/Sketch/loop.adoc b/Language/Structure/Sketch/loop.adoc index 0c7937fc3..a9261c1d2 100644 --- a/Language/Structure/Sketch/loop.adoc +++ b/Language/Structure/Sketch/loop.adoc @@ -1,58 +1,69 @@ ---- -title: loop() -categories: [ "Functions" ] -subCategories: [ "Sketch" ] ---- - - - - - -= loop() - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -After creating a link:../setup[setup()] function, which initializes and sets the initial values, the `loop()` function does precisely what its name suggests, and loops consecutively, allowing your program to change and respond. Use it to actively control the Arduino board. -[%hardbreaks] - --- -// OVERVIEW SECTION ENDS - - -// HOW TO USE SECTION STARTS -[#howtouse] --- - -[float] -=== Example Code -[source,arduino] ----- -int buttonPin = 3; - -// setup initializes serial and the button pin -void setup() -{ - Serial.begin(9600); - pinMode(buttonPin, INPUT); -} - -// loop checks the button pin each time, -// and will send serial if it is pressed -void loop() -{ - if (digitalRead(buttonPin) == HIGH) - Serial.write('H'); - else - Serial.write('L'); - - delay(1000); -} ----- - --- -// HOW TO USE SECTION ENDS +--- +title: loop() +categories: [ "Functions" ] +subCategories: [ "Sketch" ] +--- + + + + + += loop() + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +After creating a `link:../setup[setup()]` function, which initializes and sets the initial values, the `loop()` function does precisely what its name suggests, and loops consecutively, allowing your program to change and respond. Use it to actively control the Arduino board. +[%hardbreaks] + +-- +// OVERVIEW SECTION ENDS + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code +[source,arduino] +---- +int buttonPin = 3; + +// setup initializes serial and the button pin +void setup() { + Serial.begin(9600); + pinMode(buttonPin, INPUT); +} + +// loop checks the button pin each time, +// and will send serial if it is pressed +void loop() { + if (digitalRead(buttonPin) == HIGH) { + Serial.write('H'); + } + else { + Serial.write('L'); + } + + delay(1000); +} +---- + +-- +// HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Structure/Sketch/setup.adoc b/Language/Structure/Sketch/setup.adoc index bee7c874b..3b46b5523 100644 --- a/Language/Structure/Sketch/setup.adoc +++ b/Language/Structure/Sketch/setup.adoc @@ -1,51 +1,60 @@ ---- -title: setup() -categories: [ "Functions" ] -subCategories: [ "Sketch" ] ---- - - - - - -= setup() - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -The `setup()` function is called when a sketch starts. Use it to initialize variables, pin modes, start using libraries, etc. The `setup()` function will only run once, after each powerup or reset of the Arduino board. -[%hardbreaks] - --- -// OVERVIEW SECTION ENDS - - -// HOW TO USE SECTION STARTS -[#howtouse] --- - -[float] -=== Example Code - -[source,arduino] ----- -int buttonPin = 3; - -void setup() -{ - Serial.begin(9600); - pinMode(buttonPin, INPUT); -} - -void loop() -{ - // ... -} ----- - --- -// HOW TO USE SECTION ENDS +--- +title: setup() +categories: [ "Functions" ] +subCategories: [ "Sketch" ] +--- + + + + + += setup() + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +The `setup()` function is called when a sketch starts. Use it to initialize variables, pin modes, start using libraries, etc. The `setup()` function will only run once, after each powerup or reset of the Arduino board. +[%hardbreaks] + +-- +// OVERVIEW SECTION ENDS + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code + +[source,arduino] +---- +int buttonPin = 3; + +void setup() { + Serial.begin(9600); + pinMode(buttonPin, INPUT); +} + +void loop() { + // ... +} +---- + +-- +// HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Variables/Constants/constants.adoc b/Language/Variables/Constants/constants.adoc deleted file mode 100644 index dd43ad366..000000000 --- a/Language/Variables/Constants/constants.adoc +++ /dev/null @@ -1,135 +0,0 @@ ---- -title: constants -categories: [ "Variables" ] -subCategories: [ "Constants" ] ---- - - - - - -= Constants - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -== Description -Constants are predefined expressions in the Arduino language. They are used to make the programs easier to read. We classify constants in groups: - -[float] -== Defining Logical Levels: true and false (Boolean Constants) -There are two constants used to represent truth and falsity in the Arduino language: `true`, and `false`. - -[float] -=== false -`false` is the easier of the two to define. false is defined as 0 (zero). -[%hardbreaks] - -[float] -=== true -`true` is often said to be defined as 1, which is correct, but true has a wider definition. Any integer which is non-zero is true, in a Boolean sense. So -1, 2 and -200 are all defined as true, too, in a Boolean sense. -[%hardbreaks] - -Note that the `true` and `false` constants are typed in lowercase unlike `HIGH`, `LOW`, `INPUT`, and `OUTPUT`. -[%hardbreaks] - -[float] -== Defining Pin Levels: HIGH and LOW -When reading or writing to a digital pin there are only two possible values a pin can take/be-set-to: `HIGH` and `LOW`. - -[float] -=== HIGH -The meaning of `HIGH` (in reference to a pin) is somewhat different depending on whether a pin is set to an `INPUT` or `OUTPUT`. When a pin is configured as an `INPUT` with link:../../../functions/digital-io/pinmode[pinMode()], and read with link:../../../functions/digital-io/digitalread[digitalRead()], the Arduino (ATmega) will report `HIGH` if: - - - a voltage greater than 3.0V is present at the pin (5V boards) - - a voltage greater than 2.0V volts is present at the pin (3.3V boards) -[%hardbreaks] - -A pin may also be configured as an INPUT with `pinMode()`, and subsequently made HIGH with link:../../../functions/digital-io/digitalwrite[digitalWrite()]. This will enable the internal 20K pullup resistors, which will _pull up_ the input pin to a `HIGH` reading unless it is pulled `LOW` by external circuitry. This is how `INPUT_PULLUP` works and is described below in more detail. -[%hardbreaks] - -When a pin is configured to OUTPUT with `pinMode()`, and set to `HIGH` with `digitalWrite()`, the pin is at: - - - 5 volts (5V boards) - - 3.3 volts (3.3V boards) - -In this state it can source current, e.g. light an LED that is connected through a series resistor to ground. -[%hardbreaks] - -[float] -=== LOW -The meaning of `LOW` also has a different meaning depending on whether a pin is set to `INPUT` or `OUTPUT`. When a pin is configured as an `INPUT` with `pinMode()`, and read with `digitalRead()`, the Arduino (ATmega) will report LOW if: - - - a voltage less than 1.5V is present at the pin (5V boards) - - a voltage less than 1.0V (Approx) is present at the pin (3.3V boards) - -When a pin is configured to `OUTPUT` with `pinMode()`, and set to `LOW` with `digitalWrite()`, the pin is at 0 volts (both 5V and 3.3V boards). In this state it can sink current, e.g. light an LED that is connected through a series resistor to +5 volts (or +3.3 volts). -[%hardbreaks] - -[float] -== Defining Digital Pins modes: INPUT, INPUT_PULLUP, and OUTPUT -Digital pins can be used as `INPUT`, `INPUT_PULLUP`, or `OUTPUT`. Changing a pin with `pinMode()` changes the electrical behavior of the pin. - -[float] -=== Pins Configured as INPUT -Arduino (ATmega) pins configured as `INPUT` with `pinMode()` are said to be in a _high-impedance_ state. Pins configured as `INPUT` make extremely small demands on the circuit that they are sampling, equivalent to a series resistor of 100 Megohms in front of the pin. This makes them useful for reading a sensor. -[%hardbreaks] - -If you have your pin configured as an `INPUT`, and are reading a switch, when the switch is in the open state the input pin will be "floating", resulting in unpredictable results. In order to assure a proper reading when the switch is open, a pull-up or pull-down resistor must be used. The purpose of this resistor is to pull the pin to a known state when the switch is open. A 10 K ohm resistor is usually chosen, as it is a low enough value to reliably prevent a floating input, and at the same time a high enough value to not not draw too much current when the switch is closed. See the http://arduino.cc/en/Tutorial/DigitalReadSerial[Digital Read Serial^] tutorial for more information. -[%hardbreaks] - -If a pull-down resistor is used, the input pin will be `LOW` when the switch is open and `HIGH` when the switch is closed. -[%hardbreaks] - -If a pull-up resistor is used, the input pin will be `HIGH` when the switch is open and `LOW` when the switch is closed. -[%hardbreaks] - -[float] -=== Pins Configured as INPUT_PULLUP -The ATmega microcontroller on the Arduino has internal pull-up resistors (resistors that connect to power internally) that you can access. If you prefer to use these instead of external pull-up resistors, you can use the `INPUT_PULLUP` argument in `pinMode()`. -[%hardbreaks] - -See the http://arduino.cc/en/Tutorial/InputPullupSerial[Input Pullup Serial^] tutorial for an example of this in use. -[%hardbreaks] - -Pins configured as inputs with either `INPUT` or `INPUT_PULLUP` can be damaged or destroyed if they are connected to voltages below ground (negative voltages) or above the positive power rail (5V or 3V). -[%hardbreaks] - -[float] -=== Pins Configured as OUTPUT -Pins configured as `OUTPUT` with `pinMode()` are said to be in a _low-impedance_ state. This means that they can provide a substantial amount of current to other circuits. ATmega pins can source (provide current) or sink (absorb current) up to 40 mA (milliamps) of current to other devices/circuits. This makes them useful for powering LEDs because LEDs typically use less than 40 mA. Loads greater than 40 mA (e.g. motors) will require a transistor or other interface circuitry. -[%hardbreaks] - -Pins configured as outputs can be damaged or destroyed if they are connected to either the ground or positive power rails. -[%hardbreaks] - -[float] -== Defining built-ins: LED_BUILTIN -Most Arduino boards have a pin connected to an on-board LED in series with a resistor. The constant `LED_BUILTIN` is the number of the pin to which the on-board LED is connected. Most boards have this LED connected to digital pin 13. - --- -// OVERVIEW SECTION ENDS - - - -// HOW TO USE SECTION STARTS -[#howtouse] --- - --- -// HOW TO USE SECTION ENDS - -// SEE ALSO SECTION BEGINS -[#see_also] --- - -[float] -=== See also - -[role="language"] - --- -// SEE ALSO SECTION ENDS diff --git a/Language/Variables/Constants/floatingPointConstants.adoc b/Language/Variables/Constants/floatingPointConstants.adoc index 01af89e6c..2d3defe04 100644 --- a/Language/Variables/Constants/floatingPointConstants.adoc +++ b/Language/Variables/Constants/floatingPointConstants.adoc @@ -1,80 +1,80 @@ ---- -title: Floating Point Constants -categories: [ "Variables" ] -subCategories: [ "Constants" ] ---- - - - - - -= Floating Point Constants - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -Similar to integer constants, floating point constants are used to make code more readable. Floating point constants are swapped at compile time for the value to which the expression evaluates. -[%hardbreaks] - --- -// OVERVIEW SECTION ENDS - - - -// HOW TO USE SECTION STARTS -[#howtouse] --- - -[float] -=== Example Code - -[source,arduino] ----- -n = 0.005; // 0.005 is a floating point constant ----- -[%hardbreaks] - -[float] -=== Notes and Warnings -Floating point constants can also be expressed in a variety of scientific notation. 'E' and 'e' are both accepted as valid exponent indicators. -[%hardbreaks] - -|=== -|floating-point constant |evaluates to: |also evaluates to: - -|10.0 -|10 -| - -|2.34E5 -|2.34 * 10^5 -|234000 - -|67e-12 -|67.0 * 10^-12 -|0.000000000067 - -|=== -[%hardbreaks] - --- -// HOW TO USE SECTION ENDS - - - - -// SEE ALSO SECTION BEGINS -[#see_also] --- - -[float] -=== See also - -[role="language"] - --- -// SEE ALSO SECTION ENDS \ No newline at end of file +--- +title: Floating Point Constants +categories: [ "Variables" ] +subCategories: [ "Constants" ] +--- + + + + + += Floating Point Constants + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Similar to integer constants, floating point constants are used to make code more readable. Floating point constants are swapped at compile time for the value to which the expression evaluates. +[%hardbreaks] + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code + +[source,arduino] +---- +float n = 0.005; // 0.005 is a floating point constant +---- +[%hardbreaks] + +[float] +=== Notes and Warnings +Floating point constants can also be expressed in a variety of scientific notation. 'E' and 'e' are both accepted as valid exponent indicators. +[%hardbreaks] + +|=== +|floating-point constant |evaluates to: |also evaluates to: + +|10.0 +|10 +| + +|2.34E5 +|2.34 * 10^5 +|234000 + +|67e-12 +|67.0 * 10^-12 +|0.000000000067 + +|=== +[%hardbreaks] + +-- +// HOW TO USE SECTION ENDS + + + + +// SEE ALSO SECTION BEGINS +[#see_also] +-- + +[float] +=== See also + +[role="language"] + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Variables/Constants/highLow.adoc b/Language/Variables/Constants/highLow.adoc new file mode 100644 index 000000000..1bec2b54e --- /dev/null +++ b/Language/Variables/Constants/highLow.adoc @@ -0,0 +1,61 @@ +--- +title: HIGH | LOW +categories: [ "Variables" ] +subCategories: [ "Constants" ] +--- + += HIGH | LOW + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +== Defining Pin Levels: HIGH and LOW +When reading or writing to a digital pin there are only two possible values a pin can take/be-set-to: `HIGH` and `LOW`. These are the same as `true` and `false`, as well as `1` and `0`. + +[float] +=== HIGH +The meaning of `HIGH` (in reference to a pin) is somewhat different depending on whether a pin is set to an `INPUT` or `OUTPUT`. When a pin is configured as an `INPUT` with `link:../../../functions/digital-io/pinmode[pinMode()]`, and read with `link:../../../functions/digital-io/digitalread[digitalRead()]`, the Arduino (ATmega) will report `HIGH` if: + + - a voltage greater than 3.0V is present at the pin (5V boards) + - a voltage greater than 2.0V is present at the pin (3.3V boards) +[%hardbreaks] + +A pin may also be configured as an INPUT with link:../../../functions/digital-io/pinmode[`pinMode()`], and subsequently made HIGH with `link:../../../functions/digital-io/digitalwrite[digitalWrite()]`. This will enable the internal 20K pullup resistors, which will _pull up_ the input pin to a `HIGH` reading unless it is pulled `LOW` by external circuitry. This can be done alternatively by passing `INPUT_PULLUP` as argument to the link:../../../functions/digital-io/pinmode[`pinMode()`] function, as explained in more detail in the section "Defining Digital Pins modes: INPUT, INPUT_PULLUP, and OUTPUT" further below. +[%hardbreaks] + +When a pin is configured to OUTPUT with link:../../../functions/digital-io/pinmode[`pinMode()`], and set to `HIGH` with link:../../../functions/digital-io/digitalwrite[`digitalWrite()`], the pin is at: + + - 5 volts (5V boards) + - 3.3 volts (3.3V boards) + +In this state it can source current, e.g. light an LED that is connected through a series resistor to ground. +[%hardbreaks] + +[float] +=== LOW + +The meaning of LOW also has a different meaning depending on whether a pin is set to INPUT or OUTPUT. When a pin is configured as an INPUT with pinMode(), and read with digitalRead(), the Arduino (ATmega) will report LOW if: + +a voltage less than 1.5V is present at the pin (5V boards) + +a voltage less than 1.0V (Approx) is present at the pin (3.3V boards) + +When a pin is configured to OUTPUT with pinMode(), and set to LOW with digitalWrite(), the pin is at 0 volts (both 5V and 3.3V boards). In this state it can sink current, e.g. light an LED that is connected through a series resistor to +5 volts (or +3.3 volts). + +-- +// OVERVIEW SECTION ENDS + + +// SEE ALSO SECTION BEGINS +[#see_also] +-- + +[float] +=== See also + +[role="language"] + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Variables/Constants/inputOutputPullup.adoc b/Language/Variables/Constants/inputOutputPullup.adoc new file mode 100644 index 000000000..5cf653401 --- /dev/null +++ b/Language/Variables/Constants/inputOutputPullup.adoc @@ -0,0 +1,73 @@ +--- +title: INPUT | INPUT_PULLUP | OUTPUT +categories: [ "Variables" ] +subCategories: [ "Constants" ] +--- + += INPUT | INPUT_PULLUP | OUTPUT + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +== Defining Digital Pins modes: INPUT, INPUT_PULLUP, and OUTPUT +Digital pins can be used as `INPUT`, `INPUT_PULLUP`, or `OUTPUT`. Changing a pin with link:../../../functions/digital-io/pinmode[`pinMode()`] changes the electrical behavior of the pin. + +-- +// OVERVIEW SECTION ENDS + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== INPUT +Arduino (ATmega) pins configured as `INPUT` with link:../../../functions/digital-io/pinmode[`pinMode()`] are said to be in a _high-impedance_ state. Pins configured as `INPUT` make extremely small demands on the circuit that they are sampling, equivalent to a series resistor of 100 Megohms in front of the pin. This makes them useful for reading a sensor. +[%hardbreaks] + +If you have your pin configured as an `INPUT`, and are reading a switch, when the switch is in the open state the input pin will be "floating", resulting in unpredictable results. In order to assure a proper reading when the switch is open, a pull-up or pull-down resistor must be used. The purpose of this resistor is to pull the pin to a known state when the switch is open. A 10 K ohm resistor is usually chosen, as it is a low enough value to reliably prevent a floating input, and at the same time a high enough value to not draw too much current when the switch is closed. See the http://arduino.cc/en/Tutorial/DigitalReadSerial[Digital Read Serial^] tutorial for more information. +[%hardbreaks] + +If a pull-down resistor is used, the input pin will be `LOW` when the switch is open and `HIGH` when the switch is closed. +[%hardbreaks] + +If a pull-up resistor is used, the input pin will be `HIGH` when the switch is open and `LOW` when the switch is closed. +[%hardbreaks] + +[float] +=== INPUT_PULLUP +The ATmega microcontroller on the Arduino has internal pull-up resistors (resistors that connect to power internally) that you can access. If you prefer to use these instead of external pull-up resistors, you can use the `INPUT_PULLUP` argument in link:../../../functions/digital-io/pinmode[`pinMode()`]. +[%hardbreaks] + +See the http://arduino.cc/en/Tutorial/InputPullupSerial[Input Pullup Serial^] tutorial for an example of this in use. +[%hardbreaks] + +Pins configured as inputs with either `INPUT` or `INPUT_PULLUP` can be damaged or destroyed if they are connected to voltages below ground (negative voltages) or above the positive power rail (5V or 3V). +[%hardbreaks] + +[float] +=== OUTPUT +Pins configured as `OUTPUT` with link:../../../functions/digital-io/pinmode[`pinMode()`] are said to be in a _low-impedance_ state. This means that they can provide a substantial amount of current to other circuits. ATmega pins can source (provide current) or sink (absorb current) up to 40 mA (milliamps) of current to other devices/circuits. This makes them useful for powering LEDs because LEDs typically use less than 40 mA. Loads greater than 40 mA (e.g. motors) will require a transistor or other interface circuitry. +[%hardbreaks] + +Pins configured as outputs can be damaged or destroyed if they are connected to either the ground or positive power rails. +[%hardbreaks] + + +-- +// HOW TO USE SECTION ENDS + + + +// SEE ALSO SECTION BEGINS +[#see_also] +-- + +[float] +=== See also + +[role="language"] + +-- +// SEE ALSO SECTION ENDS \ No newline at end of file diff --git a/Language/Variables/Constants/integerConstants.adoc b/Language/Variables/Constants/integerConstants.adoc index 10d970d4a..71e93ed15 100644 --- a/Language/Variables/Constants/integerConstants.adoc +++ b/Language/Variables/Constants/integerConstants.adoc @@ -1,143 +1,137 @@ ---- -title: Integer Constants -categories: [ "Variables" ] -subCategories: [ "Constants" ] ---- - - - - - -= Integer Constants - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -Integer constants are numbers that are used directly in a sketch, like 123. By default, these numbers are treated as link:../../data-types/int[int] but you can change this with the U and L modifiers (see below). -[%hardbreaks] - -Normally, integer constants are treated as base 10 (decimal) integers, but special notation (formatters) may be used to enter numbers in other bases. -[%hardbreaks] - -|=== -|Base |Example |Formatter |Comment - -|10 (decimal) -|123 -|none -| - -|2 (binary) -|B1111011 -|leading 'B' -|only works with 8 bit values (0 to 255) characters 0&1 valid - -|8 (octal) -|0173 -|leading "0" -|characters 0-7 valid - -|16 (hexadecimal) -|0x7B -|leading "0x" -|characters 0-9, A-F, a-f valid -|=== -[%hardbreaks] - --- -// OVERVIEW SECTION ENDS - - - -// HOW TO USE SECTION STARTS -[#howtouse] --- -[float] -== Decimal (base 10) -This is the common-sense math with which you are acquainted. Constants without other prefixes are assumed to be in decimal format. - -[float] -=== Example Code: -[source,arduino] ----- -n = 101; // same as 101 decimal ((1 * 10^2) + (0 * 10^1) + 1) ----- -[%hardbreaks] - -[float] -== Binary (base 2) -Only the characters 0 and 1 are valid. - -[float] -=== Example Code: -[source,arduino] ----- -n = B101; // same as 5 decimal ((1 * 2^2) + (0 * 2^1) + 1) ----- - -The binary formatter only works on bytes (8 bits) between 0 (B0) and 255 (B11111111). If it is convenient to input an int (16 bits) in binary form you can do it a two-step procedure such as: -[source,arduino] ----- -myInt = (B11001100 * 256) + B10101010; // B11001100 is the high byte` ----- -[%hardbreaks] - -[float] -== Octal (base 8) -Only the characters 0 through 7 are valid. Octal values are indicated by the prefix "0" (zero). - -[float] -=== Example Code: -[source,arduino] ----- -n = 0101; // same as 65 decimal ((1 * 8^2) + (0 * 8^1) + 1) ----- -It is possible to generate a hard-to-find bug by (unintentionally) including a leading zero before a constant and having the compiler unintentionally interpret your constant as octal. -[%hardbreaks] - -[float] -== Hexadecimal (base 16) -Valid characters are 0 through 9 and letters A through F; A has the value 10, B is 11, up to F, which is 15. Hex values are indicated by the prefix "0x". Note that A-F may be syted in upper or lower case (a-f). - -[float] -=== Example Code: -[source,arduino] ----- -n = 0x101; // same as 257 decimal ((1 * 16^2) + (0 * 16^1) + 1) ----- -[%hardbreaks] - - -[float] -=== Notes and Warnings -*U & L formatters:* - -By default, an integer constant is treated as an int with the attendant limitations in values. To specify an integer constant with another data type, follow it with: - - - a 'u' or 'U' to force the constant into an unsigned data format. Example: 33u - - a 'l' or 'L' to force the constant into a long data format. Example: 100000L - - a 'ul' or 'UL' to force the constant into an unsigned long constant. Example: 32767ul - -[%hardbreaks] - --- -// HOW TO USE SECTION ENDS - - - - -// SEE ALSO SECTION BEGINS -[#see_also] --- - -[float] -=== See also - -[role="language"] - --- -// SEE ALSO SECTION ENDS \ No newline at end of file +--- +title: Integer Constants +categories: [ "Variables" ] +subCategories: [ "Constants" ] +--- + + + + + += Integer Constants + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Integer constants are numbers that are used directly in a sketch, like 123. By default, these numbers are treated as link:../../data-types/int[int] but you can change this with the U and L modifiers (see below). +[%hardbreaks] + +Normally, integer constants are treated as base 10 (decimal) integers, but special notation (formatters) may be used to enter numbers in other bases. +[%hardbreaks] + +|=== +|Base |Example |Formatter |Comment + +|10 (decimal) +|123 +|none +| + +|2 (binary) +|0b1111011 +|leading "0b" +|characters 0&1 valid + +|8 (octal) +|0173 +|leading "0" +|characters 0-7 valid + +|16 (hexadecimal) +|0x7B +|leading "0x" +|characters 0-9, A-F, a-f valid +|=== +[%hardbreaks] + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- +[float] +== Decimal (base 10) +This is the common-sense math with which you are acquainted. Constants without other prefixes are assumed to be in decimal format. + +[float] +=== Example Code: +[source,arduino] +---- +n = 101; // same as 101 decimal ((1 * 10^2) + (0 * 10^1) + 1) +---- +[%hardbreaks] + +[float] +== Binary (base 2) +Only the characters 0 and 1 are valid. + +[float] +=== Example Code: +[source,arduino] +---- +n = 0b101; // same as 5 decimal ((1 * 2^2) + (0 * 2^1) + 1) +---- +[%hardbreaks] + +[float] +== Octal (base 8) +Only the characters 0 through 7 are valid. Octal values are indicated by the prefix "0" (zero). + +[float] +=== Example Code: +[source,arduino] +---- +n = 0101; // same as 65 decimal ((1 * 8^2) + (0 * 8^1) + 1) +---- +It is possible to generate a hard-to-find bug by (unintentionally) including a leading zero before a constant and having the compiler unintentionally interpret your constant as octal. +[%hardbreaks] + +[float] +== Hexadecimal (base 16) +Valid characters are 0 through 9 and letters A through F; A has the value 10, B is 11, up to F, which is 15. Hex values are indicated by the prefix "0x". Note that A-F may be upper (A-F) or lower case (a-f). + +[float] +=== Example Code: +[source,arduino] +---- +n = 0x101; // same as 257 decimal ((1 * 16^2) + (0 * 16^1) + 1) +---- +[%hardbreaks] + + +[float] +=== Notes and Warnings +*U & L formatters:* + +By default, an integer constant is treated as an int with the attendant limitations in values. To specify an integer constant with another data type, follow it with: + + - a 'u' or 'U' to force the constant into an unsigned data format. Example: 33u + - a 'l' or 'L' to force the constant into a long data format. Example: 100000L + - a 'ul' or 'UL' to force the constant into an unsigned long constant. Example: 32767ul + +[%hardbreaks] + +-- +// HOW TO USE SECTION ENDS + + + + +// SEE ALSO SECTION BEGINS +[#see_also] +-- + +[float] +=== See also + +[role="language"] + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Variables/Constants/ledbuiltin.adoc b/Language/Variables/Constants/ledbuiltin.adoc new file mode 100644 index 000000000..7ff780510 --- /dev/null +++ b/Language/Variables/Constants/ledbuiltin.adoc @@ -0,0 +1,31 @@ +--- +title: LED_BUILTIN +categories: [ "Variables" ] +subCategories: [ "Constants" ] +--- + += LED_BUILTIN + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +== Defining built-ins: LED_BUILTIN +Most Arduino boards have a pin connected to an on-board LED in series with a resistor. The constant `LED_BUILTIN` is the number of the pin to which the on-board LED is connected. Most boards have this LED connected to digital pin 13. + +-- +// OVERVIEW SECTION ENDS + + +// SEE ALSO SECTION BEGINS +[#see_also] +-- + +[float] +=== See also + +[role="language"] + +-- +// SEE ALSO SECTION ENDS \ No newline at end of file diff --git a/Language/Variables/Constants/trueFalse.adoc b/Language/Variables/Constants/trueFalse.adoc new file mode 100644 index 000000000..fe260f872 --- /dev/null +++ b/Language/Variables/Constants/trueFalse.adoc @@ -0,0 +1,47 @@ +--- +title: 'true | false' +categories: [ "Variables" ] +subCategories: [ "Constants" ] +--- + += true | false + +// OVERVIEW SECTION STARTS +[#overview] +-- + +There are two constants used to represent truth and falsity in the Arduino language: `true`, and `false`. + +[float] +=== true +`true` is often said to be defined as 1, which is correct, but true has a wider definition. Any integer which is non-zero is true, in a Boolean sense. So -1, 2 and -200 are all defined as true, too, in a Boolean sense. +[%hardbreaks] + +Note that the `true` and `false` constants are typed in lowercase unlike `HIGH`, `LOW`, `INPUT`, and `OUTPUT`. +[%hardbreaks] + + +[float] +=== false +`false` is the easier of the two to define. false is defined as 0 (zero). +[%hardbreaks] + +Note that the `true` and `false` constants are typed in lowercase unlike `HIGH`, `LOW`, `INPUT`, and `OUTPUT`. +[%hardbreaks] + +-- +// OVERVIEW SECTION ENDS + + + +// SEE ALSO SECTION BEGINS +[#see_also] +-- + +[float] +=== See also + +[role="language"] + +-- +// SEE ALSO SECTION ENDS \ No newline at end of file diff --git a/Language/Variables/Conversion/byteCast.adoc b/Language/Variables/Conversion/byteCast.adoc index 1b6eb6e9d..e1d50ee4e 100644 --- a/Language/Variables/Conversion/byteCast.adoc +++ b/Language/Variables/Conversion/byteCast.adoc @@ -17,22 +17,24 @@ subCategories: [ "Conversion" ] [float] === Description -Converts a value to the link:../../data-types/byte[byte] data type. +Converts a value to the `link:../../data-types/byte[byte]` data type. [%hardbreaks] [float] === Syntax -`byte(x)` +`byte(x)` + +`(byte)x` (C-style type conversion) [float] === Parameters -`x`: a value of any type +`x`: a value. Allowed data types: any type. + [float] === Returns -`byte` +Data type: link:../../data-types/byte[`byte`]. -- // OVERVIEW SECTION ENDS @@ -50,4 +52,4 @@ Converts a value to the link:../../data-types/byte[byte] data type. * #LANGUAGE# link:../../data-types/byte[byte] -- -// SEE ALSO SECTION ENDS \ No newline at end of file +// SEE ALSO SECTION ENDS diff --git a/Language/Variables/Conversion/charCast.adoc b/Language/Variables/Conversion/charCast.adoc index 6c2d8e791..b4a6963fe 100644 --- a/Language/Variables/Conversion/charCast.adoc +++ b/Language/Variables/Conversion/charCast.adoc @@ -17,22 +17,24 @@ subCategories: [ "Conversion" ] [float] === Description -Converts a value to the link:../../data-types/char[char] data type. +Converts a value to the `link:../../data-types/char[char]` data type. [%hardbreaks] [float] === Syntax -`char(x)` +`char(x)` + +`(char)x` (C-style type conversion) [float] === Parameters -`x`: a value of any type +`x`: a value. Allowed data types: any type. + [float] === Returns -`char` +Data type: link:../../data-types/char[`char`]. -- // OVERVIEW SECTION ENDS @@ -50,4 +52,4 @@ Converts a value to the link:../../data-types/char[char] data type. * #LANGUAGE# link:../../data-types/char[char] -- -// SEE ALSO SECTION ENDS \ No newline at end of file +// SEE ALSO SECTION ENDS diff --git a/Language/Variables/Conversion/floatCast.adoc b/Language/Variables/Conversion/floatCast.adoc index 9b0da90cb..ccd127afd 100644 --- a/Language/Variables/Conversion/floatCast.adoc +++ b/Language/Variables/Conversion/floatCast.adoc @@ -17,22 +17,24 @@ subCategories: [ "Conversion" ] [float] === Description -Converts a value to the link:../../data-types/float[float] data type. +Converts a value to the `link:../../data-types/float[float]` data type. [%hardbreaks] [float] === Syntax -`float(x)` +`float(x)` + +`(float)x` (C-style type conversion) [float] === Parameters -`x`: a value of any type +`x`: a value. Allowed data types: any type. + [float] === Returns -`float` +Data type: link:../../data-types/float[`float`]. -- // OVERVIEW SECTION ENDS @@ -46,7 +48,7 @@ Converts a value to the link:../../data-types/float[float] data type. [float] === Notes and Warnings -See the reference for link:../../data-types/float[float] for details about the precision and limitations of floating point numbers on Arduino. +See the reference for `link:../../data-types/float[float]` for details about the precision and limitations of floating point numbers on Arduino. [%hardbreaks] -- @@ -66,4 +68,4 @@ See the reference for link:../../data-types/float[float] for details about the p * #LANGUAGE# link:../../data-types/float[float] -- -// SEE ALSO SECTION ENDS \ No newline at end of file +// SEE ALSO SECTION ENDS diff --git a/Language/Variables/Conversion/intCast.adoc b/Language/Variables/Conversion/intCast.adoc index a087cb6a2..692ecc871 100644 --- a/Language/Variables/Conversion/intCast.adoc +++ b/Language/Variables/Conversion/intCast.adoc @@ -17,22 +17,24 @@ subCategories: [ "Conversion" ] [float] === Description -Converts a value to the link:../../data-types/int[int] data type. +Converts a value to the `link:../../data-types/int[int]` data type. [%hardbreaks] [float] === Syntax -`int(x)` +`int(x)` + +`(int)x` (C-style type conversion) [float] === Parameters -`x`: a value of any type +`x`: a value. Allowed data types: any type. + [float] === Returns -`int` +Data type: link:../../data-types/int[`int`]. -- // OVERVIEW SECTION ENDS @@ -52,4 +54,4 @@ Converts a value to the link:../../data-types/int[int] data type. -- -// SEE ALSO SECTION ENDS \ No newline at end of file +// SEE ALSO SECTION ENDS diff --git a/Language/Variables/Conversion/longCast.adoc b/Language/Variables/Conversion/longCast.adoc index 05749fd89..fefd61eb7 100644 --- a/Language/Variables/Conversion/longCast.adoc +++ b/Language/Variables/Conversion/longCast.adoc @@ -17,22 +17,24 @@ subCategories: [ "Conversion" ] [float] === Description -Converts a value to the link:../../data-types/long[long] data type. +Converts a value to the `link:../../data-types/long[long]` data type. [%hardbreaks] [float] === Syntax -`long(x)` +`long(x)` + +`(long)x` (C-style type conversion) [float] === Parameters -`x`: a value of any type +`x`: a value. Allowed data types: any type. + [float] === Returns -`long` +Data type: link:../../data-types/long[`long`]. -- // OVERVIEW SECTION ENDS @@ -52,4 +54,4 @@ Converts a value to the link:../../data-types/long[long] data type. -- -// SEE ALSO SECTION ENDS \ No newline at end of file +// SEE ALSO SECTION ENDS diff --git a/Language/Variables/Conversion/unsignedIntCast.adoc b/Language/Variables/Conversion/unsignedIntCast.adoc new file mode 100644 index 000000000..62af57a95 --- /dev/null +++ b/Language/Variables/Conversion/unsignedIntCast.adoc @@ -0,0 +1,55 @@ +--- +title: (unsigned int) +categories: [ "Variables" ] +subCategories: [ "Conversion" ] +--- + + + + + += (unsigned int) + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Converts a value to the `link:../../data-types/unsignedint[unsigned int]` data type. +[%hardbreaks] + + +[float] +=== Syntax +`(unsigned int)x` + + +[float] +=== Parameters +`x`: a value of any type + +[float] +=== Returns +link:../../data-types/unsignedint[`unsigned int`] + +-- +// OVERVIEW SECTION ENDS + + + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +[role="language"] +* #LANGUAGE# link:../../data-types/unsignedint[unsigned int] + + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Variables/Conversion/unsignedLongCast.adoc b/Language/Variables/Conversion/unsignedLongCast.adoc new file mode 100644 index 000000000..c44d19594 --- /dev/null +++ b/Language/Variables/Conversion/unsignedLongCast.adoc @@ -0,0 +1,55 @@ +--- +title: (unsigned long) +categories: [ "Variables" ] +subCategories: [ "Conversion" ] +--- + + + + + += (unsigned long) + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Converts a value to the `link:../../data-types/unsignedlong[unsigned long]` data type. +[%hardbreaks] + + +[float] +=== Syntax +`(unsigned long)x` + + +[float] +=== Parameters +`x`: a value of any type + +[float] +=== Returns +link:../../data-types/unsignedlong[`unsigned long`] + +-- +// OVERVIEW SECTION ENDS + + + + +// SEE ALSO SECTION STARTS +[#see_also] +-- + +[float] +=== See also + +[role="language"] +* #LANGUAGE# link:../../data-types/unsignedlong[unsigned long] + + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Variables/Conversion/wordcast.adoc b/Language/Variables/Conversion/wordcast.adoc index 19cff9667..e6ddc1363 100644 --- a/Language/Variables/Conversion/wordcast.adoc +++ b/Language/Variables/Conversion/wordcast.adoc @@ -17,25 +17,27 @@ subCategories: [ "Conversion" ] [float] === Description -Converts a value to the link:../../data-types/word[word] data type. +Converts a value to the `link:../../data-types/word[word]` data type. [%hardbreaks] [float] === Syntax `word(x)` + -`word(h, l)` +`word(h, l)` + +`(word)x` (C-style type conversion) + [float] === Parameters -`x`: a value of any type +`x`: a value. Allowed data types: any type. + +`h`: the high-order (leftmost) byte of the word. + +`l`: the low-order (rightmost) byte of the word. -`h`: the high-order (leftmost) byte of the word -`l`: the low-order (rightmost) byte of the word [float] === Returns -`word` +Data type: link:../../data-types/word[`word`]. -- // OVERVIEW SECTION ENDS @@ -55,4 +57,4 @@ Converts a value to the link:../../data-types/word[word] data type. -- -// SEE ALSO SECTION ENDS \ No newline at end of file +// SEE ALSO SECTION ENDS diff --git a/Language/Variables/Data Types/String.adoc b/Language/Variables/Data Types/String.adoc deleted file mode 100644 index 7029bfea9..000000000 --- a/Language/Variables/Data Types/String.adoc +++ /dev/null @@ -1,119 +0,0 @@ ---- -title: String -categories: [ "Variables" ] -subCategories: [ "Data Types" ] ---- - - - - - -= string - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -Text Strings can be represented in two ways. you can use the String data type, which is part of the core as of version 0019, or you can make a String out of an array of type char and null-terminate it. This page described the latter method. For more details on the String object, which gives you more functionality at the cost of more memory, see the link:../stringobject[String object] page. -[%hardbreaks] - -[float] -=== Syntax -All of the following are valid declarations for Strings. - -`char Str1[15];` + -`char Str2[8] = {'a', 'r', 'd', 'u', 'i', 'n', 'o'};` + -`char Str3[8] = {'a', 'r', 'd', 'u', 'i', 'n', 'o', '\0'};` + -`char Str4[ ] = "arduino";` + -`char Str5[8] = "arduino";` + -`char Str6[15] = "arduino";` - -*Possibilities for declaring Strings* - -* Declare an array of chars without initializing it as in Str1 -* Declare an array of chars (with one extra char) and the compiler will add the required null character, as in Str2 -* Explicitly add the null character, Str3 -* Initialize with a String constant in quotation marks; the compiler will size the array to fit the String constant and a terminating null character, Str4 -* Initialize the array with an explicit size and String constant, Str5 -* Initialize the array, leaving extra space for a larger String, Str6 - -*Null termination* - -Generally, Strings are terminated with a null character (ASCII code 0). This allows functions (like `Serial.print()`) to tell where the end of a String is. Otherwise, they would continue reading subsequent bytes of memory that aren't actually part of the String. - -This means that your String needs to have space for one more character than the text you want it to contain. That is why Str2 and Str5 need to be eight characters, even though "arduino" is only seven - the last position is automatically filled with a null character. Str4 will be automatically sized to eight characters, one for the extra null. In Str3, we've explicitly included the null character (written '\0') ourselves. - -Note that it's possible to have a String without a final null character (e.g. if you had specified the length of Str2 as seven instead of eight). This will break most functions that use Strings, so you shouldn't do it intentionally. If you notice something behaving strangely (operating on characters not in the String), however, this could be the problem. - -*Single quotes or double quotes?* - -Strings are always defined inside double quotes ("Abc") and characters are always defined inside single quotes('A'). - -*Wrapping long Strings* - -You can wrap long Strings like this: - -[source,arduino] ----- -char myString[] = "This is the first line" -" this is the second line" -" etcetera"; ----- - -*Arrays of Strings* - -It is often convenient, when working with large amounts of text, such as a project with an LCD display, to setup an array of Strings. Because Strings themselves are arrays, this is in actually an example of a two-dimensional array. - -In the code below, the asterisk after the datatype `char` "`char*`" indicates that this is an array of "`pointers`". All array names are actually pointers, so this is required to make an array of arrays. Pointers are one of the more esoteric parts of C for beginners to understand, but it isn't necessary to understand pointers in detail to use them effectively here. - --- -// OVERVIEW SECTION ENDS - - - - -// HOW TO USE SECTION STARTS -[#howtouse] --- - -[float] -=== Example Code -// Describe what the example code is all about and add relevant code ►►►►► THIS SECTION IS MANDATORY ◄◄◄◄◄ - - -[source,arduino] ----- -char* myStrings[]={"This is String 1", "This is String 2", "This is String 3", -"This is String 4", "This is String 5","This is String 6"}; - -void setup(){ -Serial.begin(9600); -} - -void loop(){ -for (int i = 0; i < 6; i++){ - Serial.println(myStrings[i]); - delay(500); - } -} ----- - - --- -// HOW TO USE SECTION ENDS - -// SEE ALSO SECTION STARTS -[#see_also] --- - -[float] -=== See also - -[role="language"] -* #LANGUAGE# link:../../utilities/progmem[PROGMEM] - --- -// SEE ALSO SECTION ENDS diff --git a/Language/Variables/Data Types/String/Functions/c_str.adoc b/Language/Variables/Data Types/String/Functions/c_str.adoc index ae0654eb4..825f61e06 100644 --- a/Language/Variables/Data Types/String/Functions/c_str.adoc +++ b/Language/Variables/Data Types/String/Functions/c_str.adoc @@ -1,58 +1,57 @@ ---- -title: "c_str()" -categories: [ "Data Types" ] -subCategories: [ "StringObject Function" ] ---- - - - - - -= c_str() - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -Converts the contents of a string as a C-style, null-terminated string. Note that this gives direct access to the internal String buffer and should be used with care. In particular, you should never modify the string through the pointer returned. When you modify the String object, or when it is destroyed, any pointer previously returned by c_str() becomes invalid and should not be used any longer. - -[%hardbreaks] - - -[float] -=== Syntax -[source,arduino] ----- -string.c_str() ----- - -[float] -=== Parameters -none - -[float] -=== Returns -A pointer to the C-style version of the invoking string. - --- -// OVERVIEW SECTION ENDS - - - -// HOW TO USE SECTION ENDS - - -// SEE ALSO SECTION -[#see_also] --- - -[float] -=== See also - -[role="example"] -* #EXAMPLE# link: https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[Built-in String Tutorials] --- -// SEE ALSO SECTION ENDS \ No newline at end of file +--- +title: "c_str()" +categories: [ "Data Types" ] +subCategories: [ "StringObject Function" ] +--- + + + + + += c_str() + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Converts the contents of a String as a C-style, null-terminated string. Note that this gives direct access to the internal String buffer and should be used with care. In particular, you should never modify the string through the pointer returned. When you modify the String object, or when it is destroyed, any pointer previously returned by c_str() becomes invalid and should not be used any longer. + +[%hardbreaks] + + +[float] +=== Syntax +`myString.c_str()` + + +[float] +=== Parameters +`myString`: a variable of type `String`. + + +[float] +=== Returns +A pointer to the C-style version of the invoking String. + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +[role="example"] +* #EXAMPLE# https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[String Tutorials^] +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Variables/Data Types/String/Functions/charAt.adoc b/Language/Variables/Data Types/String/Functions/charAt.adoc index 7b7d336ab..cb571e95a 100644 --- a/Language/Variables/Data Types/String/Functions/charAt.adoc +++ b/Language/Variables/Data Types/String/Functions/charAt.adoc @@ -1,61 +1,58 @@ ---- -title: "charAt()" -categories: [ "Data Types" ] -subCategories: [ "StringObject Function" ] ---- - - - - - -= charAt() - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -Access a particular character of the String. - -[%hardbreaks] - - -[float] -=== Syntax -[source,arduino] ----- -string.charAt(n) ----- - -[float] -=== Parameters -`string`: a variable of type String - -`n`: a variable of type unsigned int - - -[float] -=== Returns -The n'th character of the String. - --- -// OVERVIEW SECTION ENDS - - - -// HOW TO USE SECTION ENDS - - -// SEE ALSO SECTION -[#see_also] --- - -[float] -=== See also - -[role="example"] -* #EXAMPLE# link: https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[Built-in String Tutorials] --- -// SEE ALSO SECTION ENDS +--- +title: "charAt()" +categories: [ "Data Types" ] +subCategories: [ "StringObject Function" ] +--- + + + + + += charAt() + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Access a particular character of the String. + +[%hardbreaks] + + +[float] +=== Syntax +`myString.charAt(n)` + + +[float] +=== Parameters +`myString`: a variable of type `String`. + +`n`: a variable. Allowed data types: `unsigned int`. + + +[float] +=== Returns +The character at index n of the String. + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +[role="example"] +* #EXAMPLE# https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[String Tutorials^] +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Variables/Data Types/String/Functions/compareTo.adoc b/Language/Variables/Data Types/String/Functions/compareTo.adoc index 023519c46..e03885872 100644 --- a/Language/Variables/Data Types/String/Functions/compareTo.adoc +++ b/Language/Variables/Data Types/String/Functions/compareTo.adoc @@ -1,65 +1,61 @@ ---- -title: "compareTo()" -categories: [ "Data Types" ] -subCategories: [ "StringObject Function" ] ---- - - - - - -= compareTo() - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -Compares two Strings, testing whether one comes before or after the other, or whether they're equal. The strings are compared character by character, using the ASCII values of the characters. That means, for example, that 'a' comes before 'b' but after 'A'. Numbers come before letters. - -[%hardbreaks] - - -[float] -=== Syntax -[source,arduino] ----- -string.compareTo(string2) ----- - -[float] -=== Parameters -`string`: a variable of type String - -`string2`: another variable of type String - - -[float] -=== Returns -`a negative number`: if string comes before string2 - -`0`: if string equals string2 - -`a positive number`: if string comes after string2 --- - -// OVERVIEW SECTION ENDS - - - -// HOW TO USE SECTION ENDS - - -// SEE ALSO SECTION -[#see_also] --- - -[float] -=== See also - -[role="example"] -* #EXAMPLE# link: https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[Built-in String Tutorials] --- -// SEE ALSO SECTION ENDS \ No newline at end of file +--- +title: "compareTo()" +categories: [ "Data Types" ] +subCategories: [ "StringObject Function" ] +--- + + + + + += compareTo() + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Compares two Strings, testing whether one comes before or after the other, or whether they're equal. The strings are compared character by character, using the ASCII values of the characters. That means, for example, that 'a' comes before 'b' but after 'A'. Numbers come before letters. + +[%hardbreaks] + + +[float] +=== Syntax +`myString.compareTo(myString2)` + + +[float] +=== Parameters +`myString`: a variable of type `String`. + +`myString2`: another variable of type `String`. + + +[float] +=== Returns +`a negative number`: if myString comes before myString2. + +`0`: if String equals myString2. + +`a positive number`: if myString comes after myString2. + +-- + +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +[role="example"] +* #EXAMPLE# https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[String Tutorials^] +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Variables/Data Types/String/Functions/concat.adoc b/Language/Variables/Data Types/String/Functions/concat.adoc index b8ac5af74..95c35f550 100644 --- a/Language/Variables/Data Types/String/Functions/concat.adoc +++ b/Language/Variables/Data Types/String/Functions/concat.adoc @@ -1,60 +1,59 @@ ---- -title: "concat()" -categories: [ "Data Types" ] -subCategories: [ "StringObject Function" ] ---- - - - - - -= concat() - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -Appends the parameter to a String. - -[%hardbreaks] - - -[float] -=== Syntax -[source,arduino] ----- -string.concat(parameter) ----- - -[float] -=== Parameters -`parameter`: *Allowed types are* String, string, char, byte, int, unsigned int, long, unsigned long, float, double, __FlashStringHelper(F() macro). - -[float] -=== Returns -`true`: success - -`false`: failure (in which case the string is left unchanged). - --- -// OVERVIEW SECTION ENDS - - - -// HOW TO USE SECTION ENDS - - -// SEE ALSO SECTION -[#see_also] --- - -[float] -=== See also - -[role="example"] -* #EXAMPLE# link: https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[Built-in String Tutorials] --- -// SEE ALSO SECTION ENDS \ No newline at end of file +--- +title: "concat()" +categories: [ "Data Types" ] +subCategories: [ "StringObject Function" ] +--- + + + + + += concat() + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Appends the parameter to a String. + +[%hardbreaks] + + +[float] +=== Syntax +`myString.concat(parameter)` + + +[float] +=== Parameters +`myString`: a variable of type `String`. + +`parameter`: Allowed data types: `String`, `string`, `char`, `byte`, `int`, `unsigned int`, `long`, `unsigned long`, `float`, `double`, `__FlashStringHelper`(`F()` macro). + + +[float] +=== Returns +`true`: success. + +`false`: failure (in which case the String is left unchanged). + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +[role="example"] +* #EXAMPLE# https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[String Tutorials^] +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Variables/Data Types/String/Functions/endsWith.adoc b/Language/Variables/Data Types/String/Functions/endsWith.adoc index 20da33655..7b456df76 100644 --- a/Language/Variables/Data Types/String/Functions/endsWith.adoc +++ b/Language/Variables/Data Types/String/Functions/endsWith.adoc @@ -1,63 +1,59 @@ ---- -title: "endsWith()" -categories: [ "Data Types" ] -subCategories: [ "StringObject Function" ] ---- - - - - - -= endsWith() - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -Tests whether or not a String ends with the characters of another String. - -[%hardbreaks] - - -[float] -=== Syntax -[source,arduino] ----- -string.endsWith(string2) ----- - -[float] -=== Parameters -`string`: a variable of type String - -`string2`: another variable of type String - - -[float] -=== Returns -`true`: if string ends with the characters of string2 - -`false`: otherwise - --- -// OVERVIEW SECTION ENDS - - - -// HOW TO USE SECTION ENDS - - -// SEE ALSO SECTION -[#see_also] --- - -[float] -=== See also - -[role="example"] -* #EXAMPLE# link: https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[Built-in String Tutorials] --- -// SEE ALSO SECTION ENDS \ No newline at end of file +--- +title: "endsWith()" +categories: [ "Data Types" ] +subCategories: [ "StringObject Function" ] +--- + + + + + += endsWith() + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Tests whether or not a String ends with the characters of another String. + +[%hardbreaks] + + +[float] +=== Syntax +`myString.endsWith(myString2)` + + +[float] +=== Parameters +`myString`: a variable of type `String`. + +`myString2`: another variable of type `String`. + + +[float] +=== Returns +`true`: if myString ends with the characters of myString2. + +`false`: otherwise. + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +[role="example"] +* #EXAMPLE# https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[String Tutorials^] +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Variables/Data Types/String/Functions/equals.adoc b/Language/Variables/Data Types/String/Functions/equals.adoc index e58425d00..2de11b4ea 100644 --- a/Language/Variables/Data Types/String/Functions/equals.adoc +++ b/Language/Variables/Data Types/String/Functions/equals.adoc @@ -1,60 +1,58 @@ ---- -title: "equals()" -categories: [ "Data Types" ] -subCategories: [ "StringObject Function" ] ---- - - - - - -= equals() - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -Compares two strings for equality. The comparison is case-sensitive, meaning the String "hello" is not equal to the String "HELLO". - -[%hardbreaks] - - -[float] -=== Syntax -[source,arduino] ----- -string.equals(string2) ----- - -[float] -=== Parameters -`string, string2`: variables of type String - - -[float] -=== Returns -`true`: if string equals string2 - -`false`: otherwise --- -// OVERVIEW SECTION ENDS - - - -// HOW TO USE SECTION ENDS - - -// SEE ALSO SECTION -[#see_also] --- - -[float] -=== See also - -[role="example"] -* #EXAMPLE# link: https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[Built-in String Tutorials] --- -// SEE ALSO SECTION ENDS \ No newline at end of file +--- +title: "equals()" +categories: [ "Data Types" ] +subCategories: [ "StringObject Function" ] +--- + + + + + += equals() + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Compares two Strings for equality. The comparison is case-sensitive, meaning the String "hello" is not equal to the String "HELLO". + +[%hardbreaks] + + +[float] +=== Syntax +`myString.equals(myString2)` + + +[float] +=== Parameters +`myString, myString2`: variables of type `String`. + + +[float] +=== Returns +`true`: if string equals string2. + +`false`: otherwise. + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +[role="example"] +* #EXAMPLE# https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[String Tutorials^] +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Variables/Data Types/String/Functions/equalsIgnoreCase.adoc b/Language/Variables/Data Types/String/Functions/equalsIgnoreCase.adoc index 5ea8c8bab..d95953703 100644 --- a/Language/Variables/Data Types/String/Functions/equalsIgnoreCase.adoc +++ b/Language/Variables/Data Types/String/Functions/equalsIgnoreCase.adoc @@ -1,60 +1,59 @@ ---- -title: "equalsIgnoreCase()" -categories: [ "Data Types" ] -subCategories: [ "StringObject Function" ] ---- - - - - - -= equalsIgnoreCase() - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -Compares two Strings for equality. The comparison is not case-sensitive, meaning the String("hello") is equal to the String("HELLO"). - -[%hardbreaks] - - -[float] -=== Syntax -[source,arduino] ----- -string.equalsIgnoreCase(string2) ----- - -[float] -=== Parameters -`string, string2`: variables of type String - - -[float] -=== Returns -`true`: if string equals string2 (ignoring case) - -`false`: otherwise --- -// OVERVIEW SECTION ENDS - - - -// HOW TO USE SECTION ENDS - - -// SEE ALSO SECTION -[#see_also] --- - -[float] -=== See also - -[role="example"] -* #EXAMPLE# link: https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[Built-in String Tutorials] --- -// SEE ALSO SECTION ENDS +--- +title: "equalsIgnoreCase()" +categories: [ "Data Types" ] +subCategories: [ "StringObject Function" ] +--- + + + + + += equalsIgnoreCase() + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Compares two Strings for equality. The comparison is not case-sensitive, meaning the String("hello") is equal to the String("HELLO"). + +[%hardbreaks] + + +[float] +=== Syntax +`myString.equalsIgnoreCase(myString2)` + + +[float] +=== Parameters +`myString`: variable of type `String`. + +`myString2`: variable of type `String`. + + +[float] +=== Returns +`true`: if myString equals myString2 (ignoring case). + +`false`: otherwise. + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +[role="example"] +* #EXAMPLE# https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[String Tutorials^] +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Variables/Data Types/String/Functions/getBytes.adoc b/Language/Variables/Data Types/String/Functions/getBytes.adoc index ccafd62ca..b1a08409c 100644 --- a/Language/Variables/Data Types/String/Functions/getBytes.adoc +++ b/Language/Variables/Data Types/String/Functions/getBytes.adoc @@ -1,62 +1,59 @@ ---- -title: "getBytes()" -categories: [ "Data Types" ] -subCategories: [ "StringObject Function" ] ---- - - - - - -= getBytes() - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -Copies the String's characters to the supplied buffer. - -[%hardbreaks] - - -[float] -=== Syntax -[source,arduino] ----- -string.getBytes(buf, len) ----- - -[float] -=== Parameters -`string`: a variable of type String - -`buf`: the buffer to copy the characters into (_byte []_) - -`len`: the size of the buffer (_unsigned int_) - -[float] -=== Returns -None - --- -// OVERVIEW SECTION ENDS - - - -// HOW TO USE SECTION ENDS - - -// SEE ALSO SECTION -[#see_also] --- - -[float] -=== See also - -[role="example"] -* #EXAMPLE# link: https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[Built-in String Tutorials] --- -// SEE ALSO SECTION ENDS +--- +title: "getBytes()" +categories: [ "Data Types" ] +subCategories: [ "StringObject Function" ] +--- + + + + + += getBytes() + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Copies the String's characters to the supplied buffer. + +[%hardbreaks] + + +[float] +=== Syntax +`myString.getBytes(buf, len)` + + +[float] +=== Parameters +`myString`: a variable of type `String`. + +`buf`: the buffer to copy the characters into. Allowed data types: array of `byte`. + +`len`: the size of the buffer. Allowed data types: `unsigned int`. + + +[float] +=== Returns +Nothing + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +[role="example"] +* #EXAMPLE# https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[String Tutorials^] +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Variables/Data Types/String/Functions/indexOf.adoc b/Language/Variables/Data Types/String/Functions/indexOf.adoc index 04ca3a7f2..58df9db78 100644 --- a/Language/Variables/Data Types/String/Functions/indexOf.adoc +++ b/Language/Variables/Data Types/String/Functions/indexOf.adoc @@ -1,65 +1,61 @@ ---- -title: "indexOf()" -categories: [ "Data Types" ] -subCategories: [ "StringObject Function" ] ---- - - - - - -= indexOf() - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -Locates a character or String within another String. By default, searches from the beginning of the String, but can also start from a given index, allowing for the locating of all instances of the character or String. - - -[%hardbreaks] - - -[float] -=== Syntax -[source,arduino] ----- -string.indexOf(val) - -string.indexOf(val, from) ----- - -[float] -=== Parameters -`string`: a variable of type String - -`val`: the value to search for - char or String - -`from`: the index to start the search from - -[float] -=== Returns -The index of val within the String, or -1 if not found. - --- -// OVERVIEW SECTION ENDS - - - -// HOW TO USE SECTION ENDS - - -// SEE ALSO SECTION -[#see_also] --- - -[float] -=== See also - -[role="example"] -* #EXAMPLE# link: https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[Built-in String Tutorials] --- -// SEE ALSO SECTION ENDS \ No newline at end of file +--- +title: "indexOf()" +categories: [ "Data Types" ] +subCategories: [ "StringObject Function" ] +--- + + + + + += indexOf() + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Locates a character or String within another String. By default, searches from the beginning of the String, but can also start from a given index, allowing for the locating of all instances of the character or String. + + +[%hardbreaks] + + +[float] +=== Syntax +`myString.indexOf(val)` + +`myString.indexOf(val, from)` + + +[float] +=== Parameters +`myString`: a variable of type `String`. + +`val`: the value to search for. Allowed data types: `char`, `String`. + +`from`: the index to start the search from. + + +[float] +=== Returns +The index of val within the String, or -1 if not found. + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +[role="example"] +* #EXAMPLE# https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[String Tutorials^] +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Variables/Data Types/String/Functions/lastIndexOf.adoc b/Language/Variables/Data Types/String/Functions/lastIndexOf.adoc index 36810f486..ffabd6589 100644 --- a/Language/Variables/Data Types/String/Functions/lastIndexOf.adoc +++ b/Language/Variables/Data Types/String/Functions/lastIndexOf.adoc @@ -1,65 +1,60 @@ ---- -title: "lastIndexOf()" -categories: [ "Data Types" ] -subCategories: [ "StringObject Function" ] ---- - - - - - -= lastIndexOf() - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -Locates a character or String within another String. By default, searches from the end of the String, but can also work backwards from a given index, allowing for the locating of all instances of the character or String. - -[%hardbreaks] - - -[float] -=== Syntax -[source,arduino] ----- -string.lastIndexOf(val) - -string.lastIndexOf(val, from) ----- - -[float] -=== Parameters -`string`: a variable of type String - -`val`: the value to search for - char or String - -`from`: the index to work backwards from - - -[float] -=== Returns -The index of val within the String, or -1 if not found. - --- -// OVERVIEW SECTION ENDS - - - -// HOW TO USE SECTION ENDS - - -// SEE ALSO SECTION -[#see_also] --- - -[float] -=== See also - -[role="example"] -* #EXAMPLE# link: https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[Built-in String Tutorials] --- -// SEE ALSO SECTION ENDS \ No newline at end of file +--- +title: "lastIndexOf()" +categories: [ "Data Types" ] +subCategories: [ "StringObject Function" ] +--- + + + + + += lastIndexOf() + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Locates a character or String within another String. By default, searches from the end of the String, but can also work backwards from a given index, allowing for the locating of all instances of the character or String. + +[%hardbreaks] + + +[float] +=== Syntax +`myString.lastIndexOf(val)` + +`myString.lastIndexOf(val, from)` + + +[float] +=== Parameters +`myString`: a variable of type `String`. + +`val`: the value to search for. Allowed data types: `char`, `String`. + +`from`: the index to work backwards from. + + +[float] +=== Returns +The index of val within the String, or -1 if not found. + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +[role="example"] +* #EXAMPLE# https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[String Tutorials^] +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Variables/Data Types/String/Functions/length.adoc b/Language/Variables/Data Types/String/Functions/length.adoc index e6ce51a4b..d3703282e 100644 --- a/Language/Variables/Data Types/String/Functions/length.adoc +++ b/Language/Variables/Data Types/String/Functions/length.adoc @@ -1,59 +1,57 @@ ---- -title: "length()" -categories: [ "Data Types" ] -subCategories: [ "StringObject Function" ] ---- - - - - - -= length() - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -Returns the length of the String, in characters. (Note that this doesn't include a trailing null character.) - -[%hardbreaks] - - -[float] -=== Syntax -[source,arduino] ----- -string.length() ----- - -[float] -=== Parameters -`string`: a variable of type String - - -[float] -=== Returns -The length of the String in characters. - --- -// OVERVIEW SECTION ENDS - - - -// HOW TO USE SECTION ENDS - - -// SEE ALSO SECTION -[#see_also] --- - -[float] -=== See also - -[role="example"] -* #EXAMPLE# link: https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[Built-in String Tutorials] --- -// SEE ALSO SECTION ENDS \ No newline at end of file +--- +title: "length()" +categories: [ "Data Types" ] +subCategories: [ "StringObject Function" ] +--- + + + + + += length() + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Returns the length of the String, in characters. (Note that this doesn't include a trailing null character.) + +[%hardbreaks] + + +[float] +=== Syntax +`myString.length()` + + +[float] +=== Parameters +`myString`: a variable of type `String`. + + +[float] +=== Returns +The length of the String in characters. Data type: `unsigned int`. + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +[role="example"] +* #EXAMPLE# https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[String Tutorials^] +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Variables/Data Types/String/Functions/remove.adoc b/Language/Variables/Data Types/String/Functions/remove.adoc index 12b927d77..55b419ed1 100644 --- a/Language/Variables/Data Types/String/Functions/remove.adoc +++ b/Language/Variables/Data Types/String/Functions/remove.adoc @@ -1,63 +1,73 @@ ---- -title: "remove()" -categories: [ "Data Types" ] -subCategories: [ "StringObject Function" ] ---- - - - - - -= remove() - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -Modify in place a String removing chars from the provided index to the end of the String or from the provided index to index plus count. - -[%hardbreaks] - - -[float] -=== Syntax -[source,arduino] ----- -string.remove(index) - -string.remove(index, count) ----- - -[float] -=== Parameters -`index`: a variable of type unsigned int - -`count`: a variable of type unsigned int - - -[float] -=== Returns -None - --- -// OVERVIEW SECTION ENDS - - - -// HOW TO USE SECTION ENDS - - -// SEE ALSO SECTION -[#see_also] --- - -[float] -=== See also - -[role="example"] -* #EXAMPLE# link: https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[Built-in String Tutorials] --- -// SEE ALSO SECTION ENDS +--- +title: "remove()" +categories: [ "Data Types" ] +subCategories: [ "StringObject Function" ] +--- + + + + + += remove() + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Modify in place a String removing chars from the provided index to the end of the String or from the provided index to index plus count. + +[%hardbreaks] + + +[float] +=== Syntax +`myString.remove(index)` + +`myString.remove(index, count)` + + +[float] +=== Parameters +`myString`: a variable of type `String`. + +`index`: The position at which to start the remove process (zero indexed). Allowed data types: `unsigned int`. + +`count`: The number of characters to remove. Allowed data types: `unsigned int`. + + +[float] +=== Returns +Nothing + +-- +// OVERVIEW SECTION ENDS + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code +// Describe what the example code is all about and add relevant code ►►►►► THIS SECTION IS MANDATORY ◄◄◄◄◄ +[source,arduino] +---- +String greeting = "hello"; +greeting.remove(2, 2); // greeting now contains "heo" +---- +[%hardbreaks] +-- +// HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +[role="example"] +* #EXAMPLE# https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[String Tutorials^] +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Variables/Data Types/String/Functions/replace.adoc b/Language/Variables/Data Types/String/Functions/replace.adoc index 46ba23983..2555182a2 100644 --- a/Language/Variables/Data Types/String/Functions/replace.adoc +++ b/Language/Variables/Data Types/String/Functions/replace.adoc @@ -1,63 +1,59 @@ ---- -title: "replace()" -categories: [ "Data Types" ] -subCategories: [ "StringObject Function" ] ---- - - - - - -= replace() - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -The String replace() function allows you to replace all instances of a given character with another character. You can also use replace to replace substrings of a String with a different substring. - -[%hardbreaks] - - -[float] -=== Syntax -[source,arduino] ----- -string.replace(substring1, substring2) ----- - -[float] -=== Parameters -`string`: a variable of type String - -`substring1`: another variable of type String - -`substring2`: another variable of type String - - - -[float] -=== Returns -None --- -// OVERVIEW SECTION ENDS - - - -// HOW TO USE SECTION ENDS - - -// SEE ALSO SECTION -[#see_also] --- - -[float] -=== See also - -[role="example"] -* #EXAMPLE# link: https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[Built-in String Tutorials] --- -// SEE ALSO SECTION ENDS +--- +title: "replace()" +categories: [ "Data Types" ] +subCategories: [ "StringObject Function" ] +--- + + + + + += replace() + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +The String replace() function allows you to replace all instances of a given character with another character. You can also use replace to replace substrings of a String with a different substring. + +[%hardbreaks] + + +[float] +=== Syntax +`myString.replace(substring1, substring2)` + + +[float] +=== Parameters +`myString`: a variable of type `String`. + +`substring1`: another variable of type `String`. + +`substring2`: another variable of type `String`. + + +[float] +=== Returns +Nothing + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +[role="example"] +* #EXAMPLE# https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[String Tutorials^] +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Variables/Data Types/String/Functions/reserve.adoc b/Language/Variables/Data Types/String/Functions/reserve.adoc index bc1dc2018..de64fdd0d 100644 --- a/Language/Variables/Data Types/String/Functions/reserve.adoc +++ b/Language/Variables/Data Types/String/Functions/reserve.adoc @@ -1,88 +1,88 @@ ---- -title: "reserve()" -categories: [ "Data Types" ] -subCategories: [ "StringObject Function" ] ---- - - - - - -= reserve() - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -The String reserve() function allows you to allocate a buffer in memory for manipulating Strings. - -[%hardbreaks] - - -[float] -=== Syntax -[source,arduino] ----- -string.reserve(size) ----- - -[float] -=== Parameters -`size`: unsigned int declaring the number of bytes in memory to save for String manipulation - - -[float] -=== Returns -None --- -// OVERVIEW SECTION ENDS - -// HOW TO USE SECTION STARTS -[#howtouse] --- - -[float] -=== Example Code - -[source,arduino] ----- -String myString; - -void setup() { - // initialize serial and wait for port to open: - Serial.begin(9600); - while (!Serial) { - ; // wait for serial port to connect. Needed for native USB - } - - myString.reserve(26); - myString = "i="; - myString += "1234"; - myString += ", is that ok?"; - - // print the String: - Serial.println(myString); -} - -void loop() { - // nothing to do here -} - ----- -// HOW TO USE SECTION ENDS - - -// SEE ALSO SECTION -[#see_also] --- - -[float] -=== See also - -[role="example"] -* #EXAMPLE# link: https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[Built-in String Tutorials] --- -// SEE ALSO SECTION ENDS +--- +title: "reserve()" +categories: [ "Data Types" ] +subCategories: [ "StringObject Function" ] +--- + + + + + += reserve() + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +The String reserve() function allows you to allocate a buffer in memory for manipulating Strings. + +[%hardbreaks] + + +[float] +=== Syntax +`myString.reserve(size)` + + +[float] +=== Parameters +`myString`: a variable of type `String`. + +`size`: the number of bytes in memory to save for String manipulation. Allowed data types: `unsigned int`. + + +[float] +=== Returns +`1` on success, `0` on failure. + +-- +// OVERVIEW SECTION ENDS + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code + +[source,arduino] +---- +String myString; + +void setup() { + // initialize serial and wait for port to open: + Serial.begin(9600); + while (!Serial) { + ; // wait for serial port to connect. Needed for native USB + } + + myString.reserve(26); + myString = "i="; + myString += "1234"; + myString += ", is that ok?"; + + // print the String: + Serial.println(myString); +} + +void loop() { + // nothing to do here +} +---- +-- +// HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +[role="example"] +* #EXAMPLE# https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[String Tutorials^] +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Variables/Data Types/String/Functions/setCharAt.adoc b/Language/Variables/Data Types/String/Functions/setCharAt.adoc index d64113792..369126e44 100644 --- a/Language/Variables/Data Types/String/Functions/setCharAt.adoc +++ b/Language/Variables/Data Types/String/Functions/setCharAt.adoc @@ -1,63 +1,59 @@ ---- -title: "setCharAt()" -categories: [ "Data Types" ] -subCategories: [ "StringObject Function" ] ---- - - - - - -= setCharAt() - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -Sets a character of the String. Has no effect on indices outside the existing length of the String. - -[%hardbreaks] - - -[float] -=== Syntax -[source,arduino] ----- -string.setCharAt(index, c) ----- - -[float] -=== Parameters -`string`: a variable of type String - -`index`: the index to set the character at - -`c`: the character to store to the given location - - -[float] -=== Returns -None - --- -// OVERVIEW SECTION ENDS - - - -// HOW TO USE SECTION ENDS - - -// SEE ALSO SECTION -[#see_also] --- - -[float] -=== See also - -[role="example"] -* #EXAMPLE# link: https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[Built-in String Tutorials] --- -// SEE ALSO SECTION ENDS \ No newline at end of file +--- +title: "setCharAt()" +categories: [ "Data Types" ] +subCategories: [ "StringObject Function" ] +--- + + + + + += setCharAt() + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Sets a character of the String. Has no effect on indices outside the existing length of the String. + +[%hardbreaks] + + +[float] +=== Syntax +`myString.setCharAt(index, c)` + + +[float] +=== Parameters +`myString`: a variable of type `String`. + +`index`: the index to set the character at. + +`c`: the character to store to the given location. + + +[float] +=== Returns +Nothing + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +[role="example"] +* #EXAMPLE# https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[String Tutorials^] +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Variables/Data Types/String/Functions/startsWith.adoc b/Language/Variables/Data Types/String/Functions/startsWith.adoc index 69b019e37..3cf1acf7b 100644 --- a/Language/Variables/Data Types/String/Functions/startsWith.adoc +++ b/Language/Variables/Data Types/String/Functions/startsWith.adoc @@ -1,60 +1,58 @@ ---- -title: "startsWith()" -categories: [ "Data Types" ] -subCategories: [ "StringObject Function" ] ---- - - - - - -= startsWith() - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -Tests whether or not a String starts with the characters of another String. - -[%hardbreaks] - - -[float] -=== Syntax -[source,arduino] ----- -string.startsWith(string2) ----- - -[float] -=== Parameters -`string, string2`: a variable of type String - - -[float] -=== Returns -`true`: if string starts with the characters of string2 - -`false`: otherwise --- -// OVERVIEW SECTION ENDS - - - -// HOW TO USE SECTION ENDS - - -// SEE ALSO SECTION -[#see_also] --- - -[float] -=== See also - -[role="example"] -* #EXAMPLE# link: https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[Built-in String Tutorials] --- -// SEE ALSO SECTION ENDS \ No newline at end of file +--- +title: "startsWith()" +categories: [ "Data Types" ] +subCategories: [ "StringObject Function" ] +--- + + + + + += startsWith() + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Tests whether or not a String starts with the characters of another String. + +[%hardbreaks] + + +[float] +=== Syntax +`myString.startsWith(myString2)` + + +[float] +=== Parameters +`myString, myString2`: a variable of type `String`. + + +[float] +=== Returns +`true`: if myString starts with the characters of myString2. + +`false`: otherwise + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +[role="example"] +* #EXAMPLE# https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[String Tutorials^] +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Variables/Data Types/String/Functions/substring.adoc b/Language/Variables/Data Types/String/Functions/substring.adoc index 4b5449f4b..cee035575 100644 --- a/Language/Variables/Data Types/String/Functions/substring.adoc +++ b/Language/Variables/Data Types/String/Functions/substring.adoc @@ -1,65 +1,60 @@ ---- -title: "substring()" -categories: [ "Data Types" ] -subCategories: [ "StringObject Function" ] ---- - - - - - -= substring() - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -Get a substring of a String. The starting index is inclusive (the corresponding character is included in the substring), but the optional ending index is exclusive (the corresponding character is not included in the substring). If the ending index is omitted, the substring continues to the end of the String. - -[%hardbreaks] - - -[float] -=== Syntax -[source,arduino] ----- -string.substring(from) - -string.substring(from, to) ----- - -[float] -=== Parameters -`string`: a variable of type String - -`from`: the index to start the substring at - -`to` (optional): the index to end the substring before - - -[float] -=== Returns -The substring. - --- -// OVERVIEW SECTION ENDS - - - -// HOW TO USE SECTION ENDS - - -// SEE ALSO SECTION -[#see_also] --- - -[float] -=== See also - -[role="example"] -* #EXAMPLE# link: https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[Built-in String Tutorials] --- -// SEE ALSO SECTION ENDS \ No newline at end of file +--- +title: "substring()" +categories: [ "Data Types" ] +subCategories: [ "StringObject Function" ] +--- + + + + + += substring() + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Get a substring of a String. The starting index is inclusive (the corresponding character is included in the substring), but the optional ending index is exclusive (the corresponding character is not included in the substring). If the ending index is omitted, the substring continues to the end of the String. + +[%hardbreaks] + + +[float] +=== Syntax +`myString.substring(from)` + +`myString.substring(from, to)` + + +[float] +=== Parameters +`myString`: a variable of type `String`. + +`from`: the index to start the substring at. + +`to` (optional): the index to end the substring before. + + +[float] +=== Returns +The substring. + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +[role="example"] +* #EXAMPLE# https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[String Tutorials^] +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Variables/Data Types/String/Functions/toCharArray.adoc b/Language/Variables/Data Types/String/Functions/toCharArray.adoc index 4e743e837..95bf3c909 100644 --- a/Language/Variables/Data Types/String/Functions/toCharArray.adoc +++ b/Language/Variables/Data Types/String/Functions/toCharArray.adoc @@ -1,62 +1,59 @@ ---- -title: "toCharArray()" -categories: [ "Data Types" ] -subCategories: [ "StringObject Function" ] ---- - - - - - -= toCharArray() - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -Copies the String's characters to the supplied buffer. - -[%hardbreaks] - - -[float] -=== Syntax -[source,arduino] ----- -string.toCharArray(buf, len) ----- - -[float] -=== Parameters -`string`: a variable of type String - -`buf`: the buffer to copy the characters into (_char []_) - -`len`: the size of the buffer (_unsigned int_) - -[float] -=== Returns -None - --- -// OVERVIEW SECTION ENDS - - - -// HOW TO USE SECTION ENDS - - -// SEE ALSO SECTION -[#see_also] --- - -[float] -=== See also - -[role="example"] -* #EXAMPLE# link: https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[Built-in String Tutorials] --- -// SEE ALSO SECTION ENDS +--- +title: "toCharArray()" +categories: [ "Data Types" ] +subCategories: [ "StringObject Function" ] +--- + + + + + += toCharArray() + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Copies the String's characters to the supplied buffer. + +[%hardbreaks] + + +[float] +=== Syntax +`myString.toCharArray(buf, len)` + + +[float] +=== Parameters +`myString`: a variable of type `String`. + +`buf`: the buffer to copy the characters into. Allowed data types: array of `char`. + +`len`: the size of the buffer. Allowed data types: `unsigned int`. + + +[float] +=== Returns +Nothing + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +[role="example"] +* #EXAMPLE# https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[String Tutorials^] +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Variables/Data Types/String/Functions/toDouble.adoc b/Language/Variables/Data Types/String/Functions/toDouble.adoc new file mode 100644 index 000000000..1ede4a704 --- /dev/null +++ b/Language/Variables/Data Types/String/Functions/toDouble.adoc @@ -0,0 +1,57 @@ +--- +title: "toDouble()" +categories: [ "Data Types" ] +subCategories: [ "StringObject Function" ] +--- + + + + + += toDouble() + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Converts a valid String to a double. The input String should start with a digit. If the String contains non-digit characters, the function will stop performing the conversion. For example, the Strings "123.45", "123", and "123fish" are converted to 123.45, 123.00, and 123.00 respectively. Note that "123.456" is approximated with 123.46. Note too that floats have only 6-7 decimal digits of precision and that longer Strings might be truncated. + +[%hardbreaks] + + +[float] +=== Syntax +`myString.toDouble()` + + +[float] +=== Parameters +`myString`: a variable of type `String`. + + +[float] +=== Returns +If no valid conversion could be performed because the String doesn't start with a digit, a zero is returned. Data type: `double`. + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +[role="example"] +* #EXAMPLE# https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[String Tutorials^] +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Variables/Data Types/String/Functions/toFloat.adoc b/Language/Variables/Data Types/String/Functions/toFloat.adoc index e6dd84379..91c1e1f5f 100644 --- a/Language/Variables/Data Types/String/Functions/toFloat.adoc +++ b/Language/Variables/Data Types/String/Functions/toFloat.adoc @@ -1,61 +1,57 @@ ---- -title: "toFloat()" -categories: [ "Data Types" ] -subCategories: [ "StringObject Function" ] ---- - - - - - -= toFloat() - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -Converts a valid String to a float. The input String should start with a digit. If the String contains non-digit characters, the function will stop performing the conversion. For example, the Strings "123.45", "123", and "123fish" are converted to 123.45, 123.00, and 123.00 respectively. Note that "123.456" is approximated with 123.46. Note too that floats have only 6-7 decimal digits of precision and that longer Strings might be truncated. - -[%hardbreaks] - - -[float] -=== Syntax -[source,arduino] ----- -string.toFloat() ----- - -[float] -=== Parameters -`string`: a variable of type String - - -[float] -=== Returns -`float` - -If no valid conversion could be performed because the String doesn't start with a digit, a zero is returned. - --- -// OVERVIEW SECTION ENDS - - - -// HOW TO USE SECTION ENDS - - -// SEE ALSO SECTION -[#see_also] --- - -[float] -=== See also - -[role="example"] -* #EXAMPLE# link: https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[Built-in String Tutorials] --- -// SEE ALSO SECTION ENDS +--- +title: "toFloat()" +categories: [ "Data Types" ] +subCategories: [ "StringObject Function" ] +--- + + + + + += toFloat() + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Converts a valid String to a float. The input String should start with a digit. If the String contains non-digit characters, the function will stop performing the conversion. For example, the Strings "123.45", "123", and "123fish" are converted to 123.45, 123.00, and 123.00 respectively. Note that "123.456" is approximated with 123.46. Note too that floats have only 6-7 decimal digits of precision and that longer Strings might be truncated. + +[%hardbreaks] + + +[float] +=== Syntax +`myString.toFloat()` + + +[float] +=== Parameters +`myString`: a variable of type `String`. + + +[float] +=== Returns +If no valid conversion could be performed because the String doesn't start with a digit, a zero is returned. Data type: `float`. + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +[role="example"] +* #EXAMPLE# https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[String Tutorials^] +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Variables/Data Types/String/Functions/toInt.adoc b/Language/Variables/Data Types/String/Functions/toInt.adoc index c4cf46387..3c238da57 100644 --- a/Language/Variables/Data Types/String/Functions/toInt.adoc +++ b/Language/Variables/Data Types/String/Functions/toInt.adoc @@ -1,61 +1,57 @@ ---- -title: "toInt()" -categories: [ "Data Types" ] -subCategories: [ "StringObject Function" ] ---- - - - - - -= toInt() - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -Converts a valid String to an integer. The input String should start with an integer number. If the String contains non-integer numbers, the function will stop performing the conversion. - -[%hardbreaks] - - -[float] -=== Syntax -[source,arduino] ----- -string.toInt() ----- - -[float] -=== Parameters -`string`: a variable of type String - - -[float] -=== Returns -`long` - -If no valid conversion could be performed because the String doesn't start with a integer number, a zero is returned. - --- -// OVERVIEW SECTION ENDS - - - -// HOW TO USE SECTION ENDS - - -// SEE ALSO SECTION -[#see_also] --- - -[float] -=== See also - -[role="example"] -* #EXAMPLE# link: https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[Built-in String Tutorials] --- -// SEE ALSO SECTION ENDS +--- +title: "toInt()" +categories: [ "Data Types" ] +subCategories: [ "StringObject Function" ] +--- + + + + + += toInt() + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Converts a valid String to an integer. The input String should start with an integer number. If the String contains non-integer numbers, the function will stop performing the conversion. + +[%hardbreaks] + + +[float] +=== Syntax +`myString.toInt()` + + +[float] +=== Parameters +`myString`: a variable of type `String`. + + +[float] +=== Returns +If no valid conversion could be performed because the String doesn't start with a integer number, a zero is returned. Data type: `long`. + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +[role="example"] +* #EXAMPLE# https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[String Tutorials^] +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Variables/Data Types/String/Functions/toLowerCase.adoc b/Language/Variables/Data Types/String/Functions/toLowerCase.adoc index 46989a1a7..2d1ba3b57 100644 --- a/Language/Variables/Data Types/String/Functions/toLowerCase.adoc +++ b/Language/Variables/Data Types/String/Functions/toLowerCase.adoc @@ -1,59 +1,57 @@ ---- -title: "toLowerCase()" -categories: [ "Data Types" ] -subCategories: [ "StringObject Function" ] ---- - - - - - -= toLowerCase() - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -Get a lower-case version of a String. As of 1.0, toLowerCase() modifies the String in place rather than returning a new one. - -[%hardbreaks] - - -[float] -=== Syntax -[source,arduino] ----- -string.toLowerCase() ----- - -[float] -=== Parameters -`string`: a variable of type String - - -[float] -=== Returns -None - --- -// OVERVIEW SECTION ENDS - - - -// HOW TO USE SECTION ENDS - - -// SEE ALSO SECTION -[#see_also] --- - -[float] -=== See also - -[role="example"] -* #EXAMPLE# link: https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[Built-in String Tutorials] --- -// SEE ALSO SECTION ENDS +--- +title: "toLowerCase()" +categories: [ "Data Types" ] +subCategories: [ "StringObject Function" ] +--- + + + + + += toLowerCase() + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Get a lower-case version of a String. The `toLowerCase()` function modifies the String in place rather than returning a new one. + +[%hardbreaks] + + +[float] +=== Syntax +`myString.toLowerCase()` + + +[float] +=== Parameters +`myString`: a variable of type `String`. + + +[float] +=== Returns +Nothing + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +[role="example"] +* #EXAMPLE# https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[String Tutorials^] +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Variables/Data Types/String/Functions/toUpperCase.adoc b/Language/Variables/Data Types/String/Functions/toUpperCase.adoc index fe5f0b27a..231dcc27c 100644 --- a/Language/Variables/Data Types/String/Functions/toUpperCase.adoc +++ b/Language/Variables/Data Types/String/Functions/toUpperCase.adoc @@ -1,58 +1,56 @@ ---- -title: "toUpperCase()" -categories: [ "Data Types" ] -subCategories: [ "StringObject Function" ] ---- - - - - - -= toUpperCase() - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -Get an upper-case version of a String. As of 1.0, toUpperCase() modifies the String in place rather than returning a new one. -[%hardbreaks] - - -[float] -=== Syntax -[source,arduino] ----- -string.toUpperCase() ----- - -[float] -=== Parameters -`string`: a variable of type String - - -[float] -=== Returns -None - --- -// OVERVIEW SECTION ENDS - - - -// HOW TO USE SECTION ENDS - - -// SEE ALSO SECTION -[#see_also] --- - -[float] -=== See also - -[role="example"] -* #EXAMPLE# link: https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[Built-in String Tutorials] --- -// SEE ALSO SECTION ENDS +--- +title: "toUpperCase()" +categories: [ "Data Types" ] +subCategories: [ "StringObject Function" ] +--- + + + + + += toUpperCase() + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Get an upper-case version of a String. The `toUpperCase()` modifies the String in place rather than returning a new one. +[%hardbreaks] + + +[float] +=== Syntax +`myString.toUpperCase()` + + +[float] +=== Parameters +`myString`: a variable of type `String`. + + +[float] +=== Returns +Nothing + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +[role="example"] +* #EXAMPLE# https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[String Tutorials^] +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Variables/Data Types/String/Functions/trim.adoc b/Language/Variables/Data Types/String/Functions/trim.adoc index e90b8590d..3714c4f87 100644 --- a/Language/Variables/Data Types/String/Functions/trim.adoc +++ b/Language/Variables/Data Types/String/Functions/trim.adoc @@ -1,59 +1,57 @@ ---- -title: "trim()" -categories: [ "Data Types" ] -subCategories: [ "StringObject Function" ] ---- - - - - - -= trim() - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -Get a version of the String with any leading and trailing whitespace removed. As of 1.0, trim() modifies the String in place rather than returning a new one. - -[%hardbreaks] - - -[float] -=== Syntax -[source,arduino] ----- -string.trim() ----- - -[float] -=== Parameters -`string`: a variable of type String - - -[float] -=== Returns -None - --- -// OVERVIEW SECTION ENDS - - - -// HOW TO USE SECTION ENDS - - -// SEE ALSO SECTION -[#see_also] --- - -[float] -=== See also - -[role="example"] -* #EXAMPLE# link: https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[Built-in String Tutorials] --- -// SEE ALSO SECTION ENDS +--- +title: "trim()" +categories: [ "Data Types" ] +subCategories: [ "StringObject Function" ] +--- + + + + + += trim() + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Get a version of the String with any leading and trailing whitespace removed. The `trim()` function modifies the String in place rather than returning a new one. + +[%hardbreaks] + + +[float] +=== Syntax +`myString.trim()` + + +[float] +=== Parameters +`myString`: a variable of type String. + + +[float] +=== Returns +Nothing + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +[role="example"] +* #EXAMPLE# https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[String Tutorials^] +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Variables/Data Types/String/Operators/append.adoc b/Language/Variables/Data Types/String/Operators/append.adoc index 932fa06d1..b2ca3b289 100644 --- a/Language/Variables/Data Types/String/Operators/append.adoc +++ b/Language/Variables/Data Types/String/Operators/append.adoc @@ -1,60 +1,59 @@ ---- -title: "+=" -title_expanded: append -categories: [ "Data Types" ] -subCategories: [ "StringObject Operator" ] ---- - - - - - -= += Append - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -It concatenates Strings with other data. - -[%hardbreaks] - - -[float] -=== Syntax -[source,arduino] ----- -string += data ----- - -[float] -=== Parameters -None - -[float] -=== Returns -None - --- - -// OVERVIEW SECTION ENDS - - - -// HOW TO USE SECTION ENDS - - -// SEE ALSO SECTION -[#see_also] --- - -[float] -=== See also - -[role="example"] -* #EXAMPLE# link: https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[Built-in String Tutorials] --- -// SEE ALSO SECTION ENDS +--- +title: "+=" +title_expanded: append +categories: [ "Data Types" ] +subCategories: [ "StringObject Operator" ] +--- + + + + + += += Append + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +It concatenates Strings with other data. + +[%hardbreaks] + + +[float] +=== Syntax +`myString1 += data` + + +[float] +=== Parameters +`myString1`: a String variable. + + +[float] +=== Returns +Nothing + +-- + +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +[role="example"] +* #EXAMPLE# https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[String Tutorials^] +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Variables/Data Types/String/Operators/comparison.adoc b/Language/Variables/Data Types/String/Operators/comparison.adoc index 7ebde6831..4a711375d 100644 --- a/Language/Variables/Data Types/String/Operators/comparison.adoc +++ b/Language/Variables/Data Types/String/Operators/comparison.adoc @@ -1,58 +1,57 @@ ---- -title: "==" -title_expanded: comparison -categories: [ "Data Types" ] -subCategories: [ "StringObject Operator" ] ---- - -= == Comparison - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -Compares two Strings for equality. The comparison is case-sensitive, meaning the String "hello" is not equal to the String "HELLO". Functionally the same as string.equals() - - -[%hardbreaks] - - -[float] -=== Syntax -[source,arduino] ----- -string1 == string2 ----- - -[float] -=== Parameters -`string1, string2` - a String variable - -[float] -=== Returns -`true`: if string1 equals string2 - -`false`: otherwise --- - -// OVERVIEW SECTION ENDS - - - -// HOW TO USE SECTION ENDS - - -// SEE ALSO SECTION -[#see_also] --- - -[float] -=== See also - -[role="example"] -* #EXAMPLE# link: https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[Built-in String Tutorials] --- -// SEE ALSO SECTION ENDS +--- +title: "==" +title_expanded: comparison +categories: [ "Data Types" ] +subCategories: [ "StringObject Operator" ] +--- + += == Comparison + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Compares two Strings for equality. The comparison is case-sensitive, meaning the String "hello" is not equal to the String "HELLO". Functionally the same as string.equals() + + +[%hardbreaks] + + +[float] +=== Syntax +`myString1 == myString2` + +[float] +=== Parameters +`myString1`: a String variable. + +`myString2`: a String variable. + + +[float] +=== Returns +`true`: if myString1 equals myString2. + +`false`: otherwise. + +-- + +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +[role="example"] +* #EXAMPLE# https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[String Tutorials^] +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Variables/Data Types/String/Operators/concatenation.adoc b/Language/Variables/Data Types/String/Operators/concatenation.adoc index e4e9f01e4..67fd53ca2 100644 --- a/Language/Variables/Data Types/String/Operators/concatenation.adoc +++ b/Language/Variables/Data Types/String/Operators/concatenation.adoc @@ -1,60 +1,61 @@ ---- -title: "+" -title_expanded: concatenation -categories: [ "Data Types" ] -subCategories: [ "StringObject Operator" ] ---- - - - - - -= + Concatenation - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -Combines, or concatenates two strings into one new String. The second string is appended to the first, and the result is placed in a new String. Works the same as string.concat(). - -[%hardbreaks] - - -[float] -=== Syntax -[source,arduino] ----- -string3 = string1 + string 2; string3 += string2; ----- - -[float] -=== Parameters -`string, string1, string2, string3` - a string variable - -[float] -=== Returns -new String that is the combination of the original two Strings. - --- - -// OVERVIEW SECTION ENDS - - - -// HOW TO USE SECTION ENDS - - -// SEE ALSO SECTION -[#see_also] --- - -[float] -=== See also - -[role="example"] -* #EXAMPLE# link: https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[Built-in String Tutorials] --- -// SEE ALSO SECTION ENDS \ No newline at end of file +--- +title: "+" +title_expanded: concatenation +categories: [ "Data Types" ] +subCategories: [ "StringObject Operator" ] +--- + + + + + += + Concatenation + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Combines, or concatenates two Strings into one new String. The second String is appended to the first, and the result is placed in a new String. Works the same as string.concat(). + +[%hardbreaks] + + +[float] +=== Syntax +`myString3 = myString1 + myString2` + + +[float] +=== Parameters +`myString1`: a String variable. + +`myString2`: a String variable. + +`myString3`: a String variable. + + +[float] +=== Returns +New String that is the combination of the original two Strings. + +-- + +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +[role="example"] +* #EXAMPLE# https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[String Tutorials^] +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Variables/Data Types/String/Operators/differentFrom.adoc b/Language/Variables/Data Types/String/Operators/differentFrom.adoc index 41e2ef69c..7cb1ce0d7 100644 --- a/Language/Variables/Data Types/String/Operators/differentFrom.adoc +++ b/Language/Variables/Data Types/String/Operators/differentFrom.adoc @@ -1,62 +1,59 @@ ---- -title: "!=" -title_expanded: different from -categories: [ "Data Types" ] -subCategories: [ "StringObject Operator" ] ---- - - - - - -= != Different From - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -Compares two Strings for difference. The comparison is case-sensitive, meaning the String "hello" is not equal to the String "HELLO". Functionally the same as string.equals() - -[%hardbreaks] - - -[float] -=== Syntax -[source,arduino] ----- -string1 != string2 ----- - -[float] -=== Parameters -`string1, string2` - a String variable - -[float] -=== Returns -`true`: if string1 is different from string2 - -`false`: otherwise - --- - -// OVERVIEW SECTION ENDS - - - -// HOW TO USE SECTION ENDS - - -// SEE ALSO SECTION -[#see_also] --- - -[float] -=== See also - -[role="example"] -* #EXAMPLE# link: https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[Built-in String Tutorials] --- -// SEE ALSO SECTION ENDS +--- +title: "!=" +title_expanded: different from +categories: [ "Data Types" ] +subCategories: [ "StringObject Operator" ] +--- + + + += != Different From + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Compares two Strings for difference. The comparison is case-sensitive, meaning the String "hello" is not equal to the String "HELLO". Functionally the same as string.equals() + +[%hardbreaks] + + +[float] +=== Syntax +`myString1 != myString2` + + +[float] +=== Parameters +`myString1`: a String variable. + +`myString2`: a String variable. + + +[float] +=== Returns +`true`: if myString1 is different from myString2. + +`false`: otherwise. + +-- + +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +[role="example"] +* #EXAMPLE# https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[String Tutorials^] +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Variables/Data Types/String/Operators/elementAccess.adoc b/Language/Variables/Data Types/String/Operators/elementAccess.adoc index a43f8d03f..bc9d73a9b 100644 --- a/Language/Variables/Data Types/String/Operators/elementAccess.adoc +++ b/Language/Variables/Data Types/String/Operators/elementAccess.adoc @@ -1,64 +1,61 @@ ---- -title: "[] " -title_expanded: element access -categories: [ "Data Types" ] -subCategories: [ "StringObject Operator" ] ---- - - - - - -= [] Element Access - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -Allows you access to the individual characters of a String. - -[%hardbreaks] - - -[float] -=== Syntax -[source,arduino] ----- -char thisChar = string1[n] ----- - -[float] -=== Parameters -`char thisChar` - a character variable - -`string1` - a String variable - -`int n` - a numeric variable - -[float] -=== Returns -The nth char of the String. Same as charAt(). - --- - -// OVERVIEW SECTION ENDS - - - -// HOW TO USE SECTION ENDS - - -// SEE ALSO SECTION -[#see_also] --- - -[float] -=== See also - -[role="example"] -* #EXAMPLE# link: https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[Built-in String Tutorials] --- -// SEE ALSO SECTION ENDS +--- +title: "[] " +title_expanded: element access +categories: [ "Data Types" ] +subCategories: [ "StringObject Operator" ] +--- + + + + + += [] Element Access + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Allows you access to the individual characters of a String. + +[%hardbreaks] + + +[float] +=== Syntax +`char thisChar = myString1[n]` + + +[float] +=== Parameters +`thisChar`: Allowed data types: char. + +`myString1`: Allowed data types: String. + +`n`: a numeric variable. + + +[float] +=== Returns +The nth char of the String. Same as charAt(). + +-- + +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +[role="example"] +* #EXAMPLE# https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[String Tutorials^] +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Variables/Data Types/String/Operators/greaterThan.adoc b/Language/Variables/Data Types/String/Operators/greaterThan.adoc index 03a4ebe5c..26178c85c 100644 --- a/Language/Variables/Data Types/String/Operators/greaterThan.adoc +++ b/Language/Variables/Data Types/String/Operators/greaterThan.adoc @@ -1,63 +1,62 @@ ---- -title: ">" -title_expanded: greater than -categories: [ "Data Types" ] -subCategories: [ "StringObject Operator" ] ---- - - - - - -= > Greater Than - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -Tests if the String on the left is greater than the String on the right. This operator evaluates Strings in alphabetical order, on the first character where the two differ. So, for example "b" > "a" and "2" > "1", but "999" > "1000" because 9 comes after 1. - -Caution: String comparison operators can be confusing when you're comparing numeric strings, because the numbers are treated as Strings and not as numbers. If you need to compare numbers numerically, compare them as ints, floats, or longs, and not as Strings. -[%hardbreaks] - - -[float] -=== Syntax -[source,arduino] ----- -string1 > string2 ----- - -[float] -=== Parameters -`string1, string2` - a String variable - -[float] -=== Returns -`true`: if string1 is greater than string2 - -`false`: otherwise - --- - -// OVERVIEW SECTION ENDS - - - -// HOW TO USE SECTION ENDS - - -// SEE ALSO SECTION -[#see_also] --- - -[float] -=== See also - -[role="example"] -* #EXAMPLE# link: https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[Built-in String Tutorials] --- -// SEE ALSO SECTION ENDS +--- +title: ">" +title_expanded: greater than +categories: [ "Data Types" ] +subCategories: [ "StringObject Operator" ] +--- + + + + + += > Greater Than + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Tests if the String on the left is greater than the String on the right. This operator evaluates Strings in alphabetical order, on the first character where the two differ. So, for example "b" > "a" and "2" > "1", but "999" > "1000" because 9 comes after 1. + +Caution: String comparison operators can be confusing when you're comparing numeric Strings, because the numbers are treated as Strings and not as numbers. If you need to compare numbers numerically, compare them as ints, floats, or longs, and not as Strings. +[%hardbreaks] + + +[float] +=== Syntax +`myString1 > myString2` + + +[float] +=== Parameters +`myString1`: a String variable. + +`myString2`: a String variable. + + +[float] +=== Returns +`true`: if myString1 is greater than myString2. + +`false`: otherwise. + +-- + +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +[role="example"] +* #EXAMPLE# https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[String Tutorials^] +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Variables/Data Types/String/Operators/greaterThanOrEqualTo.adoc b/Language/Variables/Data Types/String/Operators/greaterThanOrEqualTo.adoc index 5f5aab83e..79444aa6a 100644 --- a/Language/Variables/Data Types/String/Operators/greaterThanOrEqualTo.adoc +++ b/Language/Variables/Data Types/String/Operators/greaterThanOrEqualTo.adoc @@ -1,59 +1,58 @@ ---- -title: ">=" -title_expanded: greater than or equal to -categories: [ "Data Types" ] -subCategories: [ "StringObject Operator" ] ---- - -= >= Greater Than Or Equal To - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -Tests if the String on the left is greater than, or equal to, the String on the right. This operator evaluate Strings in alphabetical order, on the first character where the two differ. So, for example "b" >= "a" and "2" >= "1", but "999" >= "1000" because 9 comes after 1. - -Caution: String comparison operators can be confusing when you're comparing numeric Strings, because the numbers are treated as Strings and not as numbers. If you need to compare numbers numerically, compare them as ints, floats, or longs, and not as Strings. - -[%hardbreaks] - - -[float] -=== Syntax -[source,arduino] ----- -string1 >= string2 ----- - -[float] -=== Parameters -`string1, string2`: variables of type String - - -[float] -=== Returns -`true`: if string1 is greater than or equal to string2 - -`false`: otherwise --- - -// OVERVIEW SECTION ENDS - - - -// HOW TO USE SECTION ENDS - - -// SEE ALSO SECTION -[#see_also] --- - -[float] -=== See also - -[role="example"] -* #EXAMPLE# link: https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[Built-in String Tutorials] --- -// SEE ALSO SECTION ENDS +--- +title: ">=" +title_expanded: greater than or equal to +categories: [ "Data Types" ] +subCategories: [ "StringObject Operator" ] +--- + += >= Greater Than Or Equal To + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Tests if the String on the left is greater than, or equal to, the String on the right. This operator evaluate Strings in alphabetical order, on the first character where the two differ. So, for example "b" >= "a" and "2" >= "1", but "999" >= "1000" because 9 comes after 1. + +Caution: String comparison operators can be confusing when you're comparing numeric Strings, because the numbers are treated as Strings and not as numbers. If you need to compare numbers numerically, compare them as ints, floats, or longs, and not as Strings. + +[%hardbreaks] + + +[float] +=== Syntax +`myString1 >= myString2` + + +[float] +=== Parameters +`myString1`: variable of type String. + +`myString2: variable of type String. + + +[float] +=== Returns +`true`: if myString1 is greater than or equal to myString2. + +`false`: otherwise. + +-- + +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +[role="example"] +* #EXAMPLE# https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[String Tutorials^] +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Variables/Data Types/String/Operators/lessThan.adoc b/Language/Variables/Data Types/String/Operators/lessThan.adoc index ac62e204a..43dda7fa1 100644 --- a/Language/Variables/Data Types/String/Operators/lessThan.adoc +++ b/Language/Variables/Data Types/String/Operators/lessThan.adoc @@ -1,58 +1,58 @@ ---- -title: "<" -title_expanded: less thans -categories: [ "Data Types" ] -subCategories: [ "StringObject Operator" ] ---- - -= < Less Than - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -Tests if the String on the left is less than the String on the right. This operator evaluate Strings in alphabetical order, on the first character where the two differ. So, for example "a" < "b" and "1" < "2", but "999" > "1000" because 9 comes after 1. - -Caution: String comparison operators can be confusing when you're comparing numeric Strings, because the numbers are treated as Strings and not as numbers. If you need to compare numbers numerically, compare them as ints, floats, or longs, and not as Strings. - -[%hardbreaks] - - -[float] -=== Syntax -[source,arduino] ----- -string1 < string2 ----- - -[float] -=== Parameters -`string1, string2`: variables of type String - -[float] -=== Returns -`true`: if string1 is less than string2 - -`false`: otherwise --- - -// OVERVIEW SECTION ENDS - - - -// HOW TO USE SECTION ENDS - - -// SEE ALSO SECTION -[#see_also] --- - -[float] -=== See also - -[role="example"] -* #EXAMPLE# link: https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[Built-in String Tutorials] --- -// SEE ALSO SECTION ENDS +--- +title: "<" +title_expanded: less thans +categories: [ "Data Types" ] +subCategories: [ "StringObject Operator" ] +--- + += < Less Than + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Tests if the String on the left is less than the String on the right. This operator evaluate Strings in alphabetical order, on the first character where the two differ. So, for example "a" < "b" and "1" < "2", but "999" > "1000" because 9 comes after 1. + +Caution: String comparison operators can be confusing when you're comparing numeric Strings, because the numbers are treated as Strings and not as numbers. If you need to compare numbers numerically, compare them as ints, floats, or longs, and not as Strings. + +[%hardbreaks] + + +[float] +=== Syntax +`myString1 < myString2` + + +[float] +=== Parameters +`myString1`: variable of type String. + +`myString2`: variable of type String. + + +[float] +=== Returns +`true`: if myString1 is less than myString2. + +`false`: otherwise. + +-- + +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +[role="example"] +* #EXAMPLE# https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[String Tutorials^] +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Variables/Data Types/String/Operators/lessThanOrEqualTo.adoc b/Language/Variables/Data Types/String/Operators/lessThanOrEqualTo.adoc index 20fc6948f..9ea998aff 100644 --- a/Language/Variables/Data Types/String/Operators/lessThanOrEqualTo.adoc +++ b/Language/Variables/Data Types/String/Operators/lessThanOrEqualTo.adoc @@ -1,64 +1,63 @@ ---- -title: "<=" -title_expanded: less than or equal -categories: [ "Data Types" ] -subCategories: [ "StringObject Operator" ] ---- - - - - - -= <= Less Than Or Equal - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -Tests if the String on the left is less than or equal to the String on the right. This operator evaluate Strings in alphabetical order, on the first character where the two differ. So, for example "a" < "b" and "1" < "2", but "999" > "1000" because 9 comes after 1. - -Caution: String comparison operators can be confusing when you're comparing numeric Strings, because the numbers are treated as Strings and not as numbers. If you need to compare numbers numerically, compare them as ints, floats, or longs, and not as Strings. - -[%hardbreaks] - - -[float] -=== Syntax -[source,arduino] ----- -string1 <= string2 ----- - -[float] -=== Parameters -`string1, string2`: variables of type String - -[float] -=== Returns -`true`: if string1 is less than or equal to string2 - -`false`: otherwise - --- - -// OVERVIEW SECTION ENDS - - - -// HOW TO USE SECTION ENDS - - -// SEE ALSO SECTION -[#see_also] --- - -[float] -=== See also - -[role="example"] -* #EXAMPLE# link: https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[Built-in String Tutorials] --- -// SEE ALSO SECTION ENDS +--- +title: "<=" +title_expanded: less than or equal +categories: [ "Data Types" ] +subCategories: [ "StringObject Operator" ] +--- + + + + + += <= Less Than Or Equal + + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Tests if the String on the left is less than or equal to the String on the right. This operator evaluate Strings in alphabetical order, on the first character where the two differ. So, for example "a" < "b" and "1" < "2", but "999" > "1000" because 9 comes after 1. + +Caution: String comparison operators can be confusing when you're comparing numeric Strings, because the numbers are treated as Strings and not as numbers. If you need to compare numbers numerically, compare them as ints, floats, or longs, and not as Strings. + +[%hardbreaks] + + +[float] +=== Syntax +`myString1 <= myString2` + + +[float] +=== Parameters +`myString1`: variable of type String. + +`myString2`: variable of type String. + + +[float] +=== Returns +`true`: if myString1 is less than or equal to myString2. + +`false`: otherwise. + +-- + +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +[role="example"] +* #EXAMPLE# https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[String Tutorials^] +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Variables/Data Types/array.adoc b/Language/Variables/Data Types/array.adoc index 89e86c46a..d9b781b61 100644 --- a/Language/Variables/Data Types/array.adoc +++ b/Language/Variables/Data Types/array.adoc @@ -4,36 +4,36 @@ categories: [ "Variables" ] subCategories: [ "Data Types" ] --- - - - - = Arrays - // OVERVIEW SECTION STARTS [#overview] -- [float] === Description -An array is a collection of variables that are accessed with an index number. Arrays in the C programming language, on which Arduino is based, can be complicated, but using simple arrays is relatively straightforward. +An array is a collection of variables that are accessed with an index number. Arrays in the C++ programming language Arduino sketches are written in can be complicated, but using simple arrays is relatively straightforward. [float] === Creating (Declaring) an Array All of the methods below are valid ways to create (declare) an array. [source,arduino] ---- + // Declare an array of a given length without initializing the values: int myInts[6]; - int myPins[] = {2, 4, 8, 3, 6}; - int mySensVals[6] = {2, 4, -8, 3, 2}; + + // Declare an array without explicitly choosing a size (the compiler + // counts the elements and creates an array of the appropriate size): + int myPins[] = {2, 4, 8, 3, 6, 4}; + + // Declare an array of a given length and initialize its values: + int mySensVals[5] = {2, 4, -8, 3, 2}; + + // When declaring an array of type char, you'll need to make it longer + // by one element to hold the required the null termination character: char message[6] = "hello"; ---- -You can declare an array without initializing it as in myInts. -{empty} + -In myPins we declare an array without explicitly choosing a size. The compiler counts the elements and creates an array of the appropriate size. -{empty} + -Finally you can both initialize and size your array, as in mySensVals. Note that when declaring an array of type char, one more element than your initialization is required, to hold the required null character. + [%hardbreaks] [float] @@ -46,14 +46,14 @@ It also means that in an array with ten elements, index nine is the last element [source,arduino] ---- -int myArray[10]={9,3,2,4,3,2,7,8,9,11}; - // myArray[9] contains 11 - // myArray[10] is invalid and contains random information (other memory address) +int myArray[10]={9, 3, 2, 4, 3, 2, 7, 8, 9, 11}; +// myArray[9] contains 11 +// myArray[10] is invalid and contains random information (other memory address) ---- For this reason you should be careful in accessing arrays. Accessing past the end of an array (using an index number greater than your declared array size - 1) is reading from memory that is in use for other purposes. Reading from these locations is probably not going to do much except yield invalid data. Writing to random memory locations is definitely a bad idea and can often lead to unhappy results such as crashes or program malfunction. This can also be a difficult bug to track down. [%hardbreaks] -Unlike BASIC or JAVA, the C compiler does no checking to see if array access is within legal bounds of the array size that you have declared. +Unlike BASIC or JAVA, the C++ compiler does no checking to see if array access is within legal bounds of the array size that you have declared. [%hardbreaks] [float] @@ -72,8 +72,7 @@ Arrays are often manipulated inside for loops, where the loop counter is used as [source,arduino] ---- -int i; -for (i = 0; i < 5; i = i + 1) { +for (byte i = 0; i < 5; i = i + 1) { Serial.println(myPins[i]); } ---- @@ -89,7 +88,7 @@ for (i = 0; i < 5; i = i + 1) { [float] === Example Code -For a complete program that demonstrates the use of arrays, see the (http://www.arduino.cc/en/Tutorial/KnightRider[Knight Rider example]) from the (http://www.arduino.cc/en/Main/LearnArduino[Tutorials]). +For a complete program that demonstrates the use of arrays, see the (https://docs.arduino.cc/built-in-examples/control-structures/Arrays[How to Use Arrays example]) from the (https://docs.arduino.cc/built-in-examples[Built-in Examples]). -- // HOW TO USE SECTION ENDS diff --git a/Language/Variables/Data Types/bool.adoc b/Language/Variables/Data Types/bool.adoc index 9486c10bf..b6e0cb199 100644 --- a/Language/Variables/Data Types/bool.adoc +++ b/Language/Variables/Data Types/bool.adoc @@ -4,24 +4,30 @@ categories: [ "Variables" ] subCategories: [ "Data Types" ] --- - - - - = bool - // OVERVIEW SECTION STARTS [#overview] -- [float] === Description -A `bool` holds one of two values, `true` or `false`. (Each `bool` variable occupies one byte of memory.) +A `bool` holds one of two values, `link:../../constants/truefalse[true]` or `link:../../constants/truefalse[false]`. (Each `bool` variable occupies one byte of memory.) [%hardbreaks] + +[float] +=== Syntax +`bool var = val;` + + +[float] +=== Parameters +`var`: variable name. + +`val`: the value to assign to that variable. + -- // OVERVIEW SECTION ENDS @@ -39,25 +45,23 @@ This code shows how to use the `bool` datatype. [source,arduino] ---- -int LEDpin = 5; // LED on pin 5 -int switchPin = 13; // momentary switch on 13, other side connected to ground +int LEDpin = 5; // LED on pin 5 +int switchPin = 13; // momentary switch on 13, other side connected to ground bool running = false; -void setup() -{ +void setup() { pinMode(LEDpin, OUTPUT); pinMode(switchPin, INPUT); - digitalWrite(switchPin, HIGH); // turn on pullup resistor + digitalWrite(switchPin, HIGH); // turn on pullup resistor } -void loop() -{ - if (digitalRead(switchPin) == LOW) - { // switch is pressed - pullup keeps pin high normally - delay(100); // delay to debounce switch - running = !running; // toggle running variable - digitalWrite(LEDpin, running); // indicate via LED +void loop() { + if (digitalRead(switchPin) == LOW) { + // switch is pressed - pullup keeps pin high normally + delay(100); // delay to debounce switch + running = !running; // toggle running variable + digitalWrite(LEDpin, running); // indicate via LED } } ---- @@ -73,8 +77,6 @@ void loop() [float] === See also -[role="language"] -* #LANGUAGE# link:../../../variables/constants/constants[constants] -- // SEE ALSO SECTION ENDS diff --git a/Language/Variables/Data Types/boolean.adoc b/Language/Variables/Data Types/boolean.adoc index e25ad8086..9815916e7 100644 --- a/Language/Variables/Data Types/boolean.adoc +++ b/Language/Variables/Data Types/boolean.adoc @@ -4,20 +4,15 @@ categories: [ "Variables" ] subCategories: [ "Data Types" ] --- - - - - = boolean - // OVERVIEW SECTION STARTS [#overview] -- [float] === Description -`boolean` is a non-standard type alias for link:../../../variables/data-types/bool/[bool] defined by Arduino. It's recommended to instead use the standard type `bool`, which is identical. +`boolean` is a non-standard type alias for `link:../../../variables/data-types/bool[bool]` defined by Arduino. It's recommended to instead use the standard type link:../../../variables/data-types/bool[`bool`], which is identical. [%hardbreaks] @@ -36,7 +31,6 @@ subCategories: [ "Data Types" ] === See also [role="language"] -* #LANGUAGE# link:../../../variables/data-types/bool/[bool] -- // SEE ALSO SECTION ENDS diff --git a/Language/Variables/Data Types/byte.adoc b/Language/Variables/Data Types/byte.adoc index d3cf357ce..4dca83539 100644 --- a/Language/Variables/Data Types/byte.adoc +++ b/Language/Variables/Data Types/byte.adoc @@ -4,13 +4,8 @@ categories: [ "Variables" ] subCategories: [ "Data Types" ] --- - - - - = byte - // OVERVIEW SECTION STARTS [#overview] -- @@ -20,25 +15,26 @@ subCategories: [ "Data Types" ] A byte stores an 8-bit unsigned number, from 0 to 255. [%hardbreaks] --- -// OVERVIEW SECTION ENDS +[float] +=== Syntax +`byte var = val;` +[float] +=== Parameters +`var`: variable name. + +`val`: the value to assign to that variable. -// HOW TO USE SECTION STARTS -[#howtouse] -- +// OVERVIEW SECTION ENDS -[float] -=== Example Code -// Describe what the example code is all about and add relevant code ►►►►► THIS SECTION IS MANDATORY ◄◄◄◄◄ -[source,arduino] ----- ----- +// HOW TO USE SECTION STARTS +[#howtouse] +-- -- // HOW TO USE SECTION ENDS @@ -54,4 +50,4 @@ A byte stores an 8-bit unsigned number, from 0 to 255. * #LANGUAGE# link:../../conversion/bytecast[byte()] -- -// SEE ALSO SECTION ENDS \ No newline at end of file +// SEE ALSO SECTION ENDS diff --git a/Language/Variables/Data Types/char.adoc b/Language/Variables/Data Types/char.adoc index 04616ad92..18a36b400 100644 --- a/Language/Variables/Data Types/char.adoc +++ b/Language/Variables/Data Types/char.adoc @@ -4,26 +4,32 @@ categories: [ "Variables" ] subCategories: [ "Data Types" ] --- - - - - = char - // OVERVIEW SECTION STARTS [#overview] -- [float] === Description -A data type that takes up 1 byte of memory that stores a character value. Character literals are written in single quotes, like this: 'A' (for multiple characters - strings - use double quotes: "ABC"). +A data type used to store a character value. Character literals are written in single quotes, like this: 'A' (for multiple characters - strings - use double quotes: "ABC"). -Characters are stored as numbers however. You can see the specific encoding in the link:https://www.arduino.cc/en/Reference/ASCIIchart[ASCII chart]. This means that it is possible to do arithmetic on characters, in which the ASCII value of the character is used (e.g. 'A' + 1 has the value 66, since the ASCII value of the capital letter A is 65). See link:../../../functions/communication/serial/println[`Serial.println`] reference for more on how characters are translated to numbers. +Characters are stored as numbers however. You can see the specific encoding in the link:https://www.arduino.cc/en/Reference/ASCIIchart[ASCII chart]. This means that it is possible to do arithmetic on characters, in which the ASCII value of the character is used (e.g. 'A' + 1 has the value 66, since the ASCII value of the capital letter A is 65). See `link:../../../functions/communication/serial/println[Serial.println]` reference for more on how characters are translated to numbers. -The char datatype is a signed type, meaning that it encodes numbers from -128 to 127. For an unsigned, one-byte (8 bit) data type, use the _byte_ data type. +The size of the `char` datatype is at least 8 bits. It's recommended to only use `char` for storing characters. For an unsigned, one-byte (8 bit) data type, use the `link:../byte[byte]` data type. [%hardbreaks] + +[float] +=== Syntax +`char var = val;` + + +[float] +=== Parameters +`var`: variable name. + +`val`: the value to assign to that variable. + -- // OVERVIEW SECTION ENDS @@ -40,8 +46,8 @@ The char datatype is a signed type, meaning that it encodes numbers from -128 to [source,arduino] ---- - char myChar = 'A'; - char myChar = 65; // both are equivalent +char myChar = 'A'; +char myChar = 65; // both are equivalent ---- @@ -60,4 +66,4 @@ The char datatype is a signed type, meaning that it encodes numbers from -128 to * #LANGUAGE# link:../../../functions/communication/serial/println[Serial.println] -- -// SEE ALSO SECTION ENDS \ No newline at end of file +// SEE ALSO SECTION ENDS diff --git a/Language/Variables/Data Types/double.adoc b/Language/Variables/Data Types/double.adoc index 25be32baa..30aa83d8a 100644 --- a/Language/Variables/Data Types/double.adoc +++ b/Language/Variables/Data Types/double.adoc @@ -4,13 +4,8 @@ categories: [ "Variables" ] subCategories: [ "Data Types" ] --- - - - - = double - // OVERVIEW SECTION STARTS [#overview] -- @@ -22,6 +17,17 @@ Double precision floating point number. On the Uno and other ATMEGA based boards On the Arduino Due, doubles have 8-byte (64 bit) precision. [%hardbreaks] + +[float] +=== Syntax +`double var = val;` + + +[float] +=== Parameters +`var`: variable name. + +`val`: the value to assign to that variable. + -- // OVERVIEW SECTION ENDS @@ -52,4 +58,4 @@ Users who borrow code from other sources that includes double variables may wish === See also -- -// SEE ALSO SECTION ENDS \ No newline at end of file +// SEE ALSO SECTION ENDS diff --git a/Language/Variables/Data Types/float.adoc b/Language/Variables/Data Types/float.adoc index bbb91a30f..fd89b97a5 100644 --- a/Language/Variables/Data Types/float.adoc +++ b/Language/Variables/Data Types/float.adoc @@ -19,22 +19,17 @@ subCategories: [ "Data Types" ] === Description Datatype for floating-point numbers, a number that has a decimal point. Floating-point numbers are often used to approximate analog and continuous values because they have greater resolution than integers. Floating-point numbers can be as large as 3.4028235E+38 and as low as -3.4028235E+38. They are stored as 32 bits (4 bytes) of information. -Floats have only 6-7 decimal digits of precision. That means the total number of digits, not the number to the right of the decimal point. Unlike other platforms, where you can get more precision by using a double (e.g. up to 15 digits), on the Arduino, double is the same size as float. -Floating point numbers are not exact, and may yield strange results when compared. For example 6.0 / 3.0 may not equal 2.0. You should instead check that the absolute value of the difference between the numbers is less than some small number. - -Floating point math is also much slower than integer math in performing calculations, so should be avoided if, for example, a loop has to run at top speed for a critical timing function. Programmers often go to some lengths to convert floating point calculations to integer math to increase speed. - -If doing math with floats, you need to add a decimal point, otherwise it will be treated as an int. See the link:../../constants/floatingpointconstants[Floating point] constants page for details. [%hardbreaks] [float] === Syntax -`float var=val;` +`float var = val;` -`var` - your float variable name -`val` - the value you assign to that variable -[%hardbreaks] +[float] +=== Parameters +`var`: variable name. + +`val`: the value you assign to that variable. -- // OVERVIEW SECTION ENDS @@ -53,31 +48,64 @@ If doing math with floats, you need to add a decimal point, otherwise it will be [source,arduino] ---- - float myfloat; - float sensorCalbrate = 1.117; +float myfloat; +float sensorCalbrate = 1.117; - int x; - int y; - float z; +int x; +int y; +float z; - x = 1; - y = x / 2; // y now contains 0, ints can't hold fractions - z = (float)x / 2.0; // z now contains .5 (you have to use 2.0, not 2) +x = 1; +y = x / 2; // y now contains 0, ints can't hold fractions +z = (float)x / 2.0; // z now contains .5 (you have to use 2.0, not 2) ---- +[%hardbreaks] +[float] +=== Notes and Warnings +If doing math with floats, you need to add a decimal point, otherwise it will be treated as an int. See the link:../../constants/floatingpointconstants[Floating point] constants page for details. + +The float data type has only 6-7 decimal digits of precision. That means the total number of digits, not the number to the right of the decimal point. Unlike other platforms, where you can get more precision by using a double (e.g. up to 15 digits), on the Arduino, double is the same size as float. + +Floating point numbers are not exact, and may yield strange results when compared. For example 9.0 / 0.3 may not quite equal 30.0. You should instead check that the absolute value of the difference between the numbers is less than some small number. + +Conversion from floating point to integer math results in truncation: +[source,arduino] +---- +float x = 2.9; // A float type variable +int y = x; // 2 +---- + +If, instead, you want to round off during the conversion process, you need to add `0.5`: +[source,arduino] +---- +float x = 2.9; +int y = x + 0.5; // 3 +---- +or use the `round()` function: +[source,arduino] +---- +float x = 2.9; +int y = round(x); // 3 +---- + +Floating point math is also much slower than integer math in performing calculations, so should be avoided if, for example, a loop has to run at top speed for a critical timing function. Programmers often go to some lengths to convert floating point calculations to integer math to increase speed. -- // HOW TO USE SECTION ENDS + + // SEE ALSO SECTION STARTS [#see_also] -- +[%hardbreaks] [float] === See also [role="language"] -- -// SEE ALSO SECTION ENDS \ No newline at end of file +// SEE ALSO SECTION ENDS diff --git a/Language/Variables/Data Types/int.adoc b/Language/Variables/Data Types/int.adoc index 4ae27dcaa..f9e2b9310 100644 --- a/Language/Variables/Data Types/int.adoc +++ b/Language/Variables/Data Types/int.adoc @@ -4,10 +4,6 @@ categories: [ "Variables" ] subCategories: [ "Data Types" ] --- - - - - = int @@ -24,7 +20,7 @@ On the Arduino Due and SAMD based boards (like MKR1000 and Zero), an int stores int's store negative numbers with a technique called (http://en.wikipedia.org/wiki/2%27s_complement[2's complement math]). The highest bit, sometimes referred to as the "sign" bit, flags the number as a negative number. The rest of the bits are inverted and 1 is added. -The Arduino takes care of dealing with negative numbers for you, so that arithmetic operations work transparently in the expected manner. There can be an unexpected complication in dealing with the link:../../../structure/bitwise-operators/bitshiftright/[bitshift right operator] (>>) however. +The Arduino takes care of dealing with negative numbers for you, so that arithmetic operations work transparently in the expected manner. There can be an unexpected complication in dealing with the link:../../../structure/bitwise-operators/bitshiftright[bitshift right operator] (`>>`) however. [%hardbreaks] @@ -32,8 +28,11 @@ The Arduino takes care of dealing with negative numbers for you, so that arithme === Syntax `int var = val;` -`var` - your int variable name + -`val` - the value you assign to that variable + +[float] +=== Parameters +`var`: variable name. + +`val`: the value you assign to that variable. -- // OVERVIEW SECTION ENDS @@ -48,17 +47,27 @@ The Arduino takes care of dealing with negative numbers for you, so that arithme [float] === Example Code // Describe what the example code is all about and add relevant code ►►►►► THIS SECTION IS MANDATORY ◄◄◄◄◄ - +This code creates an integer called 'countUp', which is initially set as the number 0 (zero). The variable goes up by 1 (one) each loop, being displayed on the serial monitor. [source,arduino] ---- - int ledPin = 13; +int countUp = 0; //creates a variable integer called 'countUp' + +void setup() { + Serial.begin(9600); // use the serial port to print the number +} + +void loop() { + countUp++; //Adds 1 to the countUp int on every loop + Serial.println(countUp); // prints out the current state of countUp + delay(1000); +} ---- [%hardbreaks] [float] === Notes and Warnings -When signed variables are made to exceed their maximum or minimum capacity they _overflow_. The result of an overflow is unpredictable so this should be avoided. A typical symptom of an overflow is the variable "rolling over" from its maximum capacity to its minimum or vice versa, but this is not always the case. If you want this behavior, use link:../unsignedint/[unsigned int]. +When signed variables are made to exceed their maximum or minimum capacity they _overflow_. The result of an overflow is unpredictable so this should be avoided. A typical symptom of an overflow is the variable "rolling over" from its maximum capacity to its minimum or vice versa, but this is not always the case. If you want this behavior, use `link:../unsignedint[unsigned int]`. -- diff --git a/Language/Variables/Data Types/long.adoc b/Language/Variables/Data Types/long.adoc index f85fb1592..07462b014 100644 --- a/Language/Variables/Data Types/long.adoc +++ b/Language/Variables/Data Types/long.adoc @@ -19,17 +19,19 @@ subCategories: [ "Data Types" ] === Description Long variables are extended size variables for number storage, and store 32 bits (4 bytes), from -2,147,483,648 to 2,147,483,647. -If doing math with integers, at least one of the numbers must be followed by an L, forcing it to be a long. See the link:../../constants/integerconstants[Integer Constants] page for details. +If doing math with integers at least one of the values must be of type long, either an integer constant followed by an L or a variable of type long, forcing it to be a long. See the link:../../constants/integerconstants[Integer Constants] page for details. [%hardbreaks] [float] === Syntax - `long var = val;` -`var` - the long variable name -`val` - the value assigned to the variable -[%hardbreaks] + +[float] +=== Parameters +`var`: variable name. + +`val`: the value assigned to the variable. + -- // OVERVIEW SECTION ENDS @@ -47,7 +49,7 @@ If doing math with integers, at least one of the numbers must be followed by an [source,arduino] ---- - long speedOfLight = 186000L; // see the Integer Constants page for explanation of the 'L' +long speedOfLight_km_s = 300000L; // see the Integer Constants page for explanation of the 'L' ---- -- diff --git a/Language/Variables/Data Types/short.adoc b/Language/Variables/Data Types/short.adoc index fb18aacc2..3f81fdab0 100644 --- a/Language/Variables/Data Types/short.adoc +++ b/Language/Variables/Data Types/short.adoc @@ -26,8 +26,12 @@ On all Arduinos (ATMega and ARM based) a short stores a 16-bit (2-byte) value. T === Syntax `short var = val;` -`var` - your short variable name -`val` - the value you assign to that variable + +[float] +=== Parameters +`var`: variable name. + +`val`: the value you assign to that variable. + -- // OVERVIEW SECTION ENDS @@ -45,7 +49,7 @@ On all Arduinos (ATMega and ARM based) a short stores a 16-bit (2-byte) value. T [source,arduino] ---- - short ledPin = 13 +short ledPin = 13 ---- -- @@ -63,4 +67,4 @@ On all Arduinos (ATMega and ARM based) a short stores a 16-bit (2-byte) value. T * #LANGUAGE# link:../../constants/integerconstants[Integer Constants] -- -// SEE ALSO SECTION ENDS \ No newline at end of file +// SEE ALSO SECTION ENDS diff --git a/Language/Variables/Data Types/size_t.adoc b/Language/Variables/Data Types/size_t.adoc new file mode 100644 index 000000000..daadd550e --- /dev/null +++ b/Language/Variables/Data Types/size_t.adoc @@ -0,0 +1,41 @@ +--- +title: size_t +categories: [ "Variables" ] +subCategories: [ "Data Types" ] +--- + += size_t + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +`size_t` is a data type capable of representing the size of any object in bytes. Examples of the use of `size_t` are the return type of `link:../../utilities/sizeof[sizeof()]` and `link:../../../functions/communication/serial/print[Serial.print()]`. +[%hardbreaks] + + +[float] +=== Syntax +`size_t var = val;` + + +[float] +=== Parameters +`var`: variable name. + +`val`: the value to assign to that variable. + +-- +// OVERVIEW SECTION ENDS + +// SEE ALSO SECTION STARTS +[#see_also] +-- + +[float] +=== See also + + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Variables/Data Types/string.adoc b/Language/Variables/Data Types/string.adoc new file mode 100644 index 000000000..29d4f97ad --- /dev/null +++ b/Language/Variables/Data Types/string.adoc @@ -0,0 +1,115 @@ +--- +title: string +categories: [ "Variables" ] +subCategories: [ "Data Types" ] +--- + += string + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Text strings can be represented in two ways. you can use the String data type, or you can make a string out of an array of type char and null-terminate it. This page described the latter method. For more details on the String object, which gives you more functionality at the cost of more memory, see the link:../stringobject[String object] page. +[%hardbreaks] + +[float] +=== Syntax +All of the following are valid declarations for strings. + +`char Str1[15];` + +`char Str2[8] = {'a', 'r', 'd', 'u', 'i', 'n', 'o'};` + +`char Str3[8] = {'a', 'r', 'd', 'u', 'i', 'n', 'o', '\0'};` + +`char Str4[] = "arduino";` + +`char Str5[8] = "arduino";` + +`char Str6[15] = "arduino";` + +*Possibilities for declaring strings* + +* Declare an array of chars without initializing it as in Str1 +* Declare an array of chars (with one extra char) and the compiler will add the required null character, as in Str2 +* Explicitly add the null character, Str3 +* Initialize with a string constant in quotation marks; the compiler will size the array to fit the string constant and a terminating null character, Str4 +* Initialize the array with an explicit size and string constant, Str5 +* Initialize the array, leaving extra space for a larger string, Str6 + +*Null termination* + +Generally, strings are terminated with a null character (ASCII code 0). This allows functions (like `link:../../../functions/communication/serial/print[Serial.print()]`) to tell where the end of a string is. Otherwise, they would continue reading subsequent bytes of memory that aren't actually part of the string. + +This means that your string needs to have space for one more character than the text you want it to contain. That is why Str2 and Str5 need to be eight characters, even though "arduino" is only seven - the last position is automatically filled with a null character. Str4 will be automatically sized to eight characters, one for the extra null. In Str3, we've explicitly included the null character (written '\0') ourselves. + +Note that it's possible to have a string without a final null character (e.g. if you had specified the length of Str2 as seven instead of eight). This will break most functions that use strings, so you shouldn't do it intentionally. If you notice something behaving strangely (operating on characters not in the string), however, this could be the problem. + +*Single quotes or double quotes?* + +Strings are always defined inside double quotes ("Abc") and characters are always defined inside single quotes('A'). + +*Wrapping long strings* + +You can wrap long strings like this: + +[source,arduino] +---- +char myString[] = "This is the first line" +" this is the second line" +" etcetera"; +---- + +*Arrays of strings* + +It is often convenient, when working with large amounts of text, such as a project with an LCD display, to setup an array of strings. Because strings themselves are arrays, this is actually an example of a two-dimensional array. + +In the code below, the asterisk after the datatype `link:../char[char]` "`char*`" indicates that this is an array of "`pointers`". All array names are actually pointers, so this is required to make an array of arrays. Pointers are one of the more esoteric parts of C++ for beginners to understand, but it isn't necessary to understand pointers in detail to use them effectively here. + +-- +// OVERVIEW SECTION ENDS + + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code +// Describe what the example code is all about and add relevant code ►►►►► THIS SECTION IS MANDATORY ◄◄◄◄◄ + + +[source,arduino] +---- +char *myStrings[] = {"This is string 1", "This is string 2", "This is string 3", + "This is string 4", "This is string 5", "This is string 6" + }; + +void setup() { + Serial.begin(9600); +} + +void loop() { + for (int i = 0; i < 6; i++) { + Serial.println(myStrings[i]); + delay(500); + } +} +---- + + +-- +// HOW TO USE SECTION ENDS + +// SEE ALSO SECTION STARTS +[#see_also] +-- + +[float] +=== See also + +[role="language"] +* #LANGUAGE# link:../../utilities/progmem[PROGMEM] + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Variables/Data Types/stringObject.adoc b/Language/Variables/Data Types/stringObject.adoc index cc9261097..b3b04a498 100644 --- a/Language/Variables/Data Types/stringObject.adoc +++ b/Language/Variables/Data Types/stringObject.adoc @@ -1,160 +1,155 @@ ---- -title: "String()" -categories: [ "Variables" ] -subCategories: [ "Data Types" ] ---- - - - - - -= String() - - -// OVERVIEW SECTION STARTS -[#overview] --- - -[float] -=== Description -Constructs an instance of the String class. There are multiple versions that construct Strings from different data types (i.e. format them as sequences of characters), including: - -* a constant string of characters, in double quotes (i.e. a char array) -* a single constant character, in single quotes -* another instance of the String object -* a constant integer or long integer -* a constant integer or long integer, using a specified base -* an integer or long integer variable -* an integer or long integer variable, using a specified base -* a float or double, using a specified decimal places - -Constructing a String from a number results in a string that contains the ASCII representation of that number. The default is base ten, so -[source,arduino] ----- -String thisString = String(13); ----- -gives you the String "13". You can use other bases, however. For example, - - -[source,arduino] ----- -String thisString = String(13, HEX); ----- - -gives you the String "D", which is the hexadecimal representation of the decimal value 13. Or if you prefer binary, - -[source,arduino] ----- -String thisString = String(13, BIN); ----- - -gives you the String "1101", which is the binary representation of 13. -[%hardbreaks] - - -[float] -=== Syntax -[source,arduino] ----- -String(val) -String(val, base) -String(val, decimalPlaces) ----- - -[float] -=== Parameters -`val`: a variable to format as a String - *Allowed data types:* string, char, byte, int, long, unsigned int, unsigned long, float, double + -`base` (optional): the base in which to format an integral value -`decimalPlaces` (*only if val is float or double*): the desired decimal places - -[float] -=== Returns -an instance of the String class. - --- -// OVERVIEW SECTION ENDS - - - -// HOW TO USE SECTION STARTS -[#howtouse] --- - -[float] -=== Example Code -All of the following are valid declarations for Strings. -[source,arduino] ----- -String stringOne = "Hello String"; // using a constant String -String stringOne = String('a'); // converting a constant char into a String -String stringTwo = String("This is a string"); // converting a constant string into a String object -String stringOne = String(stringTwo + " with more"); // concatenating two strings -String stringOne = String(13); // using a constant integer -String stringOne = String(analogRead(0), DEC); // using an int and a base -String stringOne = String(45, HEX); // using an int and a base (hexadecimal) -String stringOne = String(255, BIN); // using an int and a base (binary) -String stringOne = String(millis(), DEC); // using a long and a base -String stringOne = String(5.698, 3); // using a float and the decimal places ----- - --- -// HOW TO USE SECTION ENDS - - -[float] -=== Functions - -[role="language"] -* #LANGUAGE# link:../string/functions/charat[charAt()] -* #LANGUAGE# link:../string/functions/compareto[compareTo()] -* #LANGUAGE# link:../string/functions/concat[concat()] -* #LANGUAGE# link:../string/functions/c_str[c_str()] -* #LANGUAGE# link:../string/functions/endswith[endsWith()] -* #LANGUAGE# link:../string/functions/equals[equals()] -* #LANGUAGE# link:../string/functions/equalsignorecase[equalsIgnoreCase()] -* #LANGUAGE# link:../string/functions/getbytes[getBytes()] -* #LANGUAGE# link:../string/functions/indexof[indexOf()] -* #LANGUAGE# link:../string/functions/lastindexof[lastIndexOf()] -* #LANGUAGE# link:../string/functions/length[length()] -* #LANGUAGE# link:../string/functions/remove[remove()] -* #LANGUAGE# link:../string/functions/replace[replace()] -* #LANGUAGE# link:../string/functions/reserve[reserve()] -* #LANGUAGE# link:../string/functions/setcharat[setCharAt()] -* #LANGUAGE# link:../string/functions/startswith[startsWith()] -* #LANGUAGE# link:../string/functions/substring[substring()] -* #LANGUAGE# link:../string/functions/tochararray[toCharArray()] -* #LANGUAGE# link:../string/functions/toint[toInt()] -* #LANGUAGE# link:../string/functions/tofloat[toFloat()] -* #LANGUAGE# link:../string/functions/tolowercase[toLowerCase()] -* #LANGUAGE# link:../string/functions/touppercase[toUpperCase()] -* #LANGUAGE# link:../string/functions/trim[trim()] - -[float] -=== Operators - -[role="language"] -* #LANGUAGE# link:../string/operators/elementaccess[[\] (element access)] -* #LANGUAGE# link:../string/operators/concatenation[+ (concatenation)] -* #LANGUAGE# link:../string/operators/append[+= (append)] -* #LANGUAGE# link:../string/operators/comparison[== (comparison)] -* #LANGUAGE# link:../string/operators/greaterthan[> (greater than)] -* #LANGUAGE# link:../string/operators/greaterthanorequalto[>= (greater than or equal to)] -* #LANGUAGE# link:../string/operators/lessthan[< (less than)] -* #LANGUAGE# link:../string/operators/lessthanorequalto[\<= (less than or equal to)] -* #LANGUAGE# link:../string/operators/differentfrom[!= (different from)] - -[role="example"] -* #EXAMPLE# link: https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[Built-in String Tutorials] - - -// SEE ALSO SECTION STARTS -[#see_also] --- - -[float] -=== See also - -[role="language"] - --- -// SEE ALSO SECTION ENDS +--- +title: "String()" +categories: [ "Variables" ] +subCategories: [ "Data Types" ] +--- + += String() + +// OVERVIEW SECTION STARTS +[#overview] +-- + +[float] +=== Description +Constructs an instance of the String class. There are multiple versions that construct Strings from different data types (i.e. format them as sequences of characters), including: + +* a constant string of characters, in double quotes (i.e. a char array) +* a single constant character, in single quotes +* another instance of the String object +* a constant integer or long integer +* a constant integer or long integer, using a specified base +* an integer or long integer variable +* an integer or long integer variable, using a specified base +* a float or double, using a specified decimal places + +Constructing a String from a number results in a string that contains the ASCII representation of that number. The default is base ten, so +[source,arduino] +---- +String thisString = String(13); +---- +gives you the String "13". You can use other bases, however. For example, + + +[source,arduino] +---- +String thisString = String(13, HEX); +---- + +gives you the String "d", which is the hexadecimal representation of the decimal value 13. Or if you prefer binary, + +[source,arduino] +---- +String thisString = String(13, BIN); +---- + +gives you the String "1101", which is the binary representation of 13. +[%hardbreaks] + + +[float] +=== Syntax +`String(val)` + +`String(val, base)` + +`String(val, decimalPlaces)` + + +[float] +=== Parameters +`val`: a variable to format as a String. Allowed data types: string, char, byte, int, long, unsigned int, unsigned long, float, double. + +`base`: (optional) the base in which to format an integral value. + +`decimalPlaces`: *only if val is float or double*. The desired decimal places. + + +[float] +=== Returns +An instance of the String class. + +-- +// OVERVIEW SECTION ENDS + + + +// HOW TO USE SECTION STARTS +[#howtouse] +-- + +[float] +=== Example Code +All of the following are valid declarations for Strings. +[source,arduino] +---- +String stringOne = "Hello String"; // using a constant String +String stringOne = String('a'); // converting a constant char into a String +String stringTwo = String("This is a string"); // converting a constant string into a String object +String stringOne = String(stringTwo + " with more"); // concatenating two strings +String stringOne = String(13); // using a constant integer +String stringOne = String(analogRead(0), DEC); // using an int and a base +String stringOne = String(45, HEX); // using an int and a base (hexadecimal) +String stringOne = String(255, BIN); // using an int and a base (binary) +String stringOne = String(millis(), DEC); // using a long and a base +String stringOne = String(5.698, 3); // using a float and the decimal places +---- + +-- +// HOW TO USE SECTION ENDS + + +[float] +=== Functions + +[role="language"] +* #LANGUAGE# link:../string/functions/charat[charAt()] +* #LANGUAGE# link:../string/functions/compareto[compareTo()] +* #LANGUAGE# link:../string/functions/concat[concat()] +* #LANGUAGE# link:../string/functions/c_str[c_str()] +* #LANGUAGE# link:../string/functions/endswith[endsWith()] +* #LANGUAGE# link:../string/functions/equals[equals()] +* #LANGUAGE# link:../string/functions/equalsignorecase[equalsIgnoreCase()] +* #LANGUAGE# link:../string/functions/getbytes[getBytes()] +* #LANGUAGE# link:../string/functions/indexof[indexOf()] +* #LANGUAGE# link:../string/functions/lastindexof[lastIndexOf()] +* #LANGUAGE# link:../string/functions/length[length()] +* #LANGUAGE# link:../string/functions/remove[remove()] +* #LANGUAGE# link:../string/functions/replace[replace()] +* #LANGUAGE# link:../string/functions/reserve[reserve()] +* #LANGUAGE# link:../string/functions/setcharat[setCharAt()] +* #LANGUAGE# link:../string/functions/startswith[startsWith()] +* #LANGUAGE# link:../string/functions/substring[substring()] +* #LANGUAGE# link:../string/functions/tochararray[toCharArray()] +* #LANGUAGE# link:../string/functions/todouble[toDouble()] +* #LANGUAGE# link:../string/functions/toint[toInt()] +* #LANGUAGE# link:../string/functions/tofloat[toFloat()] +* #LANGUAGE# link:../string/functions/tolowercase[toLowerCase()] +* #LANGUAGE# link:../string/functions/touppercase[toUpperCase()] +* #LANGUAGE# link:../string/functions/trim[trim()] + +[float] +=== Operators + +[role="language"] +* #LANGUAGE# link:../string/operators/elementaccess[[\] (element access)] +* #LANGUAGE# link:../string/operators/concatenation[+ (concatenation)] +* #LANGUAGE# link:../string/operators/append[+= (append)] +* #LANGUAGE# link:../string/operators/comparison[== (comparison)] +* #LANGUAGE# link:../string/operators/greaterthan[> (greater than)] +* #LANGUAGE# link:../string/operators/greaterthanorequalto[>= (greater than or equal to)] +* #LANGUAGE# link:../string/operators/lessthan[< (less than)] +* #LANGUAGE# link:../string/operators/lessthanorequalto[\<= (less than or equal to)] +* #LANGUAGE# link:../string/operators/differentfrom[!= (different from)] + +[role="example"] +* #EXAMPLE# https://www.arduino.cc/en/Tutorial/BuiltInExamples#strings[String Tutorials^] + + +// SEE ALSO SECTION STARTS +[#see_also] +-- + +[float] +=== See also + +[role="language"] + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Variables/Data Types/unsignedChar.adoc b/Language/Variables/Data Types/unsignedChar.adoc index 1f2ccbc96..fe554cd43 100644 --- a/Language/Variables/Data Types/unsignedChar.adoc +++ b/Language/Variables/Data Types/unsignedChar.adoc @@ -4,26 +4,32 @@ categories: [ "Variables" ] subCategories: [ "Data Types" ] --- - - - - = unsigned char - // OVERVIEW SECTION STARTS [#overview] -- [float] === Description -An unsigned data type that occupies 1 byte of memory. Same as the link:../byte[byte] datatype. +An unsigned data type that occupies 1 byte of memory. Same as the `link:../byte[byte]` datatype. The unsigned char datatype encodes numbers from 0 to 255. -For consistency of Arduino programming style, the byte data type is to be preferred. +For consistency of Arduino programming style, the link:../byte[`byte`] data type is to be preferred. [%hardbreaks] + +[float] +=== Syntax +`unsigned char var = val;` + + +[float] +=== Parameters +`var`: variable name. + +`val`: the value to assign to that variable. + -- // OVERVIEW SECTION ENDS @@ -59,4 +65,4 @@ unsigned char myChar = 240; * #LANGUAGE# link:../../../functions/communication/serial/println[Serial.println] -- -// SEE ALSO SECTION ENDS \ No newline at end of file +// SEE ALSO SECTION ENDS diff --git a/Language/Variables/Data Types/unsignedInt.adoc b/Language/Variables/Data Types/unsignedInt.adoc index 4949a0b58..50328763d 100644 --- a/Language/Variables/Data Types/unsignedInt.adoc +++ b/Language/Variables/Data Types/unsignedInt.adoc @@ -4,13 +4,8 @@ categories: [ "Variables" ] subCategories: [ "Data Types" ] --- - - - - = unsigned int - // OVERVIEW SECTION STARTS [#overview] -- @@ -24,14 +19,21 @@ The Due stores a 4 byte (32-bit) value, ranging from 0 to 4,294,967,295 (2^32 - The difference between unsigned ints and (signed) ints, lies in the way the highest bit, sometimes referred to as the "sign" bit, is interpreted. In the Arduino int type (which is signed), if the high bit is a "1", the number is interpreted as a negative number, and the other 15 bits are interpreted with (http://en.wikipedia.org/wiki/2%27s_complement[2's complement math]). [%hardbreaks] --- -// OVERVIEW SECTION ENDS [float] === Syntax `unsigned int var = val;` -`var` - your unsigned int variable name -`val` - the value you assign to that variable + + +[float] +=== Parameters +`var`: variable name. + +`val`: the value you assign to that variable. + +-- +// OVERVIEW SECTION ENDS + + // HOW TO USE SECTION STARTS @@ -45,7 +47,7 @@ The difference between unsigned ints and (signed) ints, lies in the way the high [source,arduino] ---- - unsigned int ledPin = 13; +unsigned int ledPin = 13; ---- [%hardbreaks] @@ -56,9 +58,9 @@ When unsigned variables are made to exceed their maximum capacity they "roll ove [source,arduino] ---- unsigned int x; - x = 0; - x = x - 1; // x now contains 65535 - rolls over in neg direction - x = x + 1; // x now contains 0 - rolls over +x = 0; +x = x - 1; // x now contains 65535 - rolls over in neg direction +x = x + 1; // x now contains 0 - rolls over ---- Math with unsigned variables may produce unexpected results, even if your unsigned variable never rolls over. @@ -72,16 +74,16 @@ However with a calculation which requires an intermediate result, the scope of t [source,arduino] ---- -unsigned int x=5; -unsigned int y=10; +unsigned int x = 5; +unsigned int y = 10; int result; - result = x - y; // 5 - 10 = -5, as expected - result = (x - y)/2; // 5 - 10 in unsigned math is 65530! 65530/2 = 32765 - - // solution: use signed variables, or do the calculation step by step. - result = x - y; // 5 - 10 = -5, as expected - result = result / 2; // -5/2 = -2 (only integer math, decimal places are dropped) +result = x - y; // 5 - 10 = -5, as expected +result = (x - y) / 2; // 5 - 10 in unsigned math is 65530! 65530/2 = 32765 + +// solution: use signed variables, or do the calculation step by step. +result = x - y; // 5 - 10 = -5, as expected +result = result / 2; // -5/2 = -2 (only integer math, decimal places are dropped) ---- Why use unsigned variables at all? diff --git a/Language/Variables/Data Types/unsignedLong.adoc b/Language/Variables/Data Types/unsignedLong.adoc index 9cccdf9e1..efd69311c 100644 --- a/Language/Variables/Data Types/unsignedLong.adoc +++ b/Language/Variables/Data Types/unsignedLong.adoc @@ -4,13 +4,8 @@ categories: [ "Variables" ] subCategories: [ "Data Types" ] --- - - - - = unsigned long - // OVERVIEW SECTION STARTS [#overview] -- @@ -22,12 +17,13 @@ Unsigned long variables are extended size variables for number storage, and stor [float] === Syntax - `unsigned long var = val;` -`var` - your long variable name -`val` - the value you assign to that variable -[%hardbreaks] + +[float] +=== Parameters +`var`: variable name. + +`val`: the value you assign to that variable. -- // OVERVIEW SECTION ENDS @@ -48,13 +44,11 @@ Unsigned long variables are extended size variables for number storage, and stor ---- unsigned long time; -void setup() -{ +void setup() { Serial.begin(9600); } -void loop() -{ +void loop() { Serial.print("Time: "); time = millis(); //prints time since program started @@ -79,4 +73,4 @@ void loop() * #LANGUAGE# link:../../constants/integerconstants[Integer Constants] -- -// SEE ALSO SECTION ENDS \ No newline at end of file +// SEE ALSO SECTION ENDS diff --git a/Language/Variables/Data Types/void.adoc b/Language/Variables/Data Types/void.adoc index 6ab03f354..89deed9aa 100644 --- a/Language/Variables/Data Types/void.adoc +++ b/Language/Variables/Data Types/void.adoc @@ -4,13 +4,8 @@ categories: [ "Variables" ] subCategories: [ "Data Types" ] --- - - - - = void - // OVERVIEW SECTION STARTS [#overview] -- @@ -40,13 +35,11 @@ The code shows how to use `void`. // actions are performed in the functions "setup" and "loop" // but no information is reported to the larger program -void setup() -{ +void setup() { // ... } -void loop() -{ +void loop() { // ... } ---- @@ -67,4 +60,4 @@ void loop() * #LANGUAGE# link:../../constants/integerconstants[Integer Constants] -- -// SEE ALSO SECTION ENDS \ No newline at end of file +// SEE ALSO SECTION ENDS diff --git a/Language/Variables/Data Types/word.adoc b/Language/Variables/Data Types/word.adoc index d573c364c..40202e637 100644 --- a/Language/Variables/Data Types/word.adoc +++ b/Language/Variables/Data Types/word.adoc @@ -4,22 +4,28 @@ categories: [ "Variables" ] subCategories: [ "Data Types" ] --- - - - - = word - // OVERVIEW SECTION STARTS [#overview] -- [float] === Description -A word stores a 16-bit unsigned number, from 0 to 65535. Same as an unsigned int. +A word can store an unsigned number of at least 16 bits (from 0 to 65535). [%hardbreaks] + +[float] +=== Syntax +`word var = val;` + + +[float] +=== Parameters +`var`: variable name. + +`val`: the value to assign to that variable. + -- // OVERVIEW SECTION ENDS @@ -37,8 +43,19 @@ A word stores a 16-bit unsigned number, from 0 to 65535. Same as an unsigned int [source,arduino] ---- - word w = 10000; +word w = 10000; ---- -- -// HOW TO USE SECTION ENDS \ No newline at end of file +// HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Variables/Utilities/PROGMEM.adoc b/Language/Variables/Utilities/PROGMEM.adoc index 54ba8c1a2..0728741c6 100644 --- a/Language/Variables/Utilities/PROGMEM.adoc +++ b/Language/Variables/Utilities/PROGMEM.adoc @@ -17,35 +17,40 @@ subCategories: [ "Utilities" ] [float] === Description -Store data in flash (program) memory instead of SRAM. There's a description of the various http://www.arduino.cc/playground/Learning/Memory[types of memory] available on an Arduino board. -The `PROGMEM` keyword is a variable modifier, it should be used only with the datatypes defined in pgmspace.h. It tells the compiler "put this information into flash memory", instead of into SRAM, where it would normally go. +Keep constant data in flash (program) memory only, instead of copying it to SRAM when the program starts. There's a description of the various https://www.arduino.cc/en/Tutorial/Foundations/Memory[types of memory] available on an Arduino board. -PROGMEM is part of the link:http://www.nongnu.org/avr-libc/user-manual/group__avr__pgmspace.html[pgmspace.h] library. It is included automatically in modern versions of the IDE, however if you are using an IDE version below 1.0 (2011), you'll first need to include the library at the top your sketch, like this: +The `PROGMEM` keyword is a variable modifier, it should be used only with the datatypes defined in pgmspace.h. It tells the compiler "keep this information in flash memory only", instead of copying it to SRAM at start up, like it would normally do. -`#include ` -[%hardbreaks] +PROGMEM is part of the link:http://www.nongnu.org/avr-libc/user-manual/group\__avr__pgmspace.html[pgmspace.h] library. It is included automatically in the Arduino IDE. +While `PROGMEM` could be used on a single variable, it is really only worth the fuss if you have a larger block of data that needs to be stored, which is usually easiest in an array, (or another C++ data structure beyond our present discussion). -[float] -=== Syntax +Using `PROGMEM` is a two-step procedure. Once a variable has been defined with `PROGMEM`, it cannot be read like a regular SRAM-based variable: you have to read it using specific functions, also defined in link:http://www.nongnu.org/avr-libc/user-manual/group\__avr__pgmspace.html[pgmspace.h]. -const dataType variableName[] PROGMEM = {data0, data1, data3...}; +==== Important Note! -`dataType` - any variable type + -`variableName` - the name for your array of data +`PROGMEM` is useful _only_ when working with AVR boards (Uno Rev3, Leonardo etc.). Newer boards (Due, MKR WiFi 1010, GIGA R1 WiFi etc.) automatically use the program space when a variable is declared as a `const`. However, for retro compatibility, `PROGMEM` can still be used with newer boards. This implementation currently lives link:https://github.com/arduino/ArduinoCore-API/blob/master/api/deprecated-avr-comp/avr/pgmspace.h[here]. -Note that because PROGMEM is a variable modifier, there is no hard and fast rule about where it should go, so the Arduino compiler accepts all of the definitions below, which are also synonymous. However experiments have indicated that, in various versions of Arduino (having to do with GCC version), PROGMEM may work in one location and not in another. The "string table" example below has been tested to work with Arduino 13. Earlier versions of the IDE may work better if PROGMEM is included after the variable name. -`const dataType variableName[] PROGMEM = {}; // use this form` + -`const PROGMEM dataType variableName[] = {}; // or this one` + -`const dataType PROGMEM variableName[] = {}; // not this one` +[%hardbreaks] + + +[float] +=== Syntax +`const dataType variableName[] PROGMEM = {data0, data1, data3...};` +Note that because PROGMEM is a variable modifier, there is no hard and fast rule about where it should go, so the Arduino compiler accepts all of the definitions below, which are also synonymous. However, experiments have indicated that, in various versions of Arduino (having to do with GCC version), PROGMEM may work in one location and not in another. The "string table" example below has been tested to work with Arduino 13. Earlier versions of the IDE may work better if PROGMEM is included after the variable name. -While `PROGMEM` could be used on a single variable, it is really only worth the fuss if you have a larger block of data that needs to be stored, which is usually easiest in an array, (or another C data structure beyond our present discussion). +`const dataType variableName[] PROGMEM = {}; // use this form` + +`const PROGMEM dataType variableName[] = {}; // or this one` + +`const dataType PROGMEM variableName[] = {}; // not this one` -Using `PROGMEM` is also a two-step procedure. After getting the data into Flash memory, it requires special methods (functions), also defined in the link:http://www.nongnu.org/avr-libc/user-manual/group__avr__pgmspace.html[pgmspace.h] library, to read the data from program memory back into SRAM, so we can do something useful with it. +[float] +=== Parameters +`dataType`: Allowed data types: any variable type. + +`variableName`: the name for your array of data. -- // OVERVIEW SECTION ENDS @@ -65,13 +70,12 @@ The following code fragments illustrate how to read and write unsigned chars (by [source,arduino] ---- // save some unsigned ints -const PROGMEM uint16_t charSet[] = { 65000, 32796, 16843, 10, 11234}; +const PROGMEM uint16_t charSet[] = { 65000, 32796, 16843, 10, 11234}; // save some chars -const char signMessage[] PROGMEM = {"I AM PREDATOR, UNSEEN COMBATANT. CREATED BY THE UNITED STATES DEPART"}; +const char signMessage[] PROGMEM = {"I AM PREDATOR, UNSEEN COMBATANT. CREATED BY THE UNITED STATES DEPART"}; unsigned int displayInt; -int k; // counter variable char myChar; @@ -81,17 +85,16 @@ void setup() { // put your setup code here, to run once: // read back a 2-byte int - for (k = 0; k < 5; k++) - { + for (byte k = 0; k < 5; k++) { displayInt = pgm_read_word_near(charSet + k); Serial.println(displayInt); } Serial.println(); // read back a char - for (k = 0; k < strlen_P(signMessage); k++) - { - myChar = pgm_read_byte_near(signMessage + k); + int signMessageLength = strlen_P(signMessage); + for (byte k = 0; k < signMessageLength; k++) { + myChar = pgm_read_byte_near(signMessage + k); Serial.print(myChar); } @@ -100,34 +103,33 @@ void setup() { void loop() { // put your main code here, to run repeatedly: - } ---- *Arrays of strings* -It is often convenient when working with large amounts of text, such as a project with an LCD display, to setup an array of strings. Because strings themselves are arrays, this is in actually an example of a two-dimensional array. +It is often convenient when working with large amounts of text, such as a project with an LCD, to setup an array of strings. Because strings themselves are arrays, this is actually an example of a two-dimensional array. These tend to be large structures so putting them into program memory is often desirable. The code below illustrates the idea. [source,arduino] ---- /* - PROGMEM string demo - How to store a table of strings in program memory (flash), - and retrieve them. + PROGMEM string demo + How to store a table of strings in program memory (flash), + and retrieve them. - Information summarized from: - http://www.nongnu.org/avr-libc/user-manual/pgmspace.html + Information summarized from: + http://www.nongnu.org/avr-libc/user-manual/pgmspace.html - Setting up a table (array) of strings in program memory is slightly complicated, but - here is a good template to follow. + Setting up a table (array) of strings in program memory is slightly complicated, but + here is a good template to follow. - Setting up the strings is a two-step process. First define the strings. + Setting up the strings is a two-step process. First, define the strings. */ #include -const char string_0[] PROGMEM = "String 0"; // "String 0" etc are strings to store - change to suit. +const char string_0[] PROGMEM = "String 0"; // "String 0" etc are strings to store - change to suit. const char string_1[] PROGMEM = "String 1"; const char string_2[] PROGMEM = "String 2"; const char string_3[] PROGMEM = "String 3"; @@ -137,34 +139,30 @@ const char string_5[] PROGMEM = "String 5"; // Then set up a table to refer to your strings. -const char* const string_table[] PROGMEM = {string_0, string_1, string_2, string_3, string_4, string_5}; +const char *const string_table[] PROGMEM = {string_0, string_1, string_2, string_3, string_4, string_5}; -char buffer[30]; // make sure this is large enough for the largest string it must hold +char buffer[30]; // make sure this is large enough for the largest string it must hold -void setup() -{ +void setup() { Serial.begin(9600); - while(!Serial); // wait for serial port to connect. Needed for native USB + while (!Serial); // wait for serial port to connect. Needed for native USB Serial.println("OK"); } -void loop() -{ +void loop() { /* Using the string table in program memory requires the use of special functions to retrieve the data. The strcpy_P function copies a string from program space to a string in RAM ("buffer"). - Make sure your receiving string in RAM is large enough to hold whatever + Make sure your receiving string in RAM is large enough to hold whatever you are retrieving from program space. */ - for (int i = 0; i < 6; i++) - { - strcpy_P(buffer, (char*)pgm_read_word(&(string_table[i]))); // Necessary casts and dereferencing, just copy. + for (int i = 0; i < 6; i++) { + strcpy_P(buffer, (char *)pgm_read_ptr(&(string_table[i]))); // Necessary casts and dereferencing, just copy. Serial.println(buffer); - delay( 500 ); + delay(500); } } - ---- [%hardbreaks] @@ -196,7 +194,7 @@ When an instruction like : Serial.print("Write something on the Serial Monitor"); ---- -is used, the string to be printed is normally saved in RAM. If your sketch prints a lot of stuff on the Serial Monitor, you can easily fill the RAM. If you have free FLASH memory space, you can easily indicate that the string must be saved in FLASH using the syntax: +is used, the string to be printed is normally saved in RAM. If your sketch prints a lot of stuff on the Serial Monitor, you can easily fill the RAM. This can be avoided by not loading strings from the FLASH memory space until they are needed. You can easily indicate that the string is not to be copied to RAM at start up using the syntax: [source,arduino] ---- @@ -214,7 +212,7 @@ Serial.print(F("Write something on the Serial Monitor that is stored in FLASH")) === See also [role="example"] -* #EXAMPLE# https://www.arduino.cc/playground/Learning/Memory[Types of memory available on an Arduino board] +* #EXAMPLE# https://www.arduino.cc/en/Tutorial/Foundations/Memory[Types of memory available on an Arduino board^] [role="definition"] * #DEFINITION# link:../../data-types/array[array] diff --git a/Language/Variables/Utilities/sizeof.adoc b/Language/Variables/Utilities/sizeof.adoc index bae782e38..ecf4c45ec 100644 --- a/Language/Variables/Utilities/sizeof.adoc +++ b/Language/Variables/Utilities/sizeof.adoc @@ -12,7 +12,7 @@ subCategories: [ "Utilities" ] [float] === Description -The sizeof operator returns the number of bytes in a variable type, or the number of bytes occupied by an array. +The `sizeof` operator returns the number of bytes in a variable type, or the number of bytes occupied by an array. [%hardbreaks] @@ -23,11 +23,12 @@ The sizeof operator returns the number of bytes in a variable type, or the numbe [float] === Parameters -`variable`: any variable type or array (e.g. int, float, byte) +`variable`: The thing to get the size of. Allowed data types: any variable type or array (e.g. `link:../../data-types/int[int]`, `link:../../data-types/float[float]`, `link:../../data-types/byte[byte]`). + [float] === Returns -The number of bytes in a variable or bytes occupied in an array. (size_t) +The number of bytes in a variable or bytes occupied in an array. Data type: `link:../../data-types/size_t[size_t]`. -- // OVERVIEW SECTION ENDS @@ -46,34 +47,49 @@ This program prints out a text string one character at a time. Try changing the [source,arduino] ---- char myStr[] = "this is a test"; -int i; -void setup(){ +void setup() { Serial.begin(9600); } void loop() { - for (i = 0; i < sizeof(myStr) - 1; i++){ + for (byte i = 0; i < sizeof(myStr) - 1; i++) { Serial.print(i, DEC); Serial.print(" = "); Serial.write(myStr[i]); Serial.println(); } - delay(5000); // slow down the program + delay(5000); // slow down the program } ---- [%hardbreaks] [float] === Notes and Warnings -Note that `sizeof` returns the total number of bytes. So for larger variable types such as ints, the for loop would look something like this. Note also that a properly formatted string ends with the NULL symbol, which has ASCII value 0. +Note that `sizeof` returns the total number of bytes. So for arrays of larger variable types such as link:../../data-types/int[`int`]s, the for loop would look something like this. [source,arduino] ---- -for (i = 0; i < (sizeof(myInts)/sizeof(int)); i++) { - // do something with myInts[i] +int myValues[] = {123, 456, 789}; + +// this for loop works correctly with an array of any type or size +for (byte i = 0; i < (sizeof(myValues) / sizeof(myValues[0])); i++) { + // do something with myValues[i] } ---- +Note that a properly formatted string ends with the NULL symbol, which has ASCII value 0. + -- // HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Variables/Variable Scope & Qualifiers/const.adoc b/Language/Variables/Variable Scope & Qualifiers/const.adoc index a10d78221..d571776c2 100644 --- a/Language/Variables/Variable Scope & Qualifiers/const.adoc +++ b/Language/Variables/Variable Scope & Qualifiers/const.adoc @@ -19,7 +19,7 @@ subCategories: [ "Variable Scope & Qualifiers" ] === Description The `const` keyword stands for constant. It is a variable _qualifier_ that modifies the behavior of the variable, making a variable "_read-only_". This means that the variable can be used just as any other variable of its type, but its value cannot be changed. You will get a compiler error if you try to assign a value to a `const` variable. -Constants defined with the `const` keyword obey the rules of link:../scope[variable scoping] that govern other variables. This, and the pitfalls of using `#define`, makes the `const` keyword a superior method for defining constants and is preferred over using link:../../../structure/further-syntax/define[`#define`]. +Constants defined with the `const` keyword obey the rules of link:../scope[variable scoping] that govern other variables. This, and the pitfalls of using `link:../../../structure/further-syntax/define[#define]`, makes the `const` keyword a superior method for defining constants and is preferred over using link:../../../structure/further-syntax/define[`#define`]. [%hardbreaks] -- @@ -41,22 +41,17 @@ Constants defined with the `const` keyword obey the rules of link:../scope[varia ---- const float pi = 3.14; float x; - // .... - -x = pi * 2; // it's fine to use consts in math - -pi = 7; // illegal - you can't write to (modify) a constant - - +x = pi * 2; // it's fine to use consts in math +pi = 7; // illegal - you can't write to (modify) a constant ---- [%hardbreaks] [float] === Notes and Warnings -*`#define` or `const`* +*link:../../../structure/further-syntax/define[`#define`] or `const`* -You can use either `const` or `#define` for creating numeric or string constants. For link:../../data-types/array[arrays], you will need to use `const`. In general `const` is preferred over `#define` for defining constants. +You can use either `const` or link:../../../structure/further-syntax/define[`#define`] for creating numeric or string constants. For link:../../data-types/array[arrays], you will need to use `const`. In general `const` is preferred over link:../../../structure/further-syntax/define[`#define`] for defining constants. -- @@ -74,4 +69,4 @@ You can use either `const` or `#define` for creating numeric or string constants * #LANGUAGE# link:../../../structure/further-syntax/define[#define] -- -// SEE ALSO SECTION ENDS \ No newline at end of file +// SEE ALSO SECTION ENDS diff --git a/Language/Variables/Variable Scope & Qualifiers/scope.adoc b/Language/Variables/Variable Scope & Qualifiers/scope.adoc index e7fe640c4..56e366c48 100644 --- a/Language/Variables/Variable Scope & Qualifiers/scope.adoc +++ b/Language/Variables/Variable Scope & Qualifiers/scope.adoc @@ -17,13 +17,13 @@ subCategories: [ "Variable Scope & Qualifiers" ] [float] === Description -Variables in the C programming language, which Arduino uses, have a property called scope. This is in contrast to early versions of languages such as BASIC where every variable is a _global_ variable. +Variables in the C++ programming language, which Arduino uses, have a property called scope. This is in contrast to early versions of languages such as BASIC where every variable is a _global_ variable. -A global variable is one that can be seen by every function in a program. Local variables are only visible to the function in which they are declared. In the Arduino environment, any variable declared outside of a function (e.g. setup(), loop(), etc. ), is a _global_ variable. +A global variable is one that can be seen by every function in a program. Local variables are only visible to the function in which they are declared. In the Arduino environment, any variable declared outside of a function (e.g. `link:../../../structure/sketch/setup[setup()]`, `link:../../../structure/sketch/loop[loop()]`, etc. ), is a _global_ variable. When programs start to get larger and more complex, local variables are a useful way to insure that only one function has access to its own variables. This prevents programming errors when one function inadvertently modifies variables used by another function. -It is also sometimes handy to declare and initialize a variable inside a `for` loop. This creates a variable that can only be accessed from inside the for-loop brackets. +It is also sometimes handy to declare and initialize a variable inside a `link:../../../structure/control-structure/for[for]` loop. This creates a variable that can only be accessed from inside the link:../../../structure/control-structure/for[`for`]-loop brackets. [%hardbreaks] -- @@ -45,25 +45,33 @@ It is also sometimes handy to declare and initialize a variable inside a `for` l ---- int gPWMval; // any function will see this variable -void setup() -{ +void setup() { // ... } -void loop() -{ +void loop() { int i; // "i" is only "visible" inside of "loop" float f; // "f" is only "visible" inside of "loop" // ... - for (int j = 0; j <100; j++){ - // variable j can only be accessed inside the for-loop brackets + for (int j = 0; j < 100; j++) { + // variable j can only be accessed inside the for-loop brackets } - } ---- [%hardbreaks] -- -// HOW TO USE SECTION ENDS \ No newline at end of file +// HOW TO USE SECTION ENDS + + +// SEE ALSO SECTION +[#see_also] +-- + +[float] +=== See also + +-- +// SEE ALSO SECTION ENDS diff --git a/Language/Variables/Variable Scope & Qualifiers/static.adoc b/Language/Variables/Variable Scope & Qualifiers/static.adoc index 5ec52587b..ef30d90d1 100644 --- a/Language/Variables/Variable Scope & Qualifiers/static.adoc +++ b/Language/Variables/Variable Scope & Qualifiers/static.adoc @@ -4,10 +4,6 @@ categories: [ "Variables" ] subCategories: [ "Variable Scope & Qualifiers" ] --- - - - - = Static @@ -19,7 +15,7 @@ subCategories: [ "Variable Scope & Qualifiers" ] === Description The `static` keyword is used to create variables that are visible to only one function. However unlike local variables that get created and destroyed every time a function is called, static variables persist beyond the function call, preserving their data between function calls. -Variables declared as static will only be created and initialized the first time a function is called. +Variables declared as static will only be created and initialized the first time a function is called. [%hardbreaks] -- @@ -40,12 +36,12 @@ Variables declared as static will only be created and initialized the first time [source,arduino] ---- /* RandomWalk -* Paul Badger 2007 -* RandomWalk wanders up and down randomly between two -* endpoints. The maximum move in one loop is governed by -* the parameter "stepsize". -* A static variable is moved up and down a random amount. -* This technique is also known as "pink noise" and "drunken walk". + Paul Badger 2007 + RandomWalk wanders up and down randomly between two + endpoints. The maximum move in one loop is governed by + the parameter "stepsize". + A static variable is moved up and down a random amount. + This technique is also known as "pink noise" and "drunken walk". */ #define randomWalkLowRange -20 @@ -53,31 +49,29 @@ Variables declared as static will only be created and initialized the first time int stepsize; int thisTime; -int total; -void setup() -{ +void setup() { Serial.begin(9600); } -void loop() -{ // test randomWalk function +void loop() { + // test randomWalk function stepsize = 5; thisTime = randomWalk(stepsize); Serial.println(thisTime); - delay(10); + delay(10); } -int randomWalk(int moveSize){ - static int place; // variable to store value in random walk - declared static so that it stores - // values in between function calls, but no other functions can change its value +int randomWalk(int moveSize) { + static int place; // variable to store value in random walk - declared static so that it stores + // values in between function calls, but no other functions can change its value place = place + (random(-moveSize, moveSize + 1)); - if (place < randomWalkLowRange){ // check lower and upper limits - place = randomWalkLowRange + (randomWalkLowRange - place); // reflect number back in positive direction + if (place < randomWalkLowRange) { // check lower and upper limits + place = randomWalkLowRange + (randomWalkLowRange - place); // reflect number back in positive direction } - else if(place > randomWalkHighRange){ + else if (place > randomWalkHighRange) { place = randomWalkHighRange - (place - randomWalkHighRange); // reflect number back in negative direction } diff --git a/Language/Variables/Variable Scope & Qualifiers/volatile.adoc b/Language/Variables/Variable Scope & Qualifiers/volatile.adoc index d621ad3da..8845e1100 100644 --- a/Language/Variables/Variable Scope & Qualifiers/volatile.adoc +++ b/Language/Variables/Variable Scope & Qualifiers/volatile.adoc @@ -17,17 +17,17 @@ subCategories: [ "Variable Scope & Qualifiers" ] [float] === Description -`volatile` is a keyword known as a variable _qualifier_, it is usually used before the datatype of a variable, to modify the way in which the compiler and subsequent program treats the variable. +`volatile` is a keyword known as a variable _qualifier_, it is usually used before the datatype of a variable, to modify the way in which the compiler and subsequent program treat the variable. -Declaring a variable volatile is a directive to the compiler. The compiler is software which translates your C/C++ code into the machine code, which are the real instructions for the Atmega chip in the Arduino. +Declaring a variable `volatile` is a directive to the compiler. The compiler is software which translates your C/C++ code into the machine code, which are the real instructions for the Atmega chip in the Arduino. Specifically, it directs the compiler to load the variable from RAM and not from a storage register, which is a temporary memory location where program variables are stored and manipulated. Under certain conditions, the value for a variable stored in registers can be inaccurate. -A variable should be declared volatile whenever its value can be changed by something beyond the control of the code section in which it appears, such as a concurrently executing thread. In the Arduino, the only place that this is likely to occur is in sections of code associated with interrupts, called an interrupt service routine. +A variable should be declared `volatile` whenever its value can be changed by something beyond the control of the code section in which it appears, such as a concurrently executing thread. In the Arduino, the only place that this is likely to occur is in sections of code associated with interrupts, called an interrupt service routine. [float] === int or long volatiles -If the volatile variable is bigger than a byte (e.g. a 16 bit int or a 32 bit long), then the microcontroller can not read it in one step, because it is an 8 bit microcontroller. This means that while your main code section (e.g. your loop) reads the first 8 bits of the variable, the interrupt might already change the second 8 bits. This will produce random values for the variable. +If the `volatile` variable is bigger than a byte (e.g. a 16 bit int or a 32 bit long), then the microcontroller can not read it in one step, because it is an 8 bit microcontroller. This means that while your main code section (e.g. your loop) reads the first 8 bits of the variable, the interrupt might already change the second 8 bits. This will produce random values for the variable. Remedy: @@ -55,43 +55,51 @@ There are several ways to do this: === Example Code // Describe what the example code is all about and add relevant code ►►►►► THIS SECTION IS MANDATORY ◄◄◄◄◄ +The `volatile` modifier ensures that changes to the `changed` variable are immediately visible in `loop()`. Without the `volatile` modifier, the `changed` variable may be loaded into a register when entering the function and would not be updated anymore until the function ends. [source,arduino] ---- -// toggles LED when interrupt pin changes state +// Flashes the LED for 1 s if the input has changed +// in the previous second. -int pin = 13; -volatile byte state = LOW; +volatile byte changed = 0; -void setup() -{ - pinMode(pin, OUTPUT); - attachInterrupt(0, blink, CHANGE); +void setup() { + pinMode(LED_BUILTIN, OUTPUT); + attachInterrupt(digitalPinToInterrupt(2), toggle, CHANGE); } -void loop() -{ - digitalWrite(pin, state); -} +void loop() { + if (changed == 1) { + // toggle() has been called from interrupts! + + // Reset changed to 0 + changed = 0; -void blink() -{ - state = !state; + // Blink LED for 200 ms + digitalWrite(LED_BUILTIN, HIGH); + delay(200); + digitalWrite(LED_BUILTIN, LOW); + } } +void toggle() { + changed = 1; +} ---- +To access a variable with size greater than the microcontroller’s 8-bit data bus, use the `ATOMIC_BLOCK` macro. The macro ensures that the variable is read in an atomic operation, i.e. its contents cannot be altered while it is being read. [source,arduino] ---- #include // this library includes the ATOMIC_BLOCK macro. volatile int input_from_interrupt; +// Somewhere in the code, e.g. inside loop() ATOMIC_BLOCK(ATOMIC_RESTORESTATE) { - // code with interrupts blocked (consecutive atomic operations will not get interrupted) - int result = input_from_interrupt; - } - + // code with interrupts blocked (consecutive atomic operations will not get interrupted) + int result = input_from_interrupt; + } ---- diff --git a/README.adoc b/README.adoc index 4cc807d66..90010049d 100644 --- a/README.adoc +++ b/README.adoc @@ -3,24 +3,24 @@ Reference-en is the repo for the Language Reference documentation of the Arduino syntax in **English**. All the Reference terms files are in AsciiDoc format. -Thank you for taking the time to contribute to Arduino content, this is really helpful to the whole Arduino Community. If you want to learn more on how to contribute to this project please check https://create.arduino.cc/projecthub/Arduino_Genuino/contribute-to-the-arduino-reference-af7c37[this step by step tutorial]. +Thank you for taking the time to contribute to Arduino content, this is really helpful to the whole Arduino Community. If you want to learn more about how to contribute to this project, please check https://create.arduino.cc/projecthub/Arduino_Genuino/contribute-to-the-arduino-reference-af7c37[this step by step tutorial]. == Content Creation and Editing If you want to contribute new content, create a new file (with any text or code editor) and save it as .adoc. Do not use parenthesis or any special character in the file name. -In https://raw.githubusercontent.com/arduino/reference-en/master/AsciiDoc_sample/AsciiDoc_Dictionary/AsciiDoc_Template-Dictionary.adoc[`reference-en/AsciiDoc_sample/AsciiDoc_Dictionary`] you will find an overview on the AsciiDoc syntax. This includes Titles, Text, Links, Images, Tables, Code and various embeds (video, slideshow, audio and code). You can see it rendered https://www.arduino.cc/reference/en/asciidoc_sample/asciidoc_dictionary/asciidoc_template-dictionary/[here]. +In https://raw.githubusercontent.com/arduino/reference-en/master/AsciiDoc_sample/AsciiDoc_Dictionary/AsciiDoc_Template-Dictionary.adoc[`reference-en/AsciiDoc_sample/AsciiDoc_Dictionary`] you will find an overview of the AsciiDoc syntax. This includes Titles, Text, Links, Images, Tables, Code and various embeds (video, slideshow, audio, and code). You can see it rendered https://www.arduino.cc/reference/en/asciidoc_sample/asciidoc_dictionary/asciidoc_template-dictionary/[here]. If you want to contribute to the Language Reference or edit existing content, you can find two templates in reference-en/AsciiDoc_sample/Reference_Terms: * Use https://raw.githubusercontent.com/arduino/reference-en/master/AsciiDoc_sample/Reference_Terms/AsciiDoc_Template-Single_Entity.adoc[`AsciiDoc_Template-Single_Entity.adoc`] (rendered https://www.arduino.cc/reference/en/asciidoc_sample/reference_terms/asciidoc_template-single_entity/[here]) for terms such as link:http://arduino.cc/en/Reference/AnalogWrite[analogWrite]. * Use https://raw.githubusercontent.com/arduino/reference-en/master/AsciiDoc_sample/Reference_Terms/AsciiDoc_Template-Parent_Of_Entities.adoc[`AsciiDoc_Template-Parent_Of_Entities.adoc`] (rendered https://www.arduino.cc/reference/en/asciidoc_sample/reference_terms/asciidoc_template-parent_of_entities/[here]) for groups of functions such as link:http://arduino.cc/en/Reference/Serial[Serial]. -Please note that every Reference file should include as least a Description, some Example Code, and links to other relevant infos (See Also section). +Please note that every Reference file should include at least a Description, some Example Code, and links to other relevant info (See Also section). If you need to add images to the Asciidoc please create a folder called attachments in the same directory as the Asciidoc file. Images can be saved in SVG and PNG format, max size 200KB. == Contribute Content on Github -If you are not familiar with Git you can contribute content directly on Github via their online interface. We put together a short Tutorial to show you how, https://create.arduino.cc/projecthub/Arduino_Genuino/contribute-to-the-arduino-reference-af7c37[CHECK IT OUT!] +If you are not familiar with Git you can contribute content directly on Github via their online interface. We put together a short Tutorial to show you how - https://create.arduino.cc/projecthub/Arduino_Genuino/contribute-to-the-arduino-reference-af7c37[CHECK IT OUT!] link:https://help.github.com/articles/editing-files-in-another-user-s-repository/[You can also follow this guide] (written by the Github team) to learn how to edit an .adoc file and propose a file change to the Arduino team. When suggesting a change, please follow the guidelines described in the Reference template files. @@ -47,7 +47,7 @@ reference-en │ ├── Functions │ ├── Structure │ └── Variables -├── LICENCE.md +├── LICENSE.md └── README.adoc ----