mirror of
https://github.com/RIOT-OS/RIOT.git
synced 2024-12-29 04:50:03 +01:00
added information from Introduction page to the API start page
This commit is contained in:
Oleg Hahm
parent
7335cd71c7
commit
8695e3b102
@ -1,6 +1,165 @@
|
||||
/*! \mainpage RIOT Documentation
|
||||
*
|
||||
* RIOT is an operating system for the Internet of Things based on a microkernel architecture.
|
||||
* \section overview Overview
|
||||
*
|
||||
* RIOT is an operating system designed for the particular requirements of Internet
|
||||
* of Things (IoT) scenarios. This requirements comprise a low memory footprint,
|
||||
* high energy efficiency, real-time capabilities, a modular and configurable
|
||||
* communication stack, and support for a wide range of low-power devices. RIOT
|
||||
* provides a microkernel, utilities like cryptographic libraries, data structures
|
||||
* (bloom filters, hash tables, priority queues), or a shell, different network
|
||||
* stacks, and support for various microcontrollers, radio drivers, sensors, and
|
||||
* configurations for entire platforms, e.g. TelosB or STM32 Discovery Boards.
|
||||
*
|
||||
* The microkernel itself comprises thread management, a priority-based scheduler,
|
||||
* a powerful API for inter-process communication (IPC), a system timer, and
|
||||
* mutexes.
|
||||
*
|
||||
* In order to build an application or library with RIOT, you need first to
|
||||
* download the source code ([Getting the source
|
||||
* code](https://github.com/RIOT-OS/RIOT/wiki/Introduction#getting-the-source-code)). This contains - besides the
|
||||
* before mentioned features - also some example applications (located in the
|
||||
* `examples` subdirectory) and a sample Makefile you may use for your own
|
||||
* project. This Makefile template shows you how to compile and link your project
|
||||
* against RIOT ([Compiling RIOT](https://github.com/RIOT-OS/RIOT/wiki/Introduction#compiling-riot)).
|
||||
*
|
||||
* If you want to use RIOT directly with your embedded platform, you need to
|
||||
* install the corresponding toolchain for the deployed microcontroller ([ARM
|
||||
* based platforms](https://github.com/RIOT-OS/RIOT/wiki/Introduction#platforms-based-on-arm), [TI MSP430 based
|
||||
* platforms](https://github.com/RIOT-OS/RIOT/wiki/Introduction#platforms-based-on-ti-msp430)).
|
||||
*
|
||||
* ###Native RIOT - Run RIOT on your PC!
|
||||
*
|
||||
* As a special platform, you will find a CPU and board called `native` in the
|
||||
* repository. This target allows you to run RIOT as a process on Linux on most
|
||||
* supported hardware platforms. Just set CPU and BOARD to `native` in your
|
||||
* project's Makefile, call `make`, and execute the resulting elf-file. Further
|
||||
* documentation about the native port can be found in `cpu/native/README`.
|
||||
*
|
||||
* \subsection structure Structure
|
||||
*
|
||||
* The RIOT repository contains the following ten subdirectories:
|
||||
* * boards
|
||||
* * core
|
||||
* * cpu
|
||||
* * dist
|
||||
* * doc
|
||||
* * drivers
|
||||
* * examples
|
||||
* * pkg
|
||||
* * sys
|
||||
* * tests
|
||||
*
|
||||
* The `boards` directory provides the configurations and initialization code for
|
||||
* supported IoT platforms. In `core` you can find the kernel, while `cpu`
|
||||
* comprises microcontroller specific implementations like startup and exception
|
||||
* handling code. The folder `dist` contains a template for an application's Makefile
|
||||
* and external utilities like the terminal program `pyterm` or a script to build
|
||||
* your own toolchain for ARM microcontrollers. Not very surprisingly you will find
|
||||
* the (doxygen) documentation in `doc` and peripheral driver code in `drivers`.
|
||||
* The `examples` folder provides some exemplary applications, `pkg` includes
|
||||
* Makefiles to integrate external libraries into RIOT, and `sys` system libraries
|
||||
* as well as the implementation of the network stacks which are located in
|
||||
* `sys/net`. Finally, the subdirectory `tests` contains test applications,
|
||||
* including also a few expect scripts to automatically validate some of them.
|
||||
*
|
||||
* \section features Special features
|
||||
*
|
||||
* ####The build system
|
||||
*
|
||||
* RIOT uses GNU make as build system. The simplest way to compile and link a
|
||||
* project (application or library) with RIOT, is to set up a Makefile providing
|
||||
* at least the following variables:
|
||||
* * PROJECT
|
||||
* * BOARD
|
||||
* * RIOTBASE
|
||||
*
|
||||
* and an instruction to include the `Makefile.include`, located in RIOT's root
|
||||
* folder. `PROJECT` should contain the (unique) name of your project, `BOARD`
|
||||
* specifies the platform the project should be built for by default, and
|
||||
* `RIOTBASE` specifies the path to your copy of the RIOT repository (note, that
|
||||
* you may want to use `$(CURDIR)` here, to give a relative path). You can use Make's
|
||||
* `?=` operator in order to allow overwriting variables from the command line. For
|
||||
* example, you can easily specify the target platform, using the sample Makefile,
|
||||
* by invoking make like this:
|
||||
*
|
||||
* ```
|
||||
* make BOARD=telosb
|
||||
* ```
|
||||
*
|
||||
* Besides typical targets like `clean`, `all`, or `doc`, RIOT provides the special
|
||||
* targets `flash` and `term` to invoke the configured flashing and terminal tools
|
||||
* for the specified platform. These targets use the variable `PORT` for the serial
|
||||
* communication to the device. Neither this variable nor the targets `flash` and
|
||||
* `term` are mandatory for the native port.
|
||||
*
|
||||
* Some RIOT folders contain special Makefiles like `Makefile.base`,
|
||||
* `Makefile.include` or `Makefile.dep`. The first one can be included into other
|
||||
* Makefiles to define some standard targets. The files called `Makefile.include`
|
||||
* are used in `boards` and `cpu` to append target specific information to
|
||||
* variables like `INCLUDES`, setting the include paths. `Makefile.dep` serves to
|
||||
* define dependencies.
|
||||
*
|
||||
* ####Including modules
|
||||
*
|
||||
* By default a RIOT project comprises only the projects' code itself, the kernel,
|
||||
* and platform specific code. In order to use additional modules, such as a
|
||||
* particular device driver or a system library, you have to append the modules'
|
||||
* names to the USEMODULE variable. For example, to build a project using the SHT11
|
||||
* temperature sensor and 6LoWPAN network stack, your Makefile needs to contain
|
||||
* these lines:
|
||||
* ```
|
||||
* USEMODULE += sht11
|
||||
* USEMODULE += sixlowpan
|
||||
* ```
|
||||
* To contribute a new module to RIOT, your module's Makefile needs to set the
|
||||
* variable `MODULE` to a unique name. If the module depends on other modules, this
|
||||
* information needs to be added to RIOT's `Makefile.dep`.
|
||||
*
|
||||
* ####The main function
|
||||
*
|
||||
* After the board is initialized, RIOT starts two threads: the idle thread and the
|
||||
* main thread. The idle thread has the lowest priority and will run, whenever no
|
||||
* other thread is ready to run. It will automatically use the lowest possible
|
||||
* power mode for the device. The main thread - configured with a default priority
|
||||
* that is right in the middle between the lowest and the highest available
|
||||
* priority - is the first thread that runs and calls the main function. This
|
||||
* function needs to be defined by the project.
|
||||
*
|
||||
* ####The IPC
|
||||
*
|
||||
* Like any microkernel system, RIOT has an IPC API that enables data exchange
|
||||
* between modules or a single module and the kernel. This API is documented in
|
||||
* the [doxygen documentation](http://riot-os.org/api/). The IPC can be used in
|
||||
* several ways, such as synchronous or asynchronous, blocking or non-blocking,
|
||||
* with or without a message queue. In the default case, a thread does not have a
|
||||
* message queue. Hence, messages sent in a non-blocking manner are lost, when the
|
||||
* target thread is not in receive mode. A thread may set up a message queue using
|
||||
* the [corresponding function](http://riot-os.org/api/group__kernel__msg.html),
|
||||
* but has to provide the memory for this queue itself.
|
||||
*
|
||||
* ####Auto-init
|
||||
*
|
||||
* Most modules require initialization before they can be used. In some cases the
|
||||
* initialization function does not require a parameter. For these modules you
|
||||
* might use the auto-init feature by adding a line like
|
||||
* ```
|
||||
* USEMODULE += auto_init
|
||||
* ```
|
||||
* to your Makefile. Auto-init calls all module initialization functions with a
|
||||
* `void` parameter just before the main thread gets executed.
|
||||
*
|
||||
* ####The transceiver module
|
||||
*
|
||||
* The transceiver module is an abstraction layer and multiplexer between the
|
||||
* network stack and the radio driver. It runs in a single thread with the PID
|
||||
* `transceiver_pid`. It provides an IPC interface that enables to configure and
|
||||
* use available radio drivers, e.g. setting the radio channel or sending a packet.
|
||||
* A thread may also register at the transceiver module, in order to get notified
|
||||
* whenever a packet for a particular radio transceiver is received. The
|
||||
* notification message contains a pointer to the packet struct. After processing
|
||||
* the packet, the registered thread needs to decrease this struct's member
|
||||
* `processing` which acts as a semaphore for the packet's memory buffer.
|
||||
*
|
||||
* \section info_sec Community
|
||||
*
|
||||
|
||||
Loading…
Reference in New Issue
Block a user