Skip to content
This repository was archived by the owner on Jul 20, 2025. It is now read-only.

Commit 07d2977

Browse files
lkassolkasso
committed
update for docs
1 parent 996016a commit 07d2977

35 files changed

+3130
-0
lines changed

‎docs/.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
/build/
2+
/html/
3+
upload.sh

‎docs/Makefile‎

Lines changed: 223 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,223 @@
1+
# Makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line.
5+
SPHINXOPTS =
6+
SPHINXBUILD = sphinx-build
7+
PAPER =
8+
BUILDDIR = build
9+
10+
# User-friendly check for sphinx-build
11+
ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
12+
$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don\'t have Sphinx installed, grab it from http://sphinx-doc.org/)
13+
endif
14+
15+
# Internal variables.
16+
PAPEROPT_a4 = -D latex_paper_size=a4
17+
PAPEROPT_letter = -D latex_paper_size=letter
18+
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
19+
# the i18n builder cannot share the environment and doctrees with the others
20+
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
21+
22+
.PHONY: help
23+
help:
24+
@echo "Please use \`make <target>' where <target> is one of"
25+
@echo " html to make standalone HTML files"
26+
@echo " dirhtml to make HTML files named index.html in directories"
27+
@echo " singlehtml to make a single large HTML file"
28+
@echo " pickle to make pickle files"
29+
@echo " json to make JSON files"
30+
@echo " htmlhelp to make HTML files and a HTML help project"
31+
@echo " qthelp to make HTML files and a qthelp project"
32+
@echo " applehelp to make an Apple Help Book"
33+
@echo " devhelp to make HTML files and a Devhelp project"
34+
@echo " epub to make an epub"
35+
@echo " epub3 to make an epub3"
36+
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
37+
@echo " latexpdf to make LaTeX files and run them through pdflatex"
38+
@echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
39+
@echo " text to make text files"
40+
@echo " man to make manual pages"
41+
@echo " texinfo to make Texinfo files"
42+
@echo " info to make Texinfo files and run them through makeinfo"
43+
@echo " gettext to make PO message catalogs"
44+
@echo " changes to make an overview of all changed/added/deprecated items"
45+
@echo " xml to make Docutils-native XML files"
46+
@echo " pseudoxml to make pseudoxml-XML files for display purposes"
47+
@echo " linkcheck to check all external links for integrity"
48+
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
49+
@echo " coverage to run coverage check of the documentation (if enabled)"
50+
51+
.PHONY: clean
52+
clean:
53+
rm -rf $(BUILDDIR)/*
54+
55+
.PHONY: html
56+
html:
57+
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
58+
@echo
59+
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
60+
61+
.PHONY: dirhtml
62+
dirhtml:
63+
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
64+
@echo
65+
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
66+
67+
.PHONY: singlehtml
68+
singlehtml:
69+
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
70+
@echo
71+
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
72+
73+
.PHONY: pickle
74+
pickle:
75+
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
76+
@echo
77+
@echo "Build finished; now you can process the pickle files."
78+
79+
.PHONY: json
80+
json:
81+
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
82+
@echo
83+
@echo "Build finished; now you can process the JSON files."
84+
85+
.PHONY: htmlhelp
86+
htmlhelp:
87+
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
88+
@echo
89+
@echo "Build finished; now you can run HTML Help Workshop with the" \
90+
".hhp project file in $(BUILDDIR)/htmlhelp."
91+
92+
.PHONY: qthelp
93+
qthelp:
94+
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
95+
@echo
96+
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
97+
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
98+
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/MetaWeariOSAPI.qhcp"
99+
@echo "To view the help file:"
100+
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/MetaWeariOSAPI.qhc"
101+
102+
.PHONY: applehelp
103+
applehelp:
104+
$(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
105+
@echo
106+
@echo "Build finished. The help book is in $(BUILDDIR)/applehelp."
107+
@echo "N.B. You won't be able to view it unless you put it in" \
108+
"~/Library/Documentation/Help or install it in your application" \
109+
"bundle."
110+
111+
.PHONY: devhelp
112+
devhelp:
113+
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
114+
@echo
115+
@echo "Build finished."
116+
@echo "To view the help file:"
117+
@echo "# mkdir -p $$HOME/.local/share/devhelp/MetaWeariOSAPI"
118+
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/MetaWeariOSAPI"
119+
@echo "# devhelp"
120+
121+
.PHONY: epub
122+
epub:
123+
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
124+
@echo
125+
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
126+
127+
.PHONY: epub3
128+
epub3:
129+
$(SPHINXBUILD) -b epub3 $(ALLSPHINXOPTS) $(BUILDDIR)/epub3
130+
@echo
131+
@echo "Build finished. The epub3 file is in $(BUILDDIR)/epub3."
132+
133+
.PHONY: latex
134+
latex:
135+
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
136+
@echo
137+
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
138+
@echo "Run \`make' in that directory to run these through (pdf)latex" \
139+
"(use \`make latexpdf' here to do that automatically)."
140+
141+
.PHONY: latexpdf
142+
latexpdf:
143+
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
144+
@echo "Running LaTeX files through pdflatex..."
145+
$(MAKE) -C $(BUILDDIR)/latex all-pdf
146+
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
147+
148+
.PHONY: latexpdfja
149+
latexpdfja:
150+
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
151+
@echo "Running LaTeX files through platex and dvipdfmx..."
152+
$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
153+
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
154+
155+
.PHONY: text
156+
text:
157+
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
158+
@echo
159+
@echo "Build finished. The text files are in $(BUILDDIR)/text."
160+
161+
.PHONY: man
162+
man:
163+
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
164+
@echo
165+
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
166+
167+
.PHONY: texinfo
168+
texinfo:
169+
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
170+
@echo
171+
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
172+
@echo "Run \`make' in that directory to run these through makeinfo" \
173+
"(use \`make info' here to do that automatically)."
174+
175+
.PHONY: info
176+
info:
177+
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
178+
@echo "Running Texinfo files through makeinfo..."
179+
make -C $(BUILDDIR)/texinfo info
180+
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
181+
182+
.PHONY: gettext
183+
gettext:
184+
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
185+
@echo
186+
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
187+
188+
.PHONY: changes
189+
changes:
190+
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
191+
@echo
192+
@echo "The overview file is in $(BUILDDIR)/changes."
193+
194+
.PHONY: linkcheck
195+
linkcheck:
196+
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
197+
@echo
198+
@echo "Link check complete; look for any errors in the above output " \
199+
"or in $(BUILDDIR)/linkcheck/output.txt."
200+
201+
.PHONY: doctest
202+
doctest:
203+
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
204+
@echo "Testing of doctests in the sources finished, look at the " \
205+
"results in $(BUILDDIR)/doctest/output.txt."
206+
207+
.PHONY: coverage
208+
coverage:
209+
$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
210+
@echo "Testing of coverage in the sources finished, look at the " \
211+
"results in $(BUILDDIR)/coverage/python.txt."
212+
213+
.PHONY: xml
214+
xml:
215+
$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
216+
@echo
217+
@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
218+
219+
.PHONY: pseudoxml
220+
pseudoxml:
221+
$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
222+
@echo
223+
@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."

‎docs/source/_templates/layout.html‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
{% extends "!layout.html" %}
2+
3+
{%- block extrahead %}
4+
<!-- Google Analytics -->
5+
<script>
6+
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
7+
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
8+
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
9+
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
10+
ga('create', 'UA-40595645-1', 'auto');
11+
ga('send', 'pageview');
12+
</script>
13+
14+
<link rel="shortcut icon" href="../../images/favicon.ico">
15+
{% endblock %}

‎docs/source/accelerometer.rst‎

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
.. highlight:: python
2+
3+
Accelerometer
4+
=============
5+
All boards come with an accelerometer. An accelerometer is an electromechanical device that will measure acceleration forces.
6+
These forces may be static, like the constant force of gravity pulling at your feet, or they could be dynamic - caused by moving or vibrating the accelerometer.
7+
8+
Acceleration is measured in units of gravities (g) or units of m/s2. One g unit = 9.81 m/s2.
9+
10+
The specific accelerometer model varies amongst the boards, howevever the API provides accelerometer
11+
agnostic functions in the `accelerometer.h <https://mbientlab.com/docs/metawear/cpp/latest/accelerometer_8h.html>`_ header file that can be safely used
12+
with all supported accelerometers.
13+
14+
Users can check which accelerometer is on their board at runtime to determine the appropriate accelerometer specific functions they need to use, if
15+
necessary. ::
16+
17+
accType = libmetawear.mbl_mw_metawearboard_lookup_module(board, MBL_MW_MODULE_ACCELEROMETER)
18+
switch (accType) {
19+
MBL_MW_MODULE_ACC_TYPE_BMI160:
20+
break;
21+
MBL_MW_MODULE_ACC_TYPE_MMA8452Q:
22+
break;
23+
MBL_MW_MODULE_ACC_TYPE_BMA255:
24+
break;
25+
MBL_MW_MODULE_TYPE_NA:
26+
break;
27+
default:
28+
break;
29+
30+
Acceleration Sampling
31+
---------------------
32+
Acceleration sampling measures the current acceleration forces at periodic intervals. To enable acceleration sampling, call
33+
`mbl_mw_acc_enable_acceleration_sampling <https://mbientlab.com/docs/metawear/cpp/latest/accelerometer_8h.html#a58272eea512ca22d0de2ae0db0e9f867>`_
34+
before starting the accelerometer.
35+
36+
Linear acceleration is represented with the
37+
`MblMwCartesianFloat <https://mbientlab.com/docs/metawear/cpp/latest/structMblMwCartesianFloat.html>`_ struct and the values are in units of Gs. The
38+
``x``, ``y``, and ``z`` fields contain the acceleration in that direction. ::
39+
40+
accel_data_signal= libmetawear.mbl_mw_acc_bosch_get_acceleration_data_signal(board)
41+
42+
libmetawear.mbl_mw_datasignal_subscribe(accel_data_signal, None, sensor_data_handler)
43+
libmetawear.mbl_mw_acc_bosch_set_range(board, AccBoschRange._4G)
44+
45+
libmetawear.mbl_mw_acc_enable_acceleration_sampling(board)
46+
libmetawear.mbl_mw_acc_start(board)
47+
48+
Configuration
49+
^^^^^^^^^^^^^
50+
Users can configure the output data rate and the sampling range; these parameters control the sampling rate and the data range and resolution
51+
respectively. After configuring the settings, call
52+
`mbl_mw_acc_write_acceleration_config <https://mbientlab.com/docs/metawear/cpp/latest/accelerometer_8h.html#a7f3339b25871344518175f97ae7c95b7>`_ to
53+
write the configuration to the sensor. ::
54+
55+
# Set ODR to 25Hz or closest valid frequency
56+
libmetawear.mbl_mw_acc_set_odr(board, 25.0)
57+
58+
# Set range to +/-4g or closest valid range
59+
libmetawear.mbl_mw_acc_set_range(board, 4.0)
60+
61+
# Write the config to the sensor
62+
libmetawear.mbl_mw_acc_write_acceleration_config(board)
63+
64+
65+
High Frequency Stream
66+
^^^^^^^^^^^^^^^^^^^^^
67+
Firmware v1.2.3+ contains a packed mode for the accelerometer which combines 3 acceleration data samples into 1 ble packet allowing the board to
68+
stream data at a throughput higher than 100Hz. This special data signal is retrieved from the
69+
`mbl_mw_acc_get_high_freq_acceleration_data_signal <https://mbientlab.com/docs/metawear/cpp/latest/accelerometer_8h.html#a9203ed5a20d63f6c37ae173aabaaa287>`_ function
70+
and is only for streaming; do not use it with data processing or logging. ::
71+
72+
accel_data_signal= libmetawear.mbl_mw_acc_get_high_freq_acceleration_data_signal(board)
73+
74+
libmetawear.mbl_mw_datasignal_subscribe(accel_data_signal, None, sensor_data_handler)
75+
76+
libmetawear.mbl_mw_acc_set_odr(board, 200.0)
77+
libmetawear.mbl_mw_acc_write_acceleration_config(board)
78+
79+
libmetawear.mbl_mw_acc_enable_acceleration_sampling(board)
80+
libmetawear.mbl_mw_acc_start(board)
81+
82+
Step Counter
83+
------------
84+
The BMI160 accelerometer comes with a built in step counter. It has three operation modes that configure the sensitivity and robustness of the counter:
85+
86+
========= ==============================================================================================
87+
Mode Description
88+
========= ==============================================================================================
89+
Normal Balanced between false positives and false negatives, recommended for most applications
90+
Sensitive Few false negatives but eventually more false positives, recommended for light weighted people
91+
Robust Few false positives but eventually more false negatives
92+
========= ==============================================================================================
93+
94+
When you have set the operation mode, call
95+
`mbl_mw_acc_bmi160_write_step_counter_config <https://mbientlab.com/docs/metawear/cpp/latest/accelerometer__bosch_8h.html#ab4fa1b742920e8aefca8bf5e59237f8e>`_ to save the configuration to the board. ::
96+
97+
libmetawear.mbl_mw_acc_bmi160_set_step_counter_mode(board, AccBmi160StepCounterMode.NORMAL)
98+
libmetawear.mbl_mw_acc_bmi160_enable_step_counter(board)
99+
libmetawear.mbl_mw_acc_bmi160_write_step_counter_config(board)
100+
101+
Reading The Counter
102+
^^^^^^^^^^^^^^^^^^^
103+
One way to retrieve step counts is to periodcally read the step counter. To read the step counter, call
104+
`mbl_mw_datasignal_read <https://mbientlab.com/docs/metawear/cpp/latest/datasignal_8h.html#a0a456ad1b6d7e7abb157bdf2fc98f179>`_ with the step counter data signal.
105+
106+
The counter is not enabled by default so you will need enable it by calling
107+
`mbl_mw_acc_bmi160_enable_step_counter <https://mbientlab.com/docs/metawear/cpp/latest/accelerometer__bosch_8h.html#ad4ef124ad3ef8ef51667e738331333b8>`_ when configuring the board. ::
108+
109+
step_counter_signal = libmetawear.mbl_mw_acc_bmi160_get_step_counter_data_signal(board)
110+
111+
libmetawear.mbl_mw_datasignal_subscribe(step_counter_signal, None, sensor_data_handler)
112+
libmetawear.mbl_mw_datasignal_read(step_counter_signal)
113+
114+
Using The Detector
115+
^^^^^^^^^^^^^^^^^^
116+
Alternatively, you can receive notifications for each step detected by calling
117+
`mbl_mw_acc_bmi160_enable_step_detector <https://mbientlab.com/docs/metawear/cpp/latest/accelerometer__bosch_8h.html#a3f1b82cb1d70334eeb7b604431e15f20>`_ instead. ::
118+
119+
step_detector_signal= libmetawear.mbl_mw_acc_bmi160_get_step_detector_data_signal(board)
120+
libmetawear.mbl_mw_datasignal_subscribe(step_detector_signal, None, sensor_data_handler)
121+
122+
Orientation Detection
123+
---------------------
124+
The orientation detector alerts you when the sensor's orientation changes between portrait/landscape and front/back. Data is represented as an
125+
`MblMwSensorOrientation <https://mbientlab.com/docs/metawear/cpp/0/types_8h.html#a2e83167b55d36e1d48d100f342ad529c>`_ enum.
126+
127+
This feature is currently only supported on devices using the BMI160 or BMA255 accelerometers.
128+
129+
::
130+
131+
orientation = libmetawear.mbl_mw_acc_bosch_get_orientation_detection_data_signal(board)
132+
libmetawear.mbl_mw_datasignal_subscribe(orientation, None, sensor_data_handler)

0 commit comments

Comments
 (0)