Blame view

RIOT/sys/arduino/doc.txt 5.08 KB
fb11e647   vrobic   reseau statique a...
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
  /**
   * @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.
   *
   * Thats 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 two step process.
   *
   * First, the make system calls a dedicated
   * [Arduino build script](https://github.com/RIOT-OS/RIOT/tree/master/dist/tools/arduino/pre_build.sh),
   * which is called from the
   * [Makefile.include](https://github.com/RIOT-OS/RIOT/tree/master/sys/arduino/Makefile.include)
   * of the RIOT Arduino module.
   *
   * This script creates a temporary file called '_sketches.cpp' inside the
   * application folder. Into this file, the script 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.
   *
   * Second, the RIOT make system is called as usual, processing the temporary
   * file containing all the Arduino code. Simple :-)
   *
   * @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++.
   *
   * To add Arduino support to a board, it has to provide the following:
   *
   * In `RIOT/board/BOARD/include/arduino_board.h`:
   * - a mapping of GPIO pins to Arduino pin numbers named `arduino_pinmap`, e.g.
   * @code{c}
   *  static const gpio_t arduino_pinmap[] = {
   *      GPIO_PIN(PORT_D, 12),
   *      GPIO_PIN(PORT_D, 13),
   *      GPIO_PIN(PORT_D, 14),
   *      GPIO_PIN(PORT_D, 15),
   *      GPIO_PIN(PORT_A, 12),
   *      GPIO_PIN(PORT_A, 15),
   *      GPIO_PIN(PORT_B, 1),
   *      GPIO_PIN(PORT_B, 2),
   *      ...
   *  };
   * @endcode
   *
   * - a define `ARDUINO_LED` that is mapped to an Arduino pin number connected to
   *   any on-board LED, or to pin 0 in case no LED is defined:
   * @code{c}
   *  #define ARDUINO_LED         (2)
   * @endcode
   *   This links to the third entry in the `arduino_pinmap` array.
   *
   * In addition, you have to add the 'arduino' feature to the board. For this,
   * just add `FEATURES_PROVIDED += arduino` to the 'other features' section in
   * your board's `Makefile.features'.
   *
   * That's it, your board can now run Ardunio sketches.
   *
   *
   * @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 Implement SPI interface class
   * @todo Add support for the 'Wire Library' (I2C)
   * @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
   */