Welcome to Simba’s documentation!¶
Simba is an Embedded Programming Platform. It aims to make embedded programming easy and portable.
Project homepage: https://github.com/eerimoq/simba
Videos¶
Transmit CAN frames between a Nano32 and an Arduino Due. More videos are available on the Videos page.
Installation¶
There are three build systems available; PlatformIO, Arduino IDE and Simba build system. The Simba build system has more features than to the other two. It supports executing test suites, generating code coverage, profiling and more. Still, if you are familiar with Arduino IDE or PlatformIO, use that instead since it will be less troublesome.
PlatformIO¶
Install Simba in PlatformIO.
Arduino IDE¶
Install Simba in the Arduino IDE 1.6.10 as a third party board using the Boards Manager.
Open File -> Preferences.
Add these URL:s to Additional Boards Manager URLs (click on the icon to the right of the text field) and press OK.
https://raw.githubusercontent.com/eerimoq/simba-releases/master/arduino/avr/package_simba_avr_index.json https://raw.githubusercontent.com/eerimoq/simba-releases/master/arduino/sam/package_simba_sam_index.json https://raw.githubusercontent.com/eerimoq/simba-releases/master/arduino/esp/package_simba_esp_index.json https://raw.githubusercontent.com/eerimoq/simba-releases/master/arduino/esp32/package_simba_esp32_index.json
Open Tools -> Board: ... -> Boards Manager... and type simba in the search box.
Click on Simba by Erik Moqivst version x.y.z and click Install and press Close.
Open Tools -> Board: ... -> Boards Manager... and select one of the Simba boards in the list.
Open File -> Examples -> Simba -> hello_world.
Verify and upload the sketch to your device.
Done!
Simba build system¶
The Simba development environment can be installed on Windows (Cygwin) and Linux (Ubuntu 14). Just follow the steps below and you’ll be up and running in no time. =)
Windows (Cygwin)¶
Download Cygwin and select the following packages for installation:
NOTE: ESP8266 is not supported in Cygwin because there is no toolchain available.
- gcc-core (Devel -> gcc-core)
- make (Devel -> make)
- python (Python -> python)
- python-setuptools (Python -> python-setuptools)
- git (Devel -> git)
- doxygen (Devel -> doxygen)
Start Cygwin and execute the one-liner below to install Simba.
$ mkdir simba && \
cd simba && \
easy_install-2.7 pip && \
pip install pyserial xpect readchar sphinx breathe && \
git clone https://github.com/eerimoq/avr-toolchain-windows && \
git clone https://github.com/eerimoq/arm-toolchain-windows && \
git clone https://github.com/eerimoq/simba
Linux (Ubuntu 14)¶
Execute the one-liner below to install Simba.
$ mkdir simba && \
cd simba && \
sudo apt install ckermit valgrind cppcheck cloc python python-pip doxygen git lcov && \
sudo apt install avrdude gcc-avr binutils-avr gdb-avr avr-libc && \
sudo apt install bossa-cli gcc-arm-none-eabi && \
sudo apt install make unrar autoconf automake libtool gcc g++ gperf \
flex bison texinfo gawk ncurses-dev libexpat-dev \
python-serial sed libtool-bin pmccabe && \
sudo pip install pyserial xpect readchar sphinx breathe sphinx_rtd_theme && \
(git clone --recursive https://github.com/pfalcon/esp-open-sdk && \
cd esp-open-sdk && \
make) && \
wget https://github.com/eerimoq/simba-releases/raw/master/arduino/esp32/tools/xtensa-esp32-elf-linux$(getconf LONG_BIT)-1.22.0-59.tar.gz && \
tar xf xtensa-esp32-elf-linux$(getconf LONG_BIT)-1.22.0-59.tar.gz && \
rm xtensa-esp32-elf-linux$(getconf LONG_BIT)-1.22.0-59.tar.gz && \
git clone --recursive https://github.com/eerimoq/simba
Post-install¶
Let’s build and run the hello world application to verify that the installation was successful.
$ cd simba && \
source setup.sh && \
cd examples/hello_world && \
make -s run
User Guide¶
This guide is intended for users of the Simba Embedded Programming Platform and the Simba build system. Parts of the guide is applicable to other build systems as well, in particular the configuration section.
The Simba installation guide can be found on the Installation page.
Software architecture¶
Below is a picture of all packages and their relation to the hardware. At the bottom is the hardware. On top of the hardware is the kernel and drivers packages, which exports a hardware independent interface that other packages and the user application can use. The user application on the right can use any package, and in rare cases directly access the hardware registers.
Contents:
Environment setup¶
The first step is always to setup the Simba environment. It’s a simple matter of sourcing a setup-script in the simba root folder.
$ cd simba/simba
$ source setup.sh
Hello World application¶
Let’s start with the Simba “Hello World” application. It examplifies what an application is and how to build and run it.
It consists of two files; main.c
and Makefile
.
main.c¶
main.c defines the
application entry function main()
.
#include "simba.h"
int main()
{
/* Start the system. */
sys_start();
std_printf(FSTR("Hello world!\n"));
}
Makefile¶
Makefile contains build configuration of the application.
NAME = hello_world
BOARD ?= linux
RUN_END_PATTERN = "Hello world!"
RUN_END_PATTERN_SUCCESS = "Hello world!"
SIMBA_ROOT = ../..
include $(SIMBA_ROOT)/make/app.mk
Build and run¶
Compile, link and run it by typing the commands below in a shell:
$ cd examples/hello_world
$ make -s run
<build system output>
Hello world!
$
Cross-compile, link and then run on an Arduino Due:
$ cd examples/hello_world
$ make -s BOARD=arduino_due run
<build system output>
Hello world!
$
Applications, packages and modules¶
Simba has three software components; the application, the package and the module.
Application¶
An application is an executable consisting of zero or more packages.
An application file tree can either be created manually or by using the tool simba.
myapp
├── main.c
└── Makefile
Build and run often! More to be added, hopefully.
Package¶
A package is a container of modules.
A package file tree can either be created manually or by using the tool simba.
A package file tree must be organized as seen below. This is required by the build framework and Simba tools.
See the inline comments for details about the files and folders contents.
mypkg
├── mypkg
│ ├── doc # package documentation
│ ├── __init__.py
│ ├── src # package source code
│ │ ├── mypkg
│ │ │ ├── module1.c
│ │ │ └── module1.h
│ │ ├── mypkg.h # package header file
│ │ └── mypkg.mk # package makefile
│ └── tst # package test code
│ └── module1
│ ├── main.c
│ └── Makefile
└── setup.py
The package development workflow is fairly straight forward. Suppose
we want to add a new module to the file tree above. Create
src/mypkg/module2.h
and src/mypkg/module2.c
, then include
mypkg/module2.h
in src/mypkg.h
and add mypkg/module2.c
to
the list of source files in src/mypkg.mk
. Create a test suite for
the module. It consists of the two files tst/module2/main.c
and
tst/module2/Makefile
.
It’s often conveniant to use an existing modules’ files as skeleton for the new module.
After adding the module module2
the file tree looks like this.
mypkg
├── mypkg
│ ├── doc
│ ├── __init__.py
│ ├── src
│ │ ├── mypkg
│ │ │ ├── module1.c
│ │ │ ├── module1.h
│ │ │ ├── module2.c
│ │ │ └── module2.h
│ │ ├── mypkg.h
│ │ └── mypkg.mk
│ └── tst
│ ├── module1
│ │ ├── main.c
│ │ └── Makefile
│ └── module2
│ ├── main.c
│ └── Makefile
└── setup.py
Now, build and run the test suite to make sure the empty module implementation compiles and can be executed.
$ cd tst/module2
$ make -s run
Often the module development is started by implementing the module header file and at the same time write test cases. Test cases are not only useful to make sure the implementation works, but also to see how the module is intended to be used. The module interface becomes cleaner and easier to use it you actually start to use it yourself by writing test cases! All users of your module will benefit from this!
So, now we have an interface and a test suite. It’s time to start the implementation of the module. Usually you write some code, then run the test suite, then fix the code, then run the tests again, then you realize the interface is bad, change it, change the implementation, change the test, change, change... and so it goes on until you are satisfied with the module.
Try to update the comments and documentation during the development process so you don’t have to do it all in the end. It’s actually quite useful for yourself to have comments. You know, you forget how to use your module too!
The documentation generation framework uses doxygen, breathe and sphinx. That means, all comments in the source code should be written for doxygen. Breathe takes the doxygen output as input and creates input for sphinx. Sphinx then generates the html documentation.
Just run make
in the doc
folder to generate the html
documentation.
$ cd doc
$ make
$ firefox _build/html/index.html # open the docs in firefox
All exported symbols in a package must have the prefix
<package>_<module>_
. This is needed to avoid namespace clashes
between modules with the same name in different packages.
There cannot be two packages with the same name, for the namespace reason. All packages must have unique names! There is one exception though, the three Simba packages; kernel, drivers and slib. Those packages does not have the package name as prefix on exported symbols.
int mypackage_module1_foo(void);
int mypackage_module2_bar(void);
Module¶
A module is normally a header and a source file.
Configuration¶
Standard Library¶
The Library Reference is configured at compile time using
defines named CONFIG_*
. The default configuration includes most
functionality, as most application wants that. If an application has
special requirements, for example memory constraints, it has to be
configured to remove unnecessaray functionality.
Highest priority first.
- Command line as
CDEFS_EXTRA="<configuration variable>=<value>"
. - A file named
config.h
in the application root folder. - The default configuration file, src/config_default.h.
- The variable
build_flags
inplatformio.ini
asbuild_flags = -D<configuration variable>=<value>
. - A file named
config.h
in the application source foldersrc
. - The default configuration file, src/config_default.h.
- A file (also called a tab) named
config.h
in the sketch. - The default configuration file, src/config_default.h.
All configuration variables are listed below. Their default values are defined in src/config_default.h.
Defines
-
CONFIG_SYS_CONFIG_STRING
¶
-
CONFIG_SYS_SIMBA_MAIN_STACK_MAX
¶ Main thread stack size for ports with a fixed size main thread stack.
-
CONFIG_ASSERT
¶ Assertions are used to check various conditions during the application execution. A typical usage is to validate function input arguments.
-
CONFIG_DEBUG
¶ Include more debug information.
-
CONFIG_FS_CMD_DS18B20_LIST
¶ Debug file system command to list all DS18B20 sensors on the bus.
-
CONFIG_FS_CMD_ESP_WIFI_STATUS
¶ Debug file system command to print the Espressif WiFi status.
-
CONFIG_FS_CMD_FS_APPEND
¶ Debug file system command to append to a file.
-
CONFIG_FS_CMD_FS_COUNTERS_LIST
¶ Debug file system command to list all counters.
-
CONFIG_FS_CMD_FS_COUNTERS_RESET
¶ Debug file system command to set all counters to zero.
-
CONFIG_FS_CMD_FS_FILESYSTEMS_LIST
¶ Debug file system command to list all registered file systems.
-
CONFIG_FS_CMD_FS_LIST
¶ Debug file system command to list all registered file systems.
-
CONFIG_FS_CMD_FS_FORMAT
¶ Debug file system command to format a file system.
-
CONFIG_FS_CMD_FS_PARAMETERS_LIST
¶ Debug file system command to list all parameters.
-
CONFIG_FS_CMD_FS_READ
¶ Debug file system command to read from a file.
-
CONFIG_FS_CMD_FS_REMOVE
¶ Debug file system command to remove a file.
-
CONFIG_FS_CMD_FS_WRITE
¶ Debug file system command to write to a file.
-
CONFIG_FS_CMD_I2C_READ
¶ Debug file system command to read from a i2c bus.
-
CONFIG_FS_CMD_I2C_WRITE
¶ Debug file system command to write to a i2c bus.
-
CONFIG_FS_CMD_LOG_LIST
¶ Debug file system command to list all log objects.
-
CONFIG_FS_CMD_LOG_PRINT
¶ Debug file system command to create a log entry and print it. Mainly used for debugging.
-
CONFIG_FS_CMD_LOG_SET_LOG_MASK
¶ Debug file system command to set the log mask of a log object.
-
CONFIG_FS_CMD_NETWORK_INTERFACE_LIST
¶ Debug file system command to list all network interfaces.
-
CONFIG_FS_CMD_PIN_READ
¶ Debug file system command to read the current value of a pin.
-
CONFIG_FS_CMD_PIN_SET_MODE
¶ Debug file system command to set the mode of a pin.
-
CONFIG_FS_CMD_PIN_WRITE
¶ Debug file system command to write a value to a pin.
-
CONFIG_FS_CMD_PING_PING
¶ Debug file system command to ping a host.
-
CONFIG_FS_CMD_SERVICE_LIST
¶ Debug file system command to list all services.
-
CONFIG_FS_CMD_SERVICE_START
¶ Debug file system command to start a service.
-
CONFIG_FS_CMD_SERVICE_STOP
¶ Debug file system command to stop a services.
-
CONFIG_FS_CMD_SETTINGS_LIST
¶ Debug file system command to list all settings.
-
CONFIG_FS_CMD_SETTINGS_READ
¶ Debug file system command to read the value of a setting.
-
CONFIG_FS_CMD_SETTINGS_RESET
¶ Debug file system command to reset the settings to their original values.
-
CONFIG_FS_CMD_SETTINGS_WRITE
¶ Debug file system command to write a value to a setting.
-
CONFIG_FS_CMD_SYS_CONFIG
¶ Debug file system command to print the system configuration.
-
CONFIG_FS_CMD_SYS_INFO
¶ Debug file system command to print the system information.
-
CONFIG_FS_CMD_SYS_UPTIME
¶ Debug file system command to print the system uptime.
-
CONFIG_FS_CMD_SYS_REBOOT
¶ Debug file system command to reboot the system uptime.
-
CONFIG_FS_CMD_THRD_LIST
¶ Debug file system command to list threads’ information.
-
CONFIG_FS_CMD_THRD_SET_LOG_MASK
¶ Debug file system command to set the log mask of a thread.
-
CONFIG_FS_CMD_USB_DEVICE_LIST
¶ Debug file system command to list all USB devices.
-
CONFIG_FS_CMD_USB_HOST_LIST
¶ Debug file system command to list all USB devices connected to the USB host.
-
CONFIG_FS_PATH_MAX
¶ The maximum length of an absolute path in the file system.
-
CONFIG_MONITOR_THREAD
¶ Start the monitor thread to gather statistics of the scheulder.
-
CONFIG_PREEMPTIVE_SCHEDULER
¶ Use a preemptive scheduler.
-
CONFIG_PROFILE_STACK
¶ Profile the stack usage in runtime. It’s a cheap operation and is recommended to have enabled.
-
CONFIG_SETTINGS_AREA_SIZE
¶ Size of the settings area. This size MUST have the same size as the settings generated by the settings.py script.
-
CONFIG_SHELL_COMMAND_MAX
¶ Maximum number of characters in a shell command.
-
CONFIG_SHELL_HISTORY_SIZE
¶ Size of the shell history buffer.
-
CONFIG_SHELL_MINIMAL
¶ Minimal shell functionality to minimize the code size of the shell module.
-
CONFIG_SHELL_PROMPT
¶ The shell prompt string.
-
CONFIG_SOCKET_RAW
¶ Raw socket support.
-
CONFIG_SPIFFS
¶ SPIFFS is a flash file system applicable for boards that has a reasonably big modifiable flash.
-
CONFIG_START_CONSOLE
¶ Start the console device (UART/USB CDC) on system startup.
-
CONFIG_START_CONSOLE_DEVICE_INDEX
¶ Console device index.
-
CONFIG_START_CONSOLE_UART_BAUDRATE
¶ Console UART baudrate.
-
CONFIG_START_CONSOLE_USB_CDC_CONTROL_INTERFACE
¶ Console USB CDC control interface number.
-
CONFIG_START_CONSOLE_USB_CDC_ENDPOINT_IN
¶ Console USB CDC input endpoint.
-
CONFIG_START_CONSOLE_USB_CDC_ENDPOINT_OUT
¶ Console USB CDC output endpoint.
-
CONFIG_START_CONSOLE_USB_CDC_WAIT_FOR_CONNETION
¶ Wait for the host to connect after starting the console.
-
CONFIG_START_FILESYSTEM
¶ Configure a default file system.
-
CONFIG_START_FILESYSTEM_ADDRESS
¶ Configure a default file system start address.
-
CONFIG_START_FILESYSTEM_SIZE
¶ Configure a default file system size.
-
CONFIG_START_NETWORK
¶ Setup the ip stack and connect to all configured networks.
-
CONFIG_START_NETWORK_INTERFACE_WIFI_CONNECT_TIMEOUT
¶ WiFi connect timeout is seconds.
-
CONFIG_START_NETWORK_INTERFACE_WIFI_SSID
¶ SSID of the WiFi to connect to.
-
CONFIG_START_NETWORK_INTERFACE_WIFI_PASSWORD
¶ Password of the WiFi to connect to.
-
CONFIG_START_SHELL
¶ Start a shell thread communication over the console channels.
-
CONFIG_START_SHELL_PRIO
¶ Shell thread priority.
-
CONFIG_START_SHELL_STACK_SIZE
¶ Shell thread stack size in words.
-
CONFIG_STD_OUTPUT_BUFFER_MAX
¶ Maximum number of bytes in the print output buffer.
-
CONFIG_SYSTEM_TICK_FREQUENCY
¶ System tick frequency in Hertz.
-
CONFIG_THRD_CPU_USAGE
¶ Calculate thread CPU usage.
-
CONFIG_THRD_ENV
¶ Each thread has a list of environment variables associated with it. A typical example of an environment variable is “CWD” - Current Working Directory.
-
CONFIG_THRD_IDLE_STACK_SIZE
¶ Stack size of the idle thread.
-
CONFIG_THRD_SCHEDULED
¶ Count the number of times each thread has been scheduled.
-
CONFIG_THRD_TERMINATE
¶ Threads are allowed to terminate.
-
CONFIG_USB_DEVICE_VID
¶ USB device vendor id.
-
CONFIG_USB_DEVICE_PID
¶ USB device product id.
lwIP¶
Use config.h
to fully configure lwIP and all of its modules. You
do not need to define every option that lwIP provides; if you do not
define an option, a default value will be used. Therefore, your
config.h
provides a way to override much of the behavior of lwIP.
By default Simba overrides a few of the variables in src/inet/lwipopts.h.
You can tune your code size by only compiling the features you really need. The following is a list of what gets compiled in “out of the box” with lwIP.
Default inclusions:
- ARP (
LWIP_ARP
) - IP and fragmentation (
IP_FRAG
) and reassembly (IP_REASSEMBLY
) - Raw IP PCB support (
LWIP_RAW
) - UDP (
LWIP_UDP
) and UDP-Lite (LWIP_UDPLITE
) - TCP (
LWIP_TCP
) – this is a big one! - Statistics (
LWIP_STATS
)
Default exclusions:
- DHCP (
LWIP_DHCP
) - AUTOIP (
LWIP_AUTOIP
) - SNMP (
LWIP_SNMP
) - IGMP (
LWIP_IGMP
) - PPP (
PPP_SUPPORT
)
If you would like to change this, then you just need to set the
options listed below. For example, if you would like to disable UDP
and enable DHCP, the following config.h
file would do it:
/* Disable UDP */
#define LWIP_UDP 0
/* Enable DHCP */
#define LWIP_DHCP 1
In an embedded environment, memory pools make for fast and efficient memory allocation. lwIP provides a flexible way to manage memory pool sizes and organization.
lwIP reserves a fixed-size static chunk of memory in the data segment,
which is subdivided into the various pools that lwip uses for the
various data structures. For example, there is a pool just for struct
tcp_pcb’s, and another pool just for struct udp_pcb’s. Each pool can
be configured to hold a fixed number of data structures; this number
can be changed in the config.h
file by changing the various
MEMP_NUM_*
values. For example, MEMP_NUM_TCP_PCB
and
MEMP_NUM_UDP_PCB
control the maximum number of tcp_pcb and udp_pcb
structures that can be active in the system at any given time.
It is also possible to create custom memory pools in addition to the standard ones provided by lwIP.
lwIP uses a custom function mem_malloc for all dynamic allocation; therefore, it is easy to change how lwIP uses its RAM. There are three possibilities provided out-of-the-box:
- (default) lwIP’s custom heap-based mem_malloc. By default, lwIP
uses a statically-allocated chunk of memory like a heap for all
memory operations. Use
MEM_SIZE
to change the size of the lwIP heap. - C standard library malloc and free. If you wish to have lwIP use
the standard library functions provided by your
compiler/architecture, then define the option
MEM_LIBC_MALLOC
. - Memory pools. lwIP can also emulate dynamic allocation using custom
memory pools (see that chapter for more information). This involves
the options
MEM_USE_POOLS
andMEMP_USE_CUSTOM_POOLS
and a new custom filelwippools.h
.
lwIP uses memory for:
code (depending on your system, may use ROM instead of RAM)
statically allocated variables (some initialized, some not initialized)
task stack
dynamically allocated memory
- heap
- memp pools
Unless you use a C library heap implementation (by defining
MEM_LIBC_MALLOC
to 1), dynamically allocated memory must be statically
allocated somewhere. This means you reserve a specific amount of
memory for the heap or the memp pools from which the code dynamically
allocates memory at runtime.
The size of this heap and memp pools can be adjusted to save RAM:
There are 3 types of pbufs:
- REF/ROM, RAM and POOL.
PBUF_POOL_SIZE
*PBUF_POOL_BUFSIZE
only refers to type POOL. - RAM pbufs are allocated in the memory defined by
MEM_SIZE
(this memory is not used much aside from RAM pbufs) - this is the heap and it is allocated as mem_memory. - REF/ROM pbufs as well as pcbs and some other stuff is allocated from
dedicated pools per structure type. The amount of structures is
defined by the various
MEMP_NUM_
defines. Together, this memory is allocated as memp_memory and it includes the pbuf POOL.
However, if you define MEMP_MEM_MALLOC
to 1 in your config.h
,
every piece of dynamically allocated memory will come from the heap
(the size of which is defined by MEM_SIZE
). If you then even
define MEM_LIBC_MALLOC
to 1, too, lwIP doesn’t need extra memory
for dynamically allocated memory but only uses the C library heap
instead. However, you then have to make sure that this heap is big
enough to run your application.
To tweak the various MEMP_NUM_
defines, define LWIP_STATS=1
and LWIP_STATS_DISPLAY=1
and call stats_display() to see how
many entries of each pool are used (or have a look at the global
variable lwip_stats
instead).
To see the options that you can set, open 3pp/lwip-1.4.1/src/include/lwip/opt.h. This file is fully commented and explains how many of the options are used.
Build system¶
The Simba build system is based on GNU Make.
Targets¶
Name | Description |
---|---|
all | Compile and link the application. |
clean | Remove all generated files and folders. |
new | clean + all |
upload | all + Upload the application to the device. |
console | Open a serial console on /dev/arduino with baudrate BAUDRATE. |
run | all + upload + Wait for application output. |
run-debugger | Run the application in the debugger, break at main. |
report | Print the test report from a previous run. |
test | run + report |
release | Compile with NASSERT=yes and NDEBUG=yes. |
size | Print application size information. |
help | Show the help. |
Variables¶
There are plenty of make variables used to control the build process. Below is a list of the most frequently used variables. The advanced user may read the make files in make.
Name | Description |
---|---|
SIMBA_ROOT | Path to the Simba root folder. |
BOARD | The BOARD variable selects which board to build for. It can be assigned to one of the boards listed here. For example, the command to build for Arduino Due is make BOARD=arduino_due . |
BAUDRATE | Serial port baudrate used by console and run targets. |
VERSION | The application version string. Usually on the form <major>.<minor>.<revision>. |
SETTINGS_INI | Path to the settings file. |
INC | Include paths. |
SRC | Source files (.c, .asm, .rs). |
CFLAGS_EXTRA | Extra flags passed to the compiler. |
LDFLAGS_EXTRA | Extra flags passed to the linker. |
NASSERT | Build the application without assertions. |
simba¶
The program simba is used to manage Simba packages and applications.
The main purpose of simba is to distribute software in the Simba community, just like pip for Python.
How to create an application skeletorn¶
The code block below shows how to create an new application using simba. After the application has been created, it is built and executed.
$ mkdir myapp
$ cd myapp
$ simba application init
Application name [foo]: <Enter>
Author [erik]: <Enter>
Version [0.3.0]: <Enter>
$ tree .
.
├── main.c
└── Makefile
$ make -s run
How to create a package¶
The code block below shows how to create a new package using simba. After the package has been created, the generated test suite is built and executed.
$ mkdir mypkg
$ cd mypkg
$ simba package init
Package name [foo]: <Enter>
Author [erik]: <Enter>
Version [0.3.0]: <Enter>
$ tree
.
├── mypkg
│ ├── doc
│ │ ├── about.rst
│ │ ├── api-reference.rst
│ │ ├── conf.py
│ │ ├── doxygen.cfg
│ │ ├── index.rst
│ │ ├── Makefile
│ │ ├── mypkg
│ │ │ └── hello.rst
│ │ ├── requirements.txt
│ │ └── sphinx.mk
│ ├── __init__.py
│ ├── src
│ │ ├── mypkg
│ │ │ ├── hello.c
│ │ │ └── hello.h
│ │ ├── mypkg.h
│ │ └── mypkg.mk
│ └── tst
│ └── hello
│ ├── main.c
│ └── Makefile
└── setup.py
$ cd mypkg/tst/hello
$ make -s test
In the output from tree
below, two files may catch your
eyes; setup.py and __init__.py. Those are Python files and are often
seen in Python packages. They are present in a Simba package because
Simba uses the Python tool pip to release and install
packages. The idea is that everyone that implements a useful package
should release it and make it available for other users to install,
just as Python!
How to release a package¶
This is how to release a package. Two files are created, one with the
suffix tar.gz
and one with the suffix .whl
. The .whl
-file
is input to the installation command, described in the next section.
$ cd ../../..
$ simba package release
$ tree dist
dist
├── mypkg-0.1-py2.py3-none-any.whl
└── mypkg-0.1.tar.gz
How to install a package¶
This is how to install a package in ${SIMBA_ROOT}/dist-packages
.
$ simba package install dist/mypkg-0.1-py2.py3-none-any.whl
Developer Guide¶
This guide is intended for developers of the Simba Embedded Programming Platform. Users are advised to read the User Guide instead.
Contents:
Boards and mcus¶
A board is the top level configuration entity in the build framework. It contains information about the MCU and the pin mapping.
In turn, the MCU contains information about available devices and clock frequencys in the microcontroller.
See src/boards/ and src/mcus for available configurations.
Only one MCU per board is supported. If there are two MCU:s on one physical board, two board configurations have to be created, one for each MCU.
The porting guide Porting shows how to port Simba to a new board.
Threads and channels¶
A thread is the basic execution entity. A scheduler controls the execution of threads.
A simple thread that waits to be resumed by another thread.
#include "simba.h"
void *my_thread_main(void *arg_p)
{
UNUSED(arg_p);
while (1) {
thrd_suspend(NULL);
std_printf(FSTR("Thread resumed.\r\n"));
}
return (NULL);
}
Threads usually communicates over channels. There are two kinds of channels; queue and event. Both implementing the same abstract channel interface (see src/kernel/chan.h). This abstraction makes channel very powerful as a synchronization primitive. They can be seen as limited functionality file descriptors in linux.
The most common channel is the queue. It can be either synchronous or semi-asynchronous. In the synchronous version the writing thread will block until all written data has been read by the reader. In the semi-asynchronous version the writer writes to a buffer within the queue, and only blocks all data does not fit in the buffer. The buffer size is selected by the application.
File tree¶
simba - this directory
├── 3pp - third party products
├── bin - executables and scripts
├── doc - documentation source
├── environment - environment setup
├── examples - example applications
├── LICENSE - license
├── make - build and run files
├── README.rst - readme
├── setup.sh - setup script
├── src - source code directory
│ ├── alloc - alloc package
│ ├── boards - board configurations
│ ├── collections - collections package
│ ├── debug - debug package
│ ├── drivers - drivers package
│ ├── encode - encode package
│ ├── filesystems - filesystems package
│ ├── hash - hash package
│ ├── inet - inet package
│ ├── kernel - kernel package
│ ├── mcus - mcu configurations
│ ├── multimedia - multimedia package
│ ├── oam - oam package
│ ├── sync - sync package
│ ├── text - text package
│ ├── simba.h - includes all package headers
│ └── simba.mk - build system configuration
├── tst - test suites
│ ├── alloc - alloc package test suite
│ ├── collections - collections package test suite
│ ├── debug - debug package test suite
│ ├── drivers - drivers package test suite
│ ├── encode - encode package test suite
│ ├── filesystems - filesystems package test suite
│ ├── hash - hash package test suite
│ ├── inet - inet package test suite
│ ├── kernel - kernel package test suite
│ ├── multimedia - multimedia package test suite
│ ├── oam - oam package test suite
│ ├── sync - sync package test suite
│ └── text - text package test suite
└── VERSION.txt - `Simba` version
Testing¶
To ensure high code quility each module is tested extensively by many test suites. The test suites are executed both on native Linux and on many of the supported boards. See Test suites for a list of all test suites that are executed before each release.
The native Linux test suites are executed automatically on each commit.
Test result: https://travis-ci.org/eerimoq/simba
Code coverage: https://codecov.io/gh/eerimoq/simba
Hardware setup¶
Below is a picture of all supported boards connected to a USB hub. The USB hub is connected to a linux PC (not in the picture) that executes test suites on all boards.
A short description of the setup:
- The DS3231 device (on the breadboard to the left) is connected over i2c to the Arduino Mega.
- CAN0 is connected to CAN1 on the Arduino Due. The CAN driver is tested by sending frames between the two CAN devices.
- The UART of the STM32VLDISCOVERY board is connected to a serial to USB adaptor. DTR on the adaptor is used to reset the board.
- The ESP-12E Development Board also has a serial to USB adaptor connected. RTS is used to set the board in flashing mode (GPIO0) and DTR is used to reset the board (REST).
Test suites¶
Below is a list of all test suites that are executed before every release. They are listed per board.
Arduino Due¶
- kernel/sys
- kernel/thrd
- kernel/time
- kernel/timer
- sync/bus
- sync/event
- sync/queue
- sync/rwlock
- sync/sem
- collections/binary_tree
- collections/bits
- collections/fifo
- collections/hash_map
- alloc/circular_heap
- alloc/heap
- text/configfile
- text/std
- text/re
- debug/log
- oam/settings
- oam/shell
- filesystems/fs
- filesystems/spiffs
- encode/base64
- encode/json
- hash/crc
- hash/sha1
- inet/http_server
- inet/http_websocket_client
- inet/http_websocket_server
- inet/inet
- inet/mqtt_client
- inet/ping
- drivers/chipid
- drivers/can
- drivers/flash
- drivers/pin
Arduino Mega¶
- kernel/sys
- kernel/thrd
- kernel/time
- kernel/timer
- sync/bus
- sync/event
- sync/queue
- sync/rwlock
- sync/sem
- collections/binary_tree
- collections/bits
- collections/fifo
- collections/hash_map
- alloc/circular_heap
- alloc/heap
- text/configfile
- text/std
- text/re
- debug/log
- oam/settings
- oam/shell
- filesystems/fat16
- filesystems/fs
- encode/base64
- hash/crc
- hash/sha1
- inet/http_websocket_client
- inet/http_websocket_server
- inet/inet
- inet/mqtt_client
- inet/ping
- drivers/adc
- drivers/analog_input_pin
- drivers/ds3231
- drivers/sd
- drivers/pin
Arduino Nano¶
Arduino Pro Micro¶
Arduino Uno¶
Cygwin¶
ESP-01¶
ESP-12E Development Board¶
- kernel/sys
- kernel/thrd
- kernel/timer
- sync/bus
- sync/event
- sync/queue
- sync/rwlock
- sync/sem
- collections/binary_tree
- collections/bits
- collections/fifo
- collections/hash_map
- alloc/circular_heap
- text/std
- text/re
- debug/log
- oam/shell
- encode/base64
- encode/json
- hash/crc
- hash/sha1
- inet/http_websocket_client
- inet/http_websocket_server
- inet/inet
- inet/mqtt_client
- inet/network_interface/wifi_esp
- inet/ping
- drivers/pin
- filesystems/fs
- filesystems/spiffs
Linux¶
- kernel/sys
- kernel/thrd
- kernel/time
- kernel/timer
- sync/bus
- sync/chan
- sync/event
- sync/queue
- sync/rwlock
- sync/sem
- collections/binary_tree
- collections/bits
- collections/fifo
- collections/hash_map
- alloc/circular_heap
- alloc/heap
- text/configfile
- text/std
- text/re
- debug/log
- oam/service
- oam/settings
- oam/shell
- filesystems/fat16
- filesystems/fs
- filesystems/spiffs
- encode/base64
- encode/json
- hash/crc
- hash/sha1
- inet/http_server
- inet/http_websocket_client
- inet/http_websocket_server
- inet/inet
- inet/mqtt_client
- inet/ping
- multimedia/midi
Nano32¶
- kernel/sys
- kernel/thrd
- kernel/timer
- sync/bus
- sync/event
- sync/queue
- sync/rwlock
- sync/sem
- collections/binary_tree
- collections/bits
- collections/fifo
- collections/hash_map
- alloc/circular_heap
- text/std
- text/re
- debug/log
- oam/shell
- encode/base64
- encode/json
- hash/crc
- hash/sha1
- inet/http_websocket_client
- inet/http_websocket_server
- inet/inet
- inet/network_interface/wifi_esp
- inet/ping
- filesystems/fs
- filesystems/spiffs
NodeMCU¶
Particle IO Photon¶
- kernel/sys
- kernel/thrd
- kernel/time
- kernel/timer
- sync/bus
- sync/event
- sync/queue
- sync/rwlock
- sync/sem
- collections/binary_tree
- collections/bits
- collections/fifo
- collections/hash_map
- alloc/circular_heap
- text/std
- text/re
- debug/log
- oam/shell
- encode/base64
- encode/json
- hash/crc
- hash/sha1
- inet/http_websocket_client
- inet/http_websocket_server
- inet/inet
- inet/mqtt_client
- inet/ping
STM32F3DISCOVERY¶
STM32VLDISCOVERY¶
- kernel/sys
- kernel/thrd
- kernel/timer
- sync/bus
- sync/event
- sync/queue
- sync/rwlock
- sync/sem
- collections/binary_tree
- collections/bits
- collections/fifo
- collections/hash_map
- alloc/circular_heap
- text/std
- text/re
- debug/log
- oam/shell
- encode/base64
- encode/json
- hash/crc
- hash/sha1
- inet/http_websocket_client
- inet/http_websocket_server
- inet/inet
- inet/mqtt_client
- inet/ping
- drivers/pin
Releasing¶
Follow these steps to create a new release:
Write the new version in
VERSION.txt
. The version should hace the format<major>.<minor>.<revision>
.Increment
<major>
for non-backwards compatible changes.Increment
<minor>
for new features.Increment
<revision>
for bug fixes.Write the new version in
package.json
. This file is used by PlatformIO 3 to find the current Simba release.Run the test suites and generate the documentation.
make -s test-all-boards make -s release-test
Generate files for Arduino.
make -s arduino
Add the new releases to
make/arduino/<family>/package_simba_<family>_index.json
. The sha256 sums of the zip-archives are calculated bymake -s arduino
and written tosimba-arduino/*.sha256
.Copy the Simba Arduino releases to the release repository, add, commit and push in the release repository.
cp simba-arduino/simba-arduino-avr-*.zip ../simba-releases/arduino/avr cp simba-arduino/simba-arduino-sam-*.zip ../simba-releases/arduino/sam cp simba-arduino/simba-arduino-esp-*.zip ../simba-releases/arduino/esp cp simba-arduino/simba-arduino-esp32-*.zip ../simba-releases/arduino/esp32
Start a http server used to download package manifests in the Arduino IDE.
(cd make/arduino && python -m SimpleHTTPServer)
Start the Arduino IDE and add these URL:s in Preferences.
http://localhost:8000/avr/package_simba_avr_index.json http://localhost:8000/esp/package_simba_esp_index.json http://localhost:8000/esp32/package_simba_esp32_index.json http://localhost:8000/sam/package_simba_sam_index.json
Install all four packages and run the blink example for each one of them.
Commit the changes, and tag the commit with the new version.
Push the new commit and tag.
Copy the Simba Arduino package manifests the release repository, add, commit and push in the release repository.
cp make/arduino/avr/package_simba_avr_index.json ../simba-releases/arduino/avr cp make/arduino/sam/package_simba_sam_index.json ../simba-releases/arduino/sam cp make/arduino/esp/package_simba_esp_index.json ../simba-releases/arduino/esp cp make/arduino/esp32/package_simba_esp32_index.json ../simba-releases/arduino/esp32
- Download the release zip-file from Github and calculate its SHA1
checksum. Add the zip-file to the release repository and add the
new releases to
make/platformio/manifest.json
.
wget https://github.com/eerimoq/simba/archive/<version>.zip sha1sum <version>.zip cp <version>.zip ../simba-releases/platformio
- Commit and push.
- Done.
Porting¶
Often the board you want to use in your project is not yet supported
by Simba. If you are lucky, Simba is already ported to the MCU on
your board. Just create a folder with you board name in
src/boards/ and populate it with the board.h
,
board.c
and board.mk
. If Simba is not ported to your MCU,
the kernel and drivers has to be ported.
Kernel¶
Porting the kernel is a matter of configuring the system tick timer and inplement a few locking primitives. If you are familiar with your CPU, the port can be implemented quickly.
A kernel port is roughly 300 lines of code.
Kernel ports are implemented in src/kernel/ports.
Drivers¶
The required work to port the drivers depends of which drivers you are intrested in. The more drivers you have to port, the longer time it takes, obviously.
A drivers port is roughly 100 lines of code per driver.
Drivers ports are implemented in src/drivers/ports.
Boards¶
The boards supported by Simba.
Arduino Due¶
Pinout¶
Default system features¶
The default configuration includes those major features. They are all
initialized by sys_start()
at the startup of the application.
- Console.
- File system.
- Debug shell.
Drivers¶
Supported drivers for this board.
- adc — Analog to digital convertion
- analog_input_pin — Analog input pin
- can — Controller Area Network
- chipid — Chip identity
- dac — Digital to analog convertion
- ds18b20 — One-wire temperature sensor
- exti — External interrupts
- flash — Flash memory
- i2c_soft — Software I2C
- mcp2515 — CAN BUS chipset
- owi — One-Wire Interface
- pin — Digital pins
- sd — Secure Digital memory
- spi — Serial Peripheral Interface
- uart — Universal Asynchronous Receiver/Transmitter
- usb — Universal Serial Bus
- usb_host — Universal Serial Bus - Host
Library Reference¶
Read more about board specific functionality in the Arduino Due module documentation in the Library Reference.
Memory usage¶
Below is the memory usage of two applications:
- The minimal-configuration application is configured to only include the bare minimum of functionality for the low level kernel to run. That is, the thread scheduler and system tick.
- The default-configuration application is built with the default configuration, including a lot more functionality. See the list of Default system features above for a summary.
Application | Flash | RAM |
---|---|---|
minimal-configuration | 21540 | 5464 |
default-configuration | 94568 | 11034 |
Default configuration¶
Default Standard Library configuration.
Arduino Mega¶
Pinout¶
Default system features¶
The default configuration includes those major features. They are all
initialized by sys_start()
at the startup of the application.
Drivers¶
Supported drivers for this board.
- adc — Analog to digital convertion
- analog_input_pin — Analog input pin
- analog_output_pin — Analog output pin
- ds18b20 — One-wire temperature sensor
- ds3231 — RTC clock
- exti — External interrupts
- i2c — I2C
- i2c_soft — Software I2C
- mcp2515 — CAN BUS chipset
- nrf24l01 — Wireless communication
- owi — One-Wire Interface
- pin — Digital pins
- pwm — Pulse width modulation
- sd — Secure Digital memory
- spi — Serial Peripheral Interface
- uart — Universal Asynchronous Receiver/Transmitter
- uart_soft — Bitbang UART
- watchdog — Hardware watchdog
Library Reference¶
Read more about board specific functionality in the Arduino Mega module documentation in the Library Reference.
Memory usage¶
Below is the memory usage of two applications:
- The minimal-configuration application is configured to only include the bare minimum of functionality for the low level kernel to run. That is, the thread scheduler and system tick.
- The default-configuration application is built with the default configuration, including a lot more functionality. See the list of Default system features above for a summary.
Application | Flash | RAM |
---|---|---|
minimal-configuration | 13674 | 1053 |
default-configuration | 58156 | 3737 |
Default configuration¶
Default Standard Library configuration.
Mcu¶
Arduino Nano¶
Pinout¶
Default system features¶
The default configuration includes those major features. They are all
initialized by sys_start()
at the startup of the application.
Drivers¶
Supported drivers for this board.
- adc — Analog to digital convertion
- analog_input_pin — Analog input pin
- analog_output_pin — Analog output pin
- ds18b20 — One-wire temperature sensor
- ds3231 — RTC clock
- exti — External interrupts
- i2c — I2C
- i2c_soft — Software I2C
- mcp2515 — CAN BUS chipset
- nrf24l01 — Wireless communication
- owi — One-Wire Interface
- pin — Digital pins
- pwm — Pulse width modulation
- sd — Secure Digital memory
- spi — Serial Peripheral Interface
- uart — Universal Asynchronous Receiver/Transmitter
- uart_soft — Bitbang UART
- watchdog — Hardware watchdog
Library Reference¶
Read more about board specific functionality in the Arduino Nano module documentation in the Library Reference.
Memory usage¶
Below is the memory usage of two applications:
- The minimal-configuration application is configured to only include the bare minimum of functionality for the low level kernel to run. That is, the thread scheduler and system tick.
- The default-configuration application is built with the default configuration, including a lot more functionality. See the list of Default system features above for a summary.
Application | Flash | RAM |
---|---|---|
minimal-configuration | 5604 | 755 |
default-configuration | 10998 | 868 |
Default configuration¶
Default Standard Library configuration.
Mcu¶
Arduino Pro Micro¶
Pinout¶
Default system features¶
The default configuration includes those major features. They are all
initialized by sys_start()
at the startup of the application.
Drivers¶
Supported drivers for this board.
- adc — Analog to digital convertion
- analog_input_pin — Analog input pin
- analog_output_pin — Analog output pin
- ds18b20 — One-wire temperature sensor
- ds3231 — RTC clock
- exti — External interrupts
- i2c — I2C
- i2c_soft — Software I2C
- mcp2515 — CAN BUS chipset
- nrf24l01 — Wireless communication
- owi — One-Wire Interface
- pin — Digital pins
- pwm — Pulse width modulation
- sd — Secure Digital memory
- spi — Serial Peripheral Interface
- uart — Universal Asynchronous Receiver/Transmitter
- uart_soft — Bitbang UART
- usb — Universal Serial Bus
- usb_device — Universal Serial Bus - Device
- watchdog — Hardware watchdog
Library Reference¶
Read more about board specific functionality in the Arduino Pro Micro module documentation in the Library Reference.
Memory usage¶
Below is the memory usage of two applications:
- The minimal-configuration application is configured to only include the bare minimum of functionality for the low level kernel to run. That is, the thread scheduler and system tick.
- The default-configuration application is built with the default configuration, including a lot more functionality. See the list of Default system features above for a summary.
Application | Flash | RAM |
---|---|---|
minimal-configuration | 6562 | 837 |
default-configuration | 10078 | 993 |
Default configuration¶
Default Standard Library configuration.
Mcu¶
Enter the bootloader¶
Recover a bricked board by entering the bootloader.
- Power up the board.
- Connect RST to GND for a second to enter the bootloader and stay in it for 8 seconds.
Arduino Uno¶
Pinout¶
Default system features¶
The default configuration includes those major features. They are all
initialized by sys_start()
at the startup of the application.
Drivers¶
Supported drivers for this board.
- adc — Analog to digital convertion
- analog_input_pin — Analog input pin
- analog_output_pin — Analog output pin
- ds18b20 — One-wire temperature sensor
- ds3231 — RTC clock
- exti — External interrupts
- i2c — I2C
- i2c_soft — Software I2C
- mcp2515 — CAN BUS chipset
- nrf24l01 — Wireless communication
- owi — One-Wire Interface
- pin — Digital pins
- pwm — Pulse width modulation
- sd — Secure Digital memory
- spi — Serial Peripheral Interface
- uart — Universal Asynchronous Receiver/Transmitter
- uart_soft — Bitbang UART
- watchdog — Hardware watchdog
Library Reference¶
Read more about board specific functionality in the Arduino Uno module documentation in the Library Reference.
Memory usage¶
Below is the memory usage of two applications:
- The minimal-configuration application is configured to only include the bare minimum of functionality for the low level kernel to run. That is, the thread scheduler and system tick.
- The default-configuration application is built with the default configuration, including a lot more functionality. See the list of Default system features above for a summary.
Application | Flash | RAM |
---|---|---|
minimal-configuration | 5604 | 755 |
default-configuration | 10998 | 868 |
Default configuration¶
Default Standard Library configuration.
Mcu¶
Cygwin¶
Pinout¶
Default system features¶
The default configuration includes those major features. They are all
initialized by sys_start()
at the startup of the application.
- Console.
- File system.
- Debug shell.
Drivers¶
Supported drivers for this board.
- adc — Analog to digital convertion
- analog_input_pin — Analog input pin
- analog_output_pin — Analog output pin
- can — Controller Area Network
- dac — Digital to analog convertion
- ds18b20 — One-wire temperature sensor
- exti — External interrupts
- flash — Flash memory
- i2c_soft — Software I2C
- owi — One-Wire Interface
- pin — Digital pins
- pwm — Pulse width modulation
- sd — Secure Digital memory
- spi — Serial Peripheral Interface
- uart — Universal Asynchronous Receiver/Transmitter
Library Reference¶
Read more about board specific functionality in the Cygwin module documentation in the Library Reference.
Memory usage¶
Below is the memory usage of two applications:
- The minimal-configuration application is configured to only include the bare minimum of functionality for the low level kernel to run. That is, the thread scheduler and system tick.
- The default-configuration application is built with the default configuration, including a lot more functionality. See the list of Default system features above for a summary.
Application | Flash | RAM |
---|---|---|
minimal-configuration | 313303 | 121312 |
default-configuration | 404151 | 212608 |
Default configuration¶
Default Standard Library configuration.
Homepage¶
ESP-01¶
Pinout¶
Default system features¶
The default configuration includes those major features. They are all
initialized by sys_start()
at the startup of the application.
- Console.
- File system.
- Debug shell.
Drivers¶
Supported drivers for this board.
Library Reference¶
Read more about board specific functionality in the ESP-01 module documentation in the Library Reference.
Memory usage¶
Below is the memory usage of two applications:
- The minimal-configuration application is configured to only include the bare minimum of functionality for the low level kernel to run. That is, the thread scheduler and system tick.
- The default-configuration application is built with the default configuration, including a lot more functionality. See the list of Default system features above for a summary.
Application | Flash | RAM |
---|---|---|
minimal-configuration | 269288 | 35732 |
default-configuration | 306728 | 55176 |
Default configuration¶
Default Standard Library configuration.
Homepage¶
Flashing¶
- Connect VCC to 3.3 V and GND to ground.
- Connect GPIO0 to GND.
- Connect EN/CHPH to 3.3 V.
- Turn on the power.
- Upload the software to Flash using esptool.
Boot from flash¶
- Connect VCC to 3.3 V and GND to ground.
- Connect GPIO0 to 3.3 V.
- Connect EN/CHPH to 3.3 V.
- Turn on the power.
ESP-12E Development Board¶
Pinout¶
Default system features¶
The default configuration includes those major features. They are all
initialized by sys_start()
at the startup of the application.
- Console.
- File system.
- Debug shell.
Drivers¶
Supported drivers for this board.
Library Reference¶
Read more about board specific functionality in the ESP-12E Development Board module documentation in the Library Reference.
Memory usage¶
Below is the memory usage of two applications:
- The minimal-configuration application is configured to only include the bare minimum of functionality for the low level kernel to run. That is, the thread scheduler and system tick.
- The default-configuration application is built with the default configuration, including a lot more functionality. See the list of Default system features above for a summary.
Application | Flash | RAM |
---|---|---|
minimal-configuration | 269288 | 35732 |
default-configuration | 306728 | 55204 |
Default configuration¶
Default Standard Library configuration.
Homepage¶
ESP-12 pinout¶
Flashing¶
- Connect 3.3 V to VCC and ground to GND.
- Attach the flash jumper (to the right in the picture).
- Turn on the power.
- Upload the software to Flash using esptool.
- The application starts automatically when the download is completed.
Hardware¶
- 3.3 V power supply and logical level voltage.
- Boot message at 76800 buad on a virgin board. Blue, red and RGB LEDs turned on.
- 4 MB Flash.
How to determine the Flash size:
$ python esptool.py --port /dev/ttyUSB0 flash_id
Connecting...
head: 0 ;total: 0
erase size : 0
Manufacturer: e0
Device: 4016
Device 4016 gives a Flash of size 2 ^ (16 - 1) / 8 = 4096 kB = 4 MB
.
Linux¶
Pinout¶
Default system features¶
The default configuration includes those major features. They are all
initialized by sys_start()
at the startup of the application.
- Console.
- File system.
- Debug shell.
Drivers¶
Supported drivers for this board.
- adc — Analog to digital convertion
- analog_input_pin — Analog input pin
- analog_output_pin — Analog output pin
- can — Controller Area Network
- dac — Digital to analog convertion
- ds18b20 — One-wire temperature sensor
- exti — External interrupts
- flash — Flash memory
- i2c_soft — Software I2C
- owi — One-Wire Interface
- pin — Digital pins
- pwm — Pulse width modulation
- sd — Secure Digital memory
- spi — Serial Peripheral Interface
- uart — Universal Asynchronous Receiver/Transmitter
Library Reference¶
Read more about board specific functionality in the Linux module documentation in the Library Reference.
Memory usage¶
Below is the memory usage of two applications:
- The minimal-configuration application is configured to only include the bare minimum of functionality for the low level kernel to run. That is, the thread scheduler and system tick.
- The default-configuration application is built with the default configuration, including a lot more functionality. See the list of Default system features above for a summary.
Application | Flash | RAM |
---|---|---|
minimal-configuration | 313239 | 121312 |
default-configuration | 404087 | 212608 |
Default configuration¶
Default Standard Library configuration.
Homepage¶
Nano32¶
Pinout¶
Default system features¶
The default configuration includes those major features. They are all
initialized by sys_start()
at the startup of the application.
- Console.
- File system.
- Debug shell.
Drivers¶
Supported drivers for this board.
Library Reference¶
Read more about board specific functionality in the Nano32 module documentation in the Library Reference.
Memory usage¶
Below is the memory usage of two applications:
- The minimal-configuration application is configured to only include the bare minimum of functionality for the low level kernel to run. That is, the thread scheduler and system tick.
- The default-configuration application is built with the default configuration, including a lot more functionality. See the list of Default system features above for a summary.
Application | Flash | RAM |
---|---|---|
minimal-configuration | 179049 | 38060 |
default-configuration | 210097 | 59792 |
Default configuration¶
Default Standard Library configuration.
Homepage¶
NodeMCU¶
Pinout¶
Default system features¶
The default configuration includes those major features. They are all
initialized by sys_start()
at the startup of the application.
- Console.
- File system.
- Debug shell.
Drivers¶
Supported drivers for this board.
Library Reference¶
Read more about board specific functionality in the NodeMCU module documentation in the Library Reference.
Memory usage¶
Below is the memory usage of two applications:
- The minimal-configuration application is configured to only include the bare minimum of functionality for the low level kernel to run. That is, the thread scheduler and system tick.
- The default-configuration application is built with the default configuration, including a lot more functionality. See the list of Default system features above for a summary.
Application | Flash | RAM |
---|---|---|
minimal-configuration | 269288 | 35732 |
default-configuration | 306728 | 55188 |
Default configuration¶
Default Standard Library configuration.
Homepage¶
Particle IO Photon¶
Pinout¶
Default system features¶
The default configuration includes those major features. They are all
initialized by sys_start()
at the startup of the application.
Drivers¶
Supported drivers for this board.
Library Reference¶
Read more about board specific functionality in the Particle IO Photon module documentation in the Library Reference.
Memory usage¶
Below is the memory usage of two applications:
- The minimal-configuration application is configured to only include the bare minimum of functionality for the low level kernel to run. That is, the thread scheduler and system tick.
- The default-configuration application is built with the default configuration, including a lot more functionality. See the list of Default system features above for a summary.
Application | Flash | RAM |
---|---|---|
minimal-configuration | 16604 | 3376 |
default-configuration | 60268 | 6746 |
Default configuration¶
Default Standard Library configuration.
Mcu¶
Prerequisities¶
Install the dfu-utility.
git clone git://git.code.sf.net/p/dfu-util/dfu-util
cd dfu-util
sudo apt-get build-dep dfu-util
./autogen.sh
./configure
make
sudo make install
cd ..
# Give users access to the device.
sudo cp simba/environment/udev/49-photon.rules /etc/udec/rules.d
Flashing¶
The Photon must enter DFU mode before software can be uploaded to it. It’s recommended to use the manual method to verify that software can be successfully uploaded to the board, and then start using the automatic method to reduce the manual work for each software upload.
Automatic (recommended)¶
- Connect DTR on the serial adapter to the RST pin on the Photon.
- Connect RTS on the serial adapter to the SETUP pad on the bottom side of the Photon. This requires soldering a cable to the SETUP pad.
Upload the software with make BOARD=photon upload
.
Manual¶
To enter DFU Mode:
- Hold down the RESET and SETUP buttons.
- Release only the RESET button, while holding down the SETUP button.
- Wait for the LED to start flashing yellow (it will flash magenta first).
- Release the SETUP button.
NOTE: Do not connect DTR and/or RTS using manual upload. They must only be connected using the automatic method.
Upload the software with make BOARD=photon upload
.
STM32F3DISCOVERY¶
Pinout¶
Default system features¶
The default configuration includes those major features. They are all
initialized by sys_start()
at the startup of the application.
Drivers¶
Supported drivers for this board.
Library Reference¶
Read more about board specific functionality in the STM32F3DISCOVERY module documentation in the Library Reference.
Memory usage¶
Below is the memory usage of two applications:
- The minimal-configuration application is configured to only include the bare minimum of functionality for the low level kernel to run. That is, the thread scheduler and system tick.
- The default-configuration application is built with the default configuration, including a lot more functionality. See the list of Default system features above for a summary.
Application | Flash | RAM |
---|---|---|
minimal-configuration | 16344 | 2896 |
default-configuration | 58988 | 6254 |
Default configuration¶
Default Standard Library configuration.
Homepage¶
Mcu¶
Pin functions¶
These are the default pin functions in Simba.
Function | Pin |
---|---|
UART0 TX | PA9 |
UART0 RX | PA10 |
UART1 TX | PA2 |
UART1 RX | PA3 |
UART2 TX | PB10 |
UART2 RX | PB11 |
SPI0 SCK | PA5 |
SPI0 MISO | PA6 |
SPI0 MOSI | PA7 |
SPI1 SCK | PA13 |
SPI1 MISO | PA14 |
SPI1 MOSI | PA15 |
SPI2 SCK | PC10 |
SPI2 MISO | PC11 |
SPI2 MOSI | PC12 |
I2C0 SCL | PB8 |
I2C0 SDA | PB9 |
I2C1 SCL | PF0 |
I2C1 SDA | PF1 |
CAN TX | PD1 |
CAN RX | PD0 |
STM32VLDISCOVERY¶
Pinout¶
Default system features¶
The default configuration includes those major features. They are all
initialized by sys_start()
at the startup of the application.
Drivers¶
Supported drivers for this board.
Library Reference¶
Read more about board specific functionality in the STM32VLDISCOVERY module documentation in the Library Reference.
Memory usage¶
Below is the memory usage of two applications:
- The minimal-configuration application is configured to only include the bare minimum of functionality for the low level kernel to run. That is, the thread scheduler and system tick.
- The default-configuration application is built with the default configuration, including a lot more functionality. See the list of Default system features above for a summary.
Application | Flash | RAM |
---|---|---|
minimal-configuration | 17036 | 3052 |
default-configuration | 59808 | 6290 |
Default configuration¶
Default Standard Library configuration.
Homepage¶
Mcu¶
st-link¶
sudo apt install libusb-1.0-0-dev
git clone https://github.com/eerimoq/stlink
./autogen.sh
./configure
make
sudo cp etc/udev/rules.d/49* /etc/udev/rules.d
udevadm control --reload-rules
udevadm trigger
modprobe -r usb-storage && modprobe usb-storage quirks=483:3744:i
st-util -1
arm-none-eabi-gdb app.out
$ target extended-remote localhost:4242
Plug in the board in the PC.
Pin functions¶
These are the default pin functions in Simba.
Function | Pin |
---|---|
UART0 TX | PA9 |
UART0 RX | PA10 |
UART1 TX | PA2 |
UART1 RX | PA3 |
UART2 TX | PC10 |
UART2 RX | PC11 |
SPI0 SCK | PA5 |
SPI0 MISO | PA6 |
SPI0 MOSI | PA7 |
I2C0 SCL | PB8 |
I2C0 SDA | PB9 |
Examples¶
Below is a list of simple examples that are useful to understand the basics of Simba.
There are a lot more examples and unit tests on Github that shows how to use most of the Simba modules.
Analog Read¶
About¶
Read the value of an analog pin periodically once every second and print the read value to standard output.
Source code¶
/**
* @section License
*
* The MIT License (MIT)
*
* Copyright (c) 2014-2016, Erik Moqvist
*
* Permission is hereby granted, free of charge, to any person
* obtaining a copy of this software and associated documentation
* files (the "Software"), to deal in the Software without
* restriction, including without limitation the rights to use, copy,
* modify, merge, publish, distribute, sublicense, and/or sell copies
* of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be
* included in all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
* NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
* BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
* ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
* CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
* SOFTWARE.
*
* This file is part of the Simba project.
*/
#include "simba.h"
int main()
{
int value;
struct analog_input_pin_t pin;
sys_start();
analog_input_pin_module_init();
/* Initialize the analog input pin. */
analog_input_pin_init(&pin, &pin_a0_dev);
while (1) {
/* Read the analog pin value and print it. */
value = analog_input_pin_read(&pin);
std_printf(FSTR("value = %d\r\n"), value);
/* Wait 100 ms. */
thrd_sleep_ms(100);
}
return (0);
}
The source code can also be found on Github in the examples/analog_read folder.
Build and run¶
Build and run the application.
$ cd examples/analog_read
$ make -s BOARD=<board> run
value = 234
value = 249
value = 230
Analog Write¶
About¶
Write analog values to an analog output pin to form a sawtooth wave. Connect a LED to the analog output pin and watch the brightness of the LED change.
Source code¶
/**
* @section License
*
* The MIT License (MIT)
*
* Copyright (c) 2014-2016, Erik Moqvist
*
* Permission is hereby granted, free of charge, to any person
* obtaining a copy of this software and associated documentation
* files (the "Software"), to deal in the Software without
* restriction, including without limitation the rights to use, copy,
* modify, merge, publish, distribute, sublicense, and/or sell copies
* of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be
* included in all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
* NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
* BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
* ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
* CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
* SOFTWARE.
*
* This file is part of the Simba project.
*/
#include "simba.h"
int main()
{
int value;
struct analog_output_pin_t pin;
sys_start();
analog_output_pin_module_init();
/* Initialize the analog output pin. */
analog_output_pin_init(&pin, &pin_d10_dev);
value = 0;
while (1) {
/* Write a sawtooth wave to the analog output pin. */
analog_output_pin_write(&pin, value);
value += 5;
value %= 1024;
/* Wait ten milliseconds. */
thrd_sleep_ms(10);
}
return (0);
}
The source code can also be found on Github in the examples/analog_write folder.
Build and run¶
Build and upload the application.
$ cd examples/analog_write
$ make -s BOARD=<board> upload
Blink¶
About¶
Turn a LED on and off periodically once a second. This example illustrates how to use digital pins and sleep a thread.
Source code¶
/**
* @section License
*
* The MIT License (MIT)
*
* Copyright (c) 2014-2016, Erik Moqvist
*
* Permission is hereby granted, free of charge, to any person
* obtaining a copy of this software and associated documentation
* files (the "Software"), to deal in the Software without
* restriction, including without limitation the rights to use, copy,
* modify, merge, publish, distribute, sublicense, and/or sell copies
* of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be
* included in all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
* NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
* BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
* ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
* CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
* SOFTWARE.
*
* This file is part of the Simba project.
*/
#include "simba.h"
int main()
{
struct pin_driver_t led;
/* Start the system. */
sys_start();
/* Initialize the LED pin as output and set its value to 1. */
pin_init(&led, &pin_led_dev, PIN_OUTPUT);
pin_write(&led, 1);
while (1) {
/* Wait half a second. */
thrd_sleep_ms(500);
/* Toggle the LED on/off. */
pin_toggle(&led);
}
return (0);
}
The source code can also be found on Github in the examples/blink folder.
DS18B20¶
About¶
Read and print the temperature measured with one or more DS18B20 sensors.
Source code¶
/**
* @section License
*
* The MIT License (MIT)
*
* Copyright (c) 2014-2016, Erik Moqvist
*
* Permission is hereby granted, free of charge, to any person
* obtaining a copy of this software and associated documentation
* files (the "Software"), to deal in the Software without
* restriction, including without limitation the rights to use, copy,
* modify, merge, publish, distribute, sublicense, and/or sell copies
* of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be
* included in all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
* NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
* BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
* ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
* CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
* SOFTWARE.
*
* This file is part of the Simba project.
*/
#include "simba.h"
int main()
{
struct owi_driver_t owi;
struct ds18b20_driver_t ds;
struct owi_device_t devices[4];
char temperature[16], *temperature_p;
int number_of_sensors;
int i;
/* Initialization. */
sys_start();
ds18b20_module_init();
owi_init(&owi, &pin_d7_dev, devices, membersof(devices));
ds18b20_init(&ds, &owi);
time_busy_wait_us(50000);
/* Search for devices on the OWI bus. */
number_of_sensors = owi_search(&owi);
std_printf(FSTR("Number of sensors: %d\r\n"), number_of_sensors);
while (1) {
/* Take a new temperature sample. */
ds18b20_convert(&ds);
for (i = 0; i < owi.len; i++) {
if (devices[i].id[0] != DS18B20_FAMILY_CODE) {
continue;
}
temperature_p = ds18b20_get_temperature_str(&ds,
devices[i].id,
temperature);
std_printf(FSTR("Device id: %02x %02x %02x %02x %02x %02x %02x %02x,"
" Temperature: %s\r\n"),
(unsigned int)devices[i].id[0],
(unsigned int)devices[i].id[1],
(unsigned int)devices[i].id[2],
(unsigned int)devices[i].id[3],
(unsigned int)devices[i].id[4],
(unsigned int)devices[i].id[5],
(unsigned int)devices[i].id[6],
(unsigned int)devices[i].id[7],
temperature_p);
}
}
return (0);
}
The source code can also be found on Github in the examples/ds18b20 folder.
Build and run¶
Build and run the application.
$ cd examples/ds18b20
$ make -s BOARD=<board> run
Number of sensors: 2
Device id: 28 9c 1d 5d 05 00 00 32, Temperature: 22.6250
Device id: 28 95 32 5d 05 00 00 33, Temperature: 22.6875
Filesystem¶
About¶
Create the file counter.txt
and write 0
to it. Everytime the
application is restarted the counter is incremented by one.
Source code¶
/**
* @section License
*
* The MIT License (MIT)
*
* Copyright (c) 2014-2016, Erik Moqvist
*
* Permission is hereby granted, free of charge, to any person
* obtaining a copy of this software and associated documentation
* files (the "Software"), to deal in the Software without
* restriction, including without limitation the rights to use, copy,
* modify, merge, publish, distribute, sublicense, and/or sell copies
* of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be
* included in all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
* NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
* BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
* ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
* CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
* SOFTWARE.
*
* This file is part of the Simba project.
*/
#include "simba.h"
#if !defined(BOARD_ARDUINO_DUE) && !defined(ARCH_ESP) && !defined(ARCH_ESP32)
# error "This example can only be built for Arduino Due, ESP and ESP32."
#endif
/**
* Increment the counter in 'counter.txt'.
*/
static int increment_counter(void)
{
char buf[32];
struct fs_file_t file;
long counter;
size_t size;
std_printf(FSTR("Incrementing the counter in 'counter.txt'.\r\n"));
if (fs_open(&file, "counter.txt", FS_RDWR) != 0) {
/* Create the file if missing. */
if (fs_open(&file,
"counter.txt",
FS_CREAT | FS_TRUNC | FS_RDWR) != 0) {
return (-1);
}
if (fs_write(&file, "0", 2) != 2) {
return (-2);
}
if (fs_seek(&file, 0, FS_SEEK_SET) != 0) {
return (-3);
}
}
if (fs_read(&file, buf, 16) <= 0) {
return (-4);
}
if (std_strtol(buf, &counter) == NULL) {
return (-5);
}
/* Increment the counter. */
counter++;
std_sprintf(buf, FSTR("%lu"), counter);
size = strlen(buf) + 1;
if (fs_seek(&file, 0, FS_SEEK_SET) != 0) {
return (-6);
}
if (fs_write(&file, buf, size) != size) {
return (-7);
}
if (fs_close(&file) != 0) {
return (-8);
}
std_printf(FSTR("Counter incremented to %lu\r\n"), counter);
return (0);
}
int main()
{
int res;
sys_start();
std_printf(sys_get_info());
/* Increment the counter. */
res = increment_counter();
if (res != 0) {
std_printf(FSTR("Failed to increment the counter with error %d.\r\n"),
res);
}
/* The shell thread is started in sys_start() so just suspend this
thread. */
thrd_suspend(NULL);
return (0);
}
The source code can also be found on Github in the examples/filesystem folder.
Build and run¶
Build and run the application.
$ cd examples/filesystem
$ make -s BOARD=arduino_due upload
The output in the terminal emulator:
Incrementing the counter in 'counter.txt'.
Counter incremented to 1.
<manually reset the board>
Incrementing the counter in 'counter.txt'.
Counter incremented to 2.
<manually reset the board>
Incrementing the counter in 'counter.txt'.
Counter incremented to 3.
Hello World¶
About¶
This application prints “Hello world!” to standard output.
Source code¶
/**
* @section License
*
* The MIT License (MIT)
*
* Copyright (c) 2014-2016, Erik Moqvist
*
* Permission is hereby granted, free of charge, to any person
* obtaining a copy of this software and associated documentation
* files (the "Software"), to deal in the Software without
* restriction, including without limitation the rights to use, copy,
* modify, merge, publish, distribute, sublicense, and/or sell copies
* of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be
* included in all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
* NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
* BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
* ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
* CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
* SOFTWARE.
*
* This file is part of the Simba project.
*/
#include "simba.h"
int main()
{
/* Start the system. */
sys_start();
std_printf(FSTR("Hello world!\r\n"));
return (0);
}
The source code can also be found on Github in the examples/hello_world folder.
Build and run¶
Build and run the application.
$ cd examples/hello_world
$ make -s BOARD=<board> run
...
Hello world!
$
HTTP Client¶
About¶
Conenct to a remote host perform a HTTP GET action to fetch the root page ‘/’ from the remote host.
Define CONFIG_START_NETWORK_INTERFACE_WIFI_SSID
and
CONFIG_START_NETWORK_INTERFACE_WIFI_PASSWORD
in config.h
to
the SSID and password of your WiFi, otherwise the board will fail to
connect to the WiFi network. Alternatively, the defines can be given
as defines on the make command line as seen in the example below.
Source code¶
/**
* @section License
*
* The MIT License (MIT)
*
* Copyright (c) 2014-2016, Erik Moqvist
*
* Permission is hereby granted, free of charge, to any person
* obtaining a copy of this software and associated documentation
* files (the "Software"), to deal in the Software without
* restriction, including without limitation the rights to use, copy,
* modify, merge, publish, distribute, sublicense, and/or sell copies
* of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be
* included in all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
* NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
* BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
* ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
* CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
* SOFTWARE.
*
* This file is part of the Simba project.
*/
#include "simba.h"
/* The ip address of the host to connect to. */
#define REMOTE_HOST_IP 216.58.211.142
int main()
{
struct socket_t socket;
char http_request[] =
"GET / HTTP/1.1\r\n"
"Host: " STRINGIFY(REMOTE_HOST_IP) "\r\n"
"\r\n";
char http_response[64];
char remote_host_ip[] = STRINGIFY(REMOTE_HOST_IP);
struct inet_addr_t remote_host_address;
/* Start the system. Brings up the configured network interfaces
and starts the TCP/IP-stack. */
sys_start();
/* Open the tcp socket. */
socket_open_tcp(&socket);
std_printf(FSTR("Connecting to '%s'.\r\n"), remote_host_ip);
if (inet_aton(remote_host_ip, &remote_host_address.ip) != 0) {
std_printf(FSTR("Bad ip address ''.\r\n"), remote_host_ip);
return (-1);
}
remote_host_address.port = 80;
if (socket_connect(&socket, &remote_host_address) != 0) {
std_printf(FSTR("Failed to connect to '%s'.\r\n"), remote_host_ip);
return (-1);
}
/* Send the HTTP request... */
if (socket_write(&socket,
http_request,
strlen(http_request)) != strlen(http_request)) {
std_printf(FSTR("Failed to send the HTTP request.\r\n"));
return (-1);
}
/* ...and receive the first 64 bytes of the response. */
if (socket_read(&socket,
http_response,
sizeof(http_response)) != sizeof(http_response)) {
std_printf(FSTR("Failed to receive the response.\r\n"));
}
std_printf(FSTR("First 64 bytes of the response:\r\n"
"%s"),
http_response);
/* Close the socket. */
socket_close(&socket);
return (0);
}
The source code can also be found on Github in the examples/http_client folder.
Build and run¶
Build and run the application. It must be built for ESP12E or ESP01 since those are the only boards with a network connection (WiFi).
$ cd examples/http_client
$ make -s BOARD=esp12e CDEFS_EXTRA="CONFIG_START_NETWORK_INTERFACE_WIFI_SSID=Qvist CONFIG_START_NETWORK_INTERFACE_WIFI_PASSWORD=FooBar" run
...
Connecting to WiFi with SSID 'Qvist'.
Connected to WiFi with SSID 'Qvist'. Got IP address '192.168.1.103'.
Connecting to '216.58.211.142'.
First 64 bytes of the response:
HTTP/1.1 301 Moved Permanently
Location: http://www.google.com/GET / HTTP/1.1
Host: 216.58.211.142
...
$
Ping¶
About¶
Ping a remote host periodically once every second.
Source code¶
/**
* @section License
*
* The MIT License (MIT)
*
* Copyright (c) 2014-2016, Erik Moqvist
*
* Permission is hereby granted, free of charge, to any person
* obtaining a copy of this software and associated documentation
* files (the "Software"), to deal in the Software without
* restriction, including without limitation the rights to use, copy,
* modify, merge, publish, distribute, sublicense, and/or sell copies
* of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be
* included in all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
* NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
* BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
* ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
* CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
* SOFTWARE.
*
* This file is part of the Simba project.
*/
#include "simba.h"
/* The ip address of the host to ping. */
#define REMOTE_HOST_IP 216.58.211.142
int main()
{
int res, attempt;
char remote_host_ip[] = STRINGIFY(REMOTE_HOST_IP);
struct inet_ip_addr_t remote_host_ip_address;
struct time_t round_trip_time, timeout;
sys_start();
if (inet_aton(remote_host_ip, &remote_host_ip_address) != 0) {
std_printf(FSTR("Bad ip address '%s'.\r\n"), remote_host_ip);
return (-1);
}
timeout.seconds = 3;
timeout.nanoseconds = 0;
attempt = 1;
/* Ping the remote host once every second. */
while (1) {
res = ping_host_by_ip_address(&remote_host_ip_address,
&timeout,
&round_trip_time);
if (res == 0) {
std_printf(FSTR("Successfully pinged '%s' (#%d).\r\n"),
remote_host_ip,
attempt);
} else {
std_printf(FSTR("Failed to ping '%s' (#%d).\r\n"),
remote_host_ip,
attempt);
}
attempt++;
thrd_sleep(1);
}
return (0);
}
The source code can also be found on Github in the examples/ping folder.
Build and run¶
Build and run the application.
$ cd examples/ping
$ make -s BOARD=<board> run
Successfully pinged '192.168.1.100' in 20 ms (#1).
Successfully pinged '192.168.1.100' in 20 ms (#2).
Successfully pinged '192.168.1.100' in 20 ms (#3).
Queue¶
About¶
Use a queue to communicate between two threads.
Source code¶
/**
* @section License
*
* The MIT License (MIT)
*
* Copyright (c) 2014-2016, Erik Moqvist
*
* Permission is hereby granted, free of charge, to any person
* obtaining a copy of this software and associated documentation
* files (the "Software"), to deal in the Software without
* restriction, including without limitation the rights to use, copy,
* modify, merge, publish, distribute, sublicense, and/or sell copies
* of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be
* included in all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
* NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
* BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
* ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
* CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
* SOFTWARE.
*
* This file is part of the Simba project.
*/
#include "simba.h"
static struct queue_t queue;
static THRD_STACK(writer_stack, 256);
static void *writer_main(void *arg_p)
{
int value;
/* Write to the queue. */
value = 1;
queue_write(&queue, &value, sizeof(value));
return (NULL);
}
int main()
{
int value;
sys_start();
queue_init(&queue, NULL, 0);
thrd_spawn(writer_main, NULL, 0, writer_stack, sizeof(writer_stack));
/* Read from the queue. */
queue_read(&queue, &value, sizeof(value));
std_printf(FSTR("read value = %d\r\n"), value);
return (0);
}
The source code can also be found on Github in the examples/queue folder.
Build and run¶
Build and upload the application.
$ cd examples/queue
$ make -s BOARD=<board> run
read value = 1
Shell¶
About¶
Use the serial port to monitor and control the application.
Source code¶
/**
* @section License
*
* The MIT License (MIT)
*
* Copyright (c) 2014-2016, Erik Moqvist
*
* Permission is hereby granted, free of charge, to any person
* obtaining a copy of this software and associated documentation
* files (the "Software"), to deal in the Software without
* restriction, including without limitation the rights to use, copy,
* modify, merge, publish, distribute, sublicense, and/or sell copies
* of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be
* included in all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
* NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
* BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
* ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
* CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
* SOFTWARE.
*
* This file is part of the Simba project.
*/
#include "simba.h"
/* Hello world command. */
static struct fs_command_t cmd_hello_world;
static struct shell_t shell;
/**
* The shell command callback for "/hello_world".
*/
static int cmd_hello_world_cb(int argc,
const char *argv[],
void *out_p,
void *in_p,
void *arg_p,
void *call_arg_p)
{
/* Write "Hello World!" to the output channel. */
std_fprintf(out_p, FSTR("Hello World!\r\n"));
return (0);
}
int main()
{
/* Start the system. */
sys_start();
std_printf(sys_get_info());
#if defined(__DRIVERS_I2C_H__)
i2c_module_init();
#endif
pin_module_init();
/* Register the hello world command. */
fs_command_init(&cmd_hello_world,
FSTR("/hello_world"),
cmd_hello_world_cb,
NULL);
fs_command_register(&cmd_hello_world);
/* Start the shell. */
shell_init(&shell,
sys_get_stdin(),
sys_get_stdout(),
NULL,
NULL,
NULL,
NULL);
shell_main(&shell);
return (0);
}
The source code can also be found on Github in the examples/shell folder.
Build and run¶
Build and run the application.
$ cd examples/shell
$ make -s BOARD=<board> upload
Communicate with the board using a serial terminal emulator, for example TeraTerm.
Type hello_world
in the terminal emulator and press Enter. Hello
World!
is printed.
Press Tab to print a list of all registered commands and try them if you want to.
$ hello_world
Hello World!
$ <tab>
drivers/
filesystems/
hello_world
help
history
kernel/
logout
oam/
$ kernel/thrd/list
NAME STATE PRIO CPU MAX-STACK-USAGE LOGMASK
shell current 0 0% 358/ 5575 0x0f
idle ready 127 0% 57/ 156 0x0f
$
Timer¶
About¶
Start a periodic timer that writes an event to the main thread. The main thread reads the event and prints “timeout” to the standard output.
Source code¶
/**
* @section License
*
* The MIT License (MIT)
*
* Copyright (c) 2014-2016, Erik Moqvist
*
* Permission is hereby granted, free of charge, to any person
* obtaining a copy of this software and associated documentation
* files (the "Software"), to deal in the Software without
* restriction, including without limitation the rights to use, copy,
* modify, merge, publish, distribute, sublicense, and/or sell copies
* of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be
* included in all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
* NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
* BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
* ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
* CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
* SOFTWARE.
*
* This file is part of the Simba project.
*/
#include "simba.h"
#define TIMEOUT_EVENT 0x1
static struct event_t event;
static struct timer_t timer;
static void timer_cb(void *arg_p)
{
uint32_t mask;
mask = TIMEOUT_EVENT;
event_write_isr(&event, &mask, sizeof(mask));
}
int main()
{
uint32_t mask;
struct time_t timeout;
sys_start();
event_init(&event);
/* Initialize and start a periodic timer. */
timeout.seconds = 1;
timeout.nanoseconds = 0;
timer_init(&timer, &timeout, timer_cb, NULL, TIMER_PERIODIC);
timer_start(&timer);
while (1) {
mask = TIMEOUT_EVENT;
event_read(&event, &mask, sizeof(mask));
std_printf(FSTR("timeout\r\n"));
}
return (0);
}
The source code can also be found on Github in the examples/timer folder.
Build and run¶
Build and upload the application.
$ cd examples/timer
$ make -s BOARD=<board> run
timeout
timeout
timeout
Library Reference¶
Simba’s standard library is very extensive, offering a wide range of facilities as indicated by the long table of contents listed below. The library contains modules used by many developers in their everyday programming.
Besides the generated documentation, the source code of the interfaces and their implementatins are available on Github.
kernel¶
The kernel package is the heart in Simba. It implements the thread scheduler.
The kernel package on Github.
errno
— Error numbers¶
Source code: src/kernel/errno.h
Defines
-
EPERM
¶
-
ENOENT
¶ No such file or directory.
-
ESRCH
¶ No such process.
-
EINTR
¶ Interrupted system call.
-
EIO
¶ I/O error.
-
ENXIO
¶ No such device or address.
-
E2BIG
¶ Argument list too long.
-
ENOEXEC
¶ Exec format error.
-
EBADF
¶ Bad file number.
-
ECHILD
¶ No child processes.
-
EAGAIN
¶ Try again.
-
ENOMEM
¶ Out of memory.
-
EACCES
¶ Permission denied.
-
EFAULT
¶ Bad address.
-
ENOTBLK
¶ Block device required.
-
EBUSY
¶ Device or resource busy.
-
EEXIST
¶ File exists.
-
EXDEV
¶ Cross-device link.
-
ENODEV
¶ No such device.
-
ENOTDIR
¶ Not a directory.
-
EISDIR
¶ Is a directory.
-
EINVAL
¶ Invalid argument.
-
ENFILE
¶ File table overflow.
-
EMFILE
¶ Too many open files.
-
ENOTTY
¶ Not a typewriter.
-
ETXTBSY
¶ Text file busy.
-
EFBIG
¶ File too large.
-
ENOSPC
¶ No space left on device.
-
ESPIPE
¶ Illegal seek.
-
EROFS
¶ Read-only file system.
-
EMLINK
¶ Too many links.
-
EPIPE
¶ Broken pipe.
-
EDOM
¶ Math argument out of domain of func.
-
ERANGE
¶ Math result not representable.
-
EDEADLK
¶ Resource deadlock would occur.
-
ENAMETOOLONG
¶ File name too long.
-
ENOLCK
¶ No record locks available.
-
ENOSYS
¶ Function not implemented.
-
ENOTEMPTY
¶ Directory not empty.
-
ELOOP
¶ Too many symbolic links encountered.
-
EWOULDBLOCK
¶ Operation would block.
-
ENOMSG
¶ No message of desired type.
-
EIDRM
¶ Identifier removed.
-
ECHRNG
¶ Channel number out of range.
-
EL2NSYNC
¶ Level 2 not synchronized.
-
EL3HLT
¶ Level 3 halted.
-
EL3RST
¶ Level 3 reset.
-
ELNRNG
¶ Link number out of range.
-
EUNATCH
¶ Protocol driver not attached.
-
ENOCSI
¶ No CSI structure available.
-
EL2HLT
¶ Level 2 halted.
-
EBADE
¶ Invalid exchange.
-
EBADR
¶ Invalid request descriptor.
-
EXFULL
¶ Exchange full.
-
ENOANO
¶ No anode.
-
EBADRQC
¶ Invalid request code.
-
EBADSLT
¶ Invalid slot.
-
EDEADLOCK
¶
-
EBFONT
¶ Bad font file format.
-
ENOSTR
¶ Device not a stream.
-
ENODATA
¶ No data available.
-
ETIME
¶ Timer expired.
-
ENOSR
¶ Out of streams resources.
-
ENONET
¶ Machine is not on the network.
-
ENOPKG
¶ Package not installed.
-
EREMOTE
¶ Object is remote.
-
ENOLINK
¶ Link has been severed.
-
EADV
¶ Advertise error.
-
ESRMNT
¶ Srmount error.
-
ECOMM
¶ Communication error on send.
-
EPROTO
¶ Protocol error.
-
EMULTIHOP
¶ Multihop attempted.
-
EDOTDOT
¶ RFS specific error.
-
EBADMSG
¶ Not a data message.
-
EOVERFLOW
¶ Value too large for defined data type.
-
ENOTUNIQ
¶ Name not unique on network.
-
EBADFD
¶ File descriptor in bad state.
-
EREMCHG
¶ Remote address changed.
-
ELIBACC
¶ Can not access a needed shared library.
-
ELIBBAD
¶ Accessing a corrupted shared library.
-
ELIBSCN
¶ .lib section in a.out corrupted.
-
ELIBMAX
¶ Attempting to link in too many shared libraries.
-
ELIBEXEC
¶ Cannot exec a shared library directly.
-
EILSEQ
¶ Illegal byte sequence.
-
ERESTART
¶ Interrupted system call should be restarted.
-
ESTRPIPE
¶ Streams pipe error.
-
EUSERS
¶ Too many users.
-
ENOTSOCK
¶ Socket operation on non-socket.
-
EDESTADDRREQ
¶ Destination address required.
-
EMSGSIZE
¶ Message too long.
-
EPROTOTYPE
¶ Protocol wrong type for socket.
-
ENOPROTOOPT
¶ Protocol not available.
-
EPROTONOSUPBOARD
¶ Protocol not supported.
-
ESOCKTNOSUPBOARD
¶ Socket type not supported.
-
EOPNOTSUPP
¶ Operation not supported on transport endpoint.
-
EPFNOSUPBOARD
¶ Protocol family not supported.
-
EAFNOSUPBOARD
¶ Address family not supported by protocol.
-
EADDRINUSE
¶ Address already in use.
-
EADDRNOTAVAIL
¶ Cannot assign requested address.
-
ENETDOWN
¶ Network is down.
-
ENETUNREACH
¶ Network is unreachable.
-
ENETRESET
¶ Network dropped connection because of reset.
-
ECONNABORTED
¶ Software caused connection abort.
-
ECONNRESET
¶ Connection reset by peer.
-
ENOBUFS
¶ No buffer space available.
-
EISCONN
¶ Transport endpoint is already connected.
-
ENOTCONN
¶ Transport endpoint is not connected.
-
ESHUTDOWN
¶ Cannot send after transport endpoint shutdown.
-
ETOOMANYREFS
¶ Too many references: cannot splice.
-
ETIMEDOUT
¶ Connection timed out.
-
ECONNREFUSED
¶ Connection refused.
-
EHOSTDOWN
¶ Host is down.
-
EHOSTUNREACH
¶ No route to host.
-
EALREADY
¶ Operation already in progress.
-
EINPROGRESS
¶ Operation now in progress.
-
ESTALE
¶ Stale NFS file handle.
-
EUCLEAN
¶ Structure needs cleaning.
-
ENOTNAM
¶ Not a XENIX named type file.
-
ENAVAIL
¶ No XENIX sems available.
-
EISNAM
¶ Is a named type file.
-
EREMOTEIO
¶ Remote I/O error.
-
EDQUOT
¶ Quota exceeded.
-
ENOMEDIUM
¶ No medium found.
-
EMEDIUMTYPE
¶ Wrong medium type.
-
ECANCELED
¶ Operation Canceled.
-
ENOKEY
¶ Required key not available.
-
EKEYEXPIRED
¶ Key has expired.
-
EKEYREVOKED
¶ Key has been revoked.
-
EKEYREJECTED
¶ Key was rejected by service.
-
ESTACK
¶ Stack corrupt.
-
EBTASSERT
¶ Test assertion.
sys
— System¶
System level functionality and definitions.
Source code: src/kernel/sys.h, src/kernel/sys.c
Test code: tst/kernel/sys/main.c
Test coverage: src/kernel/sys.c
Typedefs
- typedef
Functions
-
static sys_tick_t
t2st
(struct time_t *time_p)¶ Convertion from the time struct to system ticks.
-
static void
st2t
(sys_tick_t tick, struct time_t *time_p)¶ Convertion from system ticks to the time struct.
-
int
sys_module_init
(void)¶ Initialize the sys module. This function must be called before calling any other function in this module.
The module will only be initialized once even if this function is called multiple times.
- Return
- zero(0) or negative error code.
-
int
sys_start
(void)¶ Start the system and convert this context to the main thread.
This function initializes a bunch of enabled features in the simba platform. Many low level features (scheduling, timers, ...) are always enabled, but higher level features are only enabled if configured.
This function must be the first function call in main().
- Return
- zero(0) or negative error code.
-
void
sys_stop
(int error)¶ Stop the system.
- Return
- Never returns.
-
void
sys_reboot
(void)¶ Reboot the system. Sets all registers to their known, default values and restarts the application. Also known as a soft reset.
- Return
- Never returns.
-
void
sys_set_on_fatal_callback
(void (*callback)(int error))¶ Set the on-fatal-callback function to given callback.
The on-fatal-callback is called when a fatal error occurs. The default on-fatal-callback is
sys_stop()
.- Return
- void
- Parameters
callback
: Callback called when a fatal error occurs.
-
void
sys_set_stdin
(void *chan_p)¶ Set the standard input channel.
- Return
- void.
- Parameters
chan_p
: New standard input channel.
-
void *
sys_get_stdin
(void)¶ Get the standard input channel.
- Return
- Standard input channel or NULL.
-
void
sys_set_stdout
(void *chan_p)¶ Set the standard output channel.
- Return
- void.
- Parameters
chan_p
: New standard output channel.
-
void *
sys_get_stdout
(void)¶ Get the standard output channel.
- Return
- Standard output channel or NULL.
-
void
sys_lock
(void)¶ Take the system lock. Turns off interrupts.
- Return
- void.
-
void
sys_unlock
(void)¶ Release the system lock. Turn on interrupts.
- Return
- void.
-
void
sys_lock_isr
(void)¶ Take the system lock from isr. In many ports this has no effect.
- Return
- void.
-
void
sys_unlock_isr
(void)¶ Release the system lock from isr. In many ports this function has no effect.
- Return
- void.
-
far_string_t
sys_get_info
(void)¶ Get a pointer to the application information buffer.
The buffer contains various information about the application; for example the application name and the build date.
- Return
- The pointer to the application information buffer.
-
far_string_t
sys_get_config
(void)¶ Get a pointer to the application configuration buffer.
The buffer contains a string of all configuration variables and their values.
- Return
- The pointer to the application configuration buffer.
-
float
sys_interrupt_cpu_usage_get
(void)¶ Get the current interrupt cpu usage counter.
- Return
- cpu usage, 0-100.
-
void
sys_interrupt_cpu_usage_reset
(void)¶ Reset the interrupt cpu usage counter.
- struct
thrd
— Threads¶
A thread is the basic execution entity in the OS. A pre-emptive or cooperative scheduler controls the execution of threads.
Scheduler¶
The single core scheduler is configured as cooperative or preemptive at compile time. The cooperative scheduler is implemented for all boards, but the preemptive scheduler is only implemented for a few boards.
There are two threads that are always present; the main thread and the
idle thread. The main thread is the root thread in the system, created
in the main()
function by calling sys_start()
. The idle thread
is running when no other thread is ready to run. It simply waits for
an interrupt to occur and then reschedules to run other ready threads.
The diagram below is an example of how three threads; shell
,
main
and idle
are scheduled over time.
As it is a single core scheduler only one thread is runnng at a
time. In the beginning the system is idle and the idle
thread is
running. After a while the main
and shell
threads have some
work to do, and since they have higher priority than the idle
thread they are scheduled. At the end the idle
thread is running
again.
Debug file system commands¶
Four debug file system commands are available, all located in the
directory kernel/thrd/
.
Command | Description |
---|---|
list |
Print a list of all threads. |
set_log_mask <thread name> <mask> |
Set the log mask of thread <thread name> to mask . |
monitor/set_period_ms <ms> |
Set the monitor thread sampling period to <ms> milliseconds. |
monitor/set_print <state> |
Enable(1 )/disable(0 ) monitor statistics to be printed periodically. |
Example output from the shell:
$ kenel/thrd/list
NAME STATE PRIO CPU SCHEDULED LOGMASK
main current 0 0% 1 0x0f
ready 127 0% 0 0x0f
ready -80 0% 0 0x0f
Source code: src/kernel/thrd.h, src/kernel/thrd.c
Test code: tst/kernel/thrd/main.c
Test coverage: src/kernel/thrd.c
Defines
-
THRD_STACK
(name, size)¶
-
THRD_CONTEXT_STORE_ISR
¶ Push all callee-save registers not part of the context struct. The preemptive scheduler requires this macro before the
thrd_yield_isr()
function is called from interrupt context.
-
THRD_CONTEXT_LOAD_ISR
¶ Pop all callee-save registers not part of the context struct. The preemptive scheduler requires this macro after the thrd_yield_isr() function is called from interrupt context.
-
THRD_RESCHEDULE_ISR
¶ Reschuedule from isr. Used by preemptive systems to interrupt low priority threads in favour of high priority threads.
Functions
-
int
thrd_module_init
(void)¶ Initialize the thread module. This function must be called before calling any other function in this module.
The module will only be initialized once even if this function is called multiple times.
- Return
- zero(0) or negative error code
-
struct thrd_t *
thrd_spawn
(void *(*main)(void *), void *arg_p, int prio, void *stack_p, size_t stack_size, )¶ Spawn a thread with given main (entry) function and argument. The thread is initialized and added to the ready queue in the scheduler for execution when prioritized.
- Return
- Thread id, or NULL on error.
- Parameters
main
: Thread main (entry) function. This function normally contains an infinate loop waiting for events to occur.arg_p
: Main function argument. Passed as arg_p to the main function.prio
: Thread scheduling priority. [-127..127], where -127 is the highest priority and 127 is the lowest.stack_p
: Stack pointer. The pointer to a stack created with the macroTHRD_STACK()
.stack_size
: The stack size in number of bytes.
-
int
thrd_suspend
(struct time_t *timeout_p)¶ Suspend current thread and wait to be resumed or a timeout occurs (if given).
- Return
- zero(0), -ETIMEOUT on timeout or other negative error code.
- Parameters
timeout_p
: Time to wait to be resumed before a timeout occurs and the function returns.
-
int
thrd_resume
(struct thrd_t *thrd_p, int err)¶ Resume given thread. If resumed thread is not yet suspended it will not be suspended on next suspend call to
thrd_suspend()
orthrd_suspend_isr()
.- Return
- zero(0) or negative error code.
- Parameters
thrd_p
: Thread id to resume.err
: Error code to be returned bythrd_suspend()
orthrd_suspend_isr()
.
-
int
thrd_yield
(void)¶ Put the currently executing thread on the ready list and reschedule.
This function is often called periodically from low priority work heavy threads to give higher priority threads the chance to execute.
- Return
- zero(0) or negative error code.
-
int
thrd_join
(struct thrd_t *thrd_p)¶ Wait for given thread to terminate.
- Return
- zero(0) or negative error code.
- Parameters
thrd_p
: Thread to wait for.
-
int
thrd_sleep
(float seconds)¶ Pauses the current thread for given number of seconds.
- Return
- zero(0) or negative error code.
- Parameters
seconds
: Seconds to sleep.
-
int
thrd_sleep_ms
(int ms)¶ Pauses the current thread for given number of milliseconds.
- Return
- zero(0) or negative error code.
- Parameters
ms
: Milliseconds to sleep.
-
int
thrd_sleep_us
(long us)¶ Pauses the current thread for given number of microseconds.
- Return
- zero(0) or negative error code.
- Parameters
us
: Microseconds to sleep.
-
int
thrd_set_name
(const char *name_p)¶ Set the name of the current thread.
- Return
- zero(0) or negative error code.
- Parameters
name_p
: New thread name.
-
const char *
thrd_get_name
(void)¶ Get the name of the current thread.
- Return
- Current thread name.
-
struct thrd_t *
thrd_get_by_name
(const char *name_p)¶ Get the pointer to given thread.
- Return
- Thraed pointer or NULL if the thread was not found.
-
int
thrd_set_log_mask
(struct thrd_t *thrd_p, int mask)¶ Set the log mask of given thread.
- Return
- Old log mask.
- Parameters
thrd_p
: Thread to set the log mask of.mask
: Log mask. See the log module for available levels.
-
int
thrd_get_log_mask
(void)¶ Get the log mask of the current thread.
- Return
- Log mask of current thread.
-
int
thrd_set_prio
(struct thrd_t *thrd_p, int prio)¶ Set the priority of given thread.
- Return
- zero(0) or negative error code.
- Parameters
thrd_p
: Thread to set the priority for.prio
: Priority.
-
int
thrd_get_prio
(void)¶ Get the priority of the current thread.
- Return
- Priority of current thread.
-
int
thrd_init_global_env
(struct thrd_environment_variable_t *variables_p, int length)¶ Initialize the global environment variables storage. These variables are shared among all threads.
- Return
- zero(0) or negative error code.
- Parameters
variables_p
: Variables array.length
: Length of the variables array.
-
int
thrd_set_global_env
(const char *name_p, const char *value_p)¶ Set the value of given environment variable. The pointers to given name and value are stored in the current global environment array.
- Return
- zero(0) or negative error code.
- Parameters
name_p
: Name of the environment variable to set.value_p
: Value of the environment variable. Set to NULL to remove the variable.
-
const char *
thrd_get_global_env
(const char *name_p)¶ Get the value of given environment variable in the global environment array.
- Return
- Value of given environment variable or NULL if it is not found.
- Parameters
name_p
: Name of the environment variable to get.
-
int
thrd_init_env
(struct thrd_environment_variable_t *variables_p, int length)¶ Initialize the current threads’ environment variables storage.
- Return
- zero(0) or negative error code.
- Parameters
variables_p
: Variables are to be used by this therad.length
: Length of the variables array.
-
int
thrd_set_env
(const char *name_p, const char *value_p)¶ Set the value of given environment variable. The pointers to given name and value are stored in the current threads’ environment array.
- Return
- zero(0) or negative error code.
- Parameters
name_p
: Name of the environment variable to set.value_p
: Value of the environment variable. Set to NULL to remove the variable.
-
const char *
thrd_get_env
(const char *name_p)¶ Get the value of given environment variable. If given variable is not found in the current threads’ environment array, the global environment array is searched.
- Return
- Value of given environment variable or NULL if it is not found.
- Parameters
name_p
: Name of the environment variable to get.
-
int
thrd_suspend_isr
(struct time_t *timeout_p)¶ Suspend current thread with the system lock taken (see
sys_lock()
) and wait to be resumed or a timeout occurs (if given).- Return
- zero(0), -ETIMEOUT on timeout or other negative error code.
- Parameters
timeout_p
: Time to wait to be resumed before a timeout occurs and the function returns.
-
int
thrd_resume_isr
(struct thrd_t *thrd_p, int err)¶ Resume given thread from isr or with the system lock taken (see
sys_lock()
). If resumed thread is not yet suspended it will not be suspended on next suspend call tothrd_suspend()
orthrd_suspend_isr()
.- Return
- zero(0) or negative error code.
- Parameters
thrd_p
: Thread id to resume.err
: Error code to be returned bythrd_suspend()
orthrd_suspend_isr()
.
-
int
thrd_yield_isr
(void)¶ Yield current thread from isr (preemptive scheduler only) or with the system lock taken.
- Return
- zero(0) or negative error code.
- struct
- #include <thrd.h>
A thread environment variable.
- struct
Public Members
-
struct thrd_environment_variable_t *
thrd_environment_t::
variables_p
¶
-
size_t
thrd_environment_t::
number_of_variables
¶
-
size_t
thrd_environment_t::
max_number_of_variables
¶
-
struct thrd_environment_variable_t *
- struct
time
— System time¶
Source code: src/kernel/time.h, src/kernel/time.c
Test code: tst/kernel/time/main.c
Test coverage: src/kernel/time.c
Functions
-
int
time_get
(struct time_t *now_p)¶ Get current time in seconds and nanoseconds. The resolution of the time is implementation specific and may vary a lot between different architectures.
- Return
- zero(0) or negative error code.
- Parameters
now_p
: Read current time.
-
int
time_set
(struct time_t *new_p)¶ Set current time in seconds and nanoseconds.
- Return
- zero(0) or negative error code.
- Parameters
new_p
: New current time.
-
int
time_diff
(struct time_t *diff_p, struct time_t *left_p, struct time_t *right_p)¶ Subtract given times.
- Return
- zero(0) or negative error code.
- Parameters
diff_p
: The result of the subtranctingleft_p
fromright_p
.left_p
: The operand to subtract from.right_p
: The operand to subtract.
-
void
time_busy_wait_us
(long useconds)¶ Busy wait for given number of microseconds.
NOTE: The maximum allowed time to sleep is target specific.
- Return
- void
- Parameters
useconds
: Microseconds to sleep.
- struct
- #include <time.h>
- struct
- #include <time.h>
A date in year, month, date, day, hour, minute and seconds.
Public Members
-
int
date_t::
second
¶ Second [0..59].
-
int
date_t::
minute
¶ Minute [0..59].
-
int
date_t::
hour
¶ Hour [0..23].
-
int
date_t::
day
¶ Weekday [1..7], where 1 is Monday and 7 is Sunday.
-
int
date_t::
date
¶ Day in month [1..31]
-
int
date_t::
month
¶ Month [1..12] where 1 is January and 12 is December.
-
int
date_t::
year
¶ Year [1970..].
-
int
timer
— Timers¶
Timers are started with a timeout, and when the time is up the timer expires and the timer callback function is called from interrupt context.
The timeout resolution is the system tick period. Timeouts are always rounded up to the closest system tick. That is, a timer can never expire early, but may expire slightly late.
An application requiring timers with higher precision than the system tick must use the hardware timers.
Source code: src/kernel/timer.h, src/kernel/timer.c
Test code: tst/kernel/timer/main.c
Test coverage: src/kernel/timer.c
Defines
-
TIMER_PERIODIC
¶
Typedefs
- typedef
Time callback prototype.
Functions
-
int
timer_module_init
(void)¶ Initialize the timer module. This function must be called before calling any other function in this module.
The module will only be initialized once even if this function is called multiple times.
- Return
- zero(0) or negative error code.
-
int
timer_init
(struct timer_t *self_p, struct time_t *timeout_p, timer_callback_t callback, void *arg_p, int flags)¶ Initialize given timer object with given timeout and expiry callback. The timer resolution directly depends on the system tick frequency and is rounded up to the closest possible value. This applies to both single shot and periodic timers.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Timer object to initialize with given parameters.timeout_p
: The timer timeout value.callback
: Functaion called when the timer expires. Called from interrupt context.arg_p
: Function callback argument. Passed to the callback when the timer expires.flags
: Set TIMER_PERIODIC for periodic timer.
-
int
timer_start
(struct timer_t *self_p)¶ Start given initialized timer object.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Timer object to start.
-
int
timer_start_isr
(struct timer_t *self_p)¶ See
timer_start()
for a description.This function may only be called from an isr or with the system lock taken (see
sys_lock()
).
-
int
timer_stop
(struct timer_t *self_p)¶ Stop given timer object. This has no effect on a timer that already expired or was never started. The return code is 0 if the timer was stopped and -1 otherwise.
- Return
- zero(0) if the timer was stopped and -1 if the timer has already expired or was never started.
- Parameters
self_p
: Timer object to stop.
- struct
Public Members
-
sys_tick_t
timer_t::
delta
¶
-
sys_tick_t
timer_t::
timeout
¶
-
int
timer_t::
flags
¶
-
timer_callback_t
timer_t::
callback
¶
-
void *
timer_t::
arg_p
¶
-
sys_tick_t
types
— Common types¶
Source code: src/kernel/types.h
Defines
-
UNUSED
(v)¶
-
STRINGIFY
(x)¶ Create a string of an identifier using the pre-processor.
-
STRINGIFY2
(x)¶ Used internally by
STRINGIFY()
.
-
TOKENPASTE
(x, y)¶ Concatenate two tokens.
-
TOKENPASTE2
(x, y)¶ Used internally by
TOKENPASTE()
.
-
UNIQUE
(x)¶ Create a unique token.
-
membersof
(a)¶ Get the number of elements in an array.
As an example, the code below outputs
number of members in foo = 10
.int foo[10]; std_printf(FSTR("number of members in foo = %d\\r\\n"), membersof(foo));
-
container_of
(ptr, type, member)¶
-
DIV_CEIL
(n, d)¶ Integer division that rounds the result up.
-
MIN
(a, b)¶ Get the minimum value of the two.
-
MAX
(a, b)¶ Get the maximum value of the two.
-
PRINT_FILE_LINE
¶ Debug print of file and line.
-
STD_PRINTF_DEBUG
(...)¶
-
_ASSERTFMT
(fmt, ...)¶
-
ASSERTN
(cond, n, ...)¶ Assert given condition and call the system on fatal callback with given value
n
on error.
-
ASSERT
(cond, ...)¶ Assert given condition and call the system on fatal callback with value
1
on error.
-
BIT
(pos)¶
-
BITFIELD_SET
(name, value)¶
-
BITFIELD_GET
(name, value)¶
Typedefs
- typedef
- typedef
- typedef
- typedef
- typedef
- typedef
drivers¶
The drivers package on Github.
Modules:
adc
— Analog to digital convertion¶
Source code: src/drivers/adc.h, src/drivers/adc.c
Test code: tst/drivers/adc/main.c
Defines
-
ADC_REFERENCE_VCC
¶
Functions
-
int
adc_module_init
(void)¶ Initialize the ADC driver module. This function must be called before calling any other function in this module.
The module will only be initialized once even if this function is called multiple times.
- Return
- zero(0) or negative error code.
-
int
adc_init
(struct adc_driver_t *self_p, struct adc_device_t *dev_p, struct pin_device_t *pin_dev_p, int reference, long sampling_rate)¶ Initialize given driver object from given configuration.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Driver object to be initialized.dev_p
: ADC device to use.pin_dev_p
: Pin device to use.reference
: Voltage reference. OnlyADC_REFERENCE_VCC
is supported.sampling_rate
: Sampling rate in Hz. The lowest allowed value is one and the highest value depends on the architechture. The sampling rate is not used in single sample convertions, ie. calls toadc_async_convert()
andadc_convert()
with length one; or calls toadc_convert_isr()
.
-
int
adc_async_convert
(struct adc_driver_t *self_p, uint16_t *samples_p, size_t length)¶ Start an asynchronous convertion of analog signal to digital samples. Call
adc_async_wait()
to wait for the convertion to complete.- Return
- zero(0) or negative error code.
- Parameters
self_p
: Driver object.samples_p
: Converted samples.length
: Length of samples array.
-
int
adc_async_wait
(struct adc_driver_t *self_p)¶ Wait for an asynchronous convertion to complete.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Driver object.
-
int
adc_convert
(struct adc_driver_t *self_p, uint16_t *samples_p, size_t length)¶ Start a synchronous convertion of an analog signal to digital samples. This is equivalent to
adc_async_convert()
+adc_async_wait()
, but in a single function call.- Return
- zero(0) or negative error code.
- Parameters
self_p
: Driver object.samples_p
: Converted samples.length
: Length of samples array.
-
int
adc_convert_isr
(struct adc_driver_t *self_p, uint16_t *sample_p)¶ Start a synchronous convertion of analog signal to digital samples from isr or with the system lock taken. This function will poll the ADC hardware until the sample has been coverted.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Driver object.sample_p
: Converted sample.
Variables
-
struct adc_device_t
adc_device
[ADC_DEVICE_MAX]¶
analog_input_pin
— Analog input pin¶
Source code: src/drivers/analog_input_pin.h, src/drivers/analog_input_pin.c
Test code: tst/drivers/analog_input_pin/main.c
Functions
-
int
analog_input_pin_module_init
(void)¶ Initialize the analog input pin module. This function must be called before calling any other function in this module.
The module will only be initialized once even if this function is called multiple times.
- Return
- zero(0) or negative error code.
-
int
analog_input_pin_init
(struct analog_input_pin_t *self_p, struct pin_device_t *dev_p)¶ Initialize given driver object with given device and mode.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Driver object to be initialized.dev_p
: Device to use.
-
int
analog_input_pin_read
(struct analog_input_pin_t *self_p)¶ Read the current value of given pin.
- Return
- Analog pin value, otherwise negative error code.
- Parameters
self_p
: Driver object.
-
int
analog_input_pin_read_isr
(struct analog_input_pin_t *self_p)¶ Read the current value of given pin from an isr or with the system lock taken.
- Return
- Analog pin value, otherwise negative error code.
- Parameters
self_p
: Driver object.
- struct
- #include <analog_input_pin.h>
Public Members
-
struct adc_driver_t
analog_input_pin_t::
adc
¶
-
struct adc_driver_t
analog_output_pin
— Analog output pin¶
Source code: src/drivers/analog_output_pin.h, src/drivers/analog_output_pin.c
Test code: tst/drivers/analog_output_pin/main.c
Functions
-
int
analog_output_pin_module_init
(void)¶ Initialize the analog output pin module. This function must be called before calling any other function in this module.
The module will only be initialized once even if this function is called multiple times.
- Return
- zero(0) or negative error code.
-
int
analog_output_pin_init
(struct analog_output_pin_t *self_p, struct pin_device_t *dev_p)¶ Initialize given driver object with given device and mode.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Driver object to be initialized.dev_p
: Device to use.
-
int
analog_output_pin_write
(struct analog_output_pin_t *self_p, int value)¶ Write given value to the analog pin.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Driver object.value
: The value to write to the pin. A number in the range 0 to 1023, where 0 is lowest output and 1023 is highest output.
-
int
analog_output_pin_read
(struct analog_output_pin_t *self_p)¶ Read the value that is currently written to given analog output pin.
- Return
- Value in the range 0 to 1023, or negative error code.
- Parameters
self_p
: Driver object.
- struct
- #include <analog_output_pin.h>
Public Members
-
struct pwm_driver_t
analog_output_pin_t::
pwm
¶
-
struct pwm_driver_t
bcm43362
— BCM43362¶
BCM43362 is a WiFi module by Boadcom.
Homepage: https://www.broadcom.com/products/wireless-connectivity/wireless-lan/bcm43362
Source code: src/drivers/bcm43362.h, src/drivers/bcm43362.c
Test code: tst/drivers/bcm43362/main.c
Functions
-
int
bcm43362_module_init
(void)¶ Initialize the BCM43362 module. This function must be called before calling any other function in this module.
The module will only be initialized once even if this function is called multiple times.
- Return
- zero(0) or negative error code.
-
int
bcm43362_init
(struct bcm43362_driver_t *self_p, struct sdio_device_t *sdio_dev_p)¶ Initialize driver object from given configuration.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Driver object to be initialized.sdio_dev_p
: SDIO device to use.
-
int
bcm43362_start
(struct bcm43362_driver_t *self_p)¶ Starts the BCM43362 device using given driver object.
After a successful start of the device the application may call
bcm43362_connect()
to connect to an AP.- Return
- zero(0) or negative error code.
- Parameters
self_p
: Initialized driver object.
-
int
bcm43362_stop
(struct bcm43362_driver_t *self_p)¶ Stops the BCM43362 device referenced by given driver object.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Initialized driver object.
-
int
bcm43362_connect
(struct bcm43362_driver_t *self_p, const char *ssid_p, const char *password_p)¶ Connect to an WiFi Access Point (AP) with given SSID and password.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Initialized driver object.ssid_p
: SSID of the WiFi AP to connect to.password_p
: Password.
-
int
bcm43362_disconnect
(struct bcm43362_driver_t *self_p)¶ Disconnect from any connected WiFi AP.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Initialized driver object.
-
ssize_t
bcm43362_read
(struct bcm43362_driver_t *self_p, struct pbuf *pbuf_p, size_t size)¶ Read a packet from the BCM43362 device.
- Return
- Number of read bytes or negative error code.
- Parameters
self_p
: Initialized driver object.pbuf_p
: Buffer to read into.size
: Number of bytes to receive.
-
ssize_t
bcm43362_write
(struct bcm43362_driver_t *self_p, struct pbuf *pbuf_p, size_t size)¶ Write given packet to the BCM43362 device to transmit it on the network.
This function is normally called by a network interface to send a frame on the network.
- Return
- Number of written bytes or negative error code.
- Parameters
self_p
: Initialized driver object.pbuf_p
: Buffer to write.size
: Number of bytes to write.
- struct
- #include <bcm43362.h>
Public Members
-
struct sdio_driver_t
bcm43362_driver_t::
sdio
¶
-
struct sdio_driver_t
can
— Controller Area Network¶
A Controller Area Network (CAN bus) is a vehicle bus standard designed to allow microcontrollers and devices to communicate with each other in applications without a host computer. It is a message-based protocol, designed originally for multiplex electrical wiring within automobiles, but is also used in many other contexts.
Below is a short example of how to use this module. The error handling is left out for readability.
struct can_frame_t can_rx_buf[8];
struct can_frame_t frame;
/* Initialize and start the CAN conroller. */
can_init(&can,
&can_device[0],
CAN_SPEED_500KBPS,
can_rx_buf,
sizeof(can_rx_buf)) == 0);
can_start(&can);
/* Read a frame from the bus. */
can_read(&can, &frame, sizeof(frame));
/* Stop the CAN controller. */
can_stop(&can);
Source code: src/drivers/can.h, src/drivers/can.c
Test code: tst/drivers/can/main.c
Functions
-
int
can_init
(struct can_driver_t *self_p, struct can_device_t *dev_p, uint32_t speed, void *rxbuf_p, size_t size)¶ Initialize given driver object from given configuration.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Driver object to initialize.dev_p
: CAN device to use.speed
: Can bus speed. One of the defines with the prefixCAN_SPEED_
.rxbuf_p
: CAN frame reception buffer.size
: Size of the reception buffer in bytes.
-
int
can_start
(struct can_driver_t *self_p)¶ Starts the CAN device using configuration in given driver object.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Initialized driver object.
-
int
can_stop
(struct can_driver_t *self_p)¶ Stops the CAN device referenced by given driver object.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Initialized driver object.
-
ssize_t
can_read
(struct can_driver_t *self_p, struct can_frame_t *frame_p, size_t size)¶ Read one or more CAN frames from the CAN bus. Blocks until the frame(s) are received.
- Return
- Number of bytes read or negative error code.
- Parameters
self_p
: Initialized driver object.frame_p
: Array of read frames.size
: Size of frames buffer in bytes. Must be a multiple ofsizeof(struct can_frame_t)
.
-
ssize_t
can_write
(struct can_driver_t *self_p, const struct can_frame_t *frame_p, size_t size)¶ Write one or more CAN frames to the CAN bus. Blocks until the frame(s) have been transmitted.
- Return
- Number of bytes written or negative error code.
- Parameters
self_p
: Initialized driver object.frame_p
: Array of frames to write.size
: Size of frames buffer in bytes. Must be a multiple ofsizeof(struct can_frame_t)
.
Variables
-
struct can_device_t
can_device
[CAN_DEVICE_MAX]¶
- struct
chipid
— Chip identity¶
Source code: src/drivers/chipid.h, src/drivers/chipid.c
Test code: tst/drivers/chipid/main.c
Functions
-
int
chipid_read
(struct chipid_t *id_p)¶
dac
— Digital to analog convertion¶
Source code: src/drivers/dac.h, src/drivers/dac.c
Test code: tst/drivers/dac/main.c
Functions
-
int
dac_module_init
(void)¶ Initialize DAC driver module. This function must be called before calling any other function in this module.
The module will only be initialized once even if this function is called multiple times.
- Return
- zero(0) or negative error code.
-
int
dac_init
(struct dac_driver_t *self_p, struct dac_device_t *dev_p, struct pin_device_t *pin0_dev_p, struct pin_device_t *pin1_dev_p, int sampling_rate)¶ Initialize given driver object from given configuration.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Driver object to be initialized.dev_p
: Device to use.pin0_dev_p
: Pin used for mono or first stereo channel.pin1_dev_p
: Second stereo pin.sampling_rate
: Sampling rate in Hz.
-
int
dac_async_convert
(struct dac_driver_t *self_p, uint32_t *samples_p, size_t length)¶ Start an asynchronous convertion of samples to an analog signal.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Driver object.samples
: Samples to convert to an analog signal.length
: Length of samples array.
-
int
dac_async_wait
(struct dac_driver_t *self_p)¶ Wait for ongoing asynchronous convertion to finish.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Driver object.
-
int
dac_convert
(struct dac_driver_t *self_p, uint32_t *samples_p, size_t length)¶ Start synchronous convertion of samples to an analog signal.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Driver object.samples
: Converted samlpes.length
: Length of samples array.
Variables
-
struct dac_device_t
dac_device
[DAC_DEVICE_MAX]¶
ds18b20
— One-wire temperature sensor¶
Source code: src/drivers/ds18b20.h, src/drivers/ds18b20.c
Test code: tst/drivers/ds18b20/main.c
Defines
-
DS18B20_FAMILY_CODE
¶
Functions
-
int
ds18b20_module_init
(void)¶ Initialize the DS18B20 driver module. This function must be called before calling any other function in this module.
The module will only be initialized once even if this function is called multiple times.
- Return
- zero(0) or negative error code.
-
int
ds18b20_init
(struct ds18b20_driver_t *self_p, struct owi_driver_t *owi_p)¶ Initialize given driver object. The driver object will communicate with all DS18B20 devices on given OWI bus.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Driver object to be initialized.owi_p
: One-Wire (OWI) driver.
-
int
ds18b20_convert
(struct ds18b20_driver_t *self_p)¶ Start temperature convertion on all sensors.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Driver object to be initialized.
-
int
ds18b20_get_temperature
(struct ds18b20_driver_t *self_p, const uint8_t *id_p, int *temp_p)¶ Get the temperature for given device identity.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Driver object to be initialized.id_p
: Device identity.temp_p
: Measured temperature in Q4.4 to Q8.4 depending on resolution.
-
char *
ds18b20_get_temperature_str
(struct ds18b20_driver_t *self_p, const uint8_t *id_p, char *temp_p)¶ Get temperature for given device identity formatted as a string.
- Return
temp_p
on success, NULL otherwise.- Parameters
self_p
: Driver object to be initialized.id_p
: Device identity.temp_p
: Measured formatted temperature.
- struct
Public Members
-
struct owi_driver_t *
ds18b20_driver_t::
owi_p
¶
-
struct ds18b20_driver_t *
ds18b20_driver_t::
next_p
¶
-
struct owi_driver_t *
ds3231
— RTC clock¶
Source code: src/drivers/ds3231.h, src/drivers/ds3231.c
Test code: tst/drivers/ds3231/main.c
Functions
-
int
ds3231_init
(struct ds3231_driver_t *self_p, struct i2c_driver_t *i2c_p)¶ Initialize given driver object.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Driver object to be initialized.i2c_p
: I2C driver to use.
-
int
ds3231_set_date
(struct ds3231_driver_t *self_p, struct date_t *date_p)¶ Set date in the DS3231 device.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Driver object.date_p
: Date to set in the device.
-
int
ds3231_get_date
(struct ds3231_driver_t *self_p, struct date_t *date_p)¶ Get date from the DS3231 device.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Driver object.date_p
: Date read from the device.
- struct
- #include <ds3231.h>
Public Members
-
struct i2c_driver_t *
ds3231_driver_t::
i2c_p
¶
-
struct i2c_driver_t *
esp_wifi
— Espressif WiFi¶
This module is a wrapper for the Espressif WiFi interface.
Configure the WiFi as a Station and an Access Point at the same time. The application tries to connect to a Wifi with SSID ssid and will accept connections to the SSID Simba.
esp_wifi_set_op_mode(esp_wifi_op_mode_station_softap_t);
esp_wifi_softap_init("Simba", NULL);
esp_wifi_station_init("ssid", "password", NULL);
Configure the WiFi as an Access Point. The application will accept connections to the SSID Simba.
esp_wifi_set_op_mode(esp_wifi_op_mode_softap_t);
esp_wifi_softap_init("Simba", NULL);
Configure the WiFi as a Station. The application tries to connect to a Wifi with SSID ssid.
esp_wifi_set_op_mode(esp_wifi_op_mode_station_t);
esp_wifi_station_init("ssid", "password", NULL);
Submodules:
esp_wifi_softap
— Espressif WiFi SoftAP¶
This module is a wrapper for the Espressif WiFi SoftAP interface.
Source code: src/drivers/esp_wifi/softap.h, src/drivers/esp_wifi/softap.c
Test code: tst/drivers/esp_wifi/softap/main.c
Functions
-
int
esp_wifi_softap_init
(const char *ssid_p, const char *password_p)¶ Initialize the WiFi SoftAP interface.
- Return
- zero(0) or negative error code.
- Parameters
ssid_p
: SSID of the SoftAP.password_p
: Password of SoftAP.
-
int
esp_wifi_softap_set_ip_info
(const struct inet_if_ip_info_t *info_p)¶ Set the ip address, netmask and gateway of the WiFi SoftAP.
- Return
- zero(0) or negative error code.
-
int
esp_wifi_softap_get_ip_info
(struct inet_if_ip_info_t *info_p)¶ Get the SoftAP ip address, netmask and gateway.
- Return
- zero(0) or negative error code.
- Parameters
info_p
: Read ip information.
-
int
esp_wifi_softap_get_number_of_connected_stations
(void)¶ Get the number of stations connected to the SoftAP.
- Return
- Number of conencted stations.
-
int
esp_wifi_softap_get_station_info
(struct esp_wifi_softap_station_info_t *info_p, int length)¶ Get the information of stations connected to the SoftAP, including MAC and IP addresses.
- Return
- Number of valid station information entries or negative error code.
- Parameters
info_p
: An array to write the station information to.length
: Length of the info array.
-
int
esp_wifi_softap_dhcp_server_start
(void)¶ Enable the SoftAP DHCP server.
- Return
- zero(0) or negative error code.
-
int
esp_wifi_softap_dhcp_server_stop
(void)¶ Disable the SoftAP DHCP server. The DHCP server is enabled by default.
- Return
- zero(0) or negative error code.
-
enum esp_wifi_dhcp_status_t
esp_wifi_softap_dhcp_server_status
(void)¶ Get the SoftAP DHCP server status.
- Return
- DHCP server status.
- struct
- #include <softap.h>
Public Members
-
uint8_t
esp_wifi_softap_station_info_t::
bssid
[6]¶
-
struct inet_ip_addr_t
esp_wifi_softap_station_info_t::
ip_address
¶
-
uint8_t
esp_wifi_station
— Espressif WiFi Station¶
This module is a wrapper for the Espressif WiFi station interface.
Source code: src/drivers/esp_wifi/station.h, src/drivers/esp_wifi/station.c
Test code: tst/drivers/esp_wifi/station/main.c
Enums
-
enum type
esp_wifi_station_status_t
¶ Values:
- = 0
Functions
-
int
esp_wifi_station_init
(const char *ssid_p, const char *password_p, const struct inet_if_ip_info_t *info_p)¶ Initialize the WiFi station.
- Return
- zero(0) or negative error code.
- Parameters
ssid_p
: WiFi SSID to connect to.password_p
: WiFi password.info_p
: Static ip configration or NULL to use DHCP.
-
int
esp_wifi_station_connect
(void)¶ Connect the WiFi station to the Access Point (AP).
- Return
- zero(0) or negative error code.
-
int
esp_wifi_station_disconnect
(void)¶ Disconnect the WiFi station from the AP.
- Return
- zero(0) or negative error code.
-
int
esp_wifi_station_set_ip_info
(const struct inet_if_ip_info_t *info_p)¶ Set the ip address, netmask and gateway of the WiFi station.
- Return
- zero(0) or negative error code.
-
int
esp_wifi_station_get_ip_info
(struct inet_if_ip_info_t *info_p)¶ Get the station ip address, netmask and gateway.
- Return
- zero(0) or negative error code.
-
int
esp_wifi_station_set_reconnect_policy
(int policy)¶ Set whether the station will reconnect to the AP after disconnection. It will do so by default.
- Return
- zero(0) or negative error code.
- Parameters
policy
: If it’s true, it will enable reconnection; if it’s false, it will disable reconnection.
-
int
esp_wifi_station_get_reconnect_policy
(void)¶ Check whether the station will reconnect to the AP after disconnection.
- Return
- true(1) or false(0).
-
enum esp_wifi_station_status_t
esp_wifi_station_get_connect_status
(void)¶ Get the connection status of the WiFi station.
- Return
- The connection status.
-
int
esp_wifi_station_dhcp_client_start
(void)¶ Enable the station DHCP client.
- Return
- zero(0) or negative error code.
-
int
esp_wifi_station_dhcp_client_stop
(void)¶ Disable the station DHCP client.
- Return
- zero(0) or negative error code.
-
enum esp_wifi_dhcp_status_t
esp_wifi_station_dhcp_client_status
(void)¶ Get the station DHCP client status.
- Return
- Station DHCP client status.
Source code: src/drivers/esp_wifi.h, src/drivers/esp_wifi.c
Test code: tst/drivers/esp_wifi/main.c
Enums
-
enum type
esp_wifi_op_mode_t
¶ Values:
- = 0
-
enum type
esp_wifi_phy_mode_t
¶ Physical WiFi mode.
Values:
- = 1
-
enum type
esp_wifi_dhcp_status_t
¶ DHCP status.
Values:
- = 0
Functions
-
int
esp_wifi_module_init
(void)¶ Initialize the Espressif WiFi module. This function must be called before calling any other function in this module.
The module will only be initialized once even if this function is called multiple times.
- Return
- zero(0) or negative error code.
-
int
esp_wifi_set_op_mode
(enum esp_wifi_op_mode_t mode)¶ Set the WiFi operating mode to None, Station, SoftAP or Station + SoftAP. The default mode is SoftAP.
- Return
- zero(0) or negative error code.
- Parameters
mode
: Operating mode to set.
-
enum esp_wifi_op_mode_t
esp_wifi_get_op_mode
(void)¶ Get the current WiFi operating mode. The operating mode can be None, Station, SoftAP, or Station + SoftAP.
- Return
- Current operating mode.
-
int
esp_wifi_set_phy_mode
(enum esp_wifi_phy_mode_t mode)¶ Set the WiFi physical mode (802.11b/g/n).
The SoftAP only supports b/g.
- Return
- zero(0) or negative error code.
- Parameters
mode
: Physical mode.
-
enum esp_wifi_phy_mode_t
esp_wifi_get_phy_mode
(void)¶ Get the physical mode (802.11b/g/n).
- Return
- WiFi physical mode.
-
void
esp_wifi_print
(void *chout_p)¶ Print information about the WiFi.
exti
— External interrupts¶
Source code: src/drivers/exti.h, src/drivers/exti.c
Test code: tst/drivers/exti/main.c
Defines
-
EXTI_TRIGGER_BOTH_EDGES
¶ Trigger an interrupt on both rising and falling edges.
-
EXTI_TRIGGER_FALLING_EDGE
¶ Trigger an interrupt on falling edges.
-
EXTI_TRIGGER_RISING_EDGE
¶ Trigger an interrupt on both rising edges.
Functions
-
int
exti_module_init
(void)¶ Initialize the external interrupt (EXTI) module. This function must be called before calling any other function in this module.
The module will only be initialized once even if this function is called multiple times.
- Return
- zero(0) or negative error code.
-
int
exti_init
(struct exti_driver_t *self_p, struct exti_device_t *dev_p, int trigger, void (*on_interrupt)(void *arg_p), void *arg_p, )¶ Initialize given driver object.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Driver object to be initialized.dev_p
: Device to use.trigger
: One ofEXTI_TRIGGER_BOTH_EDGES
,EXTI_TRIGGER_FALLING_EDGE
orEXTI_TRIGGER_RISING_EDGE
.on_interrupt
: Function callback called when an interrupt occurs.arg_p
: Fucntion callback argument.
-
int
exti_start
(struct exti_driver_t *self_p)¶ Starts the EXTI device using given driver object.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Driver object.
-
int
exti_stop
(struct exti_driver_t *self_p)¶ Stops the EXTI device referenced by given driver object.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Driver object.
-
int
exti_clear
(struct exti_driver_t *self_p)¶ Clear the interrupt flag.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Driver object.
Variables
-
struct exti_device_t
exti_device
[EXTI_DEVICE_MAX]¶
flash
— Flash memory¶
Source code: src/drivers/flash.h, src/drivers/flash.c
Test code: tst/drivers/flash/main.c
Functions
-
int
flash_module_init
(void)¶ Initialize the flash module. This function must be called before calling any other function in this module.
The module will only be initialized once even if this function is called multiple times.
- Return
- zero(0) or negative error code.
-
int
flash_init
(struct flash_driver_t *self_p, struct flash_device_t *dev_p)¶ Initialize given driver object.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Driver object to initialize.dev_p
: Device to use.
-
ssize_t
flash_read
(struct flash_driver_t *self_p, void *dst_p, uintptr_t src, size_t size)¶ Read data from given flash memory.
- Return
- Number of read bytes or negative error code.
- Parameters
self_p
: Initialized driver object.dst_p
: Buffer to read into.src
: Address in flash memory to read from.size
: Number of bytes to receive.
-
ssize_t
flash_write
(struct flash_driver_t *self_p, uintptr_t dst, const void *src_p, size_t size)¶ Write data to given flash memory. Only erased parts of the memory can be written to.
- Return
- Number of written bytes or negative error code.
- Parameters
self_p
: Initialized driver object.dst
: Address in flash memory to write to.src_p
: Buffer to write.size
: Number of bytes to write.
-
int
flash_erase
(struct flash_driver_t *self_p, uintptr_t addr, size_t size)¶ Erase all sectors part of given memory range.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Initialized driver object.dst
: Address in flash memory to erase from.size
: Number of bytes to erase.
Variables
-
struct flash_device_t
flash_device
[FLASH_DEVICE_MAX]¶
i2c
— I2C¶
I2C is a data transfer bus. Normally one master and one or more slaves are connected to the bus. The master addresses one slave at a time to transfer data between the devices.
The master is normally fairly easy to implement since it controls the bus clock and no race conditions can occur. The slave, on the other hand, can be implemented in various ways depending on the application requirements. In this implementation the slave will always send an acknowledgement when addressed by the master, and lock the bus by pulling SCL low until it is ready for the transmission.
Source code: src/drivers/i2c.h, src/drivers/i2c.c
Test code: tst/drivers/i2c/master/main.c
Functions
-
int
i2c_module_init
()¶ Initialize the i2c module. This function must be called before calling any other function in this module.
The module will only be initialized once even if this function is called multiple times.
- Return
- zero(0) or negative error code.
-
int
i2c_init
(struct i2c_driver_t *self_p, struct i2c_device_t *dev_p, int baudrate, int address)¶ Initialize given driver object. The same driver object is used for both master and slave modes. Use
i2c_start()
to start the device as a master, andi2c_slave_start()
to start it as a slave.- Return
- zero(0) or negative error code.
- Parameters
self_p
: Driver object to initialize.dev_p
: I2C device to use.baudrates
: Bus baudrate when in master mode. Unused in slave mode.address
: Slave address when in slave mode. Unused in master mode.
-
int
i2c_start
(struct i2c_driver_t *self_p)¶ Start given driver object in master mode. Enables data reception and transmission, but does not start any transmission. Use
i2c_read()
andi2c_write()
to exchange data with the peer.- Return
- zero(0) or negative error code.
- Parameters
self_p
: Driver object to initialize.
-
int
i2c_stop
(struct i2c_driver_t *self_p)¶ Stop given driver object. Disables data reception and transmission in master mode.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Driver object to initialize.
-
ssize_t
i2c_read
(struct i2c_driver_t *self_p, int address, void *buf_p, size_t size)¶ Read given number of bytes into given buffer from given slave.
- Return
- Number of bytes read or negative error code.
- Parameters
self_p
: Driver object.address
: Slave address to read from.buf_p
: Buffer to read into.size
: Number of bytes to read.
-
ssize_t
i2c_write
(struct i2c_driver_t *self_p, int address, const void *buf_p, size_t size)¶ Write given number of bytes from given buffer to given slave.
- Return
- Number of bytes written or negative error code.
- Parameters
self_p
: Driver object.address
: Slave address to write to.buf_p
: Buffer to write.size
: Number of bytes to write.
-
int
i2c_scan
(struct i2c_driver_t *self_p, int address)¶ Scan the i2c bus for a slave with given address.
- Return
- true(1) if a slave responded to given address, otherwise false(0) or negative error code.
- Parameters
self_p
: Driver object.address
: Address of the slave to scan for.
-
int
i2c_slave_start
(struct i2c_driver_t *self_p)¶ Start given driver object in slave mode. Enables data reception and transmission, but does not start any transmission. Data transfers are started by calling the
i2c_slave_read()
andi2c_slave_write()
.- Return
- zero(0) or negative error code.
- Parameters
self_p
: Driver object to initialize.
-
int
i2c_slave_stop
(struct i2c_driver_t *self_p)¶ Stop given driver object. Disables data reception and transmission in slave mode.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Driver object to initialize.
-
ssize_t
i2c_slave_read
(struct i2c_driver_t *self_p, void *buf_p, size_t size)¶ Read into given buffer from the next master that addresses this slave.
- Return
- Number of bytes read or negative error code.
- Parameters
self_p
: Driver object.buf_p
: Buffer to read into.size
: Number of bytes to read.
-
ssize_t
i2c_slave_write
(struct i2c_driver_t *self_p, const void *buf_p, size_t size)¶ Write given buffer to the next master that addresses this slave.
- Return
- Number of bytes written or negative error code.
- Parameters
self_p
: Driver object.buf_p
: Buffer to write.size
: Number of bytes to write.
Variables
-
struct i2c_device_t
i2c_device
[I2C_DEVICE_MAX]¶
i2c_soft
— Software I2C¶
Source code: src/drivers/i2c_soft.h, src/drivers/i2c_soft.c
Test code: tst/drivers/i2c/master_soft/main.c
Functions
-
int
i2c_soft_module_init
(void)¶ Initialize the i2c soft module. This function must be called before calling any other function in this module.
The module will only be initialized once even if this function is called multiple times.
- Return
- zero(0) or negative error code.
-
int
i2c_soft_init
(struct i2c_soft_driver_t *self_p, struct pin_device_t *scl_dev_p, struct pin_device_t *sda_dev_p, long baudrate, long max_clock_stretching_us, long clock_stretching_sleep_us)¶ Initialize given driver object.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Driver object to initialize.scl_dev_p
: The I2C clock pin (SCL).sda_dev_p
: The I2C data pin (SDA).baudrate
: Bus baudrate.max_clock_stretching_us
: Maximum number of microseconds to wait for the clock stretching to end.clock_stretching_sleep_us
: SCL poll interval in number of microseconds waiting for clock stretching to end.
-
int
i2c_soft_start
(struct i2c_soft_driver_t *self_p)¶ Start given driver object. Enables data reception and transmission, but does not start any transmission. Data tarnsfers are started by calling the
i2c_soft_read()
andi2c_soft_write()
.- Return
- zero(0) or negative error code.
- Parameters
self_p
: Driver object to initialize.
-
int
i2c_soft_stop
(struct i2c_soft_driver_t *self_p)¶ Stop given driver object. Disables data reception and transmission.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Driver object to initialize.
-
ssize_t
i2c_soft_read
(struct i2c_soft_driver_t *self_p, int address, void *buf_p, size_t size)¶ Read given number of bytes into given buffer from given slave.
- Return
- Number of bytes read or negative error code.
- Parameters
self_p
: Driver object.address
: Slave address to read from.buf_p
: Buffer to read into.size
: Number of bytes to read.
-
ssize_t
i2c_soft_write
(struct i2c_soft_driver_t *self_p, int address, const void *buf_p, size_t size)¶ Write given number of bytes from given buffer to given slave.
- Return
- Number of bytes written or negative error code.
- Parameters
self_p
: Driver object.address
: Slave address to write to.buf_p
: Buffer to write.size
: Number of bytes to write.
-
int
i2c_soft_scan
(struct i2c_soft_driver_t *self_p, int address)¶ Scan the i2c bus for a slave with given address.
- Return
- true(1) if a slave responded to given address, otherwise false(0) or negative error code.
- Parameters
self_p
: Driver object.address
: Address of the slave to scan for.
- struct
- #include <i2c_soft.h>
mcp2515
— CAN BUS chipset¶
Source code: src/drivers/mcp2515.h, src/drivers/mcp2515.c
Test code: tst/drivers/mcp2515/main.c
Functions
-
int
mcp2515_init
(struct mcp2515_driver_t *self_p, struct spi_device_t *spi_p, struct pin_device_t *cs_p, struct exti_device_t *exti_p, void *chin_p, int mode, int speed)¶ Initialize given driver object.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Driver object to initialize.spi_p
: SPI driver to use.cs_p
: SPI chip select pin.exti_p
: External interrupt tp use.chin_p
: Frames received from the hardware are written to this channel.mode
: Device mode.speed
: CAN bus speed in kbps.
-
int
mcp2515_start
(struct mcp2515_driver_t *self_p)¶ Starts the CAN device using given driver object.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Initialized driver object.
-
int
mcp2515_stop
(struct mcp2515_driver_t *self_p)¶ Stops the CAN device referenced by driver object.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Initialized driver object.
-
ssize_t
mcp2515_read
(struct mcp2515_driver_t *self_p, struct mcp2515_frame_t *frame_p)¶ Read a CAN frame.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Initialized driver object.frame_p
: Read frame.
-
ssize_t
mcp2515_write
(struct mcp2515_driver_t *self_p, const struct mcp2515_frame_t *frame_p)¶ Write a CAN frame.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Initialized driver object.frame_p
: Frame to write.
- struct
- struct
Public Functions
-
mcp2515_driver_t::THRD_STACK(stack, 1024)
-
nrf24l01
— Wireless communication¶
Source code: src/drivers/nrf24l01.h, src/drivers/nrf24l01.c
Functions
-
int
nrf24l01_module_init
(void)¶ Initialize NRF24L01 module. This function must be called before calling any other function in this module.
The module will only be initialized once even if this function is called multiple times.
- Return
- zero(0) or negative error code.
-
int
nrf24l01_init
(struct nrf24l01_driver_t *self_p, struct spi_device_t *spi_p, struct pin_device_t *cs_p, struct pin_device_t *ce_p, struct exti_device_t *exti_p, uint32_t address)¶ Initialize given driver object from given configuration.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Driver object to be initialized.spi_p
: SPI device.cs_p
: Chip select pin device.ce_p
: CE pin device.exti_p
: External interrupt flagdevice.address
: 4 MSB:s of RX pipes. LSB is set to 0 through 5 for the 6 pipes.
-
int
nrf24l01_start
(struct nrf24l01_driver_t *self_p)¶ Starts the NRF24L01 device using given driver object.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Initialized driver object.
-
int
nrf24l01_stop
(struct nrf24l01_driver_t *self_p)¶ Stops the NRF24L01 device referenced by driver object.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Initialized driver object.
-
ssize_t
nrf24l01_read
(struct nrf24l01_driver_t *self_p, void *buf_p, size_t size)¶ Read data from the NRF24L01 device.
- Return
- Number of received bytes or negative error code.
- Parameters
self_p
: Initialized driver object.buf_p
: Buffer to read into.size
: Number of bytes to read (must be 32).
-
ssize_t
nrf24l01_write
(struct nrf24l01_driver_t *self_p, uint32_t address, uint8_t pipe, const void *buf_p, size_t size)¶ Write data to the NRF24L01 device.
- Return
- number of sent bytes or negative error code.
- Parameters
self_p
: Initialized driver object.address
: 4 MSB:s of TX address.pipe
: LSB of TX address.buf_p
: Buffer to write.size
: Number of bytes to write (must be 32).
- struct
- #include <nrf24l01.h>
owi
— One-Wire Interface¶
Source code: src/drivers/owi.h, src/drivers/owi.c
Test code: tst/drivers/owi/main.c
Functions
-
int
owi_init
(struct owi_driver_t *self_p, struct pin_device_t *dev_p, struct owi_device_t *devices_p, size_t nmemb)¶ Initialize driver object.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Driver object to be initialized.dev_p
: Pin device to use.devices_p
: Storage for devices found when searching.nmemb
: Number of members in devices.
-
int
owi_reset
(struct owi_driver_t *self_p)¶ Send reset on one wire bus.
- Return
- true(1) if one or more devices are connected to the bus, false(0) if no devices were found, otherwise negative error code.
- Parameters
self_p
: Driver object.
-
int
owi_search
(struct owi_driver_t *self_p)¶ Search for devices on given one wire bus. The device id of all found devices are stored in the devices array passed to
owi_init()
.- Return
- Number of devices found or negative error code.
- Parameters
self_p
: Driver object.
-
ssize_t
owi_read
(struct owi_driver_t *self_p, void *buf_p, size_t size)¶ Read into buffer from one wire bus.
- Return
- Number of bits read or negative error code.
- Parameters
self_p
: Driver object.buf_p
: Buffer to read into.size
: Number of bits to read.
-
ssize_t
owi_write
(struct owi_driver_t *self_p, const void *buf_p, size_t size)¶ Write buffer to given one wire bus.
- Return
- Number of bits written or negative error code.
- Parameters
self_p
: Driver object.buf_p
: Buffer to write.size
: Number of bits to write.
- struct
Public Members
-
uint8_t
owi_device_t::
id
[8]¶
-
uint8_t
- struct
Public Members
-
struct pin_driver_t
owi_driver_t::
pin
¶
-
struct owi_device_t *
owi_driver_t::
devices_p
¶
-
size_t
owi_driver_t::
nmemb
¶
-
size_t
owi_driver_t::
len
¶
-
struct pin_driver_t
pin
— Digital pins¶
Debug file system commands¶
Three debug file system commands are available, all located in the
directory drivers/pin/
. These commands directly access the pin
device registers, without using the pin driver object.
Command | Description |
---|---|
set_mode <pin> <mode> |
Set the mode of the pin <pin> to <mode> , where <mode> is one of output and input . |
read <pin> |
Read current input or output value of the pin <pin> . high or low is printed. |
write <pin> <value> |
Write the value <value> to pin <pin> , where <value> is one of high and low . |
Example output from the shell:
$ drivers/pin/set_mode d2 output
$ drivers/pin/read d2
low
$ drivers/pin/write d2 high
$ drivers/pin/read d2
high
$ drivers/pin/set_mode d3 input
$ drivers/pin/read d3
low
Source code: src/drivers/pin.h, src/drivers/pin.c
Test code: tst/drivers/pin/main.c
Functions
-
int
pin_module_init
(void)¶ Initialize the pin module. This function must be called before calling any other function in this module.
The module will only be initialized once even if this function is called multiple times.
- Return
- zero(0) or negative error code.
-
int
pin_init
(struct pin_driver_t *self_p, struct pin_device_t *dev_p, int mode)¶ Initialize given driver object with given device and mode.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Driver object to be initialized.dev_p
: Device to use.mode
: Pin mode. One ofPIN_INPUT
orPIN_OUTPUT
.
-
int
pin_write
(struct pin_driver_t *self_p, int value)¶ Write given value to given pin.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Driver object.value
:1
for high and0
for low output.
-
int
pin_read
(struct pin_driver_t *self_p)¶ Read the current value of given pin.
- Return
1
for high and0
for low input, otherwise negative error code.- Parameters
self_p
: Driver object.
-
int
pin_toggle
(struct pin_driver_t *self_p)¶ Toggle the pin output value (high/low).
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Driver object.
-
int
pin_set_mode
(struct pin_driver_t *self_p, int mode)¶ Set the pin mode of given pin.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Driver object.mode
: New pin mode.
-
static int
pin_device_set_mode
(const struct pin_device_t *dev_p, int mode)¶ Pin device mode to set. One of
PIN_INPUT
orPIN_OUTPUT
.- Return
- zero(0) or negative error code.
- Parameters
self_p
: Pin device.mode
: New pin mode.
-
static int
pin_device_read
(const struct pin_device_t *dev_p)¶ Read the value of given pin device.
- Return
1
for high and0
for low input, otherwise negative error code.- Parameters
self_p
: Pin device.
-
static int
pin_device_write_high
(const struct pin_device_t *dev_p)¶ Write high to given pin device.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Pin device.
-
static int
pin_device_write_low
(const struct pin_device_t *dev_p)¶ Write low to given pin device.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Pin device.
Variables
-
struct pin_device_t
pin_device
[PIN_DEVICE_MAX]¶
pwm
— Pulse width modulation¶
Source code: src/drivers/pwm.h, src/drivers/pwm.c
Functions
-
int
pwm_init
(struct pwm_driver_t *self_p, struct pwm_device_t *dev_p)¶ Initialize driver object.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Driver object to be initialized.dev_p
: Device to use.
-
int
pwm_set_duty
(struct pwm_driver_t *self_p, uint8_t value)¶ Set the duty cycle.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Driver object.value
: Value to set [0..255].
-
int
pwm_get_duty
(struct pwm_driver_t *self_p)¶ Get current duty cycle.
- Return
- Value in the range [0..255], or negative error code.
- Parameters
self_p
: Driver object.
-
struct pwm_device_t *
pwm_pin_to_device
(struct pin_device_t *pin_p)¶ Get the PWM device for given pin.
- Return
- PWM device, or NULL on error.
- Parameters
pin_p
: The pin device to get the pwm device for.
Variables
-
struct pwm_device_t
pwm_device
[PWM_DEVICE_MAX]¶
sd
— Secure Digital memory¶
Source code: src/drivers/sd.h, src/drivers/sd.c
Test code: tst/drivers/sd/main.c
Defines
-
SD_ERR_NORESPONSE_WAIT_FOR_DATA_START_BLOCK
¶
-
SD_ERR_GO_IDLE_STATE
¶
-
SD_ERR_CRC_ON_OFF
¶
-
SD_ERR_SEND_IF_COND
¶
-
SD_ERR_CHECK_PATTERN
¶
-
SD_ERR_SD_SEND_OP_COND
¶
-
SD_ERR_READ_OCR
¶
-
SD_ERR_READ_COMMAND
¶
-
SD_ERR_READ_DATA_START_BLOCK
¶
-
SD_ERR_READ_WRONG_DATA_CRC
¶
-
SD_ERR_WRITE_BLOCK
¶
-
SD_ERR_WRITE_BLOCK_TOKEN_DATA_RES_ACCEPTED
¶
-
SD_ERR_WRITE_BLOCK_WAIT_NOT_BUSY
¶
-
SD_ERR_WRITE_BLOCK_SEND_STATUS
¶
-
SD_BLOCK_SIZE
¶
-
SD_CCC
(csd_p)¶
-
SD_C_SIZE
(csd_p)¶
-
SD_C_SIZE_MULT
(csd_p)¶
-
SD_SECTOR_SIZE
(csd_p)¶
-
SD_WRITE_BL_LEN
(csd_p)¶
-
SD_CSD_STRUCTURE_V1
¶
-
SD_CSD_STRUCTURE_V2
¶
Functions
-
int
sd_init
(struct sd_driver_t *self_p, struct spi_driver_t *spi_p)¶ Initialize given driver object.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Driver object to initialize.
-
int
sd_start
(struct sd_driver_t *self_p)¶ Start given SD card driver. This resets the SD card and performs the initialization sequence.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Initialized driver object.
-
int
sd_stop
(struct sd_driver_t *self_p)¶ Stop given SD card driver.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Initialized driver object.
-
ssize_t
sd_read_cid
(struct sd_driver_t *self_p, struct sd_cid_t *cid_p)¶ Read card CID register. The CID contains card identification information such as Manufacturer ID, Product name, Product serial number and Manufacturing date.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Initialized driver object.cid
: pointer to cid data store.
-
ssize_t
sd_read_csd
(struct sd_driver_t *self_p, union sd_csd_t *csd_p)¶ Read card CSD register. The CSD contains that provides information regarding access to the card’s contents.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Initialized driver object.csd
: pointer to csd data store.
-
ssize_t
sd_read_block
(struct sd_driver_t *self_p, void *dst_p, uint32_t src_block)¶ Read given block from SD card.
- Return
- Number of read bytes or negative error code.
- Parameters
self_p
: Initialized driver object.buf_p
: Buffer to read into.src_block
: Block to read from.
-
ssize_t
sd_write_block
(struct sd_driver_t *self_p, uint32_t dst_block, const void *src_p)¶ Write data to the SD card.
- Return
- Number of written bytes or negative error code.
- Parameters
self_p
: Initialized driver object.dst_block
: Block to write to.src_p
: Buffer to write.
Variables
-
struct sd_csd_v2_t
PACKED
¶
- struct
- struct
Public Members
-
uint8_t
sd_csd_v1_t::
reserved1
¶
-
uint8_t
sd_csd_v1_t::
csd_structure
¶
-
uint8_t
sd_csd_v1_t::
taac
¶
-
uint8_t
sd_csd_v1_t::
nsac
¶
-
uint8_t
sd_csd_v1_t::
tran_speed
¶
-
uint8_t
sd_csd_v1_t::
ccc_high
¶
-
uint8_t
sd_csd_v1_t::
read_bl_len
¶
-
uint8_t
sd_csd_v1_t::
ccc_low
¶
-
uint8_t
sd_csd_v1_t::
c_size_high
¶
-
uint8_t
sd_csd_v1_t::
reserved2
¶
-
uint8_t
sd_csd_v1_t::
dsr_imp
¶
-
uint8_t
sd_csd_v1_t::
read_blk_misalign
¶
-
uint8_t
sd_csd_v1_t::
write_blk_misalign
¶
-
uint8_t
sd_csd_v1_t::
read_bl_partial
¶
-
uint8_t
sd_csd_v1_t::
c_size_mid
¶
-
uint8_t
sd_csd_v1_t::
vdd_r_curr_max
¶
-
uint8_t
sd_csd_v1_t::
vdd_r_curr_min
¶
-
uint8_t
sd_csd_v1_t::
c_size_low
¶
-
uint8_t
sd_csd_v1_t::
c_size_mult_high
¶
-
uint8_t
sd_csd_v1_t::
vdd_w_curr_max
¶
-
uint8_t
sd_csd_v1_t::
vdd_w_curr_min
¶
-
uint8_t
sd_csd_v1_t::
sector_size_high
¶
-
uint8_t
sd_csd_v1_t::
erase_blk_en
¶
-
uint8_t
sd_csd_v1_t::
c_size_mult_low
¶
-
uint8_t
sd_csd_v1_t::
wp_grp_size
¶
-
uint8_t
sd_csd_v1_t::
sector_size_low
¶
-
uint8_t
sd_csd_v1_t::
write_bl_len_high
¶
-
uint8_t
sd_csd_v1_t::
r2w_factor
¶
-
uint8_t
sd_csd_v1_t::
reserved3
¶
-
uint8_t
sd_csd_v1_t::
wp_grp_enable
¶
-
uint8_t
sd_csd_v1_t::
reserved4
¶
-
uint8_t
sd_csd_v1_t::
write_bl_partial
¶
-
uint8_t
sd_csd_v1_t::
write_bl_len_low
¶
-
uint8_t
sd_csd_v1_t::
reserved5
¶
-
uint8_t
sd_csd_v1_t::
file_format
¶
-
uint8_t
sd_csd_v1_t::
tmp_write_protect
¶
-
uint8_t
sd_csd_v1_t::
perm_write_protect
¶
-
uint8_t
sd_csd_v1_t::
copy
¶
-
uint8_t
sd_csd_v1_t::
file_format_grp
¶
-
uint8_t
sd_csd_v1_t::
crc
¶
-
uint8_t
- struct
Public Members
-
uint8_t
sd_csd_v2_t::
reserved1
¶
-
uint8_t
sd_csd_v2_t::
csd_structure
¶
-
uint8_t
sd_csd_v2_t::
taac
¶
-
uint8_t
sd_csd_v2_t::
nsac
¶
-
uint8_t
sd_csd_v2_t::
tran_speed
¶
-
uint8_t
sd_csd_v2_t::
ccc_high
¶
-
uint8_t
sd_csd_v2_t::
read_bl_len
¶
-
uint8_t
sd_csd_v2_t::
ccc_low
¶
-
uint8_t
sd_csd_v2_t::
reserved2
¶
-
uint8_t
sd_csd_v2_t::
dsr_imp
¶
-
uint8_t
sd_csd_v2_t::
read_blk_misalign
¶
-
uint8_t
sd_csd_v2_t::
write_blk_misalign
¶
-
uint8_t
sd_csd_v2_t::
read_bl_partial
¶
-
uint8_t
sd_csd_v2_t::
c_size_high
¶
-
uint8_t
sd_csd_v2_t::
reserved3
¶
-
uint8_t
sd_csd_v2_t::
c_size_mid
¶
-
uint8_t
sd_csd_v2_t::
c_size_low
¶
-
uint8_t
sd_csd_v2_t::
sector_size_high
¶
-
uint8_t
sd_csd_v2_t::
erase_blk_en
¶
-
uint8_t
sd_csd_v2_t::
reserved4
¶
-
uint8_t
sd_csd_v2_t::
wp_grp_size
¶
-
uint8_t
sd_csd_v2_t::
sector_size_low
¶
-
uint8_t
sd_csd_v2_t::
write_bl_len_high
¶
-
uint8_t
sd_csd_v2_t::
r2w_factor
¶
-
uint8_t
sd_csd_v2_t::
reserved5
¶
-
uint8_t
sd_csd_v2_t::
wp_grp_enable
¶
-
uint8_t
sd_csd_v2_t::
reserved6
¶
-
uint8_t
sd_csd_v2_t::
write_bl_partial
¶
-
uint8_t
sd_csd_v2_t::
write_bl_len_low
¶
-
uint8_t
sd_csd_v2_t::
reserved7
¶
-
uint8_t
sd_csd_v2_t::
file_format
¶
-
uint8_t
sd_csd_v2_t::
tmp_write_protect
¶
-
uint8_t
sd_csd_v2_t::
perm_write_protect
¶
-
uint8_t
sd_csd_v2_t::
copy
¶
-
uint8_t
sd_csd_v2_t::
file_format_grp
¶
-
uint8_t
sd_csd_v2_t::
crc
¶
-
uint8_t
- union
- struct
sdio
— Secure Digital Input Output¶
Source code: src/drivers/sdio.h, src/drivers/sdio.c
Defines
-
SDIO_IO_RW_EXTENDED_BLOCK_MODE_BYTE
¶
-
SDIO_IO_RW_EXTENDED_BLOCK_MODE_BLOCK
¶
-
SDIO_IO_RW_EXTENDED_OP_CODE_FIXED_ADDRESS
¶
-
SDIO_IO_RW_EXTENDED_OP_CODE_INCREMENTING_ADDRESS
¶
Functions
-
int
sdio_module_init
(void)¶ Initialize the SDIO module. This function must be called before calling any other function in this module.
The module will only be initialized once even if this function is called multiple times.
- Return
- zero(0) or negative error code.
-
int
sdio_init
(struct sdio_driver_t *self_p, struct sdio_device_t *dev_p)¶ Initialize driver object from given configuration.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Driver object to be initialized.dev_p
: Device to use.
-
int
sdio_start
(struct sdio_driver_t *self_p)¶ Starts the SDIO device using given driver object.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Initialized driver object.
-
int
sdio_stop
(struct sdio_driver_t *self_p)¶ Stops the SDIO device referenced by driver object.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Initialized driver object.
-
int
sdio_send_relative_addr
(struct sdio_driver_t *self_p)¶ Send the
send relative address
command (CMD3) to the device and optionally wait for the response.- Return
- zero(0) or negative error code.
- Parameters
self_p
: Initialized driver object.
-
int
sdio_io_send_op_cond
(struct sdio_driver_t *self_p)¶ Send the
io send operation condition
command (CMD5) to the device and optionally wait for the response.- Return
- zero(0) or negative error code.
- Parameters
self_p
: Initialized driver object.
-
int
sdio_select_deselect_card
(struct sdio_driver_t *self_p)¶ Send the
select/deselect card
command (CMD7) to the device and optionally wait for the response.- Return
- zero(0) or negative error code.
- Parameters
self_p
: Initialized driver object.
-
int
sdio_io_read_direct
(struct sdio_driver_t *self_p, void *dst_p)¶ Execute the
input output read write direct
command (CMD52) as a read operation with given parameters.- Return
- Number of bytes read or negative error code.
- Parameters
self_p
: Initialized driver object.dst_p
: Destination buffer.
-
int
sdio_io_write_direct
(struct sdio_driver_t *self_p, const void *src_p)¶ Execute the
input output read write direct
command (CMD52) as a write operation with given parameters.- Return
- Number of bytes written or negative error code.
- Parameters
self_p
: Initialized driver object.src_p
: Source buffer.
-
ssize_t
sdio_io_read_extended
(struct sdio_driver_t *self_p, int function_number, int block_mode, int op_code, void *dst_p, uint32_t src_address, size_t size)¶ Execute the
input output read write extended
command (CMD53) as a read operation with given parameters.- Return
- Number of bytes read or negative error code.
- Parameters
self_p
: Initialized driver object.function_number
: Function number.block_mode
: Block or byte mode.op_code
: Operation code.dst_p
: Destination buffer.src_address
: Source address.size
: Number of bytes to read.
-
ssize_t
sdio_io_write_extended
(struct sdio_driver_t *self_p, int function_number, int block_mode, int op_code, uint32_t dst_address, const void *src_p, size_t size)¶ Execute the
input output read write extended
command (CMD53) as a write operation with given parameters.- Return
- Number of bytes written or negative error code.
- Parameters
self_p
: Initialized driver object.function_number
: Function number.block_mode
: Block or byte mode.op_code
: Operation code.dst_address
: Destination address.src_p
: Source buffer.size
: Number of bytes to write.
Variables
-
struct sdio_device_t
sdio_device
[SDIO_DEVICE_MAX]¶
- struct
Public Members
-
uint8_t
sdio_io_rw_extended_t::
rw_flag
¶
-
uint8_t
sdio_io_rw_extended_t::
function_number
¶
-
uint8_t
sdio_io_rw_extended_t::
block_mode
¶
-
uint8_t
sdio_io_rw_extended_t::
op_code
¶
-
uint8_t
sdio_io_rw_extended_t::
register_address_16_15
¶
-
uint8_t
sdio_io_rw_extended_t::
register_address_14_7
¶
-
uint8_t
sdio_io_rw_extended_t::
register_address_6_0
¶
-
uint8_t
sdio_io_rw_extended_t::
byte_block_count_8
¶
-
uint8_t
sdio_io_rw_extended_t::
byte_block_count_7_0
¶
-
uint8_t
spi
— Serial Peripheral Interface¶
Source code: src/drivers/spi.h, src/drivers/spi.c
Defines
-
SPI_MODE_SLAVE
¶
-
SPI_MODE_MASTER
¶
-
SPI_SPEED_8MBPS
¶
-
SPI_SPEED_4MBPS
¶
-
SPI_SPEED_2MBPS
¶
-
SPI_SPEED_1MBPS
¶
-
SPI_SPEED_500KBPS
¶
-
SPI_SPEED_250KBPS
¶
-
SPI_SPEED_125KBPS
¶
Functions
-
int
spi_module_init
(void)¶ Initialize SPI module. This function must be called before calling any other function in this module.
The module will only be initialized once even if this function is called multiple times.
- Return
- zero(0) or negative error code.
-
int
spi_init
(struct spi_driver_t *self_p, struct spi_device_t *dev_p, struct pin_device_t *ss_pin_p, int mode, int speed, int polarity, int phase)¶ Initialize driver object.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Driver object to initialize.dev_p
: Device to use.ss_pin_p
: Slave select pin device.mode
: Master or slave mode.speed
: Speed in kbps.polarity
: Set to 0 or 1.phase
: Set to 0 or 1.
-
int
spi_start
(struct spi_driver_t *self_p)¶ Start given SPI driver. Configures the SPI hardware.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Initialized driver object.
-
int
spi_stop
(struct spi_driver_t *self_p)¶ Stop given SPI driver. Deconfigures the SPI hardware if given driver currently ownes the bus.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Initialized driver object.
-
int
spi_take_bus
(struct spi_driver_t *self_p)¶ In multi master application the driver must take ownership of the SPI bus before performing data transfers. Will re-configure the SPI hardware if configured by another driver.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Initialized driver object.
-
int
spi_give_bus
(struct spi_driver_t *self_p)¶ In multi master application the driver must give ownership of the SPI bus to let other masters take it.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Initialized driver object.
-
int
spi_select
(struct spi_driver_t *self_p)¶ Select the slave by asserting the slave select pin.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Initialized driver object.
-
int
spi_deselect
(struct spi_driver_t *self_p)¶ Deselect the slave by de-asserting the slave select pin.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Initialized driver object.
-
ssize_t
spi_transfer
(struct spi_driver_t *self_p, void *rxbuf_p, const void *txbuf_p, size_t size)¶ Simultaniuos read/write operation over the SPI bus.
- Return
- Number of transferred bytes or negative error code.
- Parameters
self_p
: Initialized driver object.rxbuf_p
: Buffer to read into.txbuf_p
: Buffer to write.size
: Number of bytes to transfer.
-
ssize_t
spi_read
(struct spi_driver_t *self_p, void *buf_p, size_t size)¶ Read data from the SPI bus.
- Return
- Number of read bytes or negative error code.
- Parameters
self_p
: Initialized driver object.buf_p
: Buffer to read into.size
: Number of bytes to receive.
-
ssize_t
spi_write
(struct spi_driver_t *self_p, const void *buf_p, size_t size)¶ Write data to the SPI bus.
- Return
- Number of written bytes or negative error code.
- Parameters
self_p
: Initialized driver object.buf_p
: Buffer to write.size
: Number of bytes to write.
-
ssize_t
spi_get
(struct spi_driver_t *self_p, uint8_t *data_p)¶ Get one byte of data from the SPI bus.
- Return
- Number of read bytes or negative error code.
- Parameters
self_p
: Initialized driver object.data_p
: Read data.
-
ssize_t
spi_put
(struct spi_driver_t *self_p, uint8_t data)¶ Put one byte of data to the SPI bus.
- Return
- Number of written bytes or negative error code.
- Parameters
self_p
: Initialized driver object.data
: data to write.
Variables
-
struct spi_device_t
spi_device
[SPI_DEVICE_MAX]¶
uart
— Universal Asynchronous Receiver/Transmitter¶
Source code: src/drivers/uart.h, src/drivers/uart.c
Test code: tst/drivers/uart/main.c
Defines
-
uart_read
(self_p, buf_p, size)¶ Read data from the UART.
- Return
- Number of received bytes or negative error code.
- Parameters
self_p
: Initialized driver object.buf_p
: Buffer to read into.size
: Number of bytes to receive.
-
uart_write
(self_p, buf_p, size)¶ Write data to the UART.
- Return
- Number of written bytes or negative error code.
- Parameters
self_p
: Initialized driver object.buf_p
: Buffer to write.size
: Number of bytes to write.
Typedefs
- typedef
Functions
-
int
uart_module_init
(void)¶ Initialize UART module. This function must be called before calling any other function in this module.
The module will only be initialized once even if this function is called multiple times.
- Return
- zero(0) or negative error code.
-
int
uart_init
(struct uart_driver_t *self_p, struct uart_device_t *dev_p, long baudrate, void *rxbuf_p, size_t size)¶ Initialize driver object from given configuration.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Driver object to be initialized.dev_p
: Device to use.baudrate
: Baudrate.rxbuf_p
: Reception buffer.size
: Reception buffer size.
-
int
uart_set_rx_filter_cb
(struct uart_driver_t *self_p, uart_rx_filter_cb_t rx_filter_cb)¶ Set the reception filter callback function.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Initialized driver object.rx_filter_cb
: Callback to set.
-
int
uart_start
(struct uart_driver_t *self_p)¶ Starts the UART device using given driver object.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Initialized driver object.
-
int
uart_stop
(struct uart_driver_t *self_p)¶ Stops the UART device referenced by driver object.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Initialized driver object.
Variables
-
struct uart_device_t
uart_device
[UART_DEVICE_MAX]¶
uart_soft
— Bitbang UART¶
Source code: src/drivers/uart_soft.h, src/drivers/uart_soft.c
Defines
-
uart_soft_read
(self_p, buf_p, size)¶ Read data from the UART.
- Return
- Number of received bytes or negative error code.
- Parameters
self_p
: Initialized driver object.buf_p
: Buffer to read into.size
: Number of bytes to receive.
-
uart_soft_write
(self_p, buf_p, size)¶ Write data to the UART.
- Return
- number of sent bytes or negative error code.
- Parameters
self_p
: Initialized driver object.buf_p
: Buffer to write.size
: Number of bytes to write.
Functions
-
int
uart_soft_init
(struct uart_soft_driver_t *self_p, struct pin_device_t *tx_dev_p, struct pin_device_t *rx_dev_p, struct exti_device_t *rx_exti_dev_p, int baudrate, void *rxbuf_p, size_t size)¶ Initialize driver object from given configuration.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Driver object to be initialized.tx_dev_p
: TX pin device.rx_dev_p
: RX pin device.rx_exti_dev_p
: RX pin external interrupt device.baudrate
: Baudrate.rxbuf_p
: Reception buffer.size
: Reception buffer size.
- struct
- #include <uart_soft.h>
usb
— Universal Serial Bus¶
Source code: src/drivers/usb.h, src/drivers/usb.c
Defines
-
REQUEST_TYPE_DATA_MASK
¶
-
REQUEST_TYPE_DATA_DIRECTION_HOST_TO_DEVICE
¶
-
REQUEST_TYPE_DATA_DIRECTION_DEVICE_TO_HOST
¶
-
REQUEST_TYPE_TYPE_MASK
¶
-
REQUEST_TYPE_TYPE_STANDARD
¶
-
REQUEST_TYPE_TYPE_CLASS
¶
-
REQUEST_TYPE_TYPE_VENDOR
¶
-
REQUEST_TYPE_RECIPIENT_MASK
¶
-
REQUEST_TYPE_RECIPIENT_DEVICE
¶
-
REQUEST_TYPE_RECIPIENT_INTERFACE
¶
-
REQUEST_TYPE_RECIPIENT_ENDPOINT
¶
-
REQUEST_TYPE_RECIPIENT_OTHER
¶
-
REQUEST_GET_STATUS
¶
-
REQUEST_SET_ADDRESS
¶
-
REQUEST_GET_DESCRIPTOR
¶
-
REQUEST_SET_CONFIGURATION
¶
-
DESCRIPTOR_TYPE_DEVICE
¶
-
DESCRIPTOR_TYPE_CONFIGURATION
¶
-
DESCRIPTOR_TYPE_STRING
¶
-
DESCRIPTOR_TYPE_INTERFACE
¶
-
DESCRIPTOR_TYPE_ENDPOINT
¶
-
DESCRIPTOR_TYPE_INTERFACE_ASSOCIATION
¶
-
DESCRIPTOR_TYPE_RPIPE
¶
-
DESCRIPTOR_TYPE_CDC
¶
-
USB_CLASS_USE_INTERFACE
¶
-
USB_CLASS_AUDIO
¶
-
USB_CLASS_CDC_CONTROL
¶
-
USB_CLASS_HID
¶
-
USB_CLASS_PHYSICAL
¶
-
USB_CLASS_IMAGE
¶
-
USB_CLASS_PRINTER
¶
-
USB_CLASS_MASS_STORAGE
¶
-
USB_CLASS_HUB
¶
-
USB_CLASS_CDC_DATA
¶
-
USB_CLASS_SMART_CARD
¶
-
USB_CLASS_CONTENT_SECURITY
¶
-
USB_CLASS_VIDEO
¶
-
USB_CLASS_PERSONAL_HEALTHCARE
¶
-
USB_CLASS_AUDIO_VIDEO_DEVICES
¶
-
USB_CLASS_BILLBOARD_DEVICE_CLASS
¶
-
USB_CLASS_DIAGNOSTIC_DEVICE
¶
-
USB_CLASS_WIRELESS_CONTROLLER
¶
-
USB_CLASS_MISCELLANEOUS
¶
-
USB_CLASS_APPLICATION_SPECIFIC
¶
-
USB_CLASS_VENDOR_SPECIFIC
¶
-
ENDPOINT_ENDPOINT_ADDRESS_DIRECTION
(address)¶
-
ENDPOINT_ENDPOINT_ADDRESS_NUMBER
(address)¶
-
ENDPOINT_ATTRIBUTES_USAGE_TYPE
(attributes)¶
-
ENDPOINT_ATTRIBUTES_SYNCHRONISATION_TYPE
(attributes)¶
-
ENDPOINT_ATTRIBUTES_TRANSFER_TYPE
(attributes)¶
-
ENDPOINT_ATTRIBUTES_TRANSFER_TYPE_CONTROL
¶
-
ENDPOINT_ATTRIBUTES_TRANSFER_TYPE_ISOCHRONOUS
¶
-
ENDPOINT_ATTRIBUTES_TRANSFER_TYPE_BULK
¶
-
ENDPOINT_ATTRIBUTES_TRANSFER_TYPE_INTERRUPT
¶
-
CONFIGURATION_ATTRIBUTES_BUS_POWERED
¶
-
USB_CDC_LINE_CODING
¶
-
USB_CDC_CONTROL_LINE_STATE
¶
-
USB_CDC_SEND_BREAK
¶
-
USB_MESSAGE_TYPE_ADD
¶
-
USB_MESSAGE_TYPE_REMOVE
¶
Functions
-
int
usb_format_descriptors
(void *out_p, uint8_t *buf_p, size_t size)¶ Format the descriptors and write them to given channel.
- Return
- zero(0) or negative error code.
- Parameters
out_p
: Output channel.buf_p
: Pointer to the descriptors to format.size
: Number of bytes in the descriptors buffer.
-
struct usb_descriptor_configuration_t *
usb_desc_get_configuration
(uint8_t *desc_p, size_t size, int configuration)¶ Get the configuration descriptor for given configuration index.
- Return
- Configuration or NULL on failure.
- Parameters
buf_p
: Pointer to the descriptors.size
: Number of bytes in the descriptors buffer.configuration
: Configuration to find.
-
struct usb_descriptor_interface_t *
usb_desc_get_interface
(uint8_t *desc_p, size_t size, int configuration, int interface)¶ Get the interface descriptor for given configuration and interface index.
- Return
- Interface or NULL on failure.
- Parameters
buf_p
: Pointer to the descriptors.size
: Number of bytes in the descriptors buffer.configuration
: Configuration to find.interface
: Interface to find.
-
struct usb_descriptor_endpoint_t *
usb_desc_get_endpoint
(uint8_t *desc_p, size_t size, int configuration, int interface, int endpoint)¶ Get the endpoint descriptor for given configuration, interface and endpoint index.
- Return
- Endpoint or NULL on failure.
- Parameters
buf_p
: Pointer to the descriptors.size
: Number of bytes in the descriptors buffer.configuration
: Configuration to find.interface
: Interface to find.endpoint
: Endpoint to find.
-
int
usb_desc_get_class
(uint8_t *buf_p, size_t size, int configuration, int interface)¶ Get the interface class.
- Return
- Parameters
buf_p
: Pointer to the descriptors.size
: Number of bytes in the descriptors buffer.configuration
: Configuration to find.interface
: Interface to find.
Variables
-
struct usb_device_t
usb_device
[USB_DEVICE_MAX]¶
- struct
Public Members
-
uint8_t
usb_setup_t::
request_type
¶
-
uint8_t
usb_setup_t::
request
¶
-
uint16_t
usb_setup_t::
feature_selector
¶
-
uint16_t
usb_setup_t::
zero_interface_endpoint
¶
-
struct usb_setup_t::@17::@18 usb_setup_t::clear_feature
-
uint16_t
usb_setup_t::
zero0
¶
-
uint16_t
usb_setup_t::
zero1
¶
-
struct usb_setup_t::@17::@19 usb_setup_t::get_configuration
-
uint8_t
usb_setup_t::
descriptor_index
¶
-
uint8_t
usb_setup_t::
descriptor_type
¶
-
uint16_t
usb_setup_t::
language_id
¶
-
struct usb_setup_t::@17::@20 usb_setup_t::get_descriptor
-
uint16_t
usb_setup_t::
device_address
¶
-
uint16_t
usb_setup_t::
zero
¶
-
struct usb_setup_t::@17::@21 usb_setup_t::set_address
-
uint16_t
usb_setup_t::
configuration_value
¶
-
struct usb_setup_t::@17::@22 usb_setup_t::set_configuration
-
uint16_t
usb_setup_t::
value
¶
-
uint16_t
usb_setup_t::
index
¶
-
struct usb_setup_t::@17::@23 usb_setup_t::base
-
union usb_setup_t::@17 usb_setup_t::u
-
uint16_t
usb_setup_t::
length
¶
-
uint8_t
- struct
- struct
Public Members
-
uint8_t
usb_descriptor_device_t::
length
¶
-
uint8_t
usb_descriptor_device_t::
descriptor_type
¶
-
uint16_t
usb_descriptor_device_t::
bcd_usb
¶
-
uint8_t
usb_descriptor_device_t::
device_class
¶
-
uint8_t
usb_descriptor_device_t::
device_subclass
¶
-
uint8_t
usb_descriptor_device_t::
device_protocol
¶
-
uint8_t
usb_descriptor_device_t::
max_packet_size_0
¶
-
uint16_t
usb_descriptor_device_t::
id_vendor
¶
-
uint16_t
usb_descriptor_device_t::
id_product
¶
-
uint16_t
usb_descriptor_device_t::
bcd_device
¶
-
uint8_t
usb_descriptor_device_t::
manufacturer
¶
-
uint8_t
usb_descriptor_device_t::
product
¶
-
uint8_t
usb_descriptor_device_t::
serial_number
¶
-
uint8_t
usb_descriptor_device_t::
num_configurations
¶
-
uint8_t
- struct
Public Members
-
uint8_t
usb_descriptor_configuration_t::
length
¶
-
uint8_t
usb_descriptor_configuration_t::
descriptor_type
¶
-
uint16_t
usb_descriptor_configuration_t::
total_length
¶
-
uint8_t
usb_descriptor_configuration_t::
num_interfaces
¶
-
uint8_t
usb_descriptor_configuration_t::
configuration_value
¶
-
uint8_t
usb_descriptor_configuration_t::
configuration
¶
-
uint8_t
usb_descriptor_configuration_t::
configuration_attributes
¶
-
uint8_t
usb_descriptor_configuration_t::
max_power
¶
-
uint8_t
- struct
Public Members
-
uint8_t
usb_descriptor_interface_t::
length
¶
-
uint8_t
usb_descriptor_interface_t::
descriptor_type
¶
-
uint8_t
usb_descriptor_interface_t::
interface_number
¶
-
uint8_t
usb_descriptor_interface_t::
alternate_setting
¶
-
uint8_t
usb_descriptor_interface_t::
num_endpoints
¶
-
uint8_t
usb_descriptor_interface_t::
interface_class
¶
-
uint8_t
usb_descriptor_interface_t::
interface_subclass
¶
-
uint8_t
usb_descriptor_interface_t::
interface_protocol
¶
-
uint8_t
usb_descriptor_interface_t::
interface
¶
-
uint8_t
- struct
Public Members
-
uint8_t
usb_descriptor_endpoint_t::
length
¶
-
uint8_t
usb_descriptor_endpoint_t::
descriptor_type
¶
-
uint8_t
usb_descriptor_endpoint_t::
endpoint_address
¶
-
uint8_t
usb_descriptor_endpoint_t::
attributes
¶
-
uint16_t
usb_descriptor_endpoint_t::
max_packet_size
¶
-
uint8_t
usb_descriptor_endpoint_t::
interval
¶
-
uint8_t
- struct
- struct
Public Members
-
uint8_t
usb_descriptor_interface_association_t::
length
¶
-
uint8_t
usb_descriptor_interface_association_t::
descriptor_type
¶
-
uint8_t
usb_descriptor_interface_association_t::
first_interface
¶
-
uint8_t
usb_descriptor_interface_association_t::
interface_count
¶
-
uint8_t
usb_descriptor_interface_association_t::
function_class
¶
-
uint8_t
usb_descriptor_interface_association_t::
function_subclass
¶
-
uint8_t
usb_descriptor_interface_association_t::
function_protocol
¶
-
uint8_t
usb_descriptor_interface_association_t::
function
¶
-
uint8_t
- struct
- struct
- struct
- struct
Public Members
-
uint8_t
usb_descriptor_cdc_call_management_t::
length
¶
-
uint8_t
usb_descriptor_cdc_call_management_t::
descriptor_type
¶
-
uint8_t
usb_descriptor_cdc_call_management_t::
sub_type
¶
-
uint8_t
usb_descriptor_cdc_call_management_t::
capabilities
¶
-
uint8_t
usb_descriptor_cdc_call_management_t::
data_interface
¶
-
uint8_t
- union
Public Members
-
struct usb_descriptor_header_t
usb_descriptor_t::
header
¶
-
struct usb_descriptor_device_t
usb_descriptor_t::
device
¶
-
struct usb_descriptor_configuration_t
usb_descriptor_t::
configuration
¶
-
struct usb_descriptor_interface_t
usb_descriptor_t::
interface
¶
-
struct usb_descriptor_endpoint_t
usb_descriptor_t::
endpoint
¶
-
struct usb_descriptor_string_t
usb_descriptor_t::
string
¶
-
struct usb_descriptor_header_t
- struct
- struct
Public Members
-
int
usb_message_header_t::
type
¶
-
int
- struct
Public Members
-
struct usb_message_header_t
usb_message_add_t::
header
¶
-
int
usb_message_add_t::
device
¶
-
struct usb_message_header_t
- union
Public Members
-
struct usb_message_header_t
usb_message_t::
header
¶
-
struct usb_message_add_t
usb_message_t::
add
¶
-
struct usb_message_header_t
usb_device
— Universal Serial Bus - Device¶
A USB device is powered and enumerated by a USB host.
The implementation of this module aims to be simple, but yet flexible. It’s possible to change the USB configuration descriptors at runtime by stopping the current driver, initialize a new driver and start the new driver. For simple devices only a single configuration is normally needed.
Using the USB device module is fairly easy. First write the USB descriptors, then initialize the class drivers, then initialize the USB device driver and then start it.
See the test code below for an example usage.
Class driver modules:
usb_device_class_cdc
— CDC ACM (serial port over USB)¶
USB CDC (Communications Device Class) ACM (Abstract Control Model) is a vendor-independent publicly documented protocol that can be used for emulating serial ports over USB.
More information on Wikipedia.
Source code: src/drivers/usb/device/class/cdc.h, src/drivers/usb/device/class/cdc.c
Test code: tst/drivers/usb_device/main.c
Defines
-
usb_device_class_cdc_read
(self_p, buf_p, size)¶ Read data from the CDC driver.
- Return
- Number of bytes read or negative error code.
- Parameters
self_p
: Initialized driver object.buf_p
: Buffer to read into.size
: Number of bytes to read.
-
usb_device_class_cdc_write
(self_p, buf_p, size)¶ Write data to the CDC driver.
- Return
- Number of bytes written or negative error code.
- Parameters
self_p
: Initialized driver object.buf_p
: Buffer to write.size
: Number of bytes to write.
Functions
-
int
usb_device_class_cdc_module_init
(void)¶ Initialize the CDC module.
- Return
- zero(0) or negative error code.
-
int
usb_device_class_cdc_init
(struct usb_device_class_cdc_driver_t *self_p, int control_interface, int endpoint_in, int endpoint_out, void *rxbuf_p, size_t size)¶ Initialize driver object from given configuration.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Driver object to be initialized.rxbuf_p
: Reception buffer.size
: Reception buffer size.
-
int
usb_device_class_cdc_input_isr
(struct usb_device_class_cdc_driver_t *self_p)¶ Called by the USB device driver periodically to let the CDC driver read received data from the hardware.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Initialized driver object.
-
int
usb_device_class_cdc_is_connected
(struct usb_device_class_cdc_driver_t *self_p)¶ Check if the CDC is connected to the remote endpoint.
- Return
- true(1) if connected, false(0) if disconnected, otherwise negative error code.
- Parameters
self_p
: Initialized driver object.
- struct
- #include <cdc.h>
Public Members
-
struct usb_device_driver_base_t
usb_device_class_cdc_driver_t::
base
¶
-
struct usb_device_driver_t *
usb_device_class_cdc_driver_t::
drv_p
¶
-
int
usb_device_class_cdc_driver_t::
control_interface
¶
-
int
usb_device_class_cdc_driver_t::
endpoint_in
¶
-
int
usb_device_class_cdc_driver_t::
endpoint_out
¶
-
int
usb_device_class_cdc_driver_t::
line_state
¶
-
struct usb_cdc_line_info_t
usb_device_class_cdc_driver_t::
line_info
¶
-
struct usb_device_driver_base_t
Source code: src/drivers/usb_device.h, src/drivers/usb_device.c
Test code: tst/drivers/usb_device/main.c
Functions
-
int
usb_device_module_init
(void)¶
-
int usb_device_init(struct usb_device_driver_t * self_p, struct usb_device_t * dev_p, struct usb_device_driver_base_t ** drivers_pp, int drivers_max, FAR const union usb_descriptor_t ** descriptors_pp)
Initialize the USB device driver object from given configuration.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Driver object to be initialized.dev_p
: USB device to use.drivers_pp
: An array of initialized drivers.drivers_max
: Length of the drivers array.descriptors_pp
: A NULL terminated array of USB descriptors.
-
int
usb_device_start
(struct usb_device_driver_t *self_p)¶ Start the USB device device using given driver object.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Initialized driver object.
-
int
usb_device_stop
(struct usb_device_driver_t *self_p)¶ Stop the USB device device referenced by driver object.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Initialized driver object.
-
ssize_t
usb_device_write
(struct usb_device_driver_t *self_p, int endpoint, const void *buf_p, size_t size)¶ Write data to given endpoint.
- Return
- Number of bytes written or negative error code.
- Parameters
self_p
: Initialized driver object.endpoint
: Endpoint to write to.buf_p
: Buffer to write.size
: Number of bytes to write.
-
ssize_t
usb_device_read_isr
(struct usb_device_driver_t *self_p, int endpoint, void *buf_p, size_t size)¶ Read data from given endpoint from an isr or with the system lock taken.
- Return
- Number of bytes read or negative error code.
- Parameters
self_p
: Initialized driver object.endpoint
: Endpoint to read data from.buf_p
: Buffer to read into.size
: Number of bytes to read.
-
ssize_t
usb_device_write_isr
(struct usb_device_driver_t *self_p, int endpoint, const void *buf_p, size_t size)¶ Write data to given endpoint from an isr or with the system lock taken.
- Return
- Number of bytes written or negative error code.
- Parameters
self_p
: Initialized driver object.endpoint
: Endpoint to write to.buf_p
: Buffer to write.size
: Number of bytes to write.
usb_host
— Universal Serial Bus - Host¶
A USB host powers the bus and enumerates connected USB devices.
Class driver modules:
usb_host_class_hid
— Human Interface Device (HID)¶
In computing, the USB human interface device class (USB HID class) is a part of the USB specification for computer peripherals: it specifies a device class (a type of computer hardware) for human interface devices such as keyboards, mice, game controllers and alphanumeric display devices.
More information on Wikipedia.
Source code: src/drivers/usb/host/class/hid.h, src/drivers/usb/host/class/hid.c
Defines
-
USB_CLASS_HID_SUBCLASS_NONE
¶
-
USB_CLASS_HID_SUBCLASS_BOOT_INTERFACE
¶
-
USB_CLASS_HID_PROTOCOL_NONE
¶
-
USB_CLASS_HID_PROTOCOL_KEYBOARD
¶
-
USB_CLASS_HID_PROTOCOL_MOUSE
¶
Functions
-
int
usb_host_class_hid_init
(struct usb_host_class_hid_driver_t *self_p, struct usb_host_driver_t *usb_p, struct usb_host_class_hid_device_t *devices_p, size_t length)¶ Initialize driver object from given configuration.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Driver object to be initialized.usb_p
: USB driver to use.devices_p
: Array of devices. One entry in this array is allocated for each HID device that is connected to the host.length
: Length of the devices array.
-
int
usb_host_class_hid_start
(struct usb_host_class_hid_driver_t *self_p)¶ Starts the HID driver.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Initialized driver object to start.
-
int
usb_host_class_hid_stop
(struct usb_host_class_hid_driver_t *self_p)¶ Stops the HID driver.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Initialized to stop.
- struct
Public Members
-
uint8_t
usb_host_class_hid_device_t::
buf
[1]¶
-
uint8_t
- struct
Public Members
-
struct usb_host_driver_t *
usb_host_class_hid_driver_t::
usb_p
¶
-
struct usb_host_class_hid_device_t *
usb_host_class_hid_driver_t::
devices_p
¶
-
size_t
usb_host_class_hid_driver_t::
length
¶
-
size_t
usb_host_class_hid_driver_t::
size
¶
-
struct usb_host_class_hid_driver_t::@15 usb_host_class_hid_driver_t::report
-
struct usb_host_device_driver_t
usb_host_class_hid_driver_t::
device_driver
¶
-
struct usb_host_driver_t *
usb_host_class_mass_storage
— Mass Storage¶
The USB mass storage device class (also known as USB MSC or UMS) is a set of computing communications protocols defined by the USB Implementers Forum that makes a USB device accessible to a host computing device and enables file transfers between the host and the USB device. To a host, the USB device acts as an external hard drive; the protocol set interfaces with a number of storage devices.
More information on Wikipedia.
Source code: src/drivers/usb/host/class/mass_storage.h, src/drivers/usb/host/class/mass_storage.c
Functions
-
int
usb_host_class_mass_storage_init
(struct usb_host_class_mass_storage_driver_t *self_p, struct usb_host_driver_t *usb_p, struct usb_host_class_mass_storage_device_t *devices_p, size_t length)¶
-
int
usb_host_class_mass_storage_start
(struct usb_host_class_mass_storage_driver_t *self_p)¶
-
int
usb_host_class_mass_storage_stop
(struct usb_host_class_mass_storage_driver_t *self_p)¶
-
ssize_t
usb_host_class_mass_storage_device_read
(struct usb_host_device_t *device_p, void *buf_p, size_t address, size_t size)¶
- struct
- #include <mass_storage.h>
Public Members
-
uint8_t
usb_host_class_mass_storage_device_t::
buf
[1]¶
-
uint8_t
- struct
Public Members
-
struct usb_host_driver_t *
usb_host_class_mass_storage_driver_t::
usb_p
¶
-
struct usb_host_class_mass_storage_device_t *
usb_host_class_mass_storage_driver_t::
devices_p
¶
-
size_t
usb_host_class_mass_storage_driver_t::
length
¶
-
size_t
usb_host_class_mass_storage_driver_t::
size
¶
-
struct usb_host_class_mass_storage_driver_t::@16 usb_host_class_mass_storage_driver_t::report
-
struct usb_host_device_driver_t
usb_host_class_mass_storage_driver_t::
device_driver
¶
-
struct usb_host_driver_t *
Source code: src/drivers/usb_host.h, src/drivers/usb_host.c
Defines
-
USB_HOST_DEVICE_STATE_NONE
¶
-
USB_HOST_DEVICE_STATE_ATTACHED
¶
-
USB_PIPE_TYPE_CONTROL
¶
-
USB_PIPE_TYPE_INTERRUPT
¶
-
USB_PIPE_TYPE_ISOCHRONOUS
¶
-
USB_PIPE_TYPE_BULK
¶
Functions
-
int
usb_host_module_init
(void)¶ Initialize the USB host module. This function must be called before calling any other function in this module.
The module will only be initialized once even if this function is called multiple times.
- Return
- zero(0) or negative error code.
-
int
usb_host_init
(struct usb_host_driver_t *self_p, struct usb_device_t *dev_p, struct usb_host_device_t *devices_p, size_t length)¶ Initialize the USB host driver object from given configuration.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Driver object to be initialized.dev_p
: USB device to use.devices_p
: An array of devices. One entry in this array is allocated for each USB device that is connected to the host.length
: Length of the devices array.
-
int
usb_host_start
(struct usb_host_driver_t *self_p)¶ Start the USB host device using given driver object.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Initialized driver object.
-
int
usb_host_stop
(struct usb_host_driver_t *self_p)¶ Stop the USB host device referenced by driver object.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Initialized driver object.
-
int
usb_host_driver_add
(struct usb_host_driver_t *self_p, struct usb_host_device_driver_t *driver_p, void *arg_p)¶ Add given class/vendor driver to the USB host driver.
When a USB device is plugged in, its class and vendor information is read by the host. Those values are used to find the device driver for this particular device. If there is no driver, the device cannot be configured and will not work.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Initialized driver object.driver_p
: USB device driver to add.
-
int
usb_host_driver_remove
(struct usb_host_driver_t *self_p, struct usb_host_device_driver_t *driver_p)¶ Remove given class/vendor driver from the USB host driver.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Initialized driver object.driver_p
: USB device driver to remove.
-
struct usb_host_device_t *
usb_host_device_open
(struct usb_host_driver_t *self_p, int device)¶ Open given device in given driver. Open a device before reading and writing data to it with usb_host_device_read() or usb_host_device_write().
- Return
- Opened device or NULL on failure.
- Parameters
self_p
: Initialized driver.device
: Device to open.
-
int
usb_host_device_close
(struct usb_host_driver_t *self_p, int device)¶ Close given device in given driver.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Initialized driver.device
: Device to close.
-
ssize_t
usb_host_device_read
(struct usb_host_device_t *device_p, int endpoint, void *buf_p, size_t size)¶ Read data from given endpoint for given device.
- Return
- Number of bytes read or negative error code.
- Parameters
device_p
: Device to read from.endpoint
: Endpoint to read data from.buf_p
: Buffer to read into.size
: Number of bytes to read.
-
ssize_t
usb_host_device_write
(struct usb_host_device_t *device_p, int endpoint, const void *buf_p, size_t size)¶ Write data to given endpoint for given device.
- Return
- Number of bytes written or negative error code.
- Parameters
device_p
: Device to write to.endpoint
: Endpoint to write to.buf_p
: Buffer to write.size
: Number of bytes to write.
-
ssize_t
usb_host_device_control_transfer
(struct usb_host_device_t *device_p, struct usb_setup_t *setup_p, void *buf_p, size_t size)¶ Perform a control transfer on endpoint zero(0).
A control transfer can have up to three stages. First the setup stage, then an optional data stage, and at last a status stage.
- Return
- Number of bytes read/written or negative error code.
- Parameters
device_p
: Device to write to.setup_p
: Setup packet to write.buf_p
: Buffer to read/write. May be NULL if no data shall be transferred.size
: Number of bytes to read/write.
-
int
usb_host_device_set_configuration
(struct usb_host_device_t *device_p, uint8_t configuration)¶ Set configuration for given device.
- Return
- zero(0) or negative error code.
- Parameters
device_p
: Device to use.configuration
: Configuration to set.
- struct
- #include <usb_host.h>
An USB device as seen by the host.
Public Members
-
int
usb_host_device_t::
id
¶
-
int
usb_host_device_t::
state
¶
-
int
usb_host_device_t::
address
¶
-
int
usb_host_device_t::
vid
¶
-
int
usb_host_device_t::
pid
¶
-
char *
usb_host_device_t::
description_p
¶
-
size_t
usb_host_device_t::
max_packet_size
¶
-
uint8_t
usb_host_device_t::
configuration
¶
-
struct usb_descriptor_device_t *
usb_host_device_t::
dev_p
¶
-
struct usb_descriptor_configuration_t *
usb_host_device_t::
conf_p
¶
-
struct usb_host_device_t::@24::@26 usb_host_device_t::descriptor
-
struct usb_host_device_t::@24 usb_host_device_t::current
-
struct usb_host_driver_t *
usb_host_device_t::
self_p
¶
-
struct usb_pipe_t *
usb_host_device_t::
pipes
[32]¶
-
size_t
usb_host_device_t::
size
¶
-
uint8_t
usb_host_device_t::
buf
[128]¶
-
struct usb_host_device_t::@25 usb_host_device_t::descriptors
-
int
- struct
- #include <usb_host.h>
Used to find a device driver.
Public Members
-
int (*
usb_host_device_driver_t::
supports
)(struct usb_host_device_t *)¶
-
int (*
usb_host_device_driver_t::
enumerate
)(struct usb_host_device_t *)¶
-
struct usb_host_device_driver_t *
usb_host_device_driver_t::
next_p
¶
-
int (*
watchdog
— Hardware watchdog¶
Source code: src/drivers/watchdog.h, src/drivers/watchdog.c
Functions
-
int
watchdog_module_init
(void)¶
-
int
watchdog_start_ms
(int timeout)¶ Start the watchdog with given timeout. Use
watchdog_kick()
to periodically restart the timer.- Return
- zero(0) or negative error code.
- Parameters
timeout
: Watchdog timeout in milliseconds.
-
int
watchdog_stop
(void)¶ Stop the watchdog.
- Return
- zero(0) or negative error code.
-
int
watchdog_kick
(void)¶ Kick the watchdog. Restarts the watchdog timer with its original timeout given to
watchdog_start_ms()
. The board will be reset if this function is not called before the watchdog timer expires.- Return
- zero(0) or negative error code.
sync¶
Thread synchronization refers to the idea that multiple threads are to join up or handshake at a certain point, in order to reach an agreement or commit to a certain sequence of action.
The sync package on Github.
bus
— Message bus¶
A message bus provides a software-bus abstraction that gathers all the communications between a group of threads over a single shared virtual channel. Messages are transferred on the bus from a sender to one or more attached listeners. The concept is analogous to the bus concept found in computer hardware architecture.
Example¶
In this example there is a bus with three listeners attached; listerner 0, 1 and 2. Listener 0 and 1 are attached to the bus listening for message id 7, and listener 2 for message id 9.
Any thread can write a message to the bus by calling
bus_write()
. If a message with id 7 is written to the bus, both
listerner 0 and 1 will receive the message. Listener 2 will
receive messages with id 9.
Messages are read from the listener channel by the thread that owns the listener.
+--------------+ +--------------+
| listener 0 | | listener 2 |
| id:7, chan:0 | | id:9, chan:2 |
+-------+------+ +-------+------+
| |
BUS ========+==============+==============+=======
|
+-------+------+
| listener 1 |
| id:7, chan:1 |
+--------------+
Source code: src/sync/bus.h, src/sync/bus.c
Test code: tst/sync/bus/main.c
Test coverage: src/sync/bus.c
Functions
-
int
bus_module_init
(void)¶ Initialize the bus module. This function must be called before calling any other function in this module.
The module will only be initialized once even if this function is called multiple times.
- Return
- zero(0) or negative error code
-
int
bus_init
(struct bus_t *self_p)¶ Initialize given bus.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Bus to initialize.
-
int
bus_listener_init
(struct bus_listener_t *self_p, int id, void *chan_p)¶ Initialize given listener to receive messages with given id, after the listener is attached to the bus. A listener can only receive messages of a single id, though, the same channel may be used in multiple listeners with different ids (if the channel supports it).
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Listener to initialize.id
: Message id to receive.chan_p
: Channel to receive messages on.
-
int
bus_attach
(struct bus_t *self_p, struct bus_listener_t *listener_p)¶ Attach given listener to given bus. Messages written to the bus will be written to all listeners initialized with the written message id.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Bus to attach the listener to.listener_p
: Listener to attach to the bus.
-
int
bus_detatch
(struct bus_t *self_p, struct bus_listener_t *listener_p)¶ Detatch given listener from given bus. A detached listener will not receive any messages from the bus.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Bus to detach listener from.listener_p
: Listener to detach from the bus.
-
int
bus_write
(struct bus_t *self_p, int id, const void *buf_p, size_t size)¶ Write given message to given bus. All attached listeners to given bus will receive the message.
- Return
- Number of listeners that received the message, or negative error code.
- Parameters
self_p
: Bus to write the message to.id
: Message identity.buf_p
: Buffer to write to the bus. All listeners with given message id will receive this data.size
: Number of bytes to write.
- struct
- #include <bus.h>
- struct
Public Members
-
struct binary_tree_node_t
bus_listener_t::
base
¶
-
int
bus_listener_t::
id
¶
-
void *
bus_listener_t::
chan_p
¶
-
struct bus_listener_t *
bus_listener_t::
next_p
¶
-
struct binary_tree_node_t
chan
— Abstract channel communication¶
Threads often communicate over channels. The producer thread or isr writes data to a channel and the consumer reads it. The may be multiple producers writing to a single channel, but only one consumer is allowed.
In the first example, thread 0
and thread 1
communicates over
a channel. thread 0
writes data to the channel and thread 1
read the written data.
+------------+ +------------+
| thread 0 | channel 0 | thread 1 |
| +=============+ |
| producer | | consumer |
+------------+ +------------+
In the socond example, isr 0
and thread 2
communicates over a
channel. isr 0
writes data to the channel and thread 2
read
the written data.
+------------+ +------------+
| isr 0 | channel 1 | thread 2 |
| +=============+ |
| producer | | consumer |
+------------+ +------------+
Source code: src/sync/chan.h, src/sync/chan.c
Test coverage: src/sync/chan.c
Typedefs
- typedef
- typedef
Channel write function callback type.
- Return
- Number of written bytes or negative error code.
- Parameters
self_p
: Channel to write to.buf_p
: Buffer to write.size
: Number of bytes to write.
- typedef
Channel write filter function callback type.
- Return
- true(1) if the buffer shall be written to the channel, otherwise false(0).
- Parameters
self_p
: Channel to write to.buf_p
: Buffer to write.size
: Number of bytes in buffer.
- typedef
Channel size function callback type.
- Return
- Number of bytes available.
- Parameters
self_p
: Channel to get the size of.
Functions
-
int
chan_module_init
(void)¶ Initialize the channel module. This function must be called before calling any other function in this module.
The module will only be initialized once even if this function is called multiple times.
- Return
- zero(0) or negative error code.
-
int
chan_init
(struct chan_t *self_p, chan_read_fn_t read, chan_write_fn_t write, chan_size_fn_t size)¶ Initialize given channel with given callbacks. A channel must be initialized before it can be used.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Channel to initialize.read
: Read function callback. This function must implement the channel read functionality, and will be called when the user reads data from the channel.write
: Write function callback. This function must implement the channel write functionality, and will be called when the user writes data to the channel.size
: Size function callback. This function must return the size of the channel. It should return zero(0) if there is no data available in the channel, and otherwise a positive integer.
-
int
chan_set_write_isr_cb
(struct chan_t *self_p, chan_write_fn_t write_isr_cb)¶ Set the write isr function callback.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Initialized driver object.filter
: Write isr function to set.
-
int
chan_set_write_filter_cb
(struct chan_t *self_p, chan_write_filter_fn_t write_filter_cb)¶ Set the write filter callback function. The write filter function is called when data is written to the channel, and its return value determines is the data shall be written to the underlying channel implementation, or discarded.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Initialized driver object.write_filter_cb
: filter Write filter function to set.
-
int
chan_set_write_filter_isr_cb
(struct chan_t *self_p, chan_write_filter_fn_t write_filter_isr_cb)¶ Set the write isr filter callback function. The write filter function is called when data is written to the channel, and its return value determines is the data shall be written to the underlying channel implementation, or discarded.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Initialized driver object.write_filter_isr_cb
: filter Write filter function to set.
-
ssize_t
chan_read
(void *self_p, void *buf_p, size_t size)¶ Read data from given channel. The behaviour of this function depends on the channel implementation. Often, the calling thread will be blocked until all data has been read or an error occurs.
- Return
- Number of read bytes or negative error code.
- Parameters
self_p
: Channel to read from.buf_p
: Buffer to read into.size
: Number of bytes to read.
-
ssize_t
chan_write
(void *self_p, const void *buf_p, size_t size)¶ Write data to given channel. The behaviour of this function depends on the channel implementation. Some channel implementations blocks until the receiver has read the data, and some returns immediately.
- Return
- Number of written bytes or negative error code.
- Parameters
self_p
: Channel to write to.buf_p
: Buffer to write.size
: Number of bytes to write.
-
size_t
chan_size
(void *self_p)¶ Get the number of bytes available to read from given channel.
- Return
- Number of bytes available.
- Parameters
self_p
: Channel to get the size of.
-
ssize_t
chan_write_isr
(void *self_p, const void *buf_p, size_t size)¶ Write data to given channel from interrupt context or with the system lock taken. The behaviour of this function depends on the channel implementation. Some channel implementations blocks until the receiver has read the data, and some returns immediately.
- Return
- Number of written bytes or negative error code.
- Parameters
self_p
: Channel to write to.buf_p
: Buffer to write.size
: Number of bytes to write.
-
int
chan_is_polled_isr
(struct chan_t *self_p)¶ Check if a channel is polled. May only be called from isr or with the system lock taken (see
sys_lock()
).- Return
- true(1) or false(0).
- Parameters
self_p
: Channel to check.
-
int
chan_list_init
(struct chan_list_t *list_p, void *workspace_p, size_t size)¶ Initialize an empty list of channels. A list is used to wait for data on multiple channel at the same time. When there is data on at least one channel, the poll function returns and the application can read from the channel with data.
- Return
- zero(0) or negative error code.
- Parameters
list_p
: List to initialize.workspace_p
: Workspace for internal use.size
: Size of the workspace in bytes.
-
int
chan_list_destroy
(struct chan_list_t *list_p)¶ Destroy an initialized list of channels.
- Return
- zero(0) or negative error code.
- Parameters
list_p
: List to destroy.
-
int
chan_list_add
(struct chan_list_t *list_p, void *chan_p)¶ Add given channel to list of channels.
- Return
- zero(0) or negative error code.
- Parameters
list_p
: List of channels.chan_p
: Channel to add.
-
int
chan_list_remove
(struct chan_list_t *list_p, void *chan_p)¶ Remove given channel from list of channels.
- Return
- zero(0) or negative error code.
- Parameters
list_p
: List of channels.chan_p
: Channel to remove.
-
void *
chan_list_poll
(struct chan_list_t *list_p, struct time_t *timeout_p)¶ Poll given list of channels for events. Blocks until at least one of the channels in the list has data ready to be read or an timeout occurs.
- Return
- Channel with data or NULL on timeout.
- Parameters
list_p
: List of channels to poll.timeout_p
: Time to wait for data on any channel before a timeout occurs. Set to NULL to wait forever.
-
void *
chan_poll
(void *chan_p, struct time_t *timeout_p)¶ Poll given channel for events. Blocks until the channel has data ready to be read or an timeout occurs.
- Return
- The channel or NULL on timeout.
- Parameters
chan_p
: Channel to poll.timeout_p
: Time to wait for data on the channel before a timeout occurs. Set to NULL to wait forever.
-
void *
chan_null
(void)¶ Get a reference to the null channel. This channel will ignore all written data but return that it was successfully written.
- Return
- The null channel.
-
ssize_t
chan_read_null
(void *self_p, void *buf_p, size_t size)¶ Null channel read function callback. Pass to
chan_init()
if no read function callback is needed for the channel.- Return
- Always returns -1.
-
ssize_t
chan_write_null
(void *self_p, const void *buf_p, size_t size)¶ Null channel write function callback. Pass to
chan_init()
if no write function callback is needed for the channel.- Return
- Always returns
size
.
-
size_t
chan_size_null
(void *self_p)¶ Null channel size function callback. Pass to
chan_init()
if no size function callback is needed for the channel.- Return
- Always returns zero(0).
- struct
- struct
- #include <chan.h>
Channel datastructure.
Public Members
-
chan_read_fn_t
chan_t::
read
¶
-
chan_write_fn_t
chan_t::
write
¶
-
chan_size_fn_t
chan_t::
size
¶
-
chan_write_filter_fn_t
chan_t::
write_filter_cb
¶
-
chan_write_fn_t
chan_t::
write_isr
¶
-
chan_write_filter_fn_t
chan_t::
write_filter_isr_cb
¶
-
struct chan_list_t *
chan_t::
list_p
¶
-
chan_read_fn_t
event
— Event channel¶
An event channel consists of a 32 bits bitmap, where each bit corresponds to an event state. If the bit is set, the event is active. Since an event only has two states, active and inactive, signalling the same event multiple times will just result in the event to be active. There is no internal counter of how “active” an event is, it’s simply active or inactive.
Source code: src/sync/event.h, src/sync/event.c
Test code: tst/sync/event/main.c
Test coverage: src/sync/event.c
Functions
-
int
event_init
(struct event_t *self_p)¶ Initialize given event channel.
- Return
- zero(0) or negative error code
- Parameters
self_p
: Event channel to initialize.
-
ssize_t
event_read
(struct event_t *self_p, void *buf_p, size_t size)¶ Wait for an event to occur in given event mask. This function blocks until at least one of the events in the event mask has been set. When the function returns, given event mask has been overwritten with the events that actually occured.
- Return
- sizeof(mask) or negative error code.
- Parameters
self_p
: Event channel object.buf_p
: The mask of events to wait for. When the function returns the mask contains the events that have occured.size
: Size to read (always sizeof(mask)).
-
ssize_t
event_write
(struct event_t *self_p, const void *buf_p, size_t size)¶ Write given event(s) to given event channel.
- Return
- sizeof(mask) or negative error code.
- Parameters
self_p
: Event channel object.buf_p
: The mask of events to write.size
: Must always be sizeof(mask).
-
ssize_t
event_write_isr
(struct event_t *self_p, const void *buf_p, size_t size)¶ Write given events to the event channel from isr or with the system lock taken (see
sys_lock()
).- Return
- sizeof(mask) or negative error code.
- Parameters
self_p
: Event channel object.buf_p
: The mask of events to write.size
: Must always be sizeof(mask).
- struct
- #include <event.h>
queue
— Queue channel¶
The most common channel is the queue. It can be either synchronous or semi-asynchronous. In the synchronous version the writing thread will block until all written data has been read by the reader. In the semi-asynchronous version the writer writes to a buffer within the queue, and only blocks all data does not fit in the buffer. The buffer size is selected by the application when initializing the queue.
The diagram below shows how two threads communicates using a queue. The writer thread writes from its source buffer to the queue. The reader thread reads from the queue to its destination buffer.
The data is either copied directly from the source to the destination buffer (1. in the figure), or via the internal queue buffer (2. in the figure).
- The reader thread is waiting for data. The writer writes from its source buffer directly to the readers’ destination buffer.
- The reader thread is not waiting for data. The writer writes from its source buffer into the queue buffer. Later, the reader reads data from the queue buffer to its destination buffer.
Source code: src/sync/queue.h, src/sync/queue.c
Test code: tst/sync/queue/main.c
Test coverage: src/sync/queue.c
Example code: examples/queue/main.c
Defines
-
QUEUE_INIT_DECL
(_name, _buf, _size)¶
Enums
-
enum type
queue_state_t
¶ Values:
- = 0
Queue initialized state.
Queue running state.
Queue stopped state.
Functions
-
int
queue_init
(struct queue_t *self_p, void *buf_p, size_t size)¶ Initialize given queue.
- Return
- zero(0) or negative error code
- Parameters
self_p
: Queue to initialize.buf_p
: Buffer.size
: Size of buffer.
-
int
queue_start
(struct queue_t *self_p)¶ Start given queue. It is not required to start a queue unless it has been stopped.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Queue to start.
-
int
queue_stop
(struct queue_t *self_p)¶ Stop given queue. Any ongoing read and write operations will return with the currently read/written number of bytes. Any read and write operations on a stopped queue will return zero(0).
- Return
- true(1) if a thread was resumed, false(0) if no thread was resumed, or negative error code.
- Parameters
self_p
: Queue to stop.
-
int
queue_stop_isr
(struct queue_t *self_p)¶ Same as
queue_stop()
but from isr or with the system lock taken (seesys_lock()
).
-
ssize_t
queue_read
(struct queue_t *self_p, void *buf_p, size_t size)¶ Read from given queue. Blocks until size bytes has been read.
- Return
- Number of read bytes or negative error code.
- Parameters
self_p
: Queue to read from.buf_p
: Buffer to read to.size
: Size to read.
-
ssize_t
queue_write
(struct queue_t *self_p, const void *buf_p, size_t size)¶ Write bytes to given queue. Blocks until size bytes has been written.
- Return
- Number of written bytes or negative error code.
- Parameters
self_p
: Queue to write to.buf_p
: Buffer to write from.size
: Number of bytes to write.
-
ssize_t
queue_write_isr
(struct queue_t *self_p, const void *buf_p, size_t size)¶ Write bytes to given queue from isr or with the system lock taken (see
sys_lock()
). May write less than size bytes.- Return
- Number of written bytes or negative error code.
- Parameters
self_p
: Queue to write to.buf_p
: Buffer to write from.size
: Number of bytes to write.
-
ssize_t
queue_size
(struct queue_t *self_p)¶ Get the number of bytes currently stored in the queue. May return less bytes than number of bytes stored in the channel.
- Return
- Number of bytes in queue.
- Parameters
self_p
: Queue.
- struct
- struct
Public Members
-
struct queue_buffer_t
queue_t::
buffer
¶
-
queue_state_t
queue_t::
state
¶
-
char *
queue_t::
buf_p
¶
-
size_t
queue_t::
size
¶
-
size_t
queue_t::
left
¶
-
struct queue_buffer_t
rwlock
— Reader-writer lock¶
An RW lock allows concurrent access for read-only operations, while write operations require exclusive access. This means that multiple threads can read the data in parallel but an exclusive lock is needed for writing or modifying data. When a writer is writing the data, all other writers or readers will be blocked until the writer is finished writing. A common use might be to control access to a data structure in memory that cannot be updated atomically and is invalid (and should not be read by another thread) until the update is complete.
Source code: src/sync/rwlock.h, src/sync/rwlock.c
Test code: tst/sync/rwlock/main.c
Test coverage: src/sync/rwlock.c
Functions
-
int
rwlock_module_init
(void)¶ Initialize the reader-writer lock module. This function must be called before calling any other function in this module.
The module will only be initialized once even if this function is called multiple times.
- Return
- zero(0) or negative error code
-
int
rwlock_init
(struct rwlock_t *self_p)¶ Initialize given reader-writer lock object.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Reader-writer lock to initialize.
-
int
rwlock_reader_take
(struct rwlock_t *self_p)¶ Take given reader-writer lock. Multiple threads can have the reader lock at the same time.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Reader-writer lock to take.
-
int
rwlock_reader_give
(struct rwlock_t *self_p)¶ Give given reader-writer lock.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Reader-writer lock give.
-
int
rwlock_reader_give_isr
(struct rwlock_t *self_p)¶ Give given reader-writer lock from isr or with the system lock taken.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Reader-writer lock to give.
-
int
rwlock_writer_take
(struct rwlock_t *self_p)¶ Take given reader-writer lock as a writer. Only one thread can have the lock at a time, including both readers and writers.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Reader-writer lock to take.
- struct
- #include <rwlock.h>
sem
— Counting semaphores¶
The semaphore is a synchronization primitive used to protect a shared resource. A semaphore counts the number of resources taken, and suspends threads when the maximum number of resources are taken. When a resource becomes available, a suspended thread is resumed.
A semaphore initialized with count_max one(1) is called a binary semaphore. A binary semaphore can only be taken by one thread at a time and can be used to signal that an event has occured. That is, sem_give() may be called multiple times and the semaphore resource count will remain at zero(0) until sem_take() is called.
Source code: src/sync/sem.h, src/sync/sem.c
Test code: tst/sync/sem/main.c
Test coverage: src/sync/sem.c
Defines
-
SEM_INIT_DECL
(name, _count, _count_max)¶
Functions
-
int
sem_module_init
(void)¶ Initialize the semaphore module. This function must be called before calling any other function in this module.
The module will only be initialized once even if this function is called multiple times.
- Return
- zero(0) or negative error code
-
int
sem_init
(struct sem_t *self_p, int count, int count_max)¶ Initialize given semaphore object. Maximum count is the number of resources that can be taken at any given moment.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Semaphore to initialize.count
: Initial taken resource count. Set the initial count to the same value as count_max to initialize the semaphore with all resources taken.count_max
: Maximum number of resources that can be taken at any given moment.
-
int
sem_take
(struct sem_t *self_p, struct time_t *timeout_p)¶ Take given semaphore. If the semaphore count is zero the calling thread will be suspended until count is incremented by
sem_give()
.- Return
- zero(0) or negative error code.
- Parameters
self_p
: Semaphore to get.timeout_p
: Timeout.
-
int
sem_give
(struct sem_t *self_p, int count)¶ Give given count to given semaphore. Any suspended thread waiting for this semaphore, in
sem_take()
, is resumed. This continues until the semaphore count becomes zero or there are no threads in the suspended list.Giving a count greater than the currently taken count is allowed and results in all resources available. This is especially useful for binary semaphores where
sem_give()
if often called more often thansem_take()
.- Return
- zero(0) or negative error code.
- Parameters
self_p
: Semaphore to give count to.count
: Count to give.
- struct
filesystems¶
File systems and file system like frameworks.
The filesystems package on Github.
fat16
— FAT16 filesystem¶
File Allocation Table (FAT) is a computer file system architecture and a family of industry-standard file systems utilizing it. The FAT file system is a legacy file system which is simple and robust. It offers good performance even in light-weight implementations, but cannot deliver the same performance, reliability and scalability as some modern file systems. It is, however, supported for compatibility reasons by nearly all currently developed operating systems for personal computers and many mobile devices and embedded systems, and thus is a well-suited format for data exchange between computers and devices of almost any type and age from 1981 up to the present.
Example¶
Here is the pseudo-code for mounting a file system, performing file operations and unmounting the file system.
All function arguments are omitted in this example.
/* Mount the file system. This is normally done once when the
application starts. */
fat16_init();
fat16_mount();
/* Perform file operations. */
fat16_file_open();
fat16_file_read();
fat16_file_close();
fat16_file_open();
fat16_file_write();
fat16_file_close();
/* Unmount the file system when it is no long needed. Normally when
the application stops. */
fat16_unmount();
Source code: src/filesystems/fat16.h, src/filesystems/fat16.c
Test code: tst/filesystems/fat16/main.c
Test coverage: src/filesystems/fat16.c
Example code: examples/fat16/main.c
Defines
-
FAT16_SEEK_SET
¶
-
FAT16_SEEK_CUR
¶ The offset is relative to the current position indicator.
-
FAT16_SEEK_END
¶ The offset is relative to the end of the file.
-
FAT16_EOF
¶ End of file indicator.
-
O_READ
¶ Open for reading.
-
O_RDONLY
¶ Same as O_READ.
-
O_WRITE
¶ Open for write.
-
O_WRONLY
¶ Same as O_WRITE.
-
O_RDWR
¶ Open for reading and writing.
-
O_APPEND
¶ The file position indicator shall be set to the end of the file prior to each write.
-
O_SYNC
¶ Synchronous writes.
-
O_CREAT
¶ Create the file if non-existent.
-
O_EXCL
¶ If O_CREAT and O_EXCL are set, file open shall fail if the file exists.
-
O_TRUNC
¶ Truncate the file to zero length.
-
DIR_ATTR_READ_ONLY
¶ File is read-only.
-
DIR_ATTR_HIDDEN
¶ File should hidden in directory listings.
-
DIR_ATTR_SYSTEM
¶ Entry is for a system file.
-
DIR_ATTR_VOLUME_ID
¶ Directory entry contains the volume label.
-
DIR_ATTR_DIRECTORY
¶ Entry is for a directory.
-
DIR_ATTR_ARCHIVE
¶ Old DOS archive bit for backup support.
Typedefs
- typedef
Block read function callback.
- typedef
Block write function callback.
- typedef
A FAT entry.
Functions
-
int
fat16_init
(struct fat16_t *self_p, fat16_read_t read, fat16_write_t write, void *arg_p, unsigned int partition)¶ Initialize a FAT16 volume.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: FAT16 object to initialize.read
: Callback function used to read blocks of data.write
: Callback function used to write blocks of data.arg_p
: Argument passed as the first arguemtn to read() and write().partition
: Partition to be used. Legal values for a partition are 1-4 to use the corresponding partition on a device formatted with a MBR, Master Boot Record, or zero if the device is formatted as a super floppy with the FAT boot sector in block zero.
-
int
fat16_mount
(struct fat16_t *self_p)¶ Mount given FAT16 volume.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: FAT16 object.
-
int
fat16_unmount
(struct fat16_t *self_p)¶ Unmount given FAT16 volume.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: FAT16 object.
-
int
fat16_format
(struct fat16_t *self_p)¶ Create an empty FAT16 file system on the device.
- Parameters
self_p
: FAT16 object.
-
int
fat16_print
(struct fat16_t *self_p, void *chan_p)¶ Print volume information to given channel.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: FAT16 object.chan_p
: Output channel.
-
int
fat16_file_open
(struct fat16_t *self_p, struct fat16_file_t *file_p, const char *path_p, int oflag)¶ Open a file by file path and mode flags.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: FAT16 object.file_p
: File object to be initialized.path_p
: A valid 8.3 DOS name for a file path.oflag
: mode of file open (create, read, write, etc).
-
int
fat16_file_close
(struct fat16_file_t *file_p)¶ Close a file and force cached data and directory information to be written to the media.
- Return
- zero(0) or negative error code.
- Parameters
file_p
: File object.
-
ssize_t
fat16_file_read
(struct fat16_file_t *file_p, void *buf_p, size_t size)¶ Read data to given buffer with given size from the file.
- Return
- Number of bytes read or EOF(-1).
- Parameters
file_p
: File object.buf_p
: Buffer to read into.size
: number of bytes to read.
-
ssize_t
fat16_file_write
(struct fat16_file_t *file_p, const void *buf_p, size_t size)¶ Write data from buffer with given size to the file.
- Return
- Number of bytes written or EOF(-1).
- Parameters
file_p
: File object.buf_p
: Buffer to write.size
: number of bytes to write.
-
int
fat16_file_seek
(struct fat16_file_t *file_p, int pos, int whence)¶ Sets the file’s read/write position relative to mode.
- Return
- zero(0) or negative error code.
- Parameters
file_p
: File object.pos
: New position in bytes from given mode.whence
: Absolute, relative or from end.
-
ssize_t
fat16_file_tell
(struct fat16_file_t *file_p)¶ Return current position in the file.
- Return
- Current position or negative error code.
- Parameters
file_p
: File object.
-
int
fat16_file_truncate
(struct fat16_file_t *file_p, size_t size)¶ Truncate given file to a size of precisly
size
bytes.If the file previously was larger than this size, the extra data is lost. If the file previously was shorter, it is extended, and the extended part reads as null bytes (‘\0’).
- Return
- zero(0) or negative error code.
- Parameters
file_p
: File object.size
: New size of the file in bytes.
-
ssize_t
fat16_file_size
(struct fat16_file_t *file_p)¶ Return number of bytes in the file.
- Return
- File size in bytes or negative error code.
- Parameters
file_p
: File object.
-
int
fat16_file_sync
(struct fat16_file_t *file_p)¶ Causes all modified data and directory fields to be written to the storage device.
- Return
- zero(0) or negative error code.
- Parameters
file_p
: File object.
-
int
fat16_dir_open
(struct fat16_t *self_p, struct fat16_dir_t *dir_p, const char *path_p, int oflag)¶ Open a directory by directory path and mode flags.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: FAT16 object.dir_p
: Directory object to be initialized.path_p
: A valid 8.3 DOS name for a directory path.oflag
: mode of the directory to open (create, read, etc).
-
int
fat16_dir_close
(struct fat16_dir_t *dir_p)¶ Close given directory.
- Return
- zero(0) or negative error code.
- Parameters
dir_p
: Directory object.
-
int
fat16_dir_read
(struct fat16_dir_t *dir_p, struct fat16_dir_entry_t *entry_p)¶ Read the next file or directory within the opened directory.
- Return
- true(1) if an entry was read or false(0) if no entry could be read, otherwise negative error code.
- Parameters
dir_p
: Directory object.entry_p
: Read entry.
-
int
fat16_stat
(struct fat16_t *self_p, const char *path_p, struct fat16_stat_t *stat_p)¶ Gets file status by path.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: The file system struct.path_p
: The path of the file to stat.stat_p
: The stat struct to populate.
- union
- #include <fat16.h>
FAT Time Format. A FAT directory entry time stamp is a 16-bit field that has a granularity of 2 seconds. Here is the format (bit 0 is the LSB of the 16-bit word, bit 15 is the MSB of the 16-bit word).
Bits 0-4: 2-second count, valid value range 0-29 inclusive (0-58 seconds). Bits 5-10: Minutes, valid value range 0-59 inclusive. Bits 11-15: Hours, valid value range 0-23 inclusive.
The valid time range is from Midnight 00:00:00 to 23:59:58.
- union
- #include <fat16.h>
FAT date representation support Date Format. A FAT directory entry date stamp is a 16-bit field that is basically a date relative to the MS-DOS epoch of 01/01/1980. Here is the format (bit 0 is the LSB of the 16-bit word, bit 15 is the MSB of the 16-bit word):
Bits 0-4: Day of month, valid value range 1-31 inclusive. Bits 5-8: Month of year, 1 = January, valid value range 1-12 inclusive. Bits 9-15: Count of years from 1980, valid value range 0-127 inclusive (1980-2107).
- struct
- #include <fat16.h>
MBR partition table entry. A partition table entry for a MBR formatted storage device. The MBR partition table has four entries.
Public Members
-
uint8_t
part_t::
boot
¶ Boot Indicator. Indicates whether the volume is the active partition. Legal values include: 0x00. Do not use for booting. 0x80 Active partition.
-
uint8_t
part_t::
begin_head
¶ Head part of Cylinder-head-sector address of the first block in the partition. Legal values are 0-255. Only used in old PC BIOS.
-
unsigned
part_t::
begin_sector
¶ Sector part of Cylinder-head-sector address of the first block in the partition. Legal values are 1-63. Only used in old PC BIOS.
-
unsigned
part_t::
begin_cylinder_high
¶ High bits cylinder for first block in partition.
-
uint8_t
part_t::
begin_cylinder_low
¶ Combine beginCylinderLow with beginCylinderHigh. Legal values are 0-1023. Only used in old PC BIOS.
-
uint8_t
part_t::
type
¶ Partition type. See defines that begin with PART_TYPE_ for some Microsoft partition types.
-
uint8_t
part_t::
end_head
¶ head part of cylinder-head-sector address of the last sector in the partition. Legal values are 0-255. Only used in old PC BIOS.
-
unsigned
part_t::
end_sector
¶ Sector part of cylinder-head-sector address of the last sector in the partition. Legal values are 1-63. Only used in old PC BIOS.
-
unsigned
part_t::
end_cylinder_high
¶ High bits of end cylinder
-
uint8_t
part_t::
end_cylinder_low
¶ Combine endCylinderLow with endCylinderHigh. Legal values are 0-1023. Only used in old PC BIOS.
-
uint32_t
part_t::
first_sector
¶ Logical block address of the first block in the partition.
-
uint32_t
part_t::
total_sectors
¶ Length of the partition, in blocks.
-
uint8_t
- struct
- #include <fat16.h>
BIOS parameter block; The BIOS parameter block describes the physical layout of a FAT volume.
Public Members
-
uint16_t
bpb_t::
bytes_per_sector
¶ Count of bytes per sector. This value may take on only the following values: 512, 1024, 2048 or 4096
-
uint8_t
bpb_t::
sectors_per_cluster
¶ Number of sectors per allocation unit. This value must be a power of 2 that is greater than 0. The legal values are 1, 2, 4, 8, 16, 32, 64, and 128.
-
uint16_t
bpb_t::
reserved_sector_count
¶ Number of sectors before the first FAT. This value must not be zero.
-
uint8_t
bpb_t::
fat_count
¶ The count of FAT data structures on the volume. This field should always contain the value 2 for any FAT volume of any type.
-
uint16_t
bpb_t::
root_dir_entry_count
¶ For FAT12 and FAT16 volumes, this field contains the count of 32-byte directory entries in the root directory. For FAT32 volumes, this field must be set to 0. For FAT12 and FAT16 volumes, this value should always specify a count that when multiplied by 32 results in a multiple of bytesPerSector. FAT16 volumes should use the value 512.
-
uint16_t
bpb_t::
total_sectors_small
¶ This field is the old 16-bit total count of sectors on the volume. This count includes the count of all sectors in all four regions of the volume. This field can be 0; if it is 0, then totalSectors32 must be non-zero. For FAT32 volumes, this field must be 0. For FAT12 and FAT16 volumes, this field contains the sector count, and totalSectors32 is 0 if the total sector count fits (is less than 0x10000).
-
uint8_t
bpb_t::
media_type
¶ This dates back to the old MS-DOS 1.x media determination and is no longer usually used for anything. 0xf8 is the standard value for fixed (non-removable) media. For removable media, 0xf0 is frequently used. Legal values are 0xf0 or 0xf8-0xff.
-
uint16_t
bpb_t::
sectors_per_fat
¶ Count of sectors occupied by one FAT on FAT12/FAT16 volumes. On FAT32 volumes this field must be 0, and sectorsPerFat32 contains the FAT size count.
-
uint16_t
bpb_t::
sectors_per_track
¶ Sectors per track for interrupt 0x13. Not used otherwise.
-
uint16_t
bpb_t::
head_count
¶ Number of heads for interrupt 0x13. Not used otherwise.
-
uint32_t
bpb_t::
hiddden_sectors
¶ Count of hidden sectors preceding the partition that contains this FAT volume. This field is generally only relevant for media visible on interrupt 0x13.
-
uint32_t
bpb_t::
total_sectors_large
¶ This field is the new 32-bit total count of sectors on the volume. This count includes the count of all sectors in all four regions of the volume. This field can be 0; if it is 0, then totalSectors16 must be non-zero.
-
uint16_t
- struct
- #include <fat16.h>
Boot sector for a FAT16 or FAT32 volume.
Public Members
-
uint8_t
fbs_t::
jmp_to_boot_code
[3]¶ X86 jmp to boot program
-
char
fbs_t::
oem_name
[8]¶ Informational only - don’t depend on it
-
uint8_t
fbs_t::
drive_number
¶ For int0x13 use value 0x80 for hard drive
-
uint8_t
fbs_t::
reserved1
¶ Used by Windows NT - should be zero for FAT
-
uint8_t
fbs_t::
boot_signature
¶ 0x29 if next three fields are valid
-
uint32_t
fbs_t::
volume_serial_number
¶ Usually generated by combining date and time
-
char
fbs_t::
volume_label
[11]¶ Should match volume label in root dir
-
char
fbs_t::
file_system_type
[8]¶ Informational only - don’t depend on it
-
uint8_t
fbs_t::
boot_code
[448]¶ X86 boot code
-
uint16_t
fbs_t::
boot_sector_sig
¶ Must be 0x55AA
-
uint8_t
- struct
- #include <fat16.h>
Master Boot Record. The first block of a storage device that is formatted with a MBR.
Public Members
-
uint8_t
mbr_t::
codeArea
[440]¶ Code Area for master boot program.
-
uint32_t
mbr_t::
diskSignature
¶ Optional WindowsNT disk signature. May contain more boot code.
-
uint16_t
mbr_t::
usuallyZero
¶ Usually zero but may be more boot code.
-
uint16_t
mbr_t::
mbr_sig
¶ First MBR signature byte. Must be 0x55
-
uint8_t
- struct
- #include <fat16.h>
FAT short directory entry. Short means short 8.3 name, not the entry size.
Public Members
-
uint8_t
dir_t::
name
[11]¶ Short 8.3 name. The first eight bytes contain the file name with blank fill. The last three bytes contain the file extension with blank fill.
-
uint8_t
dir_t::
attributes
¶ Entry attributes. The upper two bits of the attribute byte are reserved and should always be set to 0 when a file is created and never modified or looked at after that. See defines that begin with DIR_ATT_.
-
uint8_t
dir_t::
reserved1
¶ Reserved for use by Windows NT. Set value to 0 when a file is created and never modify or look at it after that.
-
uint8_t
dir_t::
creation_time_tenths
¶ The granularity of the seconds part of creationTime is 2 seconds so this field is a count of tenths of a second and its valid value range is 0-199 inclusive. (WHG note - seems to be hundredths)
-
uint16_t
dir_t::
creation_time
¶ Time file was created.
-
uint16_t
dir_t::
creation_date
¶ Date file was created.
-
uint16_t
dir_t::
last_access_date
¶ Last access date. Note that there is no last access time, only a date. This is the date of last read or write. In the case of a write, this should be set to the same date as lastWriteDate.
-
uint16_t
dir_t::
first_cluster_high
¶ High word of this entry’s first cluster number (always 0 for a FAT12 or FAT16 volume).
-
uint16_t
dir_t::
last_write_time
¶ Time of last write. File creation is considered a write.
-
uint16_t
dir_t::
last_write_date
¶ Date of last write. File creation is considered a write.
-
uint16_t
dir_t::
first_cluster_low
¶ Low word of this entry’s first cluster number.
-
uint32_t
dir_t::
file_size
¶ 32-bit unsigned holding this file’s size in bytes.
-
uint8_t
- union
- struct
Public Members
-
uint32_t
fat16_cache_t::
block_number
¶
-
uint8_t
fat16_cache_t::
dirty
¶
-
uint32_t
fat16_cache_t::
mirror_block
¶
-
union fat16_cache16_t
fat16_cache_t::
buffer
¶
-
uint32_t
- struct
Public Members
-
fat16_read_t
fat16_t::
read
¶
-
fat16_write_t
fat16_t::
write
¶
-
void *
fat16_t::
arg_p
¶
-
unsigned int
fat16_t::
partition
¶
-
uint8_t
fat16_t::
fat_count
¶
-
uint8_t
fat16_t::
blocks_per_cluster
¶
-
uint16_t
fat16_t::
root_dir_entry_count
¶
-
uint32_t
fat16_t::
volume_start_block
¶
-
uint32_t
fat16_t::
fat_start_block
¶
-
uint32_t
fat16_t::
root_dir_start_block
¶
-
uint32_t
fat16_t::
data_start_block
¶
-
struct fat16_cache_t
fat16_t::
cache
¶
-
fat16_read_t
- struct
- struct
- struct
- struct
fs
— Debug file system¶
The debug file system is not really a file system, but rather a file system like tree of commands, counters, parameters, and “real” file systems.
- A command is a file path mapped to a function callback. The callback
is invoked when its path is passed to the
fs_call()
function. Commands are registered into the debug file system by a call tofs_command_register()
. - A counter is a file path mapped to a 64 bit value. The value can be
incremented and read by the application. Counters are registered
into the debug file system by a call to
fs_counter_register()
. - A parameter is file path mapped to a value stored in ram that can be
easily read and modified by the user from a shell. Parameters are
registered into the debug file system by a call to
fs_parameter_register()
. - A “real” file system is a file path, or mount point, mapped to a
file system instance. The debug file system has a file access
interface. The purpose of this interface is to have a common file
access interface, independent of the underlying file systems
interface. File systems are registered into the debug file system by
a call to
fs_filesystem_register()
.
Debug file system commands¶
The debug file system module itself registers seven commands, all
located in the directory filesystems/fs/
.
Command | Description |
---|---|
filesystems/list |
Print a list of all registered file systems. |
list [<folder>] |
Print a list of all files and folders in given folder. |
read <file> |
Read from given file. |
write <file> <data> |
Create and write to a file. Overwrites existing files. |
append <file> <data> |
Append data to an existing file. |
counters/list |
Print a list of all registered counters. |
counters/reset |
Rest all counters to zero. |
parameters/list |
Print a list of all registered parameters. |
Example output from the shell:
$ filesystems/fs/filesystems/list
MOUNT-POINT MEDIUM TYPE AVAILABLE SIZE USAGE
/tmp ram fat16 54K 64K 14%
/home/erik sd fat16 1.9G 2G 5%
/etc flash spiffs 124K 128K 3%
$ filesystems/fs/write tmp/foo.txt "Hello "
$ filesystems/fs/append tmp/foo.txt world!
$ filesystems/fs/read tmp/foo.txt
Hello world!
$ filesystems/fs/list tmp
xxxx-xx-xx xx-xx 12 foo.txt
$ filesystems/fs/counters/list
NAME VALUE
/your/counter 0000000000000034
/my/counter 0000000000000002
$ filesystems/fs/counters/reset
$ filesystems/fs/counters/list
NAME VALUE
/your/counter 0000000000000000
/my/counter 0000000000000000
$ filesystems/fs/parameters/list
NAME VALUE
/foo/bar -2
Source code: src/filesystems/fs.h, src/filesystems/fs.c
Test code: tst/filesystems/fs/main.c
Test coverage: src/filesystems/fs.c
Defines
-
FS_SEEK_SET
¶
-
FS_SEEK_CUR
¶ The offset is relative to the current position indicator.
-
FS_SEEK_END
¶ The offset is relative to the end of the file.
-
FS_READ
¶ Open for reading.
-
FS_WRITE
¶ Open for write.
-
FS_RDWR
¶ Open for reading and writing.
-
FS_APPEND
¶ The file position indicator shall be set to the end of the file prior to each write.
-
FS_SYNC
¶ Synchronous writes.
-
FS_CREAT
¶ Create the file if non-existent.
-
FS_EXCL
¶ If FS_CREAT and FS_EXCL are set, file open shall fail if the file exists.
-
FS_TRUNC
¶ Truncate the file to zero length.
-
FS_TYPE_FILE
¶
-
FS_TYPE_DIR
¶
-
FS_TYPE_HARD_LINK
¶
-
FS_TYPE_SOFT_LINK
¶
Typedefs
- typedef
Command callback prototype.
- Return
- zero(0) or negative error code.
- Parameters
argc
: Number of arguements in argv.argv
: An array of agruments.out_p
: Output channel.in_p
: Input channel.arg_p
: Argument passed to the init function of given command.call_arg_p
: Argument passed to thefs_call
function.
- typedef
Parameter setter callback prototype.
- Return
- zero(0) or negative error code.
- Parameters
value_p
: Buffer the new value should be written to.src_p
: Value to set as a string.
- typedef
Parameter printer callback prototype.
- Return
- zero(0) or negative error code.
- Parameters
chout_p
: Channel to write the formatted value to.value_p
: Value to format and print to the output channel.
Enums
-
enum type
fs_type_t
¶ Values:
- = 0
Functions
-
int
fs_module_init
(void)¶ Initialize the file system module. This function must be called before calling any other function in this module.
The module will only be initialized once even if this function is called multiple times.
- Return
- zero(0) or negative error code.
-
int
fs_call
(char *command_p, void *chin_p, void *chout_p, void *arg_p)¶ Call given file system command with given input and output channels. Quote an argument if it contains spaces, otherwise it is parsed as multiple arguments. Any quotation mark in an argument string must be escaped with a backslash (
\
), otherwise it is interpreted as a string quotation mask.- Return
- zero(0) or negative error code.
- Parameters
command_p
: Command string to call. The command string will be modified by this function, so don’t use it after this function returns.chin_p
: Input channel.chout_p
: Output channel.arg_p
: User argument passed to the command callback function ascall_arg_p
.
-
int
fs_open
(struct fs_file_t *self_p, const char *path_p, int flags)¶ Open a file by file path and mode flags. File operations are permitted after the file has been opened.
The path can be either absolute or relative. It’s an absolute path if it starts with a forward slash
/
, and relative otherwise. Relative paths are are relative to the current working directory, given by the thread environment variableCWD
.- Return
- zero(0) or negative error code.
- Parameters
self_p
: File object to be initialized.path_p
: Path of the file to open. The path can be absolute or relative.flags
: Mode of file open. A combination ofFS_READ
,FS_RDONLY
,FS_WRITE
,FS_WRONLY
,FS_RDWR
,FS_APPEND
,FS_SYNC
,FS_CREAT
,FS_EXCL
andFS_TRUNC
.
-
int
fs_close
(struct fs_file_t *self_p)¶ Close given file. No file operations are permitted on a closed file.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Initialized file object.
-
ssize_t
fs_read
(struct fs_file_t *self_p, void *dst_p, size_t size)¶ Read from given file into given buffer.
- Return
- Number of bytes read or negative error code.
- Parameters
self_p
: Initialized file object.dst_p
: Buffer to read data into.size
: Number of bytes to read.
-
ssize_t
fs_read_line
(struct fs_file_t *self_p, void *dst_p, size_t size)¶ Read one line from given file into given buffer. The function reads one character at a time from given file until the destination buffer is full, a newline
\n
is found or end of file is reached.- Return
- If a line was found the number of bytes read not including the null-termination is returned. If the destination buffer becomes full before a newline character, the destination buffer size is returned. Otherwise a negative error code is returned.
- Parameters
self_p
: Initialized file object.dst_p
: Buffer to read data into. Should fit the whole line and null-termination.size
: Size of the destination buffer.
-
ssize_t
fs_write
(struct fs_file_t *self_p, const void *src_p, size_t size)¶ Write from given buffer into given file.
- Return
- Number of bytes written or negative error code.
- Parameters
self_p
: Initialized file object.dst_p
: Buffer to write.size
: Number of bytes to write.
-
int
fs_seek
(struct fs_file_t *self_p, int offset, int whence)¶ Sets the file’s read/write position relative to whence.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Initialized file object.offset
: New position in bytes from given whence.whence
: Absolute (FS_SEEK_SET
), relative (FS_SEEK_CUR
) or from end (FS_SEEK_END
).
-
ssize_t
fs_tell
(struct fs_file_t *self_p)¶ Return current position in the file.
- Return
- Current position or negative error code.
- Parameters
self_p
: Initialized file object.
-
int
fs_dir_open
(struct fs_dir_t *dir_p, const char *path_p, int oflag)¶ Open a directory by directory path and mode flags.
- Return
- zero(0) or negative error code.
- Parameters
dir_p
: Directory object to be initialized.path_p
: A valid path name for a directory path.oflag
: mode of the directory to open (create, read, etc).
-
int
fs_dir_close
(struct fs_dir_t *dir_p)¶ Close given directory.
- Return
- zero(0) or negative error code.
- Parameters
dir_p
: Directory object.
-
int
fs_dir_read
(struct fs_dir_t *dir_p, struct fs_dir_entry_t *entry_p)¶ Read the next file or directory within the opened directory.
- Return
- true(1) if an entry was read or false(0) if no entry could be read, otherwise negative error code.
- Parameters
dir_p
: Directory object.entry_p
: Read entry.
-
int
fs_remove
(const char *path_p)¶ Remove file by given path.
- Return
- zero(0) or negative error code.
- Parameters
path_p
: The path of the file to remove.
-
int
fs_stat
(const char *path_p, struct fs_stat_t *stat_p)¶ Gets file status by path.
- Return
- zero(0) or negative error code.
- Parameters
path_p
: The path of the file to stat.stat_p
: The stat struct to populate.
-
int
fs_mkdir
(const char *path_p)¶ Craete a directory with given path.
- Return
- zero(0) or negative error code.
- Parameters
path_p
: The path of the directoy to create.
-
int
fs_format
(const char *path_p)¶ Format file system at given path.
- Return
- zero(0) or negative error code.
- Parameters
path_p
: The path to the root of the file system to format. All data in the file system will be deleted.
-
int
fs_ls
(const char *path_p, const char *filter_p, void *chout_p)¶ List files and folders in given path. Optionally with given filter. The list is written to the output channel.
- Return
- zero(0) or negative error code.
- Parameters
path_p
: Directory to list.filter_p
: Filter out files and folders.chout_p
: Output chan.
-
int
fs_list
(const char *path_p, const char *filter_p, void *chout_p)¶ List files (callbacks) and directories in given path. Optionally with given filter. The list is written to the output channel.
- Return
- zero(0) or negative error code.
- Parameters
path_p
: Directory to list.filter_p
: Filter out files and folders.chout_p
: Output chan.
-
int
fs_auto_complete
(char *path_p)¶ Auto-complete given path.
- Return
- >=1 if completion happened. Number of autocompleted characters added to the path. 0 if no completion happend, or negative error code.
- Parameters
path_p
: Absolute or relative path to auto-complete.
-
void
fs_split
(char *buf_p, char **path_pp, char **cmd_pp)¶ Split buffer into path and command inplace.
- Return
- zero(0) or negative error code.
- Parameters
buf_p
: Buffer to split.path_pp
: Path or NULL if no path was found.cmd_pp
: Command or empty string.
-
void
fs_merge
(char *path_p, char *cmd_p)¶ Merge path and command previously split using
fs_split()
.- Return
- zero(0) or negative error code.
- Parameters
path_p
: Path from spilt.cmd_p
: Command from split.
-
int
fs_filesystem_init_fat16
(struct fs_filesystem_t *self_p, const char *name_p, struct fat16_t *fat16_p)¶ Initialize given FAT16 file system.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: File system to initialize.name_p
: Path to register.fat16_p
: File system pointer.
-
int
fs_filesystem_init_spiffs
(struct fs_filesystem_t *self_p, const char *name_p, struct spiffs_t *spiffs_p, struct fs_filesystem_spiffs_config_t *config_p)¶ Initialize given SPIFFS file system.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: File system to initialize.name_p
: Path to register.spiffs_p
: File system pointer.config_p
: File system configuration.
-
int
fs_filesystem_register
(struct fs_filesystem_t *self_p)¶ Register given file system. Use the functions
fs_open()
,fs_read()
,fs_write()
,fs_close()
,fs_seek()
, fs_tell() andfs_read_line()
to access files in a registerd file system.- Return
- zero(0) or negative error code.
- Parameters
self_p
: File system to register.
-
int
fs_filesystem_deregister
(struct fs_filesystem_t *self_p)¶ Deregister given file system.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: File system to deregister.
-
int fs_command_init(struct fs_command_t * self_p, const FAR char * path_p, fs_callback_t callback, void * arg_p)
Initialize given command.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Command to initialize.path_p
: Path to register.callback
: Command callback function.arg_p
: Callback argument.
-
int
fs_command_register
(struct fs_command_t *command_p)¶ Register given command. Registered commands are called by the function
fs_call()
.- Return
- zero(0) or negative error code.
- Parameters
command_p
: Command to register.
-
int
fs_command_deregister
(struct fs_command_t *command_p)¶ Deregister given command.
- Return
- zero(0) or negative error code.
- Parameters
command_p
: Command to deregister.
-
int fs_counter_init(struct fs_counter_t * self_p, const FAR char * path_p, uint64_t value)
Initialize given counter.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Counter to initialize.path_p
: Path to register.value
: Initial value of the counter.
-
int
fs_counter_increment
(struct fs_counter_t *self_p, uint64_t value)¶ Increment given counter.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Command to initialize.value
: Increment value.
-
int
fs_counter_register
(struct fs_counter_t *counter_p)¶ Register given counter.
- Return
- zero(0) or negative error code.
- Parameters
counter_p
: Counter to register.
-
int
fs_counter_deregister
(struct fs_counter_t *counter_p)¶ Deregister given counter.
- Return
- zero(0) or negative error code.
- Parameters
counter_p
: Counter to deregister.
-
int fs_parameter_init(struct fs_parameter_t * self_p, const FAR char * path_p, fs_parameter_set_callback_t set_cb, fs_parameter_print_callback_t print_cb, void * value_p)
Initialize given parameter.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Parameter to initialize.path_p
: Path to register.set_cb
: Callback function set set the parameter value.print_cb
: Callback function set print the parameter value.value_p
: Value storage area.
-
int
fs_parameter_register
(struct fs_parameter_t *parameter_p)¶ Register given parameter.
- Return
- zero(0) or negative error code.
- Parameters
parameter_p
: Parameter to register.
-
int
fs_parameter_deregister
(struct fs_parameter_t *parameter_p)¶ Deregister given parameter.
- Return
- zero(0) or negative error code.
- Parameters
parameter_p
: Parameter to deregister.
-
int
fs_parameter_int_set
(void *value_p, const char *src_p)¶ Integer parameter setter function callback
- Return
- zero(0) or negative error code.
- Parameters
value_p
: Buffer the new value should be written to.src_p
: Value to set as a string.
-
int
fs_parameter_int_print
(void *chout_p, void *value_p)¶ Integer parameter printer function callback
- Return
- zero(0) or negative error code.
- Parameters
chout_p
: Channel to write the formatted value to.value_p
: Value to format and print to the output channel.
- struct
- #include <fs.h>
A SPIFFS file system.
Public Members
-
struct spiffs_config_t *
fs_filesystem_spiffs_config_t::
config_p
¶
-
uint8_t *
fs_filesystem_spiffs_config_t::
workspace_p
¶
-
uint8_t *
fs_filesystem_spiffs_config_t::
buf_p
¶
-
size_t
fs_filesystem_spiffs_config_t::
size
¶
-
struct fs_filesystem_spiffs_config_t::@29 fs_filesystem_spiffs_config_t::fdworkspace
-
struct fs_filesystem_spiffs_config_t::@30 fs_filesystem_spiffs_config_t::cache
-
struct spiffs_config_t *
- struct
- #include <fs.h>
A FAT16 file system.
- struct
Public Members
-
const char *
fs_filesystem_t::
name_p
¶
-
union fs_filesystem_t::@31 fs_filesystem_t::fs
-
struct fs_filesystem_spiffs_config_t *
fs_filesystem_t::
spiffs_p
¶
-
union fs_filesystem_t::@32 fs_filesystem_t::config
-
struct fs_filesystem_t *
fs_filesystem_t::
next_p
¶
-
const char *
- struct
Public Members
-
struct fs_filesystem_t *
fs_file_t::
filesystem_p
¶
-
struct fat16_file_t
fs_file_t::
fat16
¶
-
spiffs_file_t
fs_file_t::
spiffs
¶
-
union fs_file_t::@33 fs_file_t::u
-
struct fs_filesystem_t *
- struct
- #include <fs.h>
Path stats.
- struct
Public Members
-
const FAR char* fs_command_t::path_p
-
fs_callback_t
fs_command_t::
callback
¶
-
void *
fs_command_t::
arg_p
¶
-
struct fs_command_t *
fs_command_t::
next_p
¶
-
- struct
Public Members
-
struct fs_command_t
fs_counter_t::
command
¶
-
long long unsigned int fs_counter_t::value
-
struct fs_counter_t *
fs_counter_t::
next_p
¶
-
struct fs_command_t
- struct
Public Members
-
struct fs_command_t
fs_parameter_t::
command
¶
-
fs_parameter_set_callback_t
fs_parameter_t::
set_cb
¶
-
fs_parameter_print_callback_t
fs_parameter_t::
print_cb
¶
-
void *
fs_parameter_t::
value_p
¶
-
struct fs_parameter_t *
fs_parameter_t::
next_p
¶
-
struct fs_command_t
- struct
Public Members
-
struct fs_filesystem_t *
fs_dir_t::
filesystem_p
¶
-
struct fat16_dir_t
fs_dir_t::
fat16
¶
-
struct spiffs_dir_t
fs_dir_t::
spiffs
¶
-
union fs_dir_t::@34 fs_dir_t::u
-
struct fs_filesystem_t *
- struct
spiffs
— SPI Flash File System¶
The source code of this module is based on https://github.com/pellepl/spiffs.
About¶
Spiffs is a file system intended for SPI NOR flash devices on embedded targets.
Spiffs is designed with following characteristics in mind:
- Small (embedded) targets, sparse RAM without heap.
- Only big areas of data (blocks) can be erased.
- An erase will reset all bits in block to ones.
- Writing pulls one to zeroes.
- Zeroes can only be pulled to ones by erase.
- Wear leveling.
Source code: src/filesystems/spiffs.h, src/filesystems/spiffs.c
Test code: tst/filesystems/spiffs/main.c
Defines
-
SPIFFS_OK
¶
-
SPIFFS_ERR_NOT_MOUNTED
¶
-
SPIFFS_ERR_FULL
¶
-
SPIFFS_ERR_NOT_FOUND
¶
-
SPIFFS_ERR_END_OF_OBJECT
¶
-
SPIFFS_ERR_DELETED
¶
-
SPIFFS_ERR_NOT_FINALIZED
¶
-
SPIFFS_ERR_NOT_INDEX
¶
-
SPIFFS_ERR_OUT_OF_FILE_DESCS
¶
-
SPIFFS_ERR_FILE_CLOSED
¶
-
SPIFFS_ERR_FILE_DELETED
¶
-
SPIFFS_ERR_BAD_DESCRIPTOR
¶
-
SPIFFS_ERR_IS_INDEX
¶
-
SPIFFS_ERR_IS_FREE
¶
-
SPIFFS_ERR_INDEX_SPAN_MISMATCH
¶
-
SPIFFS_ERR_DATA_SPAN_MISMATCH
¶
-
SPIFFS_ERR_INDEX_REF_FREE
¶
-
SPIFFS_ERR_INDEX_REF_LU
¶
-
SPIFFS_ERR_INDEX_REF_INVALID
¶
-
SPIFFS_ERR_INDEX_FREE
¶
-
SPIFFS_ERR_INDEX_LU
¶
-
SPIFFS_ERR_INDEX_INVALID
¶
-
SPIFFS_ERR_NOT_WRITABLE
¶
-
SPIFFS_ERR_NOT_READABLE
¶
-
SPIFFS_ERR_CONFLICTING_NAME
¶
-
SPIFFS_ERR_NOT_CONFIGURED
¶
-
SPIFFS_ERR_NOT_A_FS
¶
-
SPIFFS_ERR_MOUNTED
¶
-
SPIFFS_ERR_ERASE_FAIL
¶
-
SPIFFS_ERR_MAGIC_NOT_POSSIBLE
¶
-
SPIFFS_ERR_NO_DELETED_BLOCKS
¶
-
SPIFFS_ERR_FILE_EXISTS
¶
-
SPIFFS_ERR_NOT_A_FILE
¶
-
SPIFFS_ERR_RO_NOT_IMPL
¶
-
SPIFFS_ERR_RO_ABORTED_OPERATION
¶
-
SPIFFS_ERR_PROBE_TOO_FEW_BLOCKS
¶
-
SPIFFS_ERR_PROBE_NOT_A_FS
¶
-
SPIFFS_ERR_NAME_TOO_LONG
¶
-
SPIFFS_ERR_INTERNAL
¶
-
SPIFFS_ERR_TEST
¶
-
SPIFFS_DBG
(...)¶
-
SPIFFS_GC_DBG
(...)¶
-
SPIFFS_CACHE_DBG
(...)¶
-
SPIFFS_CHECK_DBG
(...)¶
-
SPIFFS_APPEND
¶ Any write to the filehandle is appended to end of the file.
-
SPIFFS_O_APPEND
¶
-
SPIFFS_TRUNC
¶ If the opened file exists, it will be truncated to zero length before opened.
-
SPIFFS_O_TRUNC
¶
-
SPIFFS_CREAT
¶ If the opened file does not exist, it will be created before opened.
-
SPIFFS_O_CREAT
¶
-
SPIFFS_RDONLY
¶ The opened file may only be read.
-
SPIFFS_O_RDONLY
¶
-
SPIFFS_WRONLY
¶ The opened file may only be written.
-
SPIFFS_O_WRONLY
¶
-
SPIFFS_RDWR
¶ The opened file may be both read and written.
-
SPIFFS_O_RDWR
¶
-
SPIFFS_DIRECT
¶ Any writes to the filehandle will never be cached but flushed directly.
-
SPIFFS_O_DIRECT
¶
-
SPIFFS_EXCL
¶ If SPIFFS_O_CREAT and SPIFFS_O_EXCL are set, SPIFFS_open() shall fail if the file exists.
-
SPIFFS_O_EXCL
¶
-
SPIFFS_SEEK_SET
¶
-
SPIFFS_SEEK_CUR
¶
-
SPIFFS_SEEK_END
¶
-
SPIFFS_TYPE_FILE
¶
-
SPIFFS_TYPE_DIR
¶
-
SPIFFS_TYPE_HARD_LINK
¶
-
SPIFFS_TYPE_SOFT_LINK
¶
-
SPIFFS_LOCK
(fs)¶
-
SPIFFS_UNLOCK
(fs)¶
Typedefs
- typedef
Spiffs file descriptor index type. must be signed.
- typedef
Spiffs file descriptor flags.
- typedef
Spiffs file mode.
- typedef
Object type.
- typedef
Spi read call function type.
- typedef
Spi write call function type.
- typedef
Spi erase call function type.
- typedef
File system check callback function.
- typedef
File system listener callback function.
- typedef
- typedef
- typedef
- typedef
- typedef
- typedef
- typedef
- typedef
- typedef
- typedef
- typedef
- typedef
- typedef
- typedef
- typedef
Enums
-
enum type
spiffs_check_type_t
¶ File system check callback report operation.
Values:
- = 0
-
enum type
spiffs_check_report_t
¶ File system check callback report type.
Values:
- = 0
-
enum type
spiffs_fileop_type_t
¶ File system listener callback operation.
Values:
- = 0
The file has been created.
The file has been updated or moved to another page.
The file has been deleted.
Functions
-
int32_t
spiffs_mount
(struct spiffs_t *self_p, struct spiffs_config_t *config_p, uint8_t *work_p, uint8_t *fd_space_p, uint32_t fd_space_size, void *cache_p, uint32_t cache_size, spiffs_check_callback_t check_cb)¶ Initializes the file system dynamic parameters and mounts the filesystem. If SPIFFS_USE_MAGIC is enabled the mounting may fail with SPIFFS_ERR_NOT_A_FS if the flash does not contain a recognizable file system. In this case, SPIFFS_format must be called prior to remounting.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: The file system struct.config_p
: The physical and logical configuration of the file system.work_p
: A memory work buffer comprising 2*config->log_page_size bytes used throughout all file system operationsfd_space_p
: Memory for file descriptors.fd_space_size
: Memory size of file descriptors.cache_p
: Memory for cache, may be NULL.cache_size
: Memory size of cache.check_cb
: Callback function for reporting during consistency checks.
-
void
spiffs_unmount
(struct spiffs_t *self_p)¶ Unmounts the file system. All file handles will be flushed of any cached writes and closed.
- Return
- void.
- Parameters
self_p
: The file system struct.
-
int32_t
spiffs_creat
(struct spiffs_t *self_p, const char *path_p, spiffs_mode_t mode)¶ Creates a new file.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: The file system struct.path_p
: The path of the new file.mode
: Ignored, for posix compliance.
-
spiffs_file_t
spiffs_open
(struct spiffs_t *self_p, const char *path_p, spiffs_flags_t flags, spiffs_mode_t mode)¶ Opens/creates a file.
- Parameters
self_p
: The file system struct.path_p
: The path of the new file.flags
: The flags for the open command, can be combinations of SPIFFS_O_APPEND, SPIFFS_O_TRUNC, SPIFFS_O_CREAT, SPIFFS_O_RDONLY, SPIFFS_O_WRONLY, SPIFFS_O_RDWR, SPIFFS_O_DIRECT, SPIFFS_O_EXCL.mode
: Ignored, for posix compliance.
-
spiffs_file_t
spiffs_open_by_dirent
(struct spiffs_t *self_p, struct spiffs_dirent_t *ent_p, spiffs_flags_t flags, spiffs_mode_t mode)¶ Opens a file by given dir entry.
Optimization purposes, when traversing a file system with SPIFFS_readdir a normal SPIFFS_open would need to traverse the filesystem again to find the file, whilst SPIFFS_open_by_dirent already knows where the file resides.
- Parameters
self_p
: The file system struct.e_p
: The dir entry to the file.flags
: The flags for the open command, can be combinations of SPIFFS_APPEND, SPIFFS_TRUNC, SPIFFS_CREAT, SPIFFS_RD_ONLY, SPIFFS_WR_ONLY, SPIFFS_RDWR, SPIFFS_DIRECT. SPIFFS_CREAT will have no effect in this case.mode
: Ignored, for posix compliance.
-
spiffs_file_t
spiffs_open_by_page
(struct spiffs_t *self_p, spiffs_page_ix_t page_ix, spiffs_flags_t flags, spiffs_mode_t mode)¶ Opens a file by given page index.
Optimization purposes, opens a file by directly pointing to the page index in the spi flash. If the page index does not point to a file header SPIFFS_ERR_NOT_A_FILE is returned.
- Parameters
self_p
: The file system struct.page_ix
: The page index.flags
: The flags for the open command, can be combinations of SPIFFS_APPEND, SPIFFS_TRUNC, SPIFFS_CREAT, SPIFFS_RD_ONLY, SPIFFS_WR_ONLY, SPIFFS_RDWR, SPIFFS_DIRECT. SPIFFS_CREAT will have no effect in this case.mode
: Ignored, for posix compliance.
-
int32_t
spiffs_read
(struct spiffs_t *self_p, spiffs_file_t fh, void *buf_p, int32_t len)¶ Reads from given filehandle.
- Return
- Number of bytes read or negative error code.
- Parameters
self_p
: The file system struct.fh
: The filehandle.buf_p
: Where to put read data.len
: How much to read.
-
int32_t
spiffs_write
(struct spiffs_t *self_p, spiffs_file_t fh, void *buf_p, int32_t len)¶ Writes to given filehandle.
- Return
- Number of bytes written, or negative error code.
- Parameters
self_p
: The file system struct.fh
: The filehandle.buf_p
: The data to write.len
: How much to write.
-
int32_t
spiffs_lseek
(struct spiffs_t *self_p, spiffs_file_t fh, int32_t offs, int whence)¶ Moves the read/write file offset. Resulting offset is returned or negative if error.
lseek(fs, fd, 0, SPIFFS_SEEK_CUR) will thus return current offset.
If SPIFFS_SEEK_CUR, the file offset shall be set to its current location plus offset.
- Parameters
self_p
: The file system struct.fh
: The filehandle.offs
: How much/where to move the offset.whence
: If SPIFFS_SEEK_SET, the file offset shall be set to offset bytes.
If SPIFFS_SEEK_END, the file offset shall be set to the size of the file plus offse, which should be negative.
- Return
- zero(0) or negative error code.
-
int32_t
spiffs_remove
(struct spiffs_t *self_p, const char *path_p)¶ Removes a file by path.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: The file system struct.path_p
: The path of the file to remove.
-
int32_t
spiffs_fremove
(struct spiffs_t *self_p, spiffs_file_t fh)¶ Removes a file by filehandle.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: The file system struct.fh
: The filehandle of the file to remove.
-
int32_t
spiffs_stat
(struct spiffs_t *self_p, const char *path_p, struct spiffs_stat_t *stat_p)¶ Gets file status by path.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: The file system struct.path_p
: The path of the file to stat.stat_p
: The stat struct to populate.
-
int32_t
spiffs_fstat
(struct spiffs_t *self_p, spiffs_file_t fh, struct spiffs_stat_t *stat_p)¶ Gets file status by filehandle.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: The file system struct.fh
: The filehandle of the file to stat.stat_p
: The stat struct to populate.
-
int32_t
spiffs_fflush
(struct spiffs_t *self_p, spiffs_file_t fh)¶ Flushes all pending write operations from cache for given file.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: The file system struct.fh
: The filehandle of the file to flush.
-
int32_t
spiffs_close
(struct spiffs_t *self_p, spiffs_file_t fh)¶ Closes a filehandle. If there are pending write operations, these are finalized before closing.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: The file system struct.fh
: The filehandle of the file to close.
-
int32_t
spiffs_rename
(struct spiffs_t *self_p, const char *old_path_p, const char *new_path_p)¶ Renames a file.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: The file system struct.old_path_p
: Path of file to rename.new_path_p
: New path of file.
-
int32_t
spiffs_errno
(struct spiffs_t *self_p)¶ Returns last error of last file operation.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: The file system struct.
-
void
spiffs_clearerr
(struct spiffs_t *self_p)¶ Clears last error.
- Return
- void.
- Parameters
self_p
: The file system struct.
-
struct spiffs_dir_t *
spiffs_opendir
(struct spiffs_t *self_p, const char *name_p, struct spiffs_dir_t *dir_p)¶ Opens a directory stream corresponding to the given name. The stream is positioned at the first entry in the directory. On hydrogen builds the name argument is ignored as hydrogen builds always correspond to a flat file structure - no directories.
- Parameters
self_p
: The file system struct.name_p
: The name of the directory.dir_p
: Pointer the directory stream to be populated.
-
int32_t
spiffs_closedir
(struct spiffs_dir_t *dir_p)¶ Closes a directory stream
- Return
- zero(0) or negative error code.
- Parameters
dir_p
: The directory stream to close.
-
struct spiffs_dirent_t *
spiffs_readdir
(struct spiffs_dir_t *dir_p, struct spiffs_dirent_t *ent_p)¶ Reads a directory into given spifs_dirent struct.
- Return
- NULL if error or end of stream, else given dirent is returned.
- Parameters
dir_p
: Pointer to the directory stream.ent_p
: The dirent struct to be populated.
-
int32_t
spiffs_check
(struct spiffs_t *self_p)¶ Runs a consistency check on given filesystem.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: The file system struct.
-
int32_t
spiffs_info
(struct spiffs_t *self_p, uint32_t *total_p, uint32_t *used_p)¶ Returns number of total bytes available and number of used bytes. This is an estimation, and depends on if there a many files with little data or few files with much data.
NB: If used number of bytes exceeds total bytes, a SPIFFS_check should run. This indicates a power loss in midst of things. In worst case (repeated powerlosses in mending or gc) you might have to delete some files.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: The file system struct.total_p
: Total number of bytes in filesystem.used_p
: Used number of bytes in filesystem.
-
int32_t
spiffs_format
(struct spiffs_t *self_p)¶ Formats the entire file system. All data will be lost. The filesystem must not be mounted when calling this.
NB: formatting is awkward. Due to backwards compatibility, SPIFFS_mount MUST be called prior to formatting in order to configure the filesystem. If SPIFFS_mount succeeds, SPIFFS_unmount must be called before calling SPIFFS_format. If SPIFFS_mount fails, SPIFFS_format can be called directly without calling SPIFFS_unmount first.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: The file system struct.
-
uint8_t
spiffs_mounted
(struct spiffs_t *self_p)¶ Returns nonzero if spiffs is mounted, or zero if unmounted.
- Parameters
self_p
: The file system struct.
-
int32_t
spiffs_gc_quick
(struct spiffs_t *self_p, uint16_t max_free_pages)¶ Tries to find a block where most or all pages are deleted, and erase that block if found. Does not care for wear levelling. Will not move pages around.
If parameter max_free_pages are set to 0, only blocks with only deleted pages will be selected.
NB: the garbage collector is automatically called when spiffs needs free pages. The reason for this function is to give possibility to do background tidying when user knows the system is idle.
Use with care.
Setting max_free_pages to anything larger than zero will eventually wear flash more as a block containing free pages can be erased.
Will set err_no to SPIFFS_OK if a block was found and erased, SPIFFS_ERR_NO_DELETED_BLOCK if no matching block was found, or other error.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: The file system struct.max_free_pages
: maximum number allowed free pages in block.
-
int32_t
spiffs_gc
(struct spiffs_t *self_p, uint32_t size)¶ Will try to make room for given amount of bytes in the filesystem by moving pages and erasing blocks. If it is physically impossible, err_no will be set to SPIFFS_ERR_FULL. If there already is this amount (or more) of free space, SPIFFS_gc will silently return. It is recommended to call SPIFFS_info before invoking this method in order to determine what amount of bytes to give.
NB: the garbage collector is automatically called when spiffs needs free pages. The reason for this function is to give possibility to do background tidying when user knows the system is idle.
Use with care.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: The file system struct.size
: Amount of bytes that should be freed.
-
int32_t
spiffs_eof
(struct spiffs_t *self_p, spiffs_file_t fh)¶ Check if EOF reached.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: The file system struct.fh
: The filehandle of the file to check.
-
int32_t
spiffs_tell
(struct spiffs_t *self_p, spiffs_file_t fh)¶ Get position in file.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: The file system struct.fh
: The filehandle of the file to check.
-
int32_t
spiffs_set_file_callback_func
(struct spiffs_t *self_p, spiffs_file_callback_t cb_func)¶ Registers a callback function that keeps track on operations on file headers. Do note, that this callback is called from within internal spiffs mechanisms. Any operations on the actual file system being callbacked from in this callback will mess things up for sure - do not do this. This can be used to track where files are and move around during garbage collection, which in turn can be used to build location tables in ram. Used in conjuction with SPIFFS_open_by_page this may improve performance when opening a lot of files. Must be invoked after mount.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: The file system struct.cb_func
: The callback on file operations.
- struct
- #include <spiffs.h>
Spiffs spi configuration struct.
Public Members
-
spiffs_read_cb_t
spiffs_config_t::
hal_read_f
¶ Physical read function.
-
spiffs_write_cb_t
spiffs_config_t::
hal_write_f
¶ Physical write function.
-
spiffs_erase_cb_t
spiffs_config_t::
hal_erase_f
¶ Physical erase function.
-
uint32_t
spiffs_config_t::
phys_size
¶ Physical size of the spi flash.
-
uint32_t
spiffs_config_t::
phys_addr
¶ Physical offset in spi flash used for spiffs, must be on block boundary.
-
uint32_t
spiffs_config_t::
phys_erase_block
¶ Physical size when erasing a block.
-
uint32_t
spiffs_config_t::
log_block_size
¶ Logical size of a block, must be on physical block size boundary and must never be less than a physical block.
-
uint32_t
spiffs_config_t::
log_page_size
¶ Logical size of a page, must be at least log_block_size /
-
spiffs_read_cb_t
- struct
Public Members
-
struct spiffs_config_t
spiffs_t::
cfg
¶ File system configuration.
-
uint32_t
spiffs_t::
block_count
¶ Number of logical blocks.
-
spiffs_block_ix_t
spiffs_t::
free_cursor_block_ix
¶ Cursor for free blocks, block index.
-
int
spiffs_t::
free_cursor_obj_lu_entry
¶ Cursor for free blocks, entry index.
-
spiffs_block_ix_t
spiffs_t::
cursor_block_ix
¶ Cursor when searching, block index.
-
int
spiffs_t::
cursor_obj_lu_entry
¶ Cursor when searching, entry index.
-
uint8_t *
spiffs_t::
lu_work
¶ Primary work buffer, size of a logical page.
-
uint8_t *
spiffs_t::
work
¶ Secondary work buffer, size of a logical page.
-
uint8_t *
spiffs_t::
fd_space
¶ File descriptor memory area.
-
uint32_t
spiffs_t::
fd_count
¶ Available file descriptors.
-
int32_t
spiffs_t::
err_code
¶ Last error.
-
uint32_t
spiffs_t::
free_blocks
¶ Current number of free blocks.
-
uint32_t
spiffs_t::
stats_p_allocated
¶ Current number of busy pages.
-
uint32_t
spiffs_t::
stats_p_deleted
¶ Current number of deleted pages.
-
uint8_t
spiffs_t::
cleaning
¶ Flag indicating that garbage collector is cleaning.
-
spiffs_obj_id_t
spiffs_t::
max_erase_count
¶ Max erase count amongst all blocks.
-
spiffs_check_callback_t
spiffs_t::
check_cb_f
¶ Check callback function.
-
spiffs_file_callback_t
spiffs_t::
file_cb_f
¶ File callback function.
-
uint8_t
spiffs_t::
mounted
¶ Mounted flag.
-
void *
spiffs_t::
user_data
¶ User data.
-
uint32_t
spiffs_t::
config_magic
¶ Config magic.
-
struct spiffs_config_t
- struct
- #include <spiffs.h>
Spiffs file status struct.
- struct
- struct
inet¶
The inet package on Github.
Modules:
http_server
— HTTP server¶
Source code: src/inet/http_server.h, src/inet/http_server.c
Test code: tst/inet/http_server/main.c
Test coverage: src/inet/http_server.c
Typedefs
- typedef
Enums
-
enum type
http_server_request_action_t
¶ Values:
- = 0
- = 1
-
enum type
http_server_content_type_t
¶ Content type.
Values:
- = 0
- = 1
-
enum type
http_server_response_code_t
¶ Response codes.
Values:
- = 200
- = 404
-
enum type
http_server_connection_state_t
¶ Connection state.
Values:
- = 0
Functions
-
int
http_server_init
(struct http_server_t *self_p, struct http_server_listener_t *listener_p, struct http_server_connection_t *connections_p, const char *root_path_p, const struct http_server_route_t *routes_p, http_server_route_callback_t on_no_route)¶ Initialize given http server with given root path and maximum number of clients.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Http server to initialize.listener_p
: Listener.connections_p
: A NULL terminated list of connections.root_path_p
: Working directory for the connection threads.routes_p
: An array of routes.on_no_route
: Callback called for all requests without a matching route in route_p.
-
int
http_server_start
(struct http_server_t *self_p)¶ Start given HTTP server.
Spawn the threads and start listening for connections.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Http server.
-
int
http_server_stop
(struct http_server_t *self_p)¶ Stop given HTTP server.
Closes the listener and all open connections, and then kills the threads.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Http server.
-
int
http_server_response_write
(struct http_server_connection_t *connection_p, struct http_server_request_t *request_p, struct http_server_response_t *response_p)¶ Write given HTTP response to given connected client. This function should only be called from the route callbacks to respond to given request.
- Return
- zero(0) or negative error code.
- Parameters
connection_p
: Current connection.request_p
: Current request.response_p
: Current response. Ifbuf_p
in the response to NULL this function will only write the HTTP header, including the size, to the socket. After this function returns write the payload by callingsocket_write()
.
- struct
- #include <http_server.h>
HTTP request.
Public Members
-
http_server_request_action_t
http_server_request_t::
action
¶
-
char
http_server_request_t::
path
[64]¶
-
int
http_server_request_t::
present
¶
-
char
http_server_request_t::
value
[64]¶
-
struct http_server_request_t::@36::@37 http_server_request_t::sec_websocket_key
-
struct http_server_request_t::@36::@38 http_server_request_t::content_type
-
long
http_server_request_t::
value
¶
-
struct http_server_request_t::@36::@39 http_server_request_t::content_length
-
struct http_server_request_t::@36::@40 http_server_request_t::authorization
-
struct http_server_request_t::@36 http_server_request_t::headers
-
http_server_request_action_t
- struct
- #include <http_server.h>
HTTP response.
Public Members
-
int
http_server_response_t::
type
¶
-
http_server_response_code_t
http_server_response_t::
code
¶
-
const char *
http_server_response_t::
buf_p
¶
-
size_t
http_server_response_t::
size
¶
-
struct http_server_response_t::@41 http_server_response_t::content
-
int
- struct
Public Members
-
const char *
http_server_listener_t::
address_p
¶
-
int
http_server_listener_t::
port
¶
-
const char *
http_server_listener_t::
name_p
¶
-
void *
http_server_listener_t::
buf_p
¶
-
size_t
http_server_listener_t::
size
¶
-
struct http_server_listener_t::@42::@43 http_server_listener_t::stack
-
struct http_server_listener_t::@42 http_server_listener_t::thrd
-
const char *
- struct
Public Members
-
http_server_connection_state_t
http_server_connection_t::
state
¶
-
const char *
http_server_connection_t::
name_p
¶
-
void *
http_server_connection_t::
buf_p
¶
-
size_t
http_server_connection_t::
size
¶
-
struct http_server_connection_t::@44::@45 http_server_connection_t::stack
-
struct http_server_connection_t::@44 http_server_connection_t::thrd
-
struct http_server_t *
http_server_connection_t::
self_p
¶
-
http_server_connection_state_t
- struct
- #include <http_server.h>
Call given callback for given path.
Public Members
-
const char *
http_server_route_t::
path_p
¶
-
http_server_route_callback_t
http_server_route_t::
callback
¶
-
const char *
- struct
Public Members
-
const char *
http_server_t::
root_path_p
¶
-
const struct http_server_route_t *
http_server_t::
routes_p
¶
-
http_server_route_callback_t
http_server_t::
on_no_route
¶
-
struct http_server_listener_t *
http_server_t::
listener_p
¶
-
struct http_server_connection_t *
http_server_t::
connections_p
¶
-
const char *
http_websocket_client
— HTTP websocket client¶
Source code: src/inet/http_websocket_client.h, src/inet/http_websocket_client.c
Test code: tst/inet/http_websocket_client/main.c
Test coverage: src/inet/http_websocket_client.c
Functions
-
int
http_websocket_client_init
(struct http_websocket_client_t *self_p, const char *server_p, int port, const char *path_p)¶ Initialize given http.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Http to initialize.server_p
: Server hostname to connect to.port
: Port to connect to.path_p
: Path.
-
int
http_websocket_client_connect
(struct http_websocket_client_t *self_p)¶ Connect given http to the server.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Http to connect.
-
int
http_websocket_client_disconnect
(struct http_websocket_client_t *self_p)¶ Disconnect given http from the server.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Http to connect.
-
ssize_t
http_websocket_client_read
(struct http_websocket_client_t *self_p, void *buf_p, size_t size)¶ Read from given http.
- Return
- Number of bytes read or negative error code.
- Parameters
self_p
: Http to read from.buf_p
: Buffer to read into.size
: Number of bytes to read..
-
ssize_t
http_websocket_client_write
(struct http_websocket_client_t *self_p, int type, const void *buf_p, uint32_t size)¶ Write given data to given http.
- Return
- Number of bytes written or negative error code.
- Parameters
self_p
: Http to write to.buf_p
: Buffer to write.size
: Number of bytes to write.
- struct
- #include <http_websocket_client.h>
Public Members
-
const char *
http_websocket_client_t::
host_p
¶
-
int
http_websocket_client_t::
port
¶
-
struct http_websocket_client_t::@46 http_websocket_client_t::server
-
size_t
http_websocket_client_t::
left
¶
-
struct http_websocket_client_t::@47 http_websocket_client_t::frame
-
const char *
http_websocket_client_t::
path_p
¶
-
const char *
http_websocket_server
— HTTP websocket server¶
Source code: src/inet/http_websocket_server.h, src/inet/http_websocket_server.c
Test code: tst/inet/http_websocket_server/main.c
Test coverage: src/inet/http_websocket_server.c
Functions
-
int
http_websocket_server_init
(struct http_websocket_server_t *self_p, struct socket_t *socket_p)¶ Initialize given websocket server. The server uses the http module interface to communicate with the client.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Http to initialize.socket_p
: Connected socket.
-
int
http_websocket_server_handshake
(struct http_websocket_server_t *self_p, struct http_server_request_t *request_p)¶ Read the handshake request from the client and send the handshake response.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Websocket server.request_p
: Read handshake request.
-
ssize_t
http_websocket_server_read
(struct http_websocket_server_t *self_p, int *type_p, void *buf_p, size_t size)¶ Read a message from given websocket.
- Return
- Number of bytes read or negative error code.
- Parameters
self_p
: Websocket to read from.type_p
: Read message type.buf_p
: Buffer to read into.size
: Number of bytes to read. Longer messages will be truncated and the leftover data dropped.
-
ssize_t
http_websocket_server_write
(struct http_websocket_server_t *self_p, int type, const void *buf_p, uint32_t size)¶ Write given message to given websocket.
- Return
- Number of bytes written or negative error code.
- Parameters
self_p
: Websocket to write to.type
: One ofHTTP_TYPE_TEXT
andHTTP_TYPE_BINARY
.buf_p
: Buffer to write.size
: Number of bytes to write.
- struct
- #include <http_websocket_server.h>
inet
— Internet utilities¶
Source code: src/inet/inet.h, src/inet/inet.c
Test code: tst/inet/inet/inet.c
Test coverage: src/inet/inet.c
Functions
-
int
inet_module_init
(void)¶ Initialize the inet module. This function must be called before calling any other function in this module.
The module will only be initialized once even if this function is called multiple times.
- Return
- zero(0) or negative error code.
-
int
inet_aton
(const char *src_p, struct inet_ip_addr_t *dst_p)¶ Convert the Internet host address src_p from the IPv4 numbers-and-dots notation into binary form (in network byte order) and stores it in the structure that dst_p points to.
The address supplied in src_p can have one of the following forms:
- a.b.c.d Each of the four numeric parts specifies a byte of the address; the bytes are assigned in left-to-right order to produce the binary address.
- Return
- zero(0) or negative error code.
- Parameters
src_p
: Address a.b.c.d to convert into a number.dst_p
: Converted address.
-
char *
inet_ntoa
(const struct inet_ip_addr_t *src_p, char *dst_p)¶ Convert the Internet host src_p from the IPv4 binary form (in network byte order) to numbers-and-dots notation and stores it in the structure that dst_p points to.
- Return
- Converted address pointer or NULL on failure.
- Parameters
src_p
: Address to convert into a string.dst_p
: Converted address as a string.
-
uint16_t
inet_checksum
(void *buf_p, size_t size)¶ Calculate the internet checksum of given buffer.
- Return
- Calculated checksum.
- Parameters
buf_p
: Buffer to calculate the chechsum of.size
: Size of the buffer.
- struct
- #include <inet.h>
Public Members
-
uint32_t
inet_ip_addr_t::
number
¶ IPv4 address.
-
uint32_t
- struct
Public Members
-
struct inet_ip_addr_t
inet_addr_t::
ip
¶ IPv4 address.
-
uint16_t
inet_addr_t::
port
¶ Port.
-
struct inet_ip_addr_t
- struct
- #include <inet.h>
Interface IP information.
Public Members
-
struct inet_ip_addr_t
inet_if_ip_info_t::
address
¶
-
struct inet_ip_addr_t
inet_if_ip_info_t::
netmask
¶
-
struct inet_ip_addr_t
inet_if_ip_info_t::
gateway
¶
-
struct inet_ip_addr_t
mqtt_client
— MQTT client¶
Source code: src/inet/mqtt_client.h, src/inet/mqtt_client.c
Test code: tst/inet/mqtt_client/main.c
Test coverage: src/inet/mqtt_client.c
Typedefs
- typedef
Prototype of the on-publish callback function.
- Return
- Number of bytes read from the input channel.
- Parameters
client_p
: The client.topic_p
: The received topic.chin_p
: The channel to read the value from.size
: Number of bytes of the value to read from chin_p.
- typedef
Prototype of the on-error callback function.
- Return
- zero(0) or nagative error code.
- Parameters
client_p
: The client.error
: The number of error that occured.
Enums
-
enum type
mqtt_client_state_t
¶ Values:
-
enum type
mqtt_qos_t
¶ Quality of Service.
Values:
- = 0
- = 1
- = 2
Functions
-
int
mqtt_client_init
(struct mqtt_client_t *self_p, const char *name_p, struct log_object_t *log_object_p, void *chout_p, void *chin_p, mqtt_on_publish_t on_publish, mqtt_on_error_t on_error)¶ Initialize given MQTT client.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: MQTT client.name_p
: Name of the thread.log_object_p
: Log object.chout_p
: Output channel for client to server packets.chin_p
: Input channel for server to client packets.on_publish
: On-publish callback function. Called when the server publishes a message.on_error
: On-error callback function. Called when an error occurs.
-
void *
mqtt_client_main
(void *arg_p)¶ MQTT client thread.
- Return
- Never returns.
- Parameters
arg_p
: MQTT client.
-
int
mqtt_client_connect
(struct mqtt_client_t *self_p)¶ Establish a connection to the server.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: MQTT client.
-
int
mqtt_client_disconnect
(struct mqtt_client_t *self_p)¶ Disconnect from the server.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: MQTT client.
-
int
mqtt_client_ping
(struct mqtt_client_t *self_p)¶ Send a ping request to the server (broker) and wait for the ping response.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: MQTT client.
-
int
mqtt_client_publish
(struct mqtt_client_t *self_p, struct mqtt_application_message_t *message_p)¶ Publish given topic.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: MQTT client.topic_p
: Topic.payload_p
: Payload to publish. May be NULL.payload_size
: Number of bytes in the payload.
-
int
mqtt_client_subscribe
(struct mqtt_client_t *self_p, struct mqtt_application_message_t *message_p)¶ Subscribe to given message.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: MQTT client.message_p
: The message to subscribe to. The payload part of the message is not used. The topic may use wildcards, given that the server supports it.
-
int
mqtt_client_unsubscribe
(struct mqtt_client_t *self_p, struct mqtt_application_message_t *message_p)¶ Unsubscribe from given message.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: MQTT client.message_p
: The message to unsubscribe from. Only the topic in the message is used.
- struct
- #include <mqtt_client.h>
MQTT client.
Public Members
-
const char *
mqtt_client_t::
name_p
¶
-
struct log_object_t *
mqtt_client_t::
log_object_p
¶
-
int
mqtt_client_t::
state
¶
-
int
mqtt_client_t::
type
¶
-
void *
mqtt_client_t::
data_p
¶
-
struct mqtt_client_t::@48 mqtt_client_t::message
-
void *
mqtt_client_t::
out_p
¶
-
void *
mqtt_client_t::
in_p
¶
-
struct mqtt_client_t::@49 mqtt_client_t::transport
-
struct mqtt_client_t::@50 mqtt_client_t::control
-
mqtt_on_publish_t
mqtt_client_t::
on_publish
¶
-
mqtt_on_error_t
mqtt_client_t::
on_error
¶
-
const char *
- struct
- #include <mqtt_client.h>
MQTT application message.
Public Members
-
const char *
mqtt_application_message_t::
buf_p
¶
-
size_t
mqtt_application_message_t::
size
¶
-
struct mqtt_application_message_t::@51 mqtt_application_message_t::topic
-
const void *
mqtt_application_message_t::
buf_p
¶
-
struct mqtt_application_message_t::@52 mqtt_application_message_t::payload
-
mqtt_qos_t
mqtt_application_message_t::
qos
¶
-
const char *
network_interface
— Network interface¶
The network interface module has a list of all network interfaces and their states.
Network interface modules:
network_interface_slip
— Serial Link Internet Protocol¶
Serial Line Internet Protocol (SLIP) is a link layer internet protocol used to transfer TCP/IP packets over a point-to-point serial line.
It is documented in RFC 1055.
Source code: src/inet/network_interface/slip.h
Example code: examples/inet/slip/main.c
Defines
-
NETWORK_INTERFACE_SLIP_FRAME_SIZE_MAX
¶
Enums
-
enum type
network_interface_slip_state_t
¶ Values:
- = 0
Functions
-
int
network_interface_slip_module_init
(void)¶ Initialize the slip module.
- Return
- zero(0) or negative error code.
-
int
network_interface_slip_init
(struct network_interface_slip_t *self_p, struct inet_ip_addr_t *ipaddr_p, struct inet_ip_addr_t *netmask_p, struct inet_ip_addr_t *gateway_p, void *chout_p)¶ Initialize given slip network interface with given configuration and output channel.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Slip to initialize.ipaddr_p
: Network interface IP address.netmask_p
: Network interface netmask.gateway_p
: Network interface gateway.chout_p
: Output channel.
-
int
network_interface_slip_input
(struct network_interface_slip_t *self_p, uint8_t data)¶ Input a byte into the SLIP IP stack. Normally a user thread reads one byte at a time from the UART and calls this functions with the read byte as argument.
- Return
- Number of bytes written to the input frame or negative error code.
- Parameters
self_p
: Slip to initialize.data
: Byte to input into the stack.
- struct
Public Members
-
network_interface_slip_state_t
network_interface_slip_t::
state
¶
-
struct pbuf *
network_interface_slip_t::
pbuf_p
¶
-
uint8_t *
network_interface_slip_t::
buf_p
¶
-
size_t
network_interface_slip_t::
size
¶
-
struct network_interface_slip_t::@54 network_interface_slip_t::frame
-
void *
network_interface_slip_t::
chout_p
¶
-
struct network_interface_t
network_interface_slip_t::
network_interface
¶
-
network_interface_slip_state_t
network_interface_wifi
— WiFi network interface¶
WiFi network interface driver modules:
network_interface_driver_esp
— ESP WiFi network interface driver¶Source code: src/inet/network_interface/driver/esp.h, src/inet/network_interface/driver/esp.c
Test code: tst/inet/network_interface/wifi_esp/main.c
Variables
-
struct network_interface_wifi_driver_t
network_interface_wifi_driver_esp_station
¶
-
struct network_interface_wifi_driver_t
network_interface_wifi_driver_esp_softap
¶ Esressif WiFi SoftAP driver callbacks. To be used as driver in the wifi network interface.
Source code: src/inet/network_interface/wifi.h, src/inet/network_interface/wifi.c
Test code: tst/inet/network_interface/wifi_esp/main.c
Functions
-
int
network_interface_wifi_module_init
(void)¶ Initialize the WiFi network interface module.
- Return
- zero(0) or negative error code.
-
int
network_interface_wifi_init
(struct network_interface_wifi_t *self_p, const char *name_p, struct network_interface_wifi_driver_t *driver_p, void *arg_p, const char *ssid_p, const char *password_p)¶ Initialize given WiFi network interface with given configuration.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: The WiFi network interface to initialize.name_p
: Name to assign the to interface.driver_p
: Driver virtualization callbacks to use.arg_p
: Argument passed to the driver callbacks.ssid_p
: Access Point SSID.password_p
: Access Point password.
-
int
network_interface_wifi_start
(struct network_interface_wifi_t *self_p)¶ Start given WiFi network interface.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: WiFi network interface to start.
-
int
network_interface_wifi_stop
(struct network_interface_wifi_t *self_p)¶ Stop given WiFi network interface.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: WiFi network interface to stop.
-
int
network_interface_wifi_is_up
(struct network_interface_wifi_t *self_p)¶ Get the connection status of given network interface.
- Return
- true(1) if the network interface is up, false(0) is it is down, and otherwise negative error code.
- Parameters
self_p
: Network interface to get the connection status of.
-
int
network_interface_wifi_set_ip_info
(struct network_interface_wifi_t *self_p, const struct inet_if_ip_info_t *info_p)¶ Set the ip address, netmask and gateway of given network interface.
- Return
- zero(0) if the interface has valid IP information, otherwise negative error code.
- Parameters
self_p
: Network interface.info_p
: Interface IP information to set.
-
int
network_interface_wifi_get_ip_info
(struct network_interface_wifi_t *self_p, struct inet_if_ip_info_t *info_p)¶ Get the ip address, netmask and gateway of given network interface.
- Return
- zero(0) if the interface has valid IP information, otherwise negative error code.
- Parameters
self_p
: Network interface.info_p
: Interface IP information. Only valid if this function returns zero(0).
- struct
- #include <wifi.h>
Public Members
-
struct network_interface_t
network_interface_wifi_t::
network_interface
¶
-
struct network_interface_wifi_driver_t *
network_interface_wifi_t::
driver_p
¶
-
void *
network_interface_wifi_t::
arg_p
¶
-
const char *
network_interface_wifi_t::
ssid_p
¶
-
const char *
network_interface_wifi_t::
password_p
¶
-
const struct inet_if_ip_info_t *
network_interface_wifi_t::
info_p
¶
-
struct network_interface_t
- struct
- #include <wifi.h>
Driver virtualization callbacks. See the
driver/
subfolder for available drivers.Public Members
-
int (*
network_interface_wifi_driver_t::
init
)(void *arg_p)¶
-
int (*
network_interface_wifi_driver_t::
start
)(void *arg_p, const char *ssid_p, const char *password_p, const struct inet_if_ip_info_t *info_p)¶
-
int (*
network_interface_wifi_driver_t::
stop
)(void *arg_p)¶
-
int (*
network_interface_wifi_driver_t::
is_up
)(void *arg_p)¶
-
int (*
network_interface_wifi_driver_t::
set_ip_info
)(void *arg_p, const struct inet_if_ip_info_t *info_p)¶
-
int (*
network_interface_wifi_driver_t::
get_ip_info
)(void *arg_p, struct inet_if_ip_info_t *info_p)¶
-
int (*
Debug file system commands¶
One debug file system command is available, located in the directory
inet/network_interface/
.
Command | Description |
---|---|
list |
Print a list of all registered network interfaces. |
Example output from the shell:
$ inet/network_interface/list
NAME STATE ADDRESS TX BYTES RX BYTES
esp-wlan-ap up 192.168.4.1 - -
esp-wlan-sta up 192.168.0.5 - -
Source code: src/inet/network_interface.h, src/inet/network_interface.c
Test coverage: src/inet/network_interface.c
Typedefs
- typedef
- typedef
- typedef
- typedef
- typedef
Functions
-
int
network_interface_module_init
(void)¶ Initialize the network interface module. This function must be called before calling any other function in this module.
The module will only be initialized once even if this function is called multiple times.
- Return
- zero(0) or negative error code.
-
int
network_interface_add
(struct network_interface_t *netif_p)¶ Add given network interface to the global list of network interfaces. Call
network_interface_start()
to enable the interface.- Return
- zero(0) or negative error code.
- Parameters
netif_p
: Network interface to register.
-
int
network_interface_start
(struct network_interface_t *netif_p)¶ Start given network interface. Enables the interface in the IP stack to allow packets to be sent and received. If the interface is a WiFi station interface it will try initiate the connection to its configured access point. Use
network_interface_is_up()
to check if the interface is connected to its access point.- Return
- zero(0) or negative error code.
- Parameters
netif_p
: Network interface to start.
-
int
network_interface_stop
(struct network_interface_t *netif_p)¶ Stop given network interface. Disconnects from any WiFi access points and disables the interface in the IP stack. No packets can be sent or received on this interface after this function is called.
- Return
- zero(0) or negative error code.
- Parameters
netif_p
: Network interface to stop.
-
int
network_interface_is_up
(struct network_interface_t *netif_p)¶ Get the connection status of given network interface. PAckets can only be sent and received when the interface in up.
- Return
- true(1) if the network interface is up, false(0) is it is down, and otherwise negative error code.
- Parameters
netif_p
: Network interface to get the connection status of.
-
struct network_interface_t *
network_interface_get_by_name
(const char *name_p)¶ Search the global list of network interfaces for an interface with given name and return it.
- Return
- Found network interface or NULL if it was not found.
- Parameters
name_p
: Name of the network interface to find.
-
int
network_interface_set_ip_info
(struct network_interface_t *netif_p, const struct inet_if_ip_info_t *info_p)¶ Set the IP information of given network interface.
- Return
- zero(0) or negative error code.
- Parameters
netif_p
: Network interface to get the IP information of.info_p
: IP information to set.
-
int
network_interface_get_ip_info
(struct network_interface_t *netif_p, struct inet_if_ip_info_t *info_p)¶ Get the IP information of given network interface.
- Return
- zero(0) or negative error code.
- Parameters
netif_p
: Network interface to get the IP information of.info_p
: Read IP information.
- struct
Public Members
-
const char *
network_interface_t::
name_p
¶
-
struct inet_if_ip_info_t
network_interface_t::
info
¶
-
network_interface_start_t
network_interface_t::
start
¶
-
network_interface_stop_t
network_interface_t::
stop
¶
-
network_interface_is_up_t
network_interface_t::
is_up
¶
-
network_interface_set_ip_info_t
network_interface_t::
set_ip_info
¶
-
network_interface_get_ip_info_t
network_interface_t::
get_ip_info
¶
-
void *
network_interface_t::
netif_p
¶
-
struct network_interface_t *
network_interface_t::
next_p
¶
-
const char *
ping
— Ping¶
Debug file system commands¶
One debug file system command is available, located in the directory
inet/ping/
.
Command | Description |
---|---|
ping <remote host> |
Ping a remote host by given ip address. |
Example output from the shell:
$ inet/ping/ping 192.168.1.100
Successfully pinged '192.168.1.100' in 10 ms.
$
Source code: src/inet/ping.h, src/inet/ping.c
Test code: tst/inet/ping/main.c
Test coverage: src/inet/ping.c
Functions
-
int
ping_module_init
(void)¶
-
int
ping_host_by_ip_address
(struct inet_ip_addr_t *address_p, struct time_t *timeout_p, struct time_t *round_trip_time_p)¶ Ping host by given ip address. Send an echo request packet to given host and wait for the echo reply packet. No extra payload data is transmitted, only the ICMP header.
- Return
- zero(0) or negative error code.
- Parameters
address_p
: IP address of the host to ping.timeout_p
: Number of seconds to wait for the echo reply packet.round_trip_time_p
: The time it took from sending the echo request packet to receiving the echo reply packet. Only valid if this functions returns zero(0).
socket
— Internet communication¶
Sockets are used to communicate over IP networks. TCP and UDP are the most common transport protocols.
No more than one thread may read from a socket at any given moment. The same applies when writing to a socket. The reader and writer may be different threads, though. The behaviour is undefined if more threads use the same socket simultaneously. The application will likely crash. Add a semaphore to protect the socket if more threads need access to a socket.
Below is a TCP client example that connects to a server and sends data.
uint8_t buf[16];
struct socket_t tcp;
struct inet_addr_t local_addr, remote_addr;
/* Set the local and remote addresses. */
inet_aton("192.168.1.103", &local_addr.ip);
local_addr.port = 6000;
inet_aton("192.168.1.106", &remote_addr.ip);
remote_addr.port = 5000;
/* Initialize the socket and connect to the server. */
socket_open_tcp(&tcp);
socket_bind(&tcp, &local_addr);
socket_connect(&tcp, &remote_addr);
/* Send the data. */
memset(buf, 0, sizeof(buf));
socket_write(&tcp, buf, sizeof(buf));
/* Close the connection. */
socket_close(&tcp);
And below is the same scenario for UDP.
uint8_t buf[16];
struct socket_t udp;
struct socket_addr_t local_addr, remote_addr;
/* Set the local and remote addresses. */
inet_aton("192.168.1.103", &local_addr.ip);
local_addr.port = 6000;
inet_aton("192.168.1.106", &remote_addr.ip);
remote_addr.port = 5000;
/* Initialize the socket and connect to the server. */
socket_open_udp(&udp);
socket_bind(&udp, &local_addr);
socket_connect(&udp, &remote_addr);
/* Send the data. */
memset(buf, 0, sizeof(buf));
socket_send(&udp, buf, sizeof(buf));
/* Close the connection. */
socket_close(&udp);
Source code: src/inet/socket.h, src/inet/socket.c
Defines
-
SOCKET_DOMAIN_INET
¶
-
SOCKET_TYPE_STREAM
¶ TCP socket type.
-
SOCKET_TYPE_DGRAM
¶ UDP socket type.
-
SOCKET_TYPE_RAW
¶ RAW socket type.
-
SOCKET_PROTO_ICMP
¶
Functions
-
int
socket_module_init
(void)¶ Initialize the socket module. This function will start the lwIP TCP/IP stack. This function must be called before calling any other function in this module.
The module will only be initialized once even if this function is called multiple times.
- Return
- zero(0) or negative error code.
-
int
socket_open_tcp
(struct socket_t *self_p)¶ Initialize given TCP socket.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Socket to initialize.
-
int
socket_open_udp
(struct socket_t *self_p)¶ Initialize given UDP socket.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Socket to initialize.
-
int
socket_open_raw
(struct socket_t *self_p)¶ Initialize given RAW socket.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Socket to initialize.
-
int
socket_open
(struct socket_t *self_p, int domain, int type, int protocol)¶ Initialize given socket.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Socket to initialize.domain
: Socket domain.type
: Socket type.protocol
: Socket protocol.
-
int
socket_close
(struct socket_t *self_p)¶ Close given socket. No data transfers are allowed on after the socket has been closed.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Socket to close.
-
int
socket_bind
(struct socket_t *self_p, const struct inet_addr_t *local_addr_p)¶ Bind given local address to given socket.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Socket.local_addr_p
: Local address.
-
int
socket_listen
(struct socket_t *self_p, int backlog)¶ Listen for connections from remote clients. Only applicable for TCP sockets.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Socket to listen on.backlog
: Unused.
-
int
socket_connect
(struct socket_t *self_p, const struct inet_addr_t *remote_addr_p)¶ Connect to given remote address. Connecting a UDP socket sets the default remote address for outgoing datagrams. For TCP a three-way handshake with the remote peer is initiated.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Socket.remote_addr_p
: Remote address.
-
int
socket_connect_by_hostname
(struct socket_t *self_p, const char *hostname_p, uint16_t port)¶ Connect to the remote device with given hostname.
In computer networking, a hostname (archaically nodename) is a label that is assigned to a device connected to a computer network and that is used to identify the device in various forms of electronic communication, such as the World Wide Web.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Socket.hostname_p
: The hostname of the remote device to connect to.port
: Remote device port to connect to.
-
int
socket_accept
(struct socket_t *self_p, struct socket_t *accepted_p, struct inet_addr_t *remote_addr_p)¶ Accept a client connect attempt. Only applicable for TCP sockets that are listening for connections.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: TCP socket.accepted_p
: New client socket of the accepted client.remote_addr_p
: Address of the client.
-
ssize_t
socket_sendto
(struct socket_t *self_p, const void *buf_p, size_t size, int flags, const struct inet_addr_t *remote_addr_p)¶ Write data to given socket. Only used by UDP sockets.
- Return
- Number of sent bytes or negative error code.
- Parameters
self_p
: Socket to send data on.buf_p
: Buffer to send.size
: Size of buffer to send.flags
: Unused.remote_addr_p
: Remote address to send the data to.
-
ssize_t
socket_recvfrom
(struct socket_t *self_p, void *buf_p, size_t size, int flags, struct inet_addr_t *remote_addr_p)¶ Read data from given socket. Only used by UDP sockets.
- Return
- Number of received bytes or negative error code.
- Parameters
self_p
: Socket to receive data on.buf_p
: Buffer to read into.size
: Size of buffer to read.flags
: Unused.remote_addr_p
: Remote address to receive data from.
-
ssize_t
socket_write
(struct socket_t *self_p, const void *buf_p, size_t size)¶ Write data to given TCP or UDP socket. For UDP sockets,
socket_connect()
must have been called prior to calling this function.- Return
- Number of written bytes or negative error code.
- Parameters
self_p
: Socket.buf_p
: Buffer to send.size
: Numer of bytes to send.
- struct
Public Members
-
int
socket_t::
type
¶
-
ssize_t
socket_t::
left
¶
-
struct socket_t::@55::@57::@59 socket_t::common
-
struct pbuf *
socket_t::
pbuf_p
¶
-
struct inet_addr_t
socket_t::
remote_addr
¶
-
int
socket_t::
closed
¶
-
struct socket_t::@55::@57::@60 socket_t::recvfrom
-
struct tcp_pcb *
socket_t::
pcb_p
¶
-
struct socket_t::@55::@57::@61 socket_t::accept
-
union socket_t::@55::@57 socket_t::u
-
int
socket_t::
state
¶
-
void *
socket_t::
args_p
¶
-
struct socket_t::@55::@58 socket_t::cb
-
struct socket_t::@55 socket_t::input
-
struct socket_t::@56::@62 socket_t::cb
-
struct socket_t::@56 socket_t::output
-
void *
socket_t::
pcb_p
¶
-
int
oam¶
Operations and maintenence of an application is essential to configure, debug and monitor its operation.
The oam package on Github.
console
— System console¶
The system console is the default communication channel to an application. The console input and output channels are often terminated by a shell to enable the user to control and debug the application.
Configure the console by changing the configuration
variables called CONFIG_START_CONSOLE*
.
Source code: src/oam/console.h, src/oam/console.c
Test coverage: src/oam/console.c
Functions
-
int
console_module_init
(void)¶
-
int
console_init
(void)¶ Initialize the console.
- Return
- zero(0) or negative error code.
-
int
console_start
(void)¶ Start the console.
- Return
- zero(0) or negative error code.
-
int
console_stop
(void)¶ Stop the console.
- Return
- zero(0) or negative error code.
-
int
console_set_input_channel
(void *chan_p)¶ Set the pointer to the input channel.
- Return
- zero(0) or negative error code.
-
void *
console_get_input_channel
(void)¶ Get the pointer to the input channel.
- Return
- Input channel or NULL.
-
void *
console_set_output_channel
(void *chan_p)¶ Set the pointer to the output channel.
- Return
- zero(0) or negative error code.
-
void *
console_get_output_channel
(void)¶ Get the pointer to the output channel.
- Return
- Output channel or NULL.
service
— Services¶
A service is as a background task. A service is either running or stopped.
Debug file system commands¶
Three debug file system commands is available, all located in the
directory oam/service/
.
Command | Description |
---|---|
list |
List all registered services. |
start <service> |
Start given service. |
stop <service> |
Stop given service. |
Example output from the shell:
$ oam/service/list
NAME STATUS
http_server running
ftp_server stopped
network_manager running
$ oam/service/start ftp_server
$ oam/service/stop http_server
$ oam/service/list
NAME STATE
http_server stopped
ftp_server running
network_manager running
Source code: src/oam/service.h, src/oam/service.c
Test code: tst/oam/service/main.c
Test coverage: src/oam/service.c
Typedefs
- typedef
Enums
-
enum type
service_status_t
¶ Values:
- = 0
- = 1
Functions
-
int
service_module_init
(void)¶ Initialize the service module. This function must be called before calling any other function in this module.
The module will only be initialized once even if this function is called multiple times.
- Return
- zero(0) or negative error code.
-
int
service_init
(struct service_t *self_p, const char *name_p, service_get_status_cb_t status_cb)¶ Initialize a service with given name and status callback.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Service to initialize.name_p
: Name of the service.status_callback
: Callback function returning the service status.
-
int
service_start
(struct service_t *self_p)¶ Start given service.
The event
SERVICE_CONTROL_EVENT_START
will be written to the control channel of given service and it’s up to the service to act on this event. All services should act on all control events.- Return
- zero(0) or negative error code.
- Parameters
self_p
: Service to start.
-
int
service_stop
(struct service_t *self_p)¶ Stop given service.
The event
SERVICE_CONTROL_EVENT_STOP
will be written to the control channel of given service and it’s up to the service to act on this event. All services should act on all control events.- Return
- zero(0) or negative error code.
- Parameters
self_p
: Service to stop.
- struct
- #include <service.h>
A service with name and control event channel.
settings
— Persistent application settings¶
Settings are stored in a non-volatile memory (NVM). In other words, settings are perserved after a board reset or power cycle.
Application settings are defined in an ini-file that is used to generate the c source code. A setting has a type, a size, an address and a default value, all defined in the ini-file.
Supported types are:
int8_t
An 8 bits signed integer.int16_t
A 16 bits signed integer.int32_t
A 32 bits signed integer.string
An ASCII string.
The size is the number of bytes of the value. For the standard integer types the size must be the value returned by sizeof(). For strings it is the length of the string, including null termination.
The address for each setting is defined by the user, starting at address 0 and increasing from there.
The build system variable SETTINGS_INI
contains the path to the
ini-file used by the build system. Set this variable to the path of
yours application ini-file and run make settings-generate
to
generate four files; settings.h
, settings.c
,
settings.little-endian.bin
and settings.big-endian.bin
.
Also add this to the Makefile: SRC += settings.c
and include
settings.h
in the source files that accesses the settings.
Debug file system commands¶
Four debug file system commands are available, all located in the
directory oam/settings/
.
Command | Description |
---|---|
list |
Print a list of the current settings. |
reset |
Overwrite the current settings values with their default values (the values defined in the ini-file values). |
read <name> |
Read the value of setting <name> . |
write <name> <value> |
Write <value> to setting <name> . |
Example output from the shell:
$ oam/settings/list
NAME TYPE SIZE VALUE
version int8_t 1 1
value_1 int16_t 2 24567
value_2 int32_t 4 -57
value_3 string 16 foobar
$ oam/settings/read value_1
24567
$ oam/settings/write value_1 -5
$ oam/settings/read value_1
-5
$ oam/settings/reset
$ oam/settings/list
NAME TYPE SIZE VALUE
version int8_t 1 1
value_1 int16_t 2 24567
value_2 int32_t 4 -57
value_3 string 16 foobar
Example¶
In this example the ini-file has one setting defined, foo
. The
type is int8_t
, the address is 0x00
, the size is 1
and the
default value is -4
.
[types]
foo = int8_t
[addresses]
foo = 0x00
[sizes]
foo = 1
[values]
foo = -4
The settings can be read and written with the functions
settings_read() and settings_write(). Give the generated defines
SETTING_FOO_ADDR
and SETTING_FOO_SIZE
as arguments to those
functions.
int my_read_write_foo()
{
int8_t foo;
/* Read the foo setting. */
if (settings_read(&foo,
SETTING_FOO_ADDR,
SETTING_FOO_SIZE) != 0) {
return (-1);
}
foo -= 1;
/* Write the foo setting. */
if (settings_write(SETTING_FOO_ADDR,
&foo,
SETTING_FOO_SIZE) != 0) {
return (-1);
}
return (0);
}
Source code: src/oam/settings.h, src/oam/settings.c
Test code: tst/oam/settings/main.c
Test coverage: src/oam/settings.c
Defines
-
SETTINGS_AREA_CRC_OFFSET
¶
Enums
-
enum type
setting_type_t
¶ Settings types. Each setting must have be one of these types.
Values:
- = 0
Functions
-
int
settings_module_init
(void)¶ Initialize the settings module. This function must be called before calling any other function in this module.
The module will only be initialized once even if this function is called multiple times.
- Return
- zero(0) or negative error code.
-
ssize_t
settings_read
(void *dst_p, size_t src, size_t size)¶ Read the value of given setting by address.
- Return
- Number of words read or negative error code.
- Parameters
dst_p
: The read value.src
: Setting source address.size
: Number of words to read.
-
ssize_t
settings_write
(size_t dst, const void *src_p, size_t size)¶ Write given value to given setting by address.
- Return
- Number of words written or negative error code.
- Parameters
dst
: Destination setting address.src_p
: Value to write.size
: Number of bytes to write.
-
ssize_t
settings_read_by_name
(const char *name_p, void *dst_p, size_t size)¶ Read the value of given setting by name.
- Return
- Number of words read or negative error code.
- Parameters
name_p
: Setting name.dst_p
: The read value.size
: Size of the destination buffer.
-
ssize_t
settings_write_by_name
(const char *name_p, const void *src_p, size_t size)¶ Write given value to given setting by name.
- Return
- Number of words read or negative error code.
- Parameters
name_p
: Setting name.src_p
: Value to write.size
: Number of bytes to write.
-
int
settings_reset
(void)¶ Overwrite all settings with their default values.
- Return
- zero(0) or negative error code.
- struct
Public Members
-
FAR const char* setting_t::name_p
-
setting_type_t
setting_t::
type
¶
-
uint32_t
setting_t::
address
¶
-
size_t
setting_t::
size
¶
-
shell
— Debug shell¶
The shell is a command line interface where the user can execute various commands to control, debug and monitor its application.
The shell module has a few configuration variables that can be used to
tailor the shell to the application requirements. Most noticeably is
the configuration variable CONFIG_SHELL_MINIMAL
. If set to 0
all the shell functionality is built; including tab completion, cursor
movement, line editing and command history. If set to 1
only the
minimal functionality is built; only including tab completion and line
editing at the end of the line.
See Configuration for a list of all configuration variables.
Source code: src/oam/shell.h, src/oam/shell.c
Test code: tst/oam/shell/main.c
Test coverage: src/oam/shell.c
Example code: examples/shell/main.c
Functions
-
int
shell_module_init
(void)¶ Initialize the shell module. This function must be called before calling any other function in this module.
The module will only be initialized once even if this function is called multiple times.
- Return
- zero(0) or negative error code.
-
int
shell_init
(struct shell_t *self_p, void *chin_p, void *chout_p, void *arg_p, const char *name_p, const char *username_p, const char *password_p)¶ Initialize a shell with given parameters.
- Parameters
chin_p
: The shell input channel. The shell waits for commands on this channel.chout_p
: The shell output channel. The shell writes responses on this channel.arg_p
: User supplied argument passed to all commands.name_p
: The shell thread name.username_p
: Shell login username, or NULL if no username is required to use the shell.password_p
: Shell login password. This field is unused ifusername_p
is NULL.
-
void *
shell_main
(void *arg_p)¶ The shell main function that listens for commands on the input channel and send response on the output channel. All received commands are passed to the debug file system function
fs_call()
for execution.Here is an example of using the shell to list and execute debug file system commands.
$ <tab> drivers/ kernel/ $ kernel/ <tab> fs/ sys/ thrd/ $ kernel/thrd/list NAME STATE PRIO CPU LOGMASK main current 0 0% 0x0f idle ready 127 0% 0x0f monitor ready -80 0% 0x0f $
- Return
- Never returns.
- Parameters
arg_p
: Pointer to the shell arguemnt structstruct shell_args_t
. See the struct definition for a description of it’s content.
- struct
- #include <shell.h>
Public Members
-
struct shell_history_elem_t *
shell_history_elem_t::
next_p
¶
-
struct shell_history_elem_t *
shell_history_elem_t::
prev_p
¶
-
char
shell_history_elem_t::
buf
[1]¶
-
struct shell_history_elem_t *
- struct
- struct
Public Members
-
void *
shell_t::
chin_p
¶
-
void *
shell_t::
chout_p
¶
-
void *
shell_t::
arg_p
¶
-
const char *
shell_t::
name_p
¶
-
const char *
shell_t::
username_p
¶
-
const char *
shell_t::
password_p
¶
-
struct shell_line_t
shell_t::
line
¶
-
struct shell_line_t
shell_t::
prev_line
¶
-
int
shell_t::
carriage_return_received
¶
-
int
shell_t::
newline_received
¶
-
struct shell_history_elem_t *
shell_t::
head_p
¶
-
struct shell_history_elem_t *
shell_t::
tail_p
¶
-
struct shell_history_elem_t *
shell_t::
current_p
¶
-
struct shell_line_t
shell_t::
pattern
¶
-
struct shell_line_t
shell_t::
match
¶
-
int
shell_t::
line_valid
¶
-
struct circular_heap_t
shell_t::
heap
¶
-
uint8_t
shell_t::
buf
[CONFIG_SHELL_HISTORY_SIZE]¶
-
struct shell_t::@86::@87 shell_t::heap
-
struct shell_t::@86 shell_t::history
-
void *
debug¶
The debug package on Github.
harness
— Test harness¶
In software testing, a test harness or automated test framework is a collection of software and test data configured to test a program unit by running it under varying conditions and monitoring its behavior and outputs. It has two main parts: the test execution engine and the test script repository.
This module implements the test execution engine.
The test scripts are part of the build system.
Example test suite¶
Below is an example of a test suite using the harness. It has three
test cases; test_passed
, test_failed
and test_skipped
.
The test macro BTASSERT(condition)
should be used to validate
conditions.
#include "simba.h"
static int test_passed(struct harness_t *harness_p)
{
/* Return zero(0) when a test case passes. */
return (0);
}
static int test_failed(struct harness_t *harness_p)
{
/* Return a negative integer when a test case fails. BTASSERT
will return -1 when the condition is false. */
BTASSERT(0);
return (0);
}
static int test_skipped(struct harness_t *harness_p)
{
/* Return a positive integer when a test case is skipped. */
return (1);
}
int main()
{
/* Test harness and NULL terminated list of test cases.*/
struct harness_t harness;
struct harness_testcase_t harness_testcases[] = {
{ test_passed, "test_passed" },
{ test_failed, "test_failed" },
{ test_skipped, "test_skipped" },
{ NULL, NULL }
};
sys_start();
harness_init(&harness);
harness_run(&harness, harness_testcases);
return (0);
}
The output from the test suite is:
app: test_suite-7.0.0 built 2016-07-25 17:38 CEST by erik.
board: Linux
mcu: Linux
enter: test_passed
exit: test_passed: PASSED
enter: test_failed
exit: test_failed: FAILED
enter: test_skipped
exit: test_skipped: SKIPPED
NAME STATE PRIO CPU LOGMASK
main current 0 0% 0x0f
ready 127 0% 0x0f
harness report: total(3), passed(1), failed(1), skipped(1)
There are plenty of test suites in the tst folder on Github.
Source code: src/debug/harness.h, src/debug/harness.c
Defines
-
BTASSERTN
(cond, res, ...)¶
-
BTASSERT
(cond, ...)¶ Assert given condition in a testcase. Print an error message and return -1 on error.
Typedefs
- typedef
The testcase function callback.
- Return
- zero(0) if the testcase passed, a negative error code if the testcase failed, and a positive value if the testcase was skipped.
- Parameters
harness_t
: The harness object.
Functions
-
int
harness_init
(struct harness_t *self_p)¶ Initialize given test harness.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Test harness to initialize.
-
int
harness_run
(struct harness_t *self_p, struct harness_testcase_t *testcases_p)¶ Run given testcases in given test harness.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Test harness.testcases_p
: An array of testcases to run. The last element in the array must havecallback
andname_p
set to NULL.
- struct
Public Members
-
harness_testcase_cb_t
harness_testcase_t::
callback
¶
-
const char *
harness_testcase_t::
name_p
¶
-
harness_testcase_cb_t
- struct
Public Members
-
struct uart_driver_t
harness_t::
uart
¶
-
struct uart_driver_t
log
— Logging¶
The logging module consists of log objects and log handlers. A log object filters log entries and a log handler writes log entries to an output channel.
A log object called “log” and a log handler writing to standard output are created during the log module initialization. The log handler can be replaced by calling log_set_default_handler_output_channel().
Normally one log object is created for each subsystem in an application. This gives the user the power to control which parts of the system to debug and/or monitor at runtime.
Sometimes it’s useful to write log entries to multiple channels. This is possible by creating and adding another log handler to the log module.
Log levels¶
There are five log levels defined; fatal, error, warning, info and
debug. The log levels are defined as LOG_<upper case level>
in the
log module header file.
Log entry format¶
A log entry consists of a timestamp, log level, thread name, log object name and the message. The timestamp is the log entry creation time and the log level is one of fatal, error, warning, info and debug. The thread name is the name of the thread that created the log entry and the log object name is the name of the log object the entry was printed on. The message is a user defined string.
<timestamp>:<log level>:<thread name>:<log object name>: <message>
Debug file system commands¶
Three debug file system commands are available, all located in the
directory debug/log/
.
Command | Description |
---|---|
list |
Print a list of all log objects. |
print <string> |
Print a log entry using the default log object and log level LOG_INFO . This command has no use except to test that the log module works. |
set_log_mask <obejct> <mask> |
Set the log mask to <mask> for log object <object> . |
Example output from the shell:
$ debug/log/list
OBJECT NAME MASK
default 0x0f
$ debug/log/print "Hello World!"
$ debug/log/set_log_mask default 0x1f
$ debug/log/list
OBJECT NAME MASK
default 0x1f
$ debug/log/print "Hello World!!!"
56:info:main:default: Hello World!!!
Example¶
Here are a few example outputs using three log objects; foo, bar and the default log object default. All logs are from the main thread as can be seen in the third field in the entries.
23:info:main:foo: A foo info message.
24:info:main:bar: A bar info message.
37:debug:main:bar: A bar debug message.
56:error:main:default: A main error message.
Source code: src/debug/log.h, src/debug/log.c
Test code: tst/debug/log/main.c
Test coverage: src/debug/log.c
Defines
-
LOG_FATAL
¶
-
LOG_ERROR
¶ A handable error conditions.
-
LOG_WARNING
¶ A warning.
-
LOG_INFO
¶ Generic (useful) information about system operation.
-
LOG_DEBUG
¶ Developer debugging messages.
-
LOG_MASK
(level)¶ Craete a log mask with given level set.
-
LOG_UPTO
(level)¶ Set all levels up to and including given level.
-
LOG_ALL
¶ Set all levels.
-
LOG_NONE
¶ Clear all levels.
Functions
-
int
log_module_init
(void)¶ Initialize the logging module. This function must be called before calling any other function in this module.
The module will only be initialized once even if this function is called multiple times.
- Return
- zero(0) or negative error code.
-
int
log_object_init
(struct log_object_t *self_p, const char *name_p, char mask)¶ Initialize given log object with given name and mask.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Log object to initialize.name_p
: Log object name.mask
: Log object mask.
-
int
log_object_set_log_mask
(struct log_object_t *self_p, char mask)¶ Set given log mask for given log object.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Log object.mask
: Log object mask.
-
char
log_object_get_log_mask
(struct log_object_t *self_p)¶ Get the log mask of given log object.
- Return
- Log mask.
- Parameters
self_p
: Log object.
-
int
log_object_is_enabled_for
(struct log_object_t *self_p, int level)¶ Check if given log level is enabled in given log object.
- Return
- true(1) if given log level is enabled, false(0) if given log level is disabled, otherwise negative error code.
- Parameters
self_p
: Log object, or NULL to check the level in the thread log mask.level
: Log level to check.
-
int
log_object_print
(struct log_object_t *self_p, int level, const char *fmt_p, ...)¶ Check if given log level is set in the log object mask. If so, format a log entry and write it to all log handlers.
self_p
may be NULL, and in that case the current thread’s log mask is used instead of the log object mask.- Return
- zero(0) or negative error code.
- Parameters
self_p
: Log object, or NULL to use the thread’s log mask.level
: Log level.fmt_p
: Log format string....
: Variable argument list.
-
int
log_handler_init
(struct log_handler_t *self_p, void *chout_p)¶ Initialize given log handler with given output channel.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Log handler to initialize.chout_p
: Output handler.
-
int
log_add_handler
(struct log_handler_t *handler_p)¶ Add given log handler to the list of log handlers. Log entries will be written to all log handlers in the list.
- Return
- zero(0) or negative error code.
- Parameters
handler_p
: Log handler to add.
-
int
log_remove_handler
(struct log_handler_t *handler_p)¶ Remove given log handler from the list of log handlers.
- Return
- zero(0) or negative error code.
- Parameters
handler_p
: Log handler to remove.
-
int
log_add_object
(struct log_object_t *object_p)¶ Add given log object to the list of log objects. There are file system commands to list all log objects in the list and also modify their log mask.
- Return
- zero(0) or negative error code.
- Parameters
object_p
: Log object to add.
-
int
log_remove_object
(struct log_object_t *object_p)¶ Remove given log object from the list of log objects.
- Return
- zero(0) or negative error code.
- Parameters
object_p
: Object to remove.
-
int
log_set_default_handler_output_channel
(void *chout_p)¶ Set the output channel of the default log handler.
- Return
- zero(0) or negative error code.
- Parameters
chout_p
: Channel to set as the default output channel. May be NULL if no output should be written.
- struct
- struct
Public Members
-
const char *
log_object_t::
name_p
¶
-
char
log_object_t::
mask
¶
-
struct log_object_t *
log_object_t::
next_p
¶
-
const char *
collections¶
In computer science, a data structure is a particular way of organizing data in a computer so that it can be used efficiently.
The collections package on Github.
binary_tree
— Binary tree¶
A binary search tree consists of nodes, where each node has zero, one or two siblings. The left sibling has a lower value and the right sibling has a higher value than the parent.
Insert, delete and search operations all have the time complexity of O(log n).
Source code: src/collections/binary_tree.h, src/collections/binary_tree.c
Test code: tst/collections/binary_tree/main.c
Test coverage: src/collections/binary_tree.c
Functions
-
int
binary_tree_init
(struct binary_tree_t *self_p)¶ Initialize given binary tree.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Binary tree.
-
int
binary_tree_insert
(struct binary_tree_t *self_p, struct binary_tree_node_t *node_p)¶ Insert given node into given binary tree.
There can not be two or more nodes in the tree with the same key. This function returns -1 if a node with the same key is already in the binary tree.
- Return
- zero(0) on success, -1 if a node with the same key is already in the binary tree, otherwise negative error code.
- Parameters
self_p
: Binary tree to insert the node into.node_p
: Node to insert.
-
int
binary_tree_delete
(struct binary_tree_t *self_p, int key)¶ Delete given node from given binary tree.
- Return
- zero(0) on success, -1 if the node was not found, otherwise negative error code.
- Parameters
self_p
: Binary tree to delete the node from.key
: Key of the node to delete.
-
struct binary_tree_node_t *
binary_tree_search
(struct binary_tree_t *self_p, int key)¶ Search the binary tree for the node with given key.
- Return
- Pointer to found node or NULL if a node with given key was not found in the tree.
- Parameters
self_p
: Binary tree to search in.key
: Key of the binary tree node to search for.
-
void
binary_tree_print
(struct binary_tree_t *self_p)¶ Print given binary tree.
- Parameters
self_p
: Binary tree to print.
- struct
- #include <binary_tree.h>
Public Members
-
int
binary_tree_node_t::
key
¶
-
int
binary_tree_node_t::
height
¶
-
struct binary_tree_node_t *
binary_tree_node_t::
left_p
¶
-
struct binary_tree_node_t *
binary_tree_node_t::
right_p
¶
-
int
- struct
Public Members
-
struct binary_tree_node_t *
binary_tree_t::
root_p
¶
-
struct binary_tree_node_t *
bits
— Bitwise operations¶
Source code: src/collections/bits.h
Test code: tst/collections/bits/main.c
Functions
-
static uint32_t
bits_insert_32
(uint32_t dst, int position, int size, uint32_t src)¶
fifo
— First In First Out queuing¶
Source code: src/collections/fifo.h
Test code: tst/collections/fifo/main.c
Defines
-
FIFO_DEFINE_TEMPLATE
(type)¶ Define the fifo structure and functions for a given type.
FIFO_DEFINE_TEMPLATE(int); int foo() { struct fifo_int_t fifo; int buf[4]; int value; fifo_init_int(&fifo, buf, membersof(buf)); // Put a value into the fifo. value = 10; fifo_put_int(&fifo, &value); // Get the value from the fifo. fifo_get_int(&fifo, &value); // Prints 'value = 10'. std_printf(FSTR("value= %d\r\n", value)); }
- Parameters
type
: Type of the elements in the defined fifo.
Functions
-
static int
fifo_init
(struct fifo_t *self_p, int max)¶ Initialize given fifo.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Fifo to initialize.max
: Maximum number of elements in the fifo.
- struct
- #include <fifo.h>
hash_map
— Hash map¶
Source code: src/collections/hash_map.h, src/collections/hash_map.c
Test code: tst/collections/hash_map/main.c
Test coverage: src/collections/hash_map.c
Typedefs
- typedef
Functions
-
int
hash_map_init
(struct hash_map_t *self_p, struct hash_map_bucket_t *buckets_p, size_t buckets_max, struct hash_map_entry_t *entries_p, size_t entries_max, hash_function_t hash)¶ Initialize hash map with given parameters.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Initialized hash map.buckets_p
: Array of buckets.buckets_max
: Number of entries inbuckets_p
.entries_p
: Array of empty entries.entries_max
: Number of entries inentries_p
.hash
: Hash function.
-
int
hash_map_add
(struct hash_map_t *self_p, long key, void *value_p)¶ Add given key-value pair into hash map. Overwrites old value if the key is already present in map.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Initialized hash map.key
: Key to hash.value_p
: Value to insert for key.
-
int
hash_map_remove
(struct hash_map_t *self_p, long key)¶ Remove given key from hash map.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Initialized hash map.key
: Key to hash.
-
void *
hash_map_get
(struct hash_map_t *self_p, long key)¶ Get value for given key.
- Return
- Value for key or NULL if key was not found in the map.
- Parameters
self_p
: Initialized hash map.key
: Key to hash.
- struct
Public Members
-
struct hash_map_entry_t *
hash_map_entry_t::
next_p
¶
-
long
hash_map_entry_t::
key
¶
-
void *
hash_map_entry_t::
value_p
¶
-
struct hash_map_entry_t *
- struct
Public Members
-
struct hash_map_entry_t *
hash_map_bucket_t::
list_p
¶
-
struct hash_map_entry_t *
- struct
Public Members
-
struct hash_map_bucket_t *
hash_map_t::
buckets_p
¶
-
size_t
hash_map_t::
buckets_max
¶
-
struct hash_map_entry_t *
hash_map_t::
entries_p
¶
-
hash_function_t
hash_map_t::
hash
¶
-
struct hash_map_bucket_t *
list
— Abstract lists¶
Source code: src/collections/list.h
Defines
-
LIST_SL_INIT
(list_p)¶ Initialize given singly linked list object.
- Parameters
list_p
: List object to initialize.
-
LIST_SL_INIT_STRUCT
¶
-
LIST_SL_PEEK_HEAD
(list_p, element_pp)¶ Peek at the first element in the list.
- Parameters
list_p
: List object.element_pp
: First element of the list.
-
LIST_SL_ADD_HEAD
(list_p, element_p)¶ Add given element to the beginning of given list.
- Parameters
list_p
: List object.element_p
: Element to add.
-
LIST_SL_ADD_TAIL
(list_p, element_p)¶ Add given element to the end of given list.
- Parameters
list_p
: List object.element_p
: Element to add.
-
LIST_SL_REMOVE_HEAD
(list_p, element_pp)¶ Get the first element of given list and then remove it from given list.
- Parameters
list_p
: List object.element_pp
: First element of the list.
-
LIST_SL_ITERATOR_INIT
(iterator_p, list_p)¶ Initialize given iterator object.
- Parameters
iterator_p
: Iterator to initialize.list_p
: List object to iterate over.
-
LIST_SL_ITERATOR_NEXT
(iterator_p, element_pp)¶ Get the next element from given iterator object.
- Parameters
iterator_p
: Iterator object.element_pp
: Next element of the list.
-
LIST_SL_REMOVE_ELEM
(list_p, iterator_p, element_p, iterator_element_p, previous_element_p)¶ Remove given element from given list.
- Parameters
list_p
: List object.iterator_p
: Used internally.element_p
: Used internally.iterator_element_p
: Used internally.previous_element_p
: Used internally.
- struct
- #include <list.h>
Public Members
-
void *
list_next_t::
next_p
¶
-
void *
- struct
- struct
Public Members
-
void *
list_sl_iterator_t::
next_p
¶
-
void *
alloc¶
Memory management is the act of managing computer memory. The essential requirement of memory management is to provide ways to dynamically allocate portions of memory to programs at their request, and free it for reuse when no longer needed.
The alloc package on Github.
circular_heap
— Circular heap¶
The circular heap is a dynamic memory allocator allocating buffers in a circular buffer. This puts a restriction on the user to free allocated buffers in the same order as they were allocated. This allocator is useful if you know the allocation order and need a low memory overhead on each allocated buffer and no memory fragmentation.
Below is an example of the internal state of a circular heap when buffers are allocated and freed.
After initialization begin, alloc and free have the same value. All memory is available for allocation.
begin alloc free end |-----------------------------------------------------|
Allocating a buffer increments alloc.
begin free alloc end |=========================|---------------------------|
Allocating another buffer increments alloc once again.
begin free alloc end |==========================================|----------|
Freeing the first buffer increments free to the position of the first alloc.
begin free alloc end |-------------------------|================|----------|
Allocating a buffer that is bigger than the available space between alloc and end results in a buffer starting at begin. The memory between the old alloc and end will be unused.
begin alloc free end |==================|------|================|oooooooooo|
Freeing the second buffer increments free to the position of the second alloc.
begin alloc free end |==================|-----------------------|oooooooooo|
Freeing the third buffer sets free to alloc. All memory is available for allocation once again.
alloc begin free end |------------------|----------------------------------|
Done!
Source code: src/alloc/circular_heap.h, src/alloc/circular_heap.c
Test code: tst/alloc/circular_heap/main.c
Test coverage: src/alloc/circular_heap.c
Functions
-
int
circular_heap_init
(struct circular_heap_t *self_p, void *buf_p, size_t size)¶ Initialize given circular_heap.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Circular heap to initialize.buf_p
: Memory buffer.size
: Size of the memory buffer.
-
void *
circular_heap_alloc
(struct circular_heap_t *self_p, size_t size)¶ Allocate a buffer of given size from given circular heap.
- Return
- Pointer to allocated buffer, or NULL on failure.
- Parameters
self_p
: Circular heap to allocate from.size
: Number of bytes to allocate.
-
int
circular_heap_free
(struct circular_heap_t *self_p, void *buf_p)¶ Free the oldest allocated buffer.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Circular heap to free to.buf_p
: Buffer to free. Must be the oldest allocated buffer.
- struct
- #include <circular_heap.h>
heap
— Heap¶
Source code: src/alloc/heap.h, src/alloc/heap.c
Test code: tst/alloc/heap/main.c
Test coverage: src/alloc/heap.c
Defines
-
HEAP_FIXED_SIZES_MAX
¶
Functions
-
int
heap_init
(struct heap_t *self_p, void *buf_p, size_t size, size_t sizes[HEAP_FIXED_SIZES_MAX])¶ Initialize given heap.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Heap to initialize.buf_p
: Heap memory buffer.size
: Size of the heap memory buffer.
-
void *
heap_alloc
(struct heap_t *self_p, size_t size)¶ Allocate a buffer of given size from given heap.
- Return
- Pointer to allocated buffer, or NULL on failure.
- Parameters
self_p
: Heap to allocate from.size
: Number of bytes to allocate.
-
int
heap_free
(struct heap_t *self_p, void *buf_p)¶ Decrement the share count by once and free the buffer if the count becomes zero(0).
- Return
- Share count after the free, or negative error code.
- Parameters
self_p
: Heap of given buffer.buf_p
: Memory buffer to free.
Share given buffer
count
times.- Return
- zero(0) or negative error code.
- Parameters
self_p
: Heap of given buffer.buf_p
: Buffer to share.count
: Share count.
- struct
- struct
Public Members
-
void *
heap_dynamic_t::
free_p
¶
-
void *
- struct
Public Members
-
void *
heap_t::
buf_p
¶
-
size_t
heap_t::
size
¶
-
void *
heap_t::
next_p
¶
-
struct heap_fixed_t
heap_t::
fixed
[HEAP_FIXED_SIZES_MAX]¶
-
struct heap_dynamic_t
heap_t::
dynamic
¶
-
void *
text¶
Text parsing, editing and colorization.
The text package on Github.
color
— ANSI colors¶
Source code: src/text/color.h
Defines
-
COLOR_RESET
¶
-
COLOR_BOLD_ON
¶
-
COLOR_ITALICS_ON
¶
-
COLOR_UNDERLINE_ON
¶
-
COLOR_INVERSE_ON
¶
-
COLOR_STRIKETHROUGH_ON
¶
-
COLOR_BOLD_OFF
¶
-
COLOR_ITALICS_OFF
¶
-
COLOR_UNDERLINE_OFF
¶
-
COLOR_INVERSE_OFF
¶
-
COLOR_STRIKETHROUGH_OFF
¶
-
COLOR_FOREGROUND_BLACK
¶
-
COLOR_FOREGROUND_RED
¶
-
COLOR_FOREGROUND_GREEN
¶
-
COLOR_FOREGROUND_YELLOW
¶
-
COLOR_FOREGROUND_BLUE
¶
-
COLOR_FOREGROUND_MAGENTA
¶
-
COLOR_FOREGROUND_CYAN
¶
-
COLOR_FOREGROUND_WHITE
¶
-
COLOR_FOREGROUND_DEFAULT
¶
-
COLOR_BACKGROUND_BLACK
¶
-
COLOR_BACKGROUND_RED
¶
-
COLOR_BACKGROUND_GREEN
¶
-
COLOR_BACKGROUND_YELLOW
¶
-
COLOR_BACKGROUND_BLUE
¶
-
COLOR_BACKGROUND_MAGENTA
¶
-
COLOR_BACKGROUND_CYAN
¶
-
COLOR_BACKGROUND_WHITE
¶
-
COLOR_BACKGROUND_DEFAULT
¶
-
COLOR
(...)¶
configfile
— Configuration file (INI-file)¶
The INI file format is an informal standard for configuration files for some platforms or software. INI files are simple text files with a basic structure composed of sections, properties, and values.
More information on Wikipedia.
File format description¶
- Line terminators:
\n
,\r\n
or\n\r
. - Opening bracket (
[
) at the beginning of a line indicates a section. The section name is all characters until a closing bracket (]
). - A property line starts with its name, then a colon (
:
) or equal sign (=
), and then the value. - Semicolon (
;
) or number sign (#
) at the beginning of a line indicate a comment.
Example file¶
; last modified 1 April 2001 by John Doe
[owner]
name = John Doe
organization = Acme Widgets Inc.
[database]
; use IP address in case network name resolution is not working
server = 192.0.2.62
port = 143
file = "payroll.dat"
Source code: src/text/configfile.h, src/text/configfile.c
Test code: tst/text/configfile/main.c
Test coverage: src/text/configfile.c
Functions
-
int
configfile_init
(struct configfile_t *self_p, char *buf_p, size_t size)¶ Initialize given configuration file object.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Object to initialize.buf_p
: Configuration file contents as a NULL terminated string.size
: Size of the configuration file contents.
-
int
configfile_set
(struct configfile_t *self_p, const char *section_p, const char *property_p, const char *value_p)¶ Set the value of given property in given section.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Initialized parser.section_p
: Section to set the property from.property_p
: Property to set the value for.value_p
: NULL terminated value to set.
-
char *
configfile_get
(struct configfile_t *self_p, const char *section_p, const char *property_p, char *value_p, int length)¶ Get the value of given property in given section.
- Return
- Value pointer or NULL on failure.
- Parameters
self_p
: Initialized parser.section_p
: Section to get the property from.property_p
: Property to get the value for.value_p
: Value of given property in given section.size
: Size of the value buffer.
-
int
configfile_get_long
(struct configfile_t *self_p, const char *section_p, const char *property_p, long *value_p)¶ Get the value of given property in given section, converted to an integer.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Initialized parser.section_p
: Section to get the property from.property_p
: Property to get the value for.value_p
: Value of given property in given section.
-
int
configfile_get_float
(struct configfile_t *self_p, const char *section_p, const char *property_p, float *value_p)¶ Get the value of given property in given section, converted to a float.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: Initialized parser.section_p
: Section to get the property from.property_p
: Property to get the value for.value_p
: Value of given property in given section.
- struct
- #include <configfile.h>
re
— Regular expressions¶
Source code: src/text/re.h, src/text/re.c
Test code: tst/text/re/main.c
Test coverage: src/text/re.c
Defines
-
RE_IGNORECASE
¶
-
RE_DOTALL
¶ Make the
'.'
special character match any character at all, including a newline; without this flag,'.'
will match anything except a newline.
-
RE_MULTILINE
¶ When specified, the pattern character
'^'
matches at the beginning of the string and at the beginning of each line (immediately following each newline); and the pattern character'$'
matches at the end of the string and at the end of each line (immediately preceding each newline). By default, ‘^’ matches only at the beginning of the string, and'$'
only at the end of the string and immediately before the newline (if any) at the end of the string.
Functions
-
char *
re_compile
(char *compiled_p, const char *pattern_p, char flags, size_t size)¶ Compile given pattern.
Pattern syntax:
'.'
- Any character.'^'
- Beginning of the string (not yet supported).'$'
- End of the string (not yet supported).'?'
- Zero or one repetitions (greedy).'*'
- Zero or more repetitions (greedy).'+'
- One or more repetitions (greedy).'??'
- Zero or one repetitions (non-greedy).*?
- Zero or more repetitions (non-greedy).+?
- One or more repetitions (non-greedy).{m}
- Exactlym
repetitions.\\
- Escape character.[]
- Set of characters.'|'
- Alternatives (not yet supported).(...)
- Groups (not yet supported).\\d
- Decimal digits[0-9]
.\\w
- Alphanumerical characters[a-ZA-Z0-9_]
.\\s
- Whitespace characters[ \t\r\n\f\v]
.
- Return
- Compiled patten, or NULL if the compilation failed.
- Parameters
compiled_p
: Compiled regular expression pattern.pattern_p
: Regular expression pattern.flags
: A combination of the flagsRE_IGNORECASE
,RE_DOTALL
andRE_MULTILINE
(RE_MULTILINE
is not yet supported).size
: Size of the compiled buffer.
-
ssize_t
re_match
(const char *compiled_p, const char *buf_p, size_t size, struct re_group_t *groups_p, size_t *number_of_groups_p)¶ Apply given regular expression to the beginning of given string.
- Return
- Number of matched bytes or negative error code.
- Parameters
compiled_p
: Compiled regular expression pattern. Compile a pattern withre_compile()
.buf_p
: Buffer to apply the compiled pattern to.size
: Number of bytes in the buffer.groups_p
: Read groups or NULL.number_of_groups_p
: Number of read groups or NULL.
- struct
std
— Standard functions¶
Source code: src/text/std.h, src/text/std.c
Test code: tst/text/std/main.c
Test coverage: src/text/std.c
Functions
-
int
std_module_init
(void)¶
-
ssize_t std_sprintf(char * dst_p, FAR const char * fmt_p, ...)
Format and write data to destination buffer. The buffer must be big enough to fit the formatted string. The output is null terminated.
A format specifier has this format:
%[flags][width][length]specifier
where
- flags:
0
or-
- width:
0
..127
- length:
l
for long or nothing - specifier:
c
,s
,d
,i
,u
,x
orf
- Return
- Length of the string written to the destination buffer, not inclusing the null termination, or negative error code.
- Parameters
dst_p
: Destination buffer. The formatted string is written to this buffer.fmt_p
: Format string....
: Variable arguments list.
- flags:
-
ssize_t std_snprintf(char * dst_p, size_t size, FAR const char * fmt_p, ...)
Format and write data to given buffer. The output is null terminated.
- Return
- Length of the string written to the destination buffer, not inclusing the null termination, or negative error code.
- Parameters
dst_p
: Destination buffer. The formatted string is written to this buffer.size
: Size of the destination buffer.fmt_p
: Format string....
: Variable arguments list.
-
ssize_t std_vsprintf(char * dst_p, FAR const char * fmt_p, va_list * ap_p)
Format and write data to given buffer. The output is null terminated.
- Return
- Length of the string written to the destination buffer, not inclusing the null termination, or negative error code.
- Parameters
dst_p
: Destination buffer. The formatted string is written to this buffer.fmt_p
: Format string.ap_p
: Variable arguments list.
-
ssize_t std_vsnprintf(char * dst_p, size_t size, FAR const char * fmt_p, va_list * ap_p)
Format and write data to given buffer. The output is null terminated.
- Return
- Length of the string written to the destination buffer, not inclusing the null termination, or negative error code.
- Parameters
dst_p
: Destination buffer. The formatted string is written to this buffer.size
: Size of the destination buffer.fmt_p
: Format string.ap_p
: Variable arguments list.
-
ssize_t
std_printf
(far_string_t fmt_p, ...)¶ Format and print data to standard output. The output is not null terminated.
See
std_sprintf()
for the the format string specification.- Return
- Number of characters written to standard output, or negative error code.
- Parameters
fmt_p
: Format string....
: Variable arguemnts list.
-
ssize_t std_vprintf(FAR const char * fmt_p, va_list * ap_p)
Format and print data to standard output. The output is not null terminated.
See
std_sprintf()
for the the format string specification.- Return
- Number of characters written to standard output, or negative error code.
- Parameters
fmt_p
: Format string.ap_p
: Variable arguemnts list.
-
ssize_t std_fprintf(void * chan_p, FAR const char * fmt_p, ...)
Format and print data to channel. The output is not null terminated.
See
std_sprintf()
for the the format string specification.- Return
- Number of characters written to given channel, or negative error code.
- Parameters
chan_p
: Output channel.fmt_p
: Format string....
: Variable arguemnts list.
-
ssize_t std_vfprintf(void * chan_p, FAR const char * fmt_p, va_list * ap_p)
Format and print data to channel. The output is not null terminated.
See
std_sprintf()
for the the format string specification.- Return
- Number of characters written to given channel, or negative error code.
- Parameters
chan_p
: Output channel.fmt_p
: Format string....
: Variable arguemnts list.
-
const char *
std_strtol
(const char *str_p, long *value_p)¶ Convert string to integer.
- Return
- Pointer to the next byte or NULL on failure.
- Parameters
str_p
: Integer string.value_p
: Integer value.
-
int std_strcpy(char * dst_p, FAR const char * src_p)
Copy string from far memory to memory.
- Return
- String length or negative error code.
- Parameters
dst_p
: Normal memory string.src_p
: Far memory string.
-
int std_strcmp(const char * str_p, FAR const char * fstr_p)
Compare a string with a far string.
- Return
- zero(0) if match, otherwise the difference of the mismatched characters
- Parameters
str_p
: Normal memory string.fstr_p
: Far memory string.
-
int std_strcmp_f(FAR const char * fstr0_p, FAR const char * fstr1_p)
Compare two far strings.
- Return
- zero(0) if match, otherwise the difference of the mismatched characters.
- Parameters
fstr0_p
: Far memory string.fstr1_p
: Far memory string.
-
int std_strncmp(FAR const char * fstr_p, const char * str_p, size_t size)
Compare at most
size
bytes of one far string and one string.- Return
- zero(0) if match, otherwise the difference of the mismatched characters.
- Parameters
fstr_p
: Far memory string.str_p
: String.size
: Compare at most size number of bytes.
-
int std_strncmp_f(FAR const char * fstr0_p, FAR const char * fstr1_p, size_t size)
Compare at most
size
bytes of two far strings.- Return
- zero(0) if match, otherwise the difference of the mismatched characters.
- Parameters
fstr0_p
: Far memory string.fstr1_p
: Far memory string.size
: Compare at most size number of bytes.
-
int std_strlen(FAR const char * fstr_p)
Get the length in bytes of given far string, not including null termination.
- Return
- String length in number of bytes (not including the null termination).
- Parameters
fstr_p
: Far memory string.
-
char *
std_strip
(char *str_p, const char *strip_p)¶ Strip leading and trailing characters from a string. The characters to strip are given by
strip_p
.- Return
- Pointer to the stripped string.
- Parameters
str_p
: String to strip characters from.strip_p
: Characters to strip or NULL for whitespace characters. Must be null-terminated.
encode¶
In computing, a character encoding is used to represent a repertoire of characters by some kind of an encoding system.
The encode package on Github.
base64
— Base64 encoding and decoding.¶
Source code: src/encode/base64.h, src/encode/base64.c
Test code: tst/encode/base64/main.c
Test coverage: src/encode/base64.c
Functions
-
int
base64_encode
(char *dst_p, const void *src_p, size_t size)¶
-
int
base64_decode
(void *dst_p, const char *src_p, size_t size)¶ Decode given base64 encoded buffer. The decoded data will be ~25% smaller than the destination data. Choose the destination buffer size accordingly.
- Return
- zero(0) or negative error code.
- Parameters
dst_p
: Output data.src_p
: Encoded input data.size
: Number of bytes in the encoded input data.
json
— JSON encoding and decoding¶
Source code: src/encode/json.h, src/encode/json.c
Test code: tst/encode/json/main.c
Test coverage: src/encode/json.c
Enums
-
enum type
json_type_t
¶ Values:
- = 0
Undefined type.
- = 1
Object,
{}
.
- = 2
Array,
[]
.
- = 3
String,
\"...\\"
.
- = 4
Other primitive: number, boolean (true/false) or null.
-
enum type
json_err_t
¶ Values:
- = -1
Not enough tokens were provided.
- = -2
Invalid character inside JSON string.
- = -3
The string is not a full JSON packet, more bytes expected.
Functions
-
int
json_init
(struct json_t *self_p, struct json_tok_t *tokens_p, int num_tokens)¶ Initialize given JSON object. The JSON object must be initialized before it can be used to parse and dump JSON data.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: JSON object to initialize.tokens_p
: Array of tokens. The tokens are either filled by the parsing functionjson_parse()
, or already filled by the user when calling this function. The latter can be used to dump the tokens as a string by callingjson_dump()
orjson_dumps()
.num_tokens
: Number of tokens in the array.
-
int
json_parse
(struct json_t *self_p, const char *js_p, size_t len)¶ Parse given JSON data string into and array of tokens, each describing a single JSON object.
- Return
- Number of decoded tokens or negative error code.
- Parameters
self_p
: JSON object.js_p
: JSON string to parse.len
: JSON string length in bytes.
-
ssize_t
json_dumps
(struct json_t *self_p, struct json_tok_t *tokens_p, char *js_p)¶ Format and write given JSON tokens into a string.
- Return
- Dumped string length (not including termination) or negative error code.
- Parameters
self_p
: JSON object.tokens_p
: Root token to dump. Set to NULL to dump the whole object.js_p
: Dumped null terminated JSON string.
-
ssize_t
json_dump
(struct json_t *self_p, struct json_tok_t *tokens_p, void *out_p)¶ Format and write given JSON tokens to given channel.
- Return
- Dumped string length (not including termination) or negative error code.
- Parameters
self_p
: JSON object.tokens_p
: Root token to dump. Set to NULL to dump the whole object.out_p
: Channel to dump the null terminated JSON string to.
-
struct json_tok_t *
json_root
(struct json_t *self_p)¶ Get the root token.
- Return
- The root token or NULL on failure.
- Parameters
self_p
: JSON object.
-
struct json_tok_t *
json_object_get
(struct json_t *self_p, const char *key_p, struct json_tok_t *object_p)¶ Get the value the string token with given key.
- Return
- Token or NULL on error.
- Parameters
self_p
: JSON object.key_p
: Key of the value to get.object_p
: The object to get the value from.
-
struct json_tok_t *
json_object_get_primitive
(struct json_t *self_p, const char *key_p, struct json_tok_t *object_p)¶ Get the value of the primitive token with given key.
- Return
- Token or NULL on error.
- Parameters
self_p
: JSON object.key_p
: Key of the value to get.object_p
: The object to get the value from.
-
struct json_tok_t *
json_array_get
(struct json_t *self_p, int index, struct json_tok_t *array_p)¶ Get the token of given array index.
- Return
- Token or NULL on error.
- Parameters
self_p
: JSON object.index
: Index to get.array_p
: The array to get the element from.
-
void
json_token_object
(struct json_tok_t *token_p, int num_keys)¶ Initialize a JSON object token.
- Parameters
token_p
: Initialized token.num_keys
: Number of keys in the object.
-
void
json_token_array
(struct json_tok_t *token_p, int num_elements)¶ Initialize a JSON array token.
- Parameters
token_p
: Initialized token.num_elements
: Number of array elements.
-
void
json_token_true
(struct json_tok_t *token_p)¶ Initialize a JSON boolean true token.
- Parameters
token_p
: Initialized token.
-
void
json_token_false
(struct json_tok_t *token_p)¶ Initialize a JSON boolean false token.
- Parameters
token_p
: Initialized token.
-
void
json_token_null
(struct json_tok_t *token_p)¶ Initialize a JSON null token.
- Parameters
token_p
: Initialized token.
-
void
json_token_number
(struct json_tok_t *token_p, const char *buf_p, size_t size)¶ Initialize a JSON number (integer/float) token.
- Parameters
token_p
: Initialized token.buf_p
: Number as a string.size
: String length.
-
void
json_token_string
(struct json_tok_t *token_p, const char *buf_p, size_t size)¶ Initialize a JSON string token.
- Parameters
token_p
: Initialized token.buf_p
: String.size
: String length.
- struct
Public Members
-
json_type_t
json_tok_t::
type
¶
-
const char *
json_tok_t::
buf_p
¶
-
size_t
json_tok_t::
size
¶
-
int
json_tok_t::
num_tokens
¶
-
json_type_t
- struct
Public Members
-
unsigned int
json_t::
pos
¶ Offset in the JSON string.
-
unsigned int
json_t::
toknext
¶ Next token to allocate.
-
int
json_t::
toksuper
¶ Superior token node, e.g parent object or array.
-
struct json_tok_t *
json_t::
tokens_p
¶ Array of tokens.
-
int
json_t::
num_tokens
¶ Number of tokens in the tokens array.
-
unsigned int
hash¶
A hash function is any function that can be used to map data of arbitrary size to data of fixed size.
The hash package on Github.
crc
— Cyclic Redundancy Checks¶
Source code: src/hash/crc.h, src/hash/crc.c
Test code: tst/hash/crc/main.c
Test coverage: src/hash/crc.c
Functions
-
uint32_t
crc_32
(uint32_t crc, const void *buf_p, size_t size)¶
-
uint16_t
crc_ccitt
(uint16_t crc, const void *buf_p, size_t size)¶ Calculate a 16 bits crc using the CCITT algorithm (polynomial
x^16+x^12+x^5+x^1
).- Return
- Calculated crc.
- Parameters
crc
: Initial crc. Should be 0xffff for CCITT.buf_p
: Buffer to calculate crc of.size
: Size of the buffer.
-
uint16_t
crc_xmodem
(uint16_t crc, const void *buf_p, size_t size)¶ Calculate a 16 bits crc using the XModem algorithm (polynomial
x^16+x^12+x^5+x^1
).- Return
- Calculated crc.
- Parameters
crc
: Initial crc. Should be 0x0000 for XModem.buf_p
: Buffer to calculate crc of.size
: Size of the buffer.
-
uint8_t
crc_7
(const void *buf_p, size_t size)¶ Calculate a 8 bits crc using the CRC-7 algorithm (polynomial
x^7+x^3+1
).- Return
- Calculated crc.
- Parameters
buf_p
: Buffer to calculate crc of.size
: Size of the buffer.
sha1
— SHA1¶
Source code: src/hash/sha1.h, src/hash/sha1.c
Test code: tst/hash/main.c
Test coverage: src/hash/sha1.c
Functions
-
int
sha1_init
(struct sha1_t *self_p)¶ Initialize given SHA1 object.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: SHA1 object.
-
int
sha1_update
(struct sha1_t *self_p, void *buf_p, size_t size)¶ Update the sha object with the given buffer. Repeated calls are equivalent to a single call with the concatenation of all the arguments.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: SHA1 object.buf_p
: Buffer to update the sha object with.size
: Size of the buffer.
-
int
sha1_digest
(struct sha1_t *self_p, uint8_t *hash_p)¶ Return the digest of the strings passed to the sha1_update() method so far. This is a 20-byte value which may contain non-ASCII characters, including null bytes.
- Return
- zero(0) or negative error code.
- Parameters
self_p
: SHA1 object.hash_p
: Hash sum.
- struct
- #include <sha1.h>
multimedia¶
The multimedia package on Github.
midi
— Musical Instrument Digital Interface¶
Source code: src/multimedia/midi.h, src/multimedia/midi.c
Test code: tst/multimedia/midi/main.c
Test coverage: src/multimedia/midi.c
Defines
-
MIDI_BAUDRATE
¶
-
MIDI_NOTE_OFF
¶
-
MIDI_NOTE_ON
¶
-
MIDI_POLYPHONIC_KEY_PRESSURE
¶
-
MIDI_CONTROL_CHANGE
¶
-
MIDI_PROGRAM_CHANGE
¶
-
MIDI_CHANNEL_PRESSURE
¶
-
MIDI_PITCH_BEND_CHANGE
¶
-
MIDI_SET_INTRUMENT
¶
-
MIDI_PERC
¶
-
MIDI_NOTE_MAX
¶
-
MIDI_NOTE_A0
¶
-
MIDI_NOTE_B0
¶
-
MIDI_NOTE_C1
¶
-
MIDI_NOTE_D1
¶
-
MIDI_NOTE_E1
¶
-
MIDI_NOTE_F1
¶
-
MIDI_NOTE_G1
¶
-
MIDI_NOTE_A1
¶
-
MIDI_NOTE_B1
¶
-
MIDI_NOTE_C2
¶
-
MIDI_NOTE_D2
¶
-
MIDI_NOTE_E2
¶
-
MIDI_NOTE_F2
¶
-
MIDI_NOTE_G2
¶
-
MIDI_NOTE_A2
¶
-
MIDI_NOTE_B2
¶
-
MIDI_NOTE_C3
¶
-
MIDI_NOTE_D3
¶
-
MIDI_NOTE_E3
¶
-
MIDI_NOTE_F3
¶
-
MIDI_NOTE_G3
¶
-
MIDI_NOTE_A3
¶
-
MIDI_NOTE_B3
¶
-
MIDI_NOTE_C4
¶
-
MIDI_NOTE_D4
¶
-
MIDI_NOTE_E4
¶
-
MIDI_NOTE_F4
¶
-
MIDI_NOTE_G4
¶
-
MIDI_NOTE_A4
¶
-
MIDI_NOTE_B4
¶
-
MIDI_NOTE_C5
¶
-
MIDI_NOTE_D5
¶
-
MIDI_NOTE_E5
¶
-
MIDI_NOTE_F5
¶
-
MIDI_NOTE_G5
¶
-
MIDI_NOTE_A5
¶
-
MIDI_NOTE_B5
¶
-
MIDI_NOTE_C6
¶
-
MIDI_NOTE_D6
¶
-
MIDI_NOTE_E6
¶
-
MIDI_NOTE_F6
¶
-
MIDI_NOTE_G6
¶
-
MIDI_NOTE_A6
¶
-
MIDI_NOTE_B6
¶
-
MIDI_NOTE_C7
¶
-
MIDI_NOTE_D7
¶
-
MIDI_NOTE_E7
¶
-
MIDI_NOTE_F7
¶
-
MIDI_NOTE_G7
¶
-
MIDI_NOTE_A7
¶
-
MIDI_NOTE_B7
¶
-
MIDI_NOTE_C8
¶
-
MIDI_PERC_ACOUSTIC_BASS_DRUM
¶
-
MIDI_PERC_BASS_DRUM_1
¶
-
MIDI_PERC_SIDE_STICK
¶
-
MIDI_PERC_ACOUSTIC_SNARE
¶
-
MIDI_PERC_HAND_CLAP
¶
-
MIDI_PERC_ELECTRIC_SNARE
¶
-
MIDI_PERC_LOW_FLOOR_TOM
¶
-
MIDI_PERC_CLOSED_HI_HAT
¶
-
MIDI_PERC_HIGH_FLOOR_TOM
¶
-
MIDI_PERC_PEDAL_HI_HAT
¶
-
MIDI_PERC_LOW_TOM
¶
-
MIDI_PERC_OPEN_HI_HAT
¶
-
MIDI_PERC_LOW_MID_TOM
¶
-
MIDI_PERC_HI_MID_TOM
¶
-
MIDI_PERC_CRASH_CYMBAL_1
¶
-
MIDI_PERC_HIGH_TOM
¶
-
MIDI_PERC_RIDE_CYMBAL_1
¶
-
MIDI_PERC_CHINESE_CYMBAL
¶
-
MIDI_PERC_RIDE_BELL
¶
-
MIDI_PERC_TAMBOURINE
¶
-
MIDI_PERC_SPLASH_CYMBAL
¶
-
MIDI_PERC_COWBELL
¶
-
MIDI_PERC_CRASH_CYMBAL_2
¶
-
MIDI_PERC_VIBRASLAP
¶
-
MIDI_PERC_RIDE_CYMBAL_2
¶
-
MIDI_PERC_HI_BONGO
¶
-
MIDI_PERC_LOW_BONGO
¶
-
MIDI_PERC_MUTE_HI_CONGA
¶
-
MIDI_PERC_OPEN_HI_CONGA
¶
-
MIDI_PERC_LOW_CONGA
¶
-
MIDI_PERC_HIGH_TIMBALE
¶
-
MIDI_PERC_LOW_TIMBALE
¶
-
MIDI_PERC_HIGH_AGOGO
¶
-
MIDI_PERC_LOW_AGOGO
¶
-
MIDI_PERC_CABASA
¶
-
MIDI_PERC_MARACAS
¶
-
MIDI_PERC_SHORT_WHISTLE
¶
-
MIDI_PERC_LONG_WHISTLE
¶
-
MIDI_PERC_SHORT_GUIRO
¶
-
MIDI_PERC_LONG_GUIRO
¶
-
MIDI_PERC_CLAVES
¶
-
MIDI_PERC_HI_WOOD_BLOCK
¶
-
MIDI_PERC_LOW_WOOD_BLOCK
¶
-
MIDI_PERC_MUTE_CUICA
¶
-
MIDI_PERC_OPEN_CUICA
¶
-
MIDI_PERC_MUTE_TRIANGLE
¶
-
MIDI_PERC_OPEN_TRIANGLE
¶
Functions
-
float
midi_note_to_frequency
(int note)¶ Get the frequency for given note.
- Return
- Note frequency.
- Parameters
note
: MIDI note.
boards¶
The boards supported by Simba.
The boards on Github.
arduino_due
— Arduino Due¶
Source code: src/boards/arduino_due/board.h, src/boards/arduino_due/board.c
Hardware reference: Arduino Due
Defines
-
pin_d0_dev
¶
-
pin_d1_dev
¶
-
pin_d2_dev
¶
-
pin_d3_dev
¶
-
pin_d4_dev
¶
-
pin_d5_dev
¶
-
pin_d6_dev
¶
-
pin_d7_dev
¶
-
pin_d8_dev
¶
-
pin_d9_dev
¶
-
pin_d10_dev
¶
-
pin_d11_dev
¶
-
pin_d12_dev
¶
-
pin_d13_dev
¶
-
pin_d14_dev
¶
-
pin_d15_dev
¶
-
pin_d16_dev
¶
-
pin_d17_dev
¶
-
pin_d18_dev
¶
-
pin_d19_dev
¶
-
pin_d20_dev
¶
-
pin_d21_dev
¶
-
pin_d22_dev
¶
-
pin_d23_dev
¶
-
pin_d24_dev
¶
-
pin_d25_dev
¶
-
pin_d26_dev
¶
-
pin_d27_dev
¶
-
pin_d28_dev
¶
-
pin_d29_dev
¶
-
pin_d30_dev
¶
-
pin_d31_dev
¶
-
pin_d32_dev
¶
-
pin_d33_dev
¶
-
pin_d34_dev
¶
-
pin_d35_dev
¶
-
pin_d36_dev
¶
-
pin_d37_dev
¶
-
pin_d38_dev
¶
-
pin_d39_dev
¶
-
pin_d40_dev
¶
-
pin_d41_dev
¶
-
pin_d42_dev
¶
-
pin_d43_dev
¶
-
pin_d44_dev
¶
-
pin_d45_dev
¶
-
pin_d46_dev
¶
-
pin_d47_dev
¶
-
pin_d48_dev
¶
-
pin_d49_dev
¶
-
pin_d50_dev
¶
-
pin_d51_dev
¶
-
pin_d52_dev
¶
-
pin_d53_dev
¶
-
pin_a0_dev
¶
-
pin_a1_dev
¶
-
pin_a2_dev
¶
-
pin_a3_dev
¶
-
pin_a4_dev
¶
-
pin_a5_dev
¶
-
pin_a6_dev
¶
-
pin_a7_dev
¶
-
pin_a8_dev
¶
-
pin_a9_dev
¶
-
pin_a10_dev
¶
-
pin_a11_dev
¶
-
pin_led_dev
¶
-
pin_dac0_dev
¶
-
pin_dac1_dev
¶
-
exti_d0_dev
¶
-
exti_d1_dev
¶
-
exti_d2_dev
¶
-
exti_d3_dev
¶
-
exti_d4_dev
¶
-
exti_d5_dev
¶
-
exti_d6_dev
¶
-
exti_d7_dev
¶
-
exti_d8_dev
¶
-
exti_d9_dev
¶
-
exti_d10_dev
¶
-
exti_d11_dev
¶
-
exti_d12_dev
¶
-
exti_d13_dev
¶
-
exti_d14_dev
¶
-
exti_d15_dev
¶
-
exti_d16_dev
¶
-
exti_d17_dev
¶
-
exti_d18_dev
¶
-
exti_d19_dev
¶
-
exti_d20_dev
¶
-
exti_d21_dev
¶
-
exti_d22_dev
¶
-
exti_d23_dev
¶
-
exti_d24_dev
¶
-
exti_d25_dev
¶
-
exti_d26_dev
¶
-
exti_d27_dev
¶
-
exti_d28_dev
¶
-
exti_d29_dev
¶
-
exti_d30_dev
¶
-
exti_d31_dev
¶
-
exti_d32_dev
¶
-
exti_d33_dev
¶
-
exti_d34_dev
¶
-
exti_d35_dev
¶
-
exti_d36_dev
¶
-
exti_d37_dev
¶
-
exti_d38_dev
¶
-
exti_d39_dev
¶
-
exti_d40_dev
¶
-
exti_d41_dev
¶
-
exti_d42_dev
¶
-
exti_d43_dev
¶
-
exti_d44_dev
¶
-
exti_d45_dev
¶
-
exti_d46_dev
¶
-
exti_d47_dev
¶
-
exti_d48_dev
¶
-
exti_d49_dev
¶
-
exti_d50_dev
¶
-
exti_d51_dev
¶
-
exti_d52_dev
¶
-
exti_d53_dev
¶
-
exti_a0_dev
¶
-
exti_a1_dev
¶
-
exti_a2_dev
¶
-
exti_a3_dev
¶
-
exti_a4_dev
¶
-
exti_a5_dev
¶
-
exti_a6_dev
¶
-
exti_a7_dev
¶
-
exti_a8_dev
¶
-
exti_a9_dev
¶
-
exti_a10_dev
¶
-
exti_a11_dev
¶
-
exti_led_dev
¶
-
exti_dac0_dev
¶
-
exti_dac1_dev
¶
-
pwm_d2_dev
¶
-
pwm_d3_dev
¶
-
pwm_d5_dev
¶
-
pwm_d6_dev
¶
-
pwm_d7_dev
¶
-
pwm_d8_dev
¶
-
pwm_d9_dev
¶
-
pwm_d10_dev
¶
-
pwm_d11_dev
¶
-
pwm_d12_dev
¶
-
adc_0_dev
¶
-
dac_0_dev
¶
-
flash_0_dev
¶
Functions
-
int
board_pin_string_to_device_index
(const char *str_p)¶ Convert given pin string to the pin number.
- Return
- Pin number of negative error code.
- Parameters
str_p
: Pin as a string.
arduino_mega
— Arduino Mega¶
Source code: src/boards/arduino_mega/board.h, src/boards/arduino_mega/board.c
Hardware reference: Arduino Mega
Defines
-
pin_d0_dev
¶
-
pin_d1_dev
¶
-
pin_d2_dev
¶
-
pin_d3_dev
¶
-
pin_d4_dev
¶
-
pin_d5_dev
¶
-
pin_d6_dev
¶
-
pin_d7_dev
¶
-
pin_d8_dev
¶
-
pin_d9_dev
¶
-
pin_d10_dev
¶
-
pin_d11_dev
¶
-
pin_d12_dev
¶
-
pin_d13_dev
¶
-
pin_d14_dev
¶
-
pin_d15_dev
¶
-
pin_d16_dev
¶
-
pin_d17_dev
¶
-
pin_d18_dev
¶
-
pin_d19_dev
¶
-
pin_d20_dev
¶
-
pin_d21_dev
¶
-
pin_d22_dev
¶
-
pin_d23_dev
¶
-
pin_d24_dev
¶
-
pin_d25_dev
¶
-
pin_d26_dev
¶
-
pin_d27_dev
¶
-
pin_d28_dev
¶
-
pin_d29_dev
¶
-
pin_d30_dev
¶
-
pin_d31_dev
¶
-
pin_d32_dev
¶
-
pin_d33_dev
¶
-
pin_d34_dev
¶
-
pin_d35_dev
¶
-
pin_d36_dev
¶
-
pin_d37_dev
¶
-
pin_d38_dev
¶
-
pin_d39_dev
¶
-
pin_d40_dev
¶
-
pin_d41_dev
¶
-
pin_d42_dev
¶
-
pin_d43_dev
¶
-
pin_d44_dev
¶
-
pin_d45_dev
¶
-
pin_d46_dev
¶
-
pin_d47_dev
¶
-
pin_d48_dev
¶
-
pin_d49_dev
¶
-
pin_d50_dev
¶
-
pin_d51_dev
¶
-
pin_d52_dev
¶
-
pin_d53_dev
¶
-
pin_a0_dev
¶
-
pin_a1_dev
¶
-
pin_a2_dev
¶
-
pin_a3_dev
¶
-
pin_a4_dev
¶
-
pin_a5_dev
¶
-
pin_a6_dev
¶
-
pin_a7_dev
¶
-
pin_a8_dev
¶
-
pin_a9_dev
¶
-
pin_a10_dev
¶
-
pin_a11_dev
¶
-
pin_a12_dev
¶
-
pin_a13_dev
¶
-
pin_a14_dev
¶
-
pin_a15_dev
¶
-
pin_led_dev
¶
-
exti_d2_dev
¶
-
exti_d3_dev
¶
-
exti_d18_dev
¶
-
exti_d19_dev
¶
-
exti_d20_dev
¶
-
exti_d21_dev
¶
-
pwm_d2_dev
¶
-
pwm_d3_dev
¶
-
pwm_d5_dev
¶
-
pwm_d6_dev
¶
-
pwm_d7_dev
¶
-
pwm_d8_dev
¶
-
pwm_d9_dev
¶
-
pwm_d10_dev
¶
-
pwm_d11_dev
¶
-
pwm_d12_dev
¶
-
adc_0_dev
¶
-
i2c_0_dev
¶
Functions
-
int
board_pin_string_to_device_index
(const char *str_p)¶ Convert given pin string to the pin number.
- Return
- Pin number of negative error code.
- Parameters
str_p
: Pin as a string.
arduino_nano
— Arduino Nano¶
Source code: src/boards/arduino_nano/board.h, src/boards/arduino_nano/board.c
Hardware reference: Arduino Nano
Defines
-
pin_d2_dev
¶
-
pin_d3_dev
¶
-
pin_d4_dev
¶
-
pin_d5_dev
¶
-
pin_d6_dev
¶
-
pin_d7_dev
¶
-
pin_d8_dev
¶
-
pin_d9_dev
¶
-
pin_d10_dev
¶
-
pin_d11_dev
¶
-
pin_d12_dev
¶
-
pin_d13_dev
¶
-
pin_a0_dev
¶
-
pin_a1_dev
¶
-
pin_a2_dev
¶
-
pin_a3_dev
¶
-
pin_a4_dev
¶
-
pin_a5_dev
¶
-
pin_led_dev
¶
-
exti_d2_dev
¶
-
exti_d3_dev
¶
-
pwm_d3_dev
¶
-
pwm_d9_dev
¶
-
pwm_d10_dev
¶
-
pwm_d11_dev
¶
-
adc_0_dev
¶
-
i2c_0_dev
¶
Functions
-
int
board_pin_string_to_device_index
(const char *str_p)¶ Convert given pin string to the pin number.
- Return
- Pin number of negative error code.
- Parameters
str_p
: Pin as a string.
arduino_pro_micro
— Arduino Pro Micro¶
Source code: src/boards/arduino_pro_micro/board.h, src/boards/arduino_pro_micro/board.c
Hardware reference: Arduino Pro Micro
Defines
-
pin_d2_dev
¶
-
pin_d3_dev
¶
-
pin_d4_dev
¶
-
pin_d5_dev
¶
-
pin_d6_dev
¶
-
pin_d7_dev
¶
-
pin_d8_dev
¶
-
pin_d9_dev
¶
-
pin_d10_dev
¶
-
pin_d14_dev
¶
-
pin_d15_dev
¶
-
pin_d16_dev
¶
-
pin_a0_dev
¶
-
pin_a1_dev
¶
-
pin_a2_dev
¶
-
pin_a3_dev
¶
-
pin_led_dev
¶
-
exti_d2_dev
¶
-
exti_d3_dev
¶
-
pwm_d3_dev
¶
-
pwm_d9_dev
¶
-
pwm_d10_dev
¶
-
pwm_d11_dev
¶
-
adc_0_dev
¶
-
i2c_0_dev
¶
Functions
-
int
board_pin_string_to_device_index
(const char *str_p)¶ Convert given pin string to the pin number.
- Return
- Pin number of negative error code.
- Parameters
str_p
: Pin as a string.
arduino_uno
— Arduino Uno¶
Source code: src/boards/arduino_uno/board.h, src/boards/arduino_uno/board.c
Hardware reference: Arduino Uno
Defines
-
pin_d2_dev
¶
-
pin_d3_dev
¶
-
pin_d4_dev
¶
-
pin_d5_dev
¶
-
pin_d6_dev
¶
-
pin_d7_dev
¶
-
pin_d8_dev
¶
-
pin_d9_dev
¶
-
pin_d10_dev
¶
-
pin_d11_dev
¶
-
pin_d12_dev
¶
-
pin_d13_dev
¶
-
pin_a0_dev
¶
-
pin_a1_dev
¶
-
pin_a2_dev
¶
-
pin_a3_dev
¶
-
pin_a4_dev
¶
-
pin_a5_dev
¶
-
pin_led_dev
¶
-
exti_d2_dev
¶
-
exti_d3_dev
¶
-
pwm_d3_dev
¶
-
pwm_d9_dev
¶
-
pwm_d10_dev
¶
-
pwm_d11_dev
¶
-
adc_0_dev
¶
-
i2c_0_dev
¶
Functions
-
int
board_pin_string_to_device_index
(const char *str_p)¶ Convert given pin string to the pin number.
- Return
- Pin number of negative error code.
- Parameters
str_p
: Pin as a string.
cygwin
— Cygwin¶
Source code: src/boards/cygwin/board.h, src/boards/cygwin/board.c
Defines
-
PIN_DEVICE_BASE
¶
-
pin_d2_dev
¶
-
pin_d3_dev
¶
-
pin_d4_dev
¶
-
pin_d5_dev
¶
-
pin_d6_dev
¶
-
pin_d7_dev
¶
-
pin_d8_dev
¶
-
pin_d9_dev
¶
-
pin_d10_dev
¶
-
pin_d11_dev
¶
-
pin_d12_dev
¶
-
pin_d13_dev
¶
-
pin_a0_dev
¶
-
pin_a1_dev
¶
-
pin_a2_dev
¶
-
pin_a3_dev
¶
-
pin_a4_dev
¶
-
pin_a5_dev
¶
-
pin_a6_dev
¶
-
pin_a7_dev
¶
-
pin_led_dev
¶
-
pwm_d3_dev
¶
-
pwm_d9_dev
¶
-
pwm_d10_dev
¶
-
pwm_d11_dev
¶
-
adc_0_dev
¶
Functions
-
int
board_pin_string_to_device_index
(const char *str_p)¶ Convert given pin string to the pin number.
- Return
- Pin number of negative error code.
- Parameters
str_p
: Pin as a string.
esp01
— ESP8266 Development Board¶
Source code: src/boards/esp01/board.h, src/boards/esp01/board.c
Hardware reference: ESP-01
Defines
-
pin_gpio0_dev
¶
-
pin_gpio1_dev
¶
-
pin_gpio2_dev
¶
-
pin_d0_dev
¶
-
pin_d1_dev
¶
-
pin_d2_dev
¶
-
pin_led_dev
¶
-
flash_0_dev
¶
Functions
-
int
board_pin_string_to_device_index
(const char *str_p)¶ Convert given pin string to the pin number.
- Return
- Pin number of negative error code.
- Parameters
str_p
: Pin as a string.
esp12e
— ESP8266 Development Board¶
Source code: src/boards/esp12e/board.h, src/boards/esp12e/board.c
Hardware reference: ESP-12E Development Board
Defines
-
pin_gpio0_dev
¶
-
pin_gpio2_dev
¶
-
pin_gpio4_dev
¶
-
pin_gpio5_dev
¶
-
pin_gpio12_dev
¶
-
pin_gpio13_dev
¶
-
pin_gpio14_dev
¶
-
pin_gpio15_dev
¶
-
pin_gpio16_dev
¶
-
pin_d0_dev
¶
-
pin_d2_dev
¶
-
pin_d4_dev
¶
-
pin_d5_dev
¶
-
pin_d12_dev
¶
-
pin_d13_dev
¶
-
pin_d14_dev
¶
-
pin_d15_dev
¶
-
pin_d16_dev
¶
-
pin_led_dev
¶
-
pin_a0_dev
¶
-
adc_0_dev
¶
-
flash_0_dev
¶
Functions
-
int
board_pin_string_to_device_index
(const char *str_p)¶ Convert given pin string to the pin number.
- Return
- Pin number of negative error code.
- Parameters
str_p
: Pin as a string.
linux
— Linux¶
Source code: src/boards/linux/board.h, src/boards/linux/board.c
Defines
-
PIN_DEVICE_BASE
¶
-
pin_d2_dev
¶
-
pin_d3_dev
¶
-
pin_d4_dev
¶
-
pin_d5_dev
¶
-
pin_d6_dev
¶
-
pin_d7_dev
¶
-
pin_d8_dev
¶
-
pin_d9_dev
¶
-
pin_d10_dev
¶
-
pin_d11_dev
¶
-
pin_d12_dev
¶
-
pin_d13_dev
¶
-
pin_a0_dev
¶
-
pin_a1_dev
¶
-
pin_a2_dev
¶
-
pin_a3_dev
¶
-
pin_a4_dev
¶
-
pin_a5_dev
¶
-
pin_a6_dev
¶
-
pin_a7_dev
¶
-
pin_led_dev
¶
-
pwm_d3_dev
¶
-
pwm_d9_dev
¶
-
pwm_d10_dev
¶
-
pwm_d11_dev
¶
-
adc_0_dev
¶
-
pin_dac0_dev
¶
-
pin_dac1_dev
¶
Functions
-
int
board_pin_string_to_device_index
(const char *str_p)¶ Convert given pin string to the pin number.
- Return
- Pin number of negative error code.
- Parameters
str_p
: Pin as a string.
nano32
— Nano32¶
Source code: src/boards/nano32/board.h, src/boards/nano32/board.c
Hardware reference: Nano32
Defines
-
pin_gpio00_dev
¶
-
pin_gpio01_dev
¶
-
pin_gpio02_dev
¶
-
pin_gpio03_dev
¶
-
pin_gpio04_dev
¶
-
pin_gpio05_dev
¶
-
pin_gpio06_dev
¶
-
pin_gpio07_dev
¶
-
pin_gpio08_dev
¶
-
pin_gpio09_dev
¶
-
pin_gpio10_dev
¶
-
pin_gpio11_dev
¶
-
pin_gpio12_dev
¶
-
pin_gpio13_dev
¶
-
pin_gpio14_dev
¶
-
pin_gpio15_dev
¶
-
pin_gpio16_dev
¶
-
pin_gpio17_dev
¶
-
pin_gpio18_dev
¶
-
pin_gpio19_dev
¶
-
pin_gpio21_dev
¶
-
pin_gpio22_dev
¶
-
pin_gpio23_dev
¶
-
pin_gpio25_dev
¶
-
pin_gpio26_dev
¶
-
pin_gpio27_dev
¶
-
pin_gpio32_dev
¶
-
pin_gpio33_dev
¶
-
pin_gpio34_dev
¶
-
pin_gpio35_dev
¶
-
pin_gpio36_dev
¶
-
pin_gpio39_dev
¶
-
pin_led_dev
¶
-
pin_adc0_dev
¶
-
pin_adc3_dev
¶
-
pin_adc4_dev
¶
-
pin_adc5_dev
¶
-
pin_adc6_dev
¶
-
pin_adc7_dev
¶
-
pin_adc10_dev
¶
-
pin_adc11_dev
¶
-
pin_adc12_dev
¶
-
pin_adc13_dev
¶
-
pin_adc14_dev
¶
-
pin_adc15_dev
¶
-
pin_adc16_dev
¶
-
pin_adc17_dev
¶
-
pin_adc18_dev
¶
-
pin_adc19_dev
¶
-
pin_dac1_dev
¶
-
pin_dac2_dev
¶
-
i2c_dev
¶
-
spi_h_dev
¶
-
spi_v_dev
¶
-
adc_1_dev
¶
-
adc_2_dev
¶
-
flash_0_dev
¶
Functions
-
int
board_pin_string_to_device_index
(const char *str_p)¶ Convert given pin string to the pin number.
- Return
- Pin number of negative error code.
- Parameters
str_p
: Pin as a string.
photon
— Photon¶
Source code: src/boards/photon/board.h, src/boards/photon/board.c
Hardware reference: Photon
Defines
-
pin_d0_dev
¶
-
pin_d1_dev
¶
-
pin_d2_dev
¶
-
pin_d3_dev
¶
-
pin_d4_dev
¶
-
pin_d5_dev
¶
-
pin_d6_dev
¶
-
pin_d7_dev
¶
-
pin_a0_dev
¶
-
pin_a1_dev
¶
-
pin_a2_dev
¶
-
pin_a3_dev
¶
-
pin_a4_dev
¶
-
pin_a5_dev
¶
-
pin_led_dev
¶
-
pin_dac0_dev
¶
-
pin_dac1_dev
¶
-
pwm_d0_dev
¶
-
pwm_d1_dev
¶
-
pwm_d2_dev
¶
-
pwm_d3_dev
¶
-
pwm_a4_dev
¶
-
pwm_a5_dev
¶
-
flash_0_dev
¶
-
sdio_0_dev
¶
Functions
-
int
board_pin_string_to_device_index
(const char *str_p)¶ Convert given pin string to the pin number.
- Return
- Pin number of negative error code.
- Parameters
str_p
: Pin as a string.
stm32f3discovery
— STM32F3DISCOVERY¶
Source code: src/boards/stm32f3discovery/board.h, src/boards/stm32f3discovery/board.c
Hardware reference: STM32F3DISCOVERY
Defines
-
pin_pa0_dev
¶
-
pin_pa1_dev
¶
-
pin_pa2_dev
¶
-
pin_pa3_dev
¶
-
pin_pa4_dev
¶
-
pin_pa5_dev
¶
-
pin_pa6_dev
¶
-
pin_pa7_dev
¶
-
pin_pa8_dev
¶
-
pin_pa9_dev
¶
-
pin_pa10_dev
¶
-
pin_pa11_dev
¶
-
pin_pa12_dev
¶
-
pin_pa13_dev
¶
-
pin_pa14_dev
¶
-
pin_pa15_dev
¶
-
pin_pb0_dev
¶
-
pin_pb1_dev
¶
-
pin_pb2_dev
¶
-
pin_pb3_dev
¶
-
pin_pb4_dev
¶
-
pin_pb5_dev
¶
-
pin_pb6_dev
¶
-
pin_pb7_dev
¶
-
pin_pb8_dev
¶
-
pin_pb9_dev
¶
-
pin_pb10_dev
¶
-
pin_pb11_dev
¶
-
pin_pb12_dev
¶
-
pin_pb13_dev
¶
-
pin_pb14_dev
¶
-
pin_pb15_dev
¶
-
pin_pc0_dev
¶
-
pin_pc1_dev
¶
-
pin_pc2_dev
¶
-
pin_pc3_dev
¶
-
pin_pc4_dev
¶
-
pin_pc5_dev
¶
-
pin_pc6_dev
¶
-
pin_pc7_dev
¶
-
pin_pc8_dev
¶
-
pin_pc9_dev
¶
-
pin_pc10_dev
¶
-
pin_pc11_dev
¶
-
pin_pc12_dev
¶
-
pin_pc13_dev
¶
-
pin_pc14_dev
¶
-
pin_pc15_dev
¶
-
pin_pd0_dev
¶
-
pin_pd1_dev
¶
-
pin_pd2_dev
¶
-
pin_pd3_dev
¶
-
pin_pd4_dev
¶
-
pin_pd5_dev
¶
-
pin_pd6_dev
¶
-
pin_pd7_dev
¶
-
pin_pd8_dev
¶
-
pin_pd9_dev
¶
-
pin_pd10_dev
¶
-
pin_pd11_dev
¶
-
pin_pd12_dev
¶
-
pin_pd13_dev
¶
-
pin_pd14_dev
¶
-
pin_pd15_dev
¶
-
pin_pe0_dev
¶
-
pin_pe1_dev
¶
-
pin_pe2_dev
¶
-
pin_pe3_dev
¶
-
pin_pe4_dev
¶
-
pin_pe5_dev
¶
-
pin_pe6_dev
¶
-
pin_pe7_dev
¶
-
pin_pe8_dev
¶
-
pin_pe9_dev
¶
-
pin_pe10_dev
¶
-
pin_pe11_dev
¶
-
pin_pe12_dev
¶
-
pin_pe13_dev
¶
-
pin_pe14_dev
¶
-
pin_pe15_dev
¶
-
uart_0_dev
¶
-
uart_1_dev
¶
-
uart_2_dev
¶
-
spi_0_dev
¶
-
spi_1_dev
¶
-
spi_2_dev
¶
-
i2c_0_dev
¶
-
i2c_1_dev
¶
-
can_0_dev
¶
-
flash_0_dev
¶
Functions
-
int
board_pin_string_to_device_index
(const char *str_p)¶ Convert given pin string to the pin number.
- Return
- Pin number of negative error code.
- Parameters
str_p
: Pin as a string.
stm32vldiscovery
— STM32VLDISCOVERY¶
Source code: src/boards/stm32vldiscovery/board.h, src/boards/stm32vldiscovery/board.c
Hardware reference: STM32VLDISCOVERY
Defines
-
pin_pa0_dev
¶
-
pin_pa1_dev
¶
-
pin_pa2_dev
¶
-
pin_pa3_dev
¶
-
pin_pa4_dev
¶
-
pin_pa5_dev
¶
-
pin_pa6_dev
¶
-
pin_pa7_dev
¶
-
pin_pa8_dev
¶
-
pin_pa9_dev
¶
-
pin_pa10_dev
¶
-
pin_pa11_dev
¶
-
pin_pa12_dev
¶
-
pin_pa13_dev
¶
-
pin_pa14_dev
¶
-
pin_pa15_dev
¶
-
pin_pb0_dev
¶
-
pin_pb1_dev
¶
-
pin_pb2_dev
¶
-
pin_pb3_dev
¶
-
pin_pb4_dev
¶
-
pin_pb5_dev
¶
-
pin_pb6_dev
¶
-
pin_pb7_dev
¶
-
pin_pb8_dev
¶
-
pin_pb9_dev
¶
-
pin_pb10_dev
¶
-
pin_pb11_dev
¶
-
pin_pb12_dev
¶
-
pin_pb13_dev
¶
-
pin_pb14_dev
¶
-
pin_pb15_dev
¶
-
pin_pc0_dev
¶
-
pin_pc1_dev
¶
-
pin_pc2_dev
¶
-
pin_pc3_dev
¶
-
pin_pc4_dev
¶
-
pin_pc5_dev
¶
-
pin_pc6_dev
¶
-
pin_pc7_dev
¶
-
pin_pc8_dev
¶
-
pin_pc9_dev
¶
-
pin_pc10_dev
¶
-
pin_pc11_dev
¶
-
pin_pc12_dev
¶
-
pin_pc13_dev
¶
-
pin_pc14_dev
¶
-
pin_pc15_dev
¶
-
pin_pd0_dev
¶
-
pin_pd1_dev
¶
-
pin_pd2_dev
¶
-
pin_led_dev
¶
-
pin_ld3_dev
¶
-
pin_ld4_dev
¶
-
uart_0_dev
¶
-
uart_1_dev
¶
-
uart_2_dev
¶
-
spi_0_dev
¶
-
spi_1_dev
¶
-
spi_2_dev
¶
-
i2c_0_dev
¶
-
i2c_1_dev
¶
-
flash_0_dev
¶
Functions
-
int
board_pin_string_to_device_index
(const char *str_p)¶ Convert given pin string to the pin number.
- Return
- Pin number of negative error code.
- Parameters
str_p
: Pin as a string.
mcus¶
The Micro Controller Units (MCU:s) supported by Simba.
The MCU:s on Github.
atmega32u4
— ATMega32u4¶
Source code: src/mcus/atmega32u4/mcu.h
Defines
-
PIN_DEVICE_MAX
¶
-
EXTI_DEVICE_MAX
¶
-
SPI_DEVICE_MAX
¶
-
UART_DEVICE_MAX
¶
-
PWM_DEVICE_MAX
¶
-
ADC_DEVICE_MAX
¶
-
I2C_DEVICE_MAX
¶
-
USB_DEVICE_MAX
¶
-
USART0_TX_vect
¶
-
USART0_RX_vect
¶
-
USART0_UDRE_vect
¶
-
UCSZ00
¶
-
UCSZ01
¶
-
UCSZ02
¶
-
UPM00
¶
-
UPM01
¶
-
USBS0
¶
-
U2X0
¶
-
UPE0
¶
-
DOR0
¶
-
FE0
¶
-
TXC0
¶
-
RXCIE0
¶
-
RXEN0
¶
-
TXEN0
¶
-
UDRE0
¶
-
UDRIE0
¶
-
TXCIE0
¶
esp32
— Esp32¶
Hardware reference: https://github.com/eerimoq/hardware-reference/tree/master/esp32
Source code: src/mcus/esp32/mcu.h
esp8266
— Esp8266¶
Hardware reference: https://github.com/eerimoq/hardware-reference/tree/master/esp8266
Source code: src/mcus/esp8266/mcu.h
License¶
The MIT License (MIT)
Copyright (c) 2014-2016, Erik Moqvist
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Videos¶
#6 Simba: CAN client-server test suite on Nano32 (ESP32) and Arduino Due.¶
Transmit CAN frames between a Nano32 and an Arduino Due.
#5 Simba: Room temperature (DS18B20).¶
Read and print the room temperature measured with a DS18B20 sensor.
#4 Simba: Hello world.¶
This application prints “Hello world!” to standard output.
#3 Simba: Analog read.¶
Read the value of an analog pin periodically once every second and print the read value to standard output.
#2 Simba: Blink example.¶
This video demonstrates the classic blink application. It’s run on a Arduino Due that has a SAM2X8E ARM MCU.
#1 Simba: Gource of the Simba repository.¶
Gource visualizes the Simba Git repository file tree over time. In this project the source, test and documentation was written simultaneously, a perfect school book example of software development.
Links¶
This page contains links to external websites that are related to Simba.
Feel free to add your project to the list by submitting a pull request of this page on Github.
Pumbaa - MicroPython on Simba¶
Python on microcontrollers thanks to MicroPython (and in this case Simba).
Documentation: http://pumbaa.readthedocs.io
Github: https://github.com/eerimoq/pumbaa
MicroPython: http://www.micropython.org
Features¶
- Threads scheduled by a priority based cooperative or preemptive scheduler.
- Channels for inter-thread communication (Queue, Event).
- Timers.
- Counting semaphores.
- Device drivers (SPI, UART, ...)
- A simple shell.
- Logging.
- Internet protocols (TCP, UDP, HTTP, ...).
- Debug file system.
- File systems (FAT16, SPIFFS).
See the Library Reference for a full list of features.
Testing¶
To ensure high code quility each module is tested extensively by many test suites. See Testing for details.
Design goals¶
- Rapid development.
- Clean interfaces.
- Small memory footprint.
- No dynamic memory allocation.
- Portability.