mirror of
https://github.com/RIOT-OS/RIOT.git
synced 2024-12-29 04:50:03 +01:00
043e8cc88e
- Rename all `arduino_pinmap.h` to `arduino_iomap.h`
- An empty `arduino_pinmap.h` that just includes `arduino_iomap.h`
is provided for backward compatibility
- Move all info from `arduino_board.h` into the new file as trivial
macros, so that they can also be used outside of sketches
- The new name reflects the fact not just pin mappings, but also
other I/O features such as PWMs are mapped
- Drop all `arduino_board.h`
- `arduino_board.h` and `arduino_iomap.h` now provide the exact
same information, just in a different format
- a generic `arduino_board.h` is provided instead that just
uses the info in `arduinio_iomap.h` and provides them in the
format the code in `sys/arduino` expects it
- Add fine grained features to indicate for mappings
- availability of mappings for analog pins, DAC pins, PWM pins,
UART devices, SPI/I2C buses to the corresponding RIOT
identification can now be expressed:
- `arduino_pins`: `ARDUINO_PIN_0` etc. are available
- `arduino_analog`: `ARDUINO_A0` etc. are available
- `arduino_pwm`: `ARDUINO_PIN_13_PWM_DEV` etc. are available
- `arduino_dac`: `ARDUINO_DAC0` etc. are available
- `arduino_uart`: `ARDUINO_UART_D0D1` or similar are available
- `arduino_spi`: `ARDUINO_SPI_ISP` or similar are available
- `arduino_i2c`: `ARDUINO_I2C_UNO` or similar are available
- mechanical/electrical compatibility with specific form factors
can now be expressed as features:
- `aruino_shield_nano`: Arduino NANO compatible headers
- `aruino_shield_uno`: Arduino UNO compatible headers
- `aruino_shield_mega`: Arduino MEGA compatible headers
- `aruino_shield_isp`: ISP header is available
This provides the groundwork to implement shield support as modules
that can rely on the I/O mappings, rather than having to provide a
configuration per board.
119 lines
4.8 KiB
Plaintext
119 lines
4.8 KiB
Plaintext
/**
|
|
* @defgroup sys_arduino Arduino
|
|
* @ingroup sys
|
|
* @brief Arduino in RIOT
|
|
*
|
|
* @section sec_about About
|
|
*
|
|
* This module enables users to run unmodified Arduino sketches in RIOT. For
|
|
* this we aim at supporting the full Arduino API.
|
|
*
|
|
* The support of the Arduino API in RIOT is useful for multiple reasons:
|
|
* - starting point for beginners
|
|
* - run your existing sketches on any non-Arduino hardware supported by RIOT
|
|
* - makes it easy to move from Arduino to RIOT
|
|
* - use Arduino device drivers in RIOT
|
|
* - is fun to implement :-)
|
|
*
|
|
* Refer to @ref sys_arduino_api for the actual API documentation
|
|
*
|
|
*
|
|
* @section sec_usage General usage
|
|
*
|
|
* To run your Arduino sketch in RIOT, just follow these steps:
|
|
*
|
|
* -# create an empty application
|
|
* -# add the `arduino` module to your application, your `Makefile` should now
|
|
* look something like this:
|
|
* @code
|
|
* APPLICATION = YOUR_APP_NAME
|
|
* BOARD ?= YOUR_TARGET_PLATFORM
|
|
* RIOTBASE ?= PATH_TO_RIOT_ROOT
|
|
*
|
|
* USEMODULE += arduino
|
|
*
|
|
* include $(RIOTBASE)/Makefile.include
|
|
* @endcode
|
|
*
|
|
* -# copy your Arduino sktech(es) into your application folder. Currently they
|
|
* must have the file ending `*.sketch` to be processed.
|
|
* -# build, flash, and run your application the usual RIOT-way: simply call
|
|
* `make all`, `make flash`, `make term`, etc.
|
|
*
|
|
* That's all. As bonus you can of course use any existing RIOT code inside your
|
|
* Arduino sketches - you simply have to add the includes to your sketch and
|
|
* the corresponding modules to your `Makefile`.
|
|
*
|
|
* @note So far, all Arduino sketches MUST have the file ending `*.sketch` to
|
|
* be recognized by RIOT's build system
|
|
*
|
|
*
|
|
* @section sec_concept Concept
|
|
*
|
|
* For enabling RIOT to run Arduino sketches, we extended the build system to
|
|
* handle `*.sketch` files and we implemented the Arduino API using RIOT's
|
|
* native functions.
|
|
*
|
|
* @subsection sec_concept_build Extension of the build system
|
|
*
|
|
* Building Arduino sketches in RIOT is done in a three step process.
|
|
*
|
|
* First, the make system defines a generated `arduino_sketches` module placed
|
|
* into `$(BINDIR)`
|
|
* [Arduino sketches makefile](https://github.com/RIOT-OS/RIOT/tree/master/sys/arduino/sketches.inc.mk),
|
|
* which is included from the
|
|
* [Makefile.include](https://github.com/RIOT-OS/RIOT/tree/master/sys/arduino/Makefile.include)
|
|
* of the RIOT Arduino module.
|
|
* The generated module is added to used modules and build directories.
|
|
*
|
|
* Second, as prerequisites for the `link` target, the make system will create
|
|
* the module into `$(BINDIR)/arduino_sketches` with an `arduino_sketches.cpp`
|
|
* source file.
|
|
* Into this file, it copies some Arduino glue code (
|
|
* [pre.snip](https://github.com/RIOT-OS/RIOT/blob/master/sys/arduino/pre.snip)
|
|
* and
|
|
* [post.snip](https://github.com/RIOT-OS/RIOT/blob/master/sys/arduino/post.snip))
|
|
* together with the contents of all `*.sketch` files contained in the
|
|
* application folder.
|
|
*
|
|
* Third, the RIOT make system is called as usual, building the generated
|
|
* library with the Arduino code and including it in the final firmware.
|
|
*
|
|
* @subsection sec_conecpt_api Implementation of the Arduino API
|
|
*
|
|
* For supporting the Arduino API, we have created our own function and class
|
|
* definitions, using the exact same signatures as in the original Arduino
|
|
* header files. These headers are then implemented using standard RIOT APIs,
|
|
* e.g. the peripheral drivers, `xtimer`, etc.
|
|
*
|
|
*
|
|
* @section sec_boardsupport Add Arduino support to a board
|
|
*
|
|
* @note As prerequisite, the board must have support for C++. Support for
|
|
* the standard C++ lib (feature `libstdcpp`) is not required.
|
|
*
|
|
* As a minimum requirement, the features `arduino_pins` is a hard dependency.
|
|
* See @ref iomaps-mapping-gpio what a board needs to provide this.
|
|
*
|
|
* Additional mappings for analog pins (see @ref iomaps-mapping-adc) and PWM
|
|
* pins (see @ref iomaps-mapping-pwm) is required to be able to use
|
|
* `analogRead()` and `analogWrite()`.
|
|
*
|
|
* See also @ref iomaps on how a board can provide more I/O mappings and even
|
|
* declare electrical and mechanical compatibility with common Arduino form
|
|
* factors.
|
|
*
|
|
* @section sec_todo Open issues
|
|
*
|
|
* @todo Make it possible to bootstrap Arduino code manually from any RIOT
|
|
* application. Include a pseudomule as e.g. arduino_base, which does not
|
|
* implement a main function calling `setup()` and `loop()`, so these
|
|
* functions have to be called manually from a RIOT application.
|
|
* @todo Implement analog outputs (PWM mapping)
|
|
* @todo Implement analog inputs (ADC mapping)
|
|
* @todo Add means to include various Arduino Libraries (maybe as pkg?)
|
|
* @todo Implement anything else that is missing...
|
|
* @todo Adapt Arduino build script, so sketches do not have to have the file
|
|
* ending `*.sketch` anymore
|
|
*/
|