Clean up documentation

parent 952f04df
......@@ -9,12 +9,12 @@ The standard Arduino calls can be used to read their values (with
3.3V nominally reading as 4095).
int analogRead(pin_size_t pin = A0..A3)
---------------------------------------
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Returns a value from 0...4095 correspionding to the ADC reading
of the specific pin.
float analogReadTemp()
----------------------
~~~~~~~~~~~~~~~~~~~~~~
Returns the temperature, in Celsius, of the onboard thermal sensor.
This reading is not exceedingly accurate and of relatively low
resolution, so it is not a replacement for an external temperature
......@@ -28,23 +28,21 @@ simulated using the standard method of using pulse width modulation
While up to 16 PWM channels can be generated, they are not independent
and there are significant restrictions as to allowed pins in parallel.
See the [RP2040 datasheet](https://datasheets.raspberrypi.org/rp2040/rp2040-datasheet.pdf)
for full details.
See the `RP2040 datasheet <https://datasheets.raspberrypi.org/rp2040/rp2040-datasheet.pdf>`_ for full details.
void analogWriteFreq(uint32_t freq)
-----------------------------------
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sets the master PWM frequency used (i.e. how often the PWM output cycles).
From 100Hz to 60KHz are supported.
}
void analogWriteRange(uint32_t range) and analogWriteResolution(int res)
------------------------------------------------------------------------
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These calls set the maximum PWM value (i.e. writing this value will result in
a PWM duty cycle of 100%)/ either explicitly (range) or as a power-of-two
(res). A range of 16 to 65535 is supported.
void analogWrite(pin_size_t pin, int val)
-----------------------------------------
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Writes a PWM value to a specific pin. The PWM machine is enabled and set to
the requested frequency and scale, and the output is generated. This will
continue until a `digitalWrite` or other digital output is performed.
continue until a ``digitalWrite`` or other digital output is performed.
Digital I/O
===========
Board-Specific Pins
-------------------
The Raspberry Pi Pico RP2040 chip supports up to 30 digital I/O pins,
however not all boards provide access to all pins.
Tone/noTone
-----------
Simple square wave tone generation is possible for up to 8 channels using
Arduino standard ``tone`` calls. Because these use the PIO to generate the
waveform, they must share resources with other calls such as ``I2S`` or
``Servo`` objects.
......@@ -9,47 +9,50 @@ writes as the onboard flash chip, not the 100,000 or so of a real EEPROM.**
Therefore, do not frequently update the EEPROM or you may prematurely wear
out the flash.
EEPROM Class API
----------------
EEPROM.begin(size=256...4096)
-----------------------------
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Call before the first use of the EEPROM data for read or write. It makes a
copy of the emulated EEPROM sector in RAM to allow random update and access.
EEPROM.read(addr), EEPROM[addr]
-------------------------------
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Returns the data at a specific offset in the EEPROM. See `EEPROM.get` later
for a more
EEPROM.write(addr, data), EEPROM[addr] = data
---------------------------------------------
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Writes a byte of data at the offset specified. Not persisted to flash until
`EEPROM.commit()` is called.
``EEPROM.commit()`` is called.
EEPROM.commit()
---------------
~~~~~~~~~~~~~~~
Writes the updated data to flash, so next reboot it will be readable.
EEPROM.end()
------------
`EEPROM.commit()` and frees all memory used. Need to call `EEPROM.begin()`
~~~~~~~~~~~~
``EEPROM.commit()`` and frees all memory used. Need to call `EEPROM.begin()`
before the EEPROM can be used again.
EEPROM.get(addr, val)
---------------------
~~~~~~~~~~~~~~~~~~~~~
Copies the (potentially multi-byte) data in EEPROM at the specific byte
offset into the returned value. Useful for reading structures from EEPROM.
EEPROM.put(addr, val)
---------------------
~~~~~~~~~~~~~~~~~~~~~
Copies the (potentially multi-byte) value into EEPROM a the byte offset
supplied. Useful for storing `struct` in EEPROM. Note that any pointers
supplied. Useful for storing ``struct`` in EEPROM. Note that any pointers
inside a written structure will not be valid, and that most C++ objects
like `String` cannot be written to EEPROM this way because of it.
like ``String`` cannot be written to EEPROM this way because of it.
EEPROM.length()
---------------
~~~~~~~~~~~~~~~
Returns the length of the EEPROM (i.e. the value specified in
`EEPROM.begin()` ).
``EEPROM.begin()`` ).
EEPROM Examples
---------------
Three EEPROM [examples](https://github.com/earlephilhower/arduino-pico/tree/master/libraries/EEPROM) are included.
Three EEPROM `examples<https://github.com/earlephilhower/arduino-pico/tree/master/libraries/EEPROM>`_ are included.
......@@ -5,7 +5,7 @@ While the RP2040 chip on the Raspberry Pi Pico does not include a hardware
I2S device, it is possible to use the PIO (Programmable I/O) state machines
to implement one dynamically.
This I2S library uses the `pico-extras` I2S audio library and wraps it in
This I2S library uses the ``pico-extras`` I2S audio library and wraps it in
an Arduino I2S library. It supports 16 bits/sample and frequencies of up
to 48kHZ, with configurable BCLK, LRCLK(always pin "BCLK + 1"), and DOUT pins.
......@@ -13,75 +13,77 @@ to 48kHZ, with configurable BCLK, LRCLK(always pin "BCLK + 1"), and DOUT pins.
its clock frequency to meet the I2S needs. That means when only 4 Tones
or only 4 Servos may be used when the I2S device is used.
I2S Class API
-------------
bool setBCLK(pin_size_t pin)
----------------------------
Sets the BCLK pin of the I2S device. The LRCLK/word clock will be `pin + 1`
due to limitations of the PIO state machines. Call this before `I2S.begin()`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sets the BCLK pin of the I2S device. The LRCLK/word clock will be ``pin + 1``
due to limitations of the PIO state machines. Call this before ``I2S.begin()``
Default BCLK = 26, LRCLK = 27
bool setDOUT(pin_size_t pin)
----------------------------
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Sets the DOUT pin of the I2S device. Any pin may be used. Default DOUT = 28
Call before `I2S.begin()`
Call before ``I2S.begin()``
bool begin(long sampleRate)
---------------------------
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Start the I2S device up with the given sample rate. The pins selected above
will be turned to output and the I2S will begin to drive silence frames (all
zero) out.
void end()
----------
~~~~~~~~~~
Stops the I2S device. **Note, at present the memory allocated for I2S buffers
is not freed leading to a memory leak when `end()` is called. This is due
to the state of the `pico-extras` release from thich this device came.**
is not freed leading to a memory leak when ``end()`` is called. This is due
to the state of the ``pico-extras`` release which this code uses.**
void flush()
------------
~~~~~~~~~~~~
Sends any partial frames in memory to the I2S output device. They may NOT play
immediately. Potential use case for this call would be when the frequency of
the output will be changing.
size_t write(uint8_t)
---------------------
~~~~~~~~~~~~~~~~~~~~~
Provided for compatibilty, but not very useful. Writes a sample from 0...255
to the I2S buffer. See `write(int16_t)` for a better one
to the I2S buffer. See ``write(int16_t)`` for a better one
size_t write(const uint8_t \*buffer, size_t size)
-------------------------------------------------
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Transfers number of bytes from an application buffer to the I2S output buffer.
Be aware that `size` is in *bytes** and not samples. Size must be a multiple
Be aware that ``size`` is in *bytes** and not samples. Size must be a multiple
of **4 bytes** (i.e. one left/right sample). Will not block, so check
the return value to find out how many bytes were actually written.
int availableForWrite()
-----------------------
~~~~~~~~~~~~~~~~~~~~~~~
Returns the number of **32-bit L/R samples** that can be written without
potentially blocking.
bool setFrequency(int newFreq)
------------------------------
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Adjusts the I2S output frequency. When changing frequency while I2S output
is underway, be sure to use `I2S.flush()` before changing the frequency to
is underway, be sure to use ``I2S.flush()`` before changing the frequency to
ensure the older data is played at the right frequency.
size_t write(int16_t)
---------------------
~~~~~~~~~~~~~~~~~~~~~
Writes a single 16-bit left or right sample to the I2S output buffer. The
user is required to ensure that an even number of samples is written (i.e.
left and right) over the application lifetime. The application also needs
to track which sample is next to be written (right/left). For this reason,
the `write(void *b, size_t lrsamples)` call may be easier and faster to use.
the ``write(void *b, size_t lrsamples)`` call may be easier and faster to use.
size_t write(const void \*buffer, size_t lrsamples)
---------------------------------------------------
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Writes up to size left+right packed samples to the I2S device. Non-blocking,
will writefrom 0...size samples and return that count. Be sure your app
handles partial writes (i.e. by yield()ing and then retrying to write the
handles partial writes (i.e. by ``yield()`` ing and then retrying to write the
remaining data.)
The `onTransmit` callback is not supported.
The ``onTransmit`` callback is not supported.
See the [ESP8266Audio](https://github.com/earlephilhower/ESP8266Audio) library
See the `ESP8266Audio <https://github.com/earlephilhower/ESP8266Audio>`_ library
for a working example, or look at the included sample tone generator.
## Welcome to Arduino-Pico
Please go to https://arduino-pico.readthedocs.io/en/latest/ for the
latest documentation.
......@@ -18,7 +18,7 @@ For the latest version, always check https://github.com/earlephilhower/arduino-p
Getting Help and Contributing <help>
Installation <install>
Using the IDE <ide>
IDE Menus <ide>
Pin (Re)Assignment <pins>
......@@ -37,10 +37,3 @@ For the latest version, always check https://github.com/earlephilhower/arduino-p
Using Pico-SDK <sdk>
Licenses <license>
Indices and Tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
......@@ -48,7 +48,7 @@ To install via GIT (for latest and greatest versions):
Installing both Arduino and CMake
---------------------------------
Tom's Hardware presented a very nice writeup on installing `arduino-pico` on
both Windows and Linux, available at [Tom's Hardware](https://www.tomshardware.com/how-to/program-raspberry-pi-pico-with-arduino-ide)
both Windows and Linux, available at `Tom's Hardware <https://www.tomshardware.com/how-to/program-raspberry-pi-pico-with-arduino-ide>`_ .
If you follow their step-by-step you will also have a fully functional
`CMake`-based environment to build Pico apps on if you outgrow the Arduino
......
Libraries Ported/Optimizef for the RP2040
Libraries Ported/Optimized for the RP2040
=========================================
Most Arduino libraries that work on modern 32-bit CPU based Arduino boards
......@@ -8,6 +8,6 @@ The following libraries have undergone additional porting and optimizations
specifically for the RP2040 and you should consider using them instead of
the generic versions available in the Library Manager
* [Adafruit GFX Library](https://github.com/Bodmer/Adafruit-GFX-Library) by @Bodmer, 2-20x faster than the standard version on the Pico
* [Adafruit ILI9341 Library](https://github.com/Bodmer/Adafruit_ILI9341), again by @Bodmer
* [ESP8266Audio](https://github.com/earlephilhower/ESP8266Audio), ported to use the included `I2S` library
* `Adafruit GFX Library <https://github.com/Bodmer/Adafruit-GFX-Library>`_ by @Bodmer, 2-20x faster than the standard version on the Pico
* `Adafruit ILI9341 Library <https://github.com/Bodmer/Adafruit_ILI9341>`_ again by @Bodmer
* `ESP8266Audio <https://github.com/earlephilhower/ESP8266Audio>_` ported to use the included ``I2S`` library
......@@ -5,10 +5,10 @@ Arduino-Pico is licensed under the LGPL license as detailed in the included READ
In addition, it contains code from additional open source projects:
* The [Arduino IDE and ArduinoCore-API](https://arduino.cc) are developed and maintained by the Arduino team. The IDE is licensed under GPL.
* The [RP2040 GCC-based toolchain](https://github.com/earlephilhower/pico-quick-toolchain) is licensed under under the GPL.
* The [Pico-SDK](https://github.com/raspberrypi/pico-sdk) and [Pico-Extras](https://github.com/raspberrypi/pico-extras) are by Raspberry Pi (Trading) Ltd and licensed under the BSD 3-Clause license.
* [Arduino-Pico](https://github.com/earlephilhower/arduino-pico) core files are licenses under the LGPL.
* [LittleFS](https://github.com/ARMmbed/littlefs) library written by ARM Limited and released under the [BSD 3-clause license](https://github.com/ARMmbed/littlefs/blob/master/LICENSE.md).
* [UF2CONV.PY](https://github.com/microsoft/uf2) is by Microsoft Corporatio and licensed under the MIT license.
* Some filesystem code taken from the [ESP8266 Arduino Core](https://github.com/esp8266/Arduino) and licensed under the LGPL.
* The `Arduino IDE and ArduinoCore-API <https://arduino.cc>`_ are developed and maintained by the Arduino team. The IDE is licensed under GPL.
* The `RP2040 GCC-based toolchain <https://github.com/earlephilhower/pico-quick-toolchain>`_ is licensed under under the GPL.
* The `Pico-SDK <https://github.com/raspberrypi/pico-sdk>`_ and `Pico-Extras <https://github.com/raspberrypi/pico-extras>`_ are by Raspberry Pi (Trading) Ltd. and licensed under the BSD 3-Clause license.
* `Arduino-Pico <https://github.com/earlephilhower/arduino-pico>`_ core files are licenses under the LGPL.
* `LittleFS <https://github.com/ARMmbed/littlefs>`_ library written by ARM Limited and released under the `BSD 3-clause license <https://github.com/ARMmbed/littlefs/blob/master/LICENSE.md>`_ .
* `UF2CONV.PY <https://github.com/microsoft/uf2>`_ is by Microsoft Corporatio and licensed under the MIT license.
* Some filesystem code taken from the `ESP8266 Arduino Core <https://github.com/esp8266/Arduino>`_ and licensed under the LGPL.
......@@ -11,24 +11,24 @@ I/O pins **before calling ::begin**. This is especially helpful when
using third party libraries: the library doesn't need to be modified,
only your own code in `setup()` is needed to adjust pinouts.
I2S:
----
I2S
---
.. code:: cpp
::setBCLK(pin)
::setDOUT(pin)
Serial1 (UART0), Serial2 (UART1):
---------------------------------
Serial1 (UART0), Serial2 (UART1)
--------------------------------
.. code:: cpp
::setRX(pin)
::setTX(pin)
SPI (SPI0), SPI1 (SPI1):
------------------------
SPI (SPI0), SPI1 (SPI1)
-----------------------
.. code:: cpp
......@@ -36,8 +36,8 @@ SPI (SPI0), SPI1 (SPI1):
::setRX(pin)
::setTX(pin)
Wire (I2C0), Wire1 (I2C1):
--------------------------
Wire (I2C0), Wire1 (I2C1)
-------------------------
.. code:: cpp
......
Using the Raspberry Pi Pico SDK (PICO-SDK)
==========================================
A complete copy of the [Raspberry Pi Pico SDK](https://datasheets.raspberrypi.org/pico/raspberry-pi-pico-c-sdk.pdf)
A complete copy of the `Raspberry Pi Pico SDK <https://datasheets.raspberrypi.org/pico/raspberry-pi-pico-c-sdk.pdf>`_
is included with the Arduino core, and all functions in the core are available
inside the standard link libraries.
......
......@@ -5,18 +5,19 @@ The Arduino-Pico core implements a software-based Serial-over-USB port
using the USB ACM-CDC model to support a wide variety of operating
systems.
`Serial` is the USB serial port, and while `Serial.begin()` doea allow
``Serial`` is the USB serial port, and while ``Serial.begin()`` does allow
specifying a baud rate, this rate is ignored since it is USB-based.
(Also be aware that this USB `Serial` port is responsible for resetting
(Also be aware that this USB ``Serial`` port is responsible for resetting
the RP2040 during the upload process, following the Arduino standard
of 1200bps = reset to bootloader).
The RP2040 provides two hardware-based UARTS with configurable
pin selection.
`Serial1` is UART0, and `Serial2` is UART1.
``Serial1`` is ``UART0``, and ``Serial2`` is ``UART1``.
Configure their pins using the ``setXXX`` calls prior to calling ``begin()``
Configure their pins using the `setXXX` calls prior to calling `begin()`
.. code:: cpp
Serial1.setRX(pin);
......@@ -24,4 +25,4 @@ Configure their pins using the `setXXX` calls prior to calling `begin()`
Serial1.begin(baud);
For detailed information about the Serial ports, see the
Arduino [Serial reference](https://www.arduino.cc/reference/en/language/functions/communication/serial/)
Arduino `Serial Reference <https://www.arduino.cc/reference/en/language/functions/communication/serial/>`_ .
Servo Library
=============
A hardware-based servo controller is provided using the `Servo` library.
A hardware-based servo controller is provided using the ``Servo`` library.
It utilizes the PIO state machines and generates the appropriate servo
control pulses, glitch-free and jitter-free (within crystal limits).
Up to 8 Servos can be controlled in parallel assuming no other tasks
require the use of a PIO machine.
See the Arduino standard [Servo documentation](https://www.arduino.cc/reference/en/libraries/servo/)
for detailed usage instructions. There is also an included `sweep` example.
See the Arduino standard
`Servo documentation <https://www.arduino.cc/reference/en/libraries/servo/>`_
for detailed usage instructions. There is also an included ``sweep`` example.
SPI (Serial Peripheral Interface)
=================================
The RP2040 has two hardware SPI interfaces, `spi0 (SPI)` and `spi1 (SPI1)`.
These interfaces are supported by the `SPI` library in master mode.
The RP2040 has two hardware SPI interfaces, ``spi0 (SPI)`` and ``spi1 (SPI1)``.
These interfaces are supported by the ``SPI`` library in master mode.
SPI pinouts can be set **before SPI.begin()** using the following calls:
......@@ -13,16 +13,12 @@ SPI pinouts can be set **before SPI.begin()** using the following calls:
bool setSCK(pin_size_t pin);
bool setTX(pin_size_t pin);
Note that the `CS` pin can be hardware or software controlled by the sketch.
When software controlled, the `setCS()` call is ignored.
Note that the ``CS`` pin can be hardware or software controlled by the sketch.
When software controlled, the ``setCS()`` call is ignored.
The [Arduino SPI documention](https://www.arduino.cc/en/reference/SPI) gives
The Arduino `SPI documentation <https://www.arduino.cc/en/reference/SPI>`_ gives
a detailed overview of the library, except for the following RP2040-specific
changes:
* `SPI.begin(bool hwCS)` can take an options `hwCS` parameter.
By passing in `true` for `hwCS` the sketch does not need to worry about
asserting and deasserting the `CS` pin between transactions. The default
is `false` and requires the sketch to handle the CS pin itself, as is the
standard way in Arduino.
* The interrupt calls (`usingInterrupt`, `notUsingInterrupt`,
`attachInterrupt`, and `detachInterrpt`) are not implemented.
* ``SPI.begin(bool hwCS)`` can take an options ``hwCS`` parameter. By passing in ``true`` for ``hwCS`` the sketch does not need to worry about asserting and deasserting the ``CS`` pin between transactions. The default is ``false`` and requires the sketch to handle the CS pin itself, as is the standard way in Arduino.
* The interrupt calls (``usingInterrupt``, ``notUsingInterrupt``, ``attachInterrupt``, and ``detachInterrpt``) are not implemented.
Wire (I2C Master and Slave)
===========================
The RP2040 has two I2C devices, `i2c0 (Wire)` and `i2c1 (Wire1)`
The RP2040 has two I2C devices, ``i2c0 (Wire)`` and ``i2c1 (Wire1)``
The current implementation is compatible with the Arduino standard
with the addition of two calls to allof the `SDA` and `SCL` pins
......@@ -15,6 +15,6 @@ to be set **before calling Wire.begin()**
Both master and slave operation is supported.
Master transmissions are buffered (up to 128 bytes) and only performed
on `endTransmission`, as is standard with modern Arduino Wire implementations.
on ``endTransmission``, as is standard with modern Arduino Wire implementations.
For more detailed information, check the [Arduino Wire documentation.](https://www.arduino.cc/en/reference/wire)
For more detailed information, check the `Arduino Wire documentation <https://www.arduino.cc/en/reference/wire>`_ .
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment