docs: fix some poor spelling & phrasing in docs
Signed-off-by: Brendan Le Foll <brendan.le.foll@intel.com>
This commit is contained in:
Brendan Le Foll
@@ -3,16 +3,16 @@ Building libmraa {#building}
|
||||
|
||||
libmraa uses cmake in order to make compilation relatively painless. Cmake runs
|
||||
build out of tree so the recommended way is to clone from git and make a build/
|
||||
directory.
|
||||
directory inside the clone directory.
|
||||
|
||||
## Build dependencies
|
||||
Not all these are required but if you're unsure of what you're doing this is
|
||||
what you'll need:
|
||||
* swig 3.0.4+
|
||||
* git
|
||||
* python 2.7 or 3.4+ (you'll need not just the interpreter but python-dev)
|
||||
* nodejs 0.10.x (you'll need not just the interneter but nodejs-dev)
|
||||
* cmake 2.8.8+
|
||||
* [SWIG](http://swig.org) 3.0.5+
|
||||
* [git](http://git-scm.com)
|
||||
* [python](http://python.org) 2.7 or 3.4+ (you'll need not just the interpreter but python-dev)
|
||||
* [node.js](http://nodejs.org) 0.10.x (you'll need not just the interpreter but nodejs-dev)
|
||||
* [CMake](http://cmake.org) 2.8.8+
|
||||
|
||||
## Basic build steps
|
||||
|
||||
@@ -31,46 +31,49 @@ got.
|
||||
|
||||
Our cmake configure has a number of options, cmake-gui or ccmake (cmake -i is
|
||||
no longer with us :() can show you all the options. A few of the more common
|
||||
ones are listed below - note that when the option starts with CMAKE_ it's an
|
||||
ones are listed below. Note that when the option starts with CMAKE_ it's an
|
||||
option that is made available by cmake and will be similar in all cmake
|
||||
projects. You need to add them after `cmake` but before `..`.
|
||||
|
||||
A few recommended options:
|
||||
Changing install path from /usr/local to /usr
|
||||
Changing install path from /usr/local to /usr:
|
||||
-DCMAKE_INSTALL_PREFIX:PATH=/usr
|
||||
|
||||
Building debug build - adds -g and disables optimisations - this will force a full rebuild:
|
||||
Building debug build - adds -g and disables optimisations - this will force a
|
||||
full rebuild:
|
||||
-DCMAKE_BUILD_TYPE=DEBUG
|
||||
|
||||
Using clang instead of gcc:
|
||||
-DCMAKE_C_COMPILER=/usr/bin/clang -DCMAKE_CXX_COMPILER=/usr/bin/clang++
|
||||
|
||||
Building with an older version of swig (swig < 3.0.2) requires the disabling of javascript:
|
||||
Building with an older version of SWIG (< 3.0.2) requires the disabling of javascript:
|
||||
-DBUILDSWIGNODE=OFF
|
||||
|
||||
Disabling python module building
|
||||
Disabling python module building:
|
||||
-DBUILDSWIGPYTHON=OFF
|
||||
|
||||
Building doc, this will require sphinx & doxygen
|
||||
Building doc, this will require [SPHINX](http://sphinx-doc.org) &
|
||||
[Doxygen](http://doxygen.org):
|
||||
-BUILDDOC=ON
|
||||
|
||||
## Dependancies continued
|
||||
## Dependencies continued
|
||||
|
||||
You'll need at least swig version 3.0.2 and we recommend 3.0.4 to build the
|
||||
You'll need at least SWIG version 3.0.2 and we recommend 3.0.5 to build the
|
||||
javascript & python modules. If your version of SWIG is older than this then
|
||||
please see below for disabling SWIGNODE otherwise you will get a weird build
|
||||
failure when building the js module. The python module builds with swig 2.x.
|
||||
please see above for disabling SWIGNODE. Otherwise you will get a weird build
|
||||
failure when building the javascript module. The python module builds with SWIG
|
||||
2.x.
|
||||
|
||||
The basic build steps are as follow, we'll assume you're building from git,
|
||||
note that if you compile with git installed your version of mraa will be tagged
|
||||
-dirty. This simply means git wasn't installed or that you where building form
|
||||
a tarball. You can modify build/src/version.c before running make if this is
|
||||
incorrect. The instructions listed here all assume that build/ is an empty dir
|
||||
that lives inside the cloned repository of mraa.
|
||||
During the build, we'll assume you're building from git, note that if you
|
||||
compile with git installed your version of mraa will be tagged -dirty. This
|
||||
simply means git wasn't installed or that you where building form a tarball.
|
||||
You can modify build/src/version.c before running make if this is incorrect.
|
||||
The instructions listed here all assume that build/ is an empty dir that lives
|
||||
inside the cloned repository of mraa.
|
||||
|
||||
If you have multiple versions of python then mraa can get confused, we
|
||||
recommend using virtualenv to select which version of python you want. We test
|
||||
2.7 the most but swig will generate valid 3.x python code but we do not
|
||||
2.7 the most but SWIG will generate valid 3.x python code but we do not
|
||||
generally support building both at once.
|
||||
|
||||
## Using a yocto/oe toolchain
|
||||
|
||||
@@ -1,30 +1,31 @@
|
||||
Debugging libmraa {#debugging}
|
||||
=================
|
||||
|
||||
This page contains a few debugging tip, when filing an issue please go through
|
||||
this list as if you don't it's the first thing we'll have to ask you to do.
|
||||
This page contains a few debugging tip. When filing an issue please go through
|
||||
this list as it's the first thing we'll ask you to do.
|
||||
|
||||
### Version
|
||||
### Finding your mraa version
|
||||
|
||||
Getting the exact version of libmraa you're running is really important to us.
|
||||
The best way to get this is to call mraa_get_version() or mraa.getVersion(). If
|
||||
mraa returns x.x.x-dirty then your version was not built from a git tree or you
|
||||
built out of tree (see our building doc) - or you don't have git installed.
|
||||
|
||||
### Syslog
|
||||
### Finding error logs
|
||||
|
||||
mraa logs pretty much everything that goes wrong to syslog, these days it'll go
|
||||
to the systemd journal usually so check with `sudo journalctl -f` whilst
|
||||
running your app or check all libmraa messages with `journalctl -t libmraa`.
|
||||
Grab all the messages from the initialisation message right up to your last
|
||||
one, using a pastebin is always a good idea, I like dpaste.com. If your system
|
||||
does not have systemd likely your log is in /var/log/messages or similar.
|
||||
mraa logs pretty much everything that goes wrong to syslog. These days it'll go
|
||||
to the systemd journal so check with `sudo journalctl -f` whilst running your
|
||||
app or check all libmraa messages with `journalctl -t libmraa`. Grab all the
|
||||
messages from the initialisation message right up to your last one. Using a
|
||||
pastebin is always a good idea, I like dpaste.com. If your system does not have
|
||||
systemd likely your log is in /var/log/messages or a similar location.
|
||||
|
||||
### Common Errors
|
||||
### Common errors to check for
|
||||
|
||||
* Not running as root
|
||||
* Incorrect IO numbers, mraa uses physical connector pin numbering see your
|
||||
platform doc for details
|
||||
* Unsuported platform
|
||||
* Using the wrong pin, check pin capabilities
|
||||
* Incorrect IO pin numbers, mraa uses physical connector pin numbering see your
|
||||
platform documentation for details
|
||||
* Your platform is unsupported
|
||||
* Using the wrong pin, check pin capabilities either using the API or your
|
||||
platform documentation
|
||||
|
||||
|
||||
@@ -14,13 +14,10 @@ confuse some, it's typically not an issue as platforms rarely expose more than
|
||||
one of these for user use and so when this is the case, libmraa will always use
|
||||
the bus in the pinmapper. For example edison uses i2c #6 but since there is
|
||||
only one, libmraa will try to be helpful and everything is treated as 6 when
|
||||
doing a mraa_i2c_init and so when this is the case, libmraa will always use the
|
||||
bus in the pinmapper. For example edison uses i2c #6 but since there is only
|
||||
one, libmraa will try to be helpful and everything is treated as 6 when doing a
|
||||
mraa_i2c_init(). The _raw functions will override the pinmapper and can be
|
||||
accessed without a valid board configuration. This can be helpful either in
|
||||
doing a mraa_i2c_init(). The _raw functions will override the pinmapper and can
|
||||
be accessed without a valid board configuration. This can be helpful either in
|
||||
development of platform configurations for mraa or when modifying kernels
|
||||
etc... The mechanism is used heavily internaly.
|
||||
etc... Internally the mechanism is used heavily.
|
||||
|
||||
In libmraa, all code is split into 7 modules, src/{i2c, spi, gpio, uart, pwm,
|
||||
aio and common}. These should be fairly self explanatory in goals/purpose but a
|
||||
@@ -52,10 +49,10 @@ also where platform hooks can be defined, functions that will be run at various
|
||||
|
||||
The mraa_pininfo_t structure needs to be set for the board pincount (set in a
|
||||
macro in the platform configuration header. Every pin will have a
|
||||
mraa_pincapabilities_t which will define what it can do. The doxygen doc
|
||||
explains how this works but it's essentially a bitfield which needs to be set
|
||||
for every capability the pin can have. Gpios can have multiple muxes which will
|
||||
be set at the gpio init before it can be toggled.
|
||||
mraa_pincapabilities_t which will define what it can do. The doxygen
|
||||
documentation explains how this works but it's essentially a bitfield which
|
||||
needs to be set for every capability the pin can have. Gpios can have multiple
|
||||
muxes which will be set at the gpio init before it can be toggled.
|
||||
|
||||
### i2c ###
|
||||
|
||||
@@ -68,8 +65,9 @@ i2c/smbus.c. This library simply makes it easier for us to handle the error
|
||||
conditions that can arrise when writing on i2c buses. Essentially the API is
|
||||
fairly simple consisting of writes & reads.
|
||||
|
||||
Careful - on alot of platforms i2cdetect will often crash, for finding your i2c
|
||||
addresses please look at your sensors datasheet!
|
||||
Careful - on alot of platforms i2cdetect will often crash. To findi your i2c
|
||||
addresses please look at your sensor's datasheet! If using i2cdetect most
|
||||
platforms do not support SMBus quick write so use the '-r' flag.
|
||||
|
||||
### spi ###
|
||||
|
||||
@@ -78,9 +76,9 @@ chip select from spidev. Spi(0) could lead to spidev5.1 and Spi(1) to
|
||||
spidev5.2. Typically on a micro using a random gpio as a chip select works
|
||||
well, and on some platforms if one is careful with threads this can work well
|
||||
with mraa. However when a kernel module shares the same bus as spidev (but on a
|
||||
different CS) this behaviour is *very* dangerous. Platforms such as galileo
|
||||
gen2 & edison + arduino breakout work this way. Mraa will not help you in using
|
||||
a non HW chip select, do so at your own peril!
|
||||
different CS) this behaviour is *very* dangerous. Platforms such as Galileo
|
||||
Gen2 & Edison + Arduino breakout board work this way. Mraa will not help you in
|
||||
using a non hardware chip select, do so at your own peril!
|
||||
|
||||
### gpio ###
|
||||
|
||||
@@ -100,9 +98,8 @@ definition.
|
||||
GPIOs are typically interfaced via sysfs because that's easier for us but we
|
||||
can also work with fast gpio. This is typically preffered to do mmap gpio
|
||||
access. This is however trickier and typically relies on lots of platform
|
||||
hooks. We do support by default to go hit /dev/mem or another device at
|
||||
specific addresses to toggle gpios which is how mmap access works on some
|
||||
boards.
|
||||
hooks. By default we support hitting /dev/mem or another device at specific
|
||||
addresses to toggle gpios which is how mmap access works on some boards.
|
||||
|
||||
Note that in Linux gpios are numbered from ARCH_NR_GPIOS down. This means that
|
||||
if ARCH_NR_GPIOS is changed, the gpio numbering will change. In 3.18+ the
|
||||
@@ -119,16 +116,16 @@ set the pinmapper correctly for uart to work on some platforms.
|
||||
|
||||
### aio ###
|
||||
|
||||
AIO pins are numbered after GPIO pins. This means that on arduino style boards
|
||||
AIO pins are numbered after GPIO pins. This means that on Arduino style boards
|
||||
pin 14 is A0. Typically mraa will only support an ADC if a platform ships with
|
||||
one and has a good kernel module for it. extra i2c/spi ADCs can be supported
|
||||
one and has a good kernel module for it. Extra i2c/spi ADCs can be supported
|
||||
via something like UPM but are unlikely to receive support in mraa at the moment.
|
||||
|
||||
Note that giving mraa_aio_init(0) will literally query the pinmapper for
|
||||
board->gpio_count + 0 so you must place your aio pins after gpio_count. This is
|
||||
the default behaviour but can of course be overriden by advance function
|
||||
pointers. Whilst maybe not the sanest of defaults, most of the hobbyist boards
|
||||
we deal with follow a similar naming pattern to arduino or have no ADC so for
|
||||
we deal with follow a naming pattern similar to Arduino or have no ADC so for
|
||||
now we have considered this sensible.
|
||||
|
||||
### Initialisation ###
|
||||
@@ -136,13 +133,13 @@ now we have considered this sensible.
|
||||
mraa_init() needs to be called in order to initialise the platform files or
|
||||
'pinmap'. Because calling this is tedious libmraa uses a C constructor to run
|
||||
mraa_init on library load. This means that it is not possible to stop this
|
||||
running and all functino calls like mraa_set_log_level() will not work during
|
||||
mraa_init(). This feature is supported by most sane compilers & libcs but you
|
||||
running and all function calls like mraa_set_log_level() will not work during
|
||||
mraa_init(). This feature is supported by most sane compilers and libcs but you
|
||||
can turn off CTORS in uclibc, though I've yet to find a configuration with
|
||||
someone doing that. mraa_init() can be called multiple times if you feel like
|
||||
being 'safe'.
|
||||
|
||||
In the SWIG modulse mraa_init() is called during the %init stage of the module
|
||||
In the SWIG modules mraa_init() is called during the %init stage of the module
|
||||
loading. This is simply to avoid mraa_init() running 'too' early, though I've
|
||||
never seen an issue in running it in a CTOR.
|
||||
|
||||
@@ -150,15 +147,15 @@ never seen an issue in running it in a CTOR.
|
||||
|
||||
At the time when libmraa was created (still the case?) the only - working -
|
||||
API/wrapper generation tool that supported nodejs was SWIG. For more general
|
||||
information on swig please see the swig documentation.
|
||||
information on SWIG please see the SWIG documentation.
|
||||
|
||||
The src/{javascript, python} & src/mraa.i folders contain all the files for the
|
||||
swig generation. The C++ headers in api/mraa/ are given as input sources to
|
||||
SWIG generation. The C++ headers in api/mraa/ are given as input sources to
|
||||
SWIG. SWIG modules do not link to libmraa (although maybe that would be a good
|
||||
idea...)
|
||||
|
||||
Typemaps are used heavily to map uint8_t* pointers to bytearrays and
|
||||
node_buffers. These are native python & nodejs types that represent uint8_t
|
||||
node_buffers. These are native python & node.js types that represent uint8_t
|
||||
data the best and are very well supported in both languages. Argument
|
||||
conversions and memory allocations are performed so the performance of using
|
||||
these functions compared to the C/C++ equivalent will likely be a little lower,
|
||||
@@ -172,7 +169,7 @@ array to generate a binding.gyp file from the skeleton binding.gyp.cmake in
|
||||
src/javascript. Because we don't expect most NPM users to have SWIG we
|
||||
precompile the src/mraajsJAVASCRIPT_wrap.cxx. The src/version.c is already
|
||||
known since this is a static tarball so we write that too. These files are
|
||||
placed not in a build/ dir but in the main mraa dir. You can then tar the dir
|
||||
up and send it to NPM. This is done automatically on every commit by our
|
||||
automated build system.
|
||||
placed not in a build/ directory but in the main mraa directory. You can then
|
||||
tar the directory up and send it to NPM. This is done automatically on every
|
||||
commit by our automated build system.
|
||||
|
||||
|
||||
10
docs/npm.md
10
docs/npm.md
@@ -15,11 +15,11 @@ we have generated for you.
|
||||
Recreating tarball
|
||||
------------------
|
||||
|
||||
From a checkout of mraa you can do the following to 'generate' this tarball.
|
||||
It's important to not leave a .git directory as npm will then consider the
|
||||
tarball contains a full git tree. Also you need a top level dir which matches
|
||||
the npm pkg name so we create one with a symlink and add the 'h' flag to tar to
|
||||
follow simlinks.
|
||||
You can run the following commands to 'generate' this tarball from a checkout
|
||||
of mraa. It's important to not leave a .git directory as npm will then
|
||||
consider the tarball contains a full git tree. You also you need a top level
|
||||
dir which matches the npm pkg name so we create one with a symlink and add the
|
||||
'h' flag to tar to follow symlinks.
|
||||
|
||||
~~~~~~~~~~~~~{.sh}
|
||||
mkdir build
|
||||
|
||||
Reference in New Issue
Block a user