Skip to content
Snippets Groups Projects
Commit ed6e7f70 authored by KERDREUX Jerome's avatar KERDREUX Jerome
Browse files

Gitlab migration

parent 0eb6add0
Branches
No related tags found
No related merge requests found
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta charset="utf-8" />
<meta name="generator" content="Docutils 0.21.2: https://docutils.sourceforge.io/" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>xAAL Python stack</title>
<style type="text/css">
/* Minimal style sheet for the HTML output of Docutils. */
/* */
/* :Author: Günter Milde, based on html4css1.css by David Goodger */
/* :Id: $Id: minimal.css 9545 2024-02-17 10:37:56Z milde $ */
/* :Copyright: © 2015, 2021 Günter Milde. */
/* :License: Released under the terms of the `2-Clause BSD license`_, */
/* in short: */
/* */
/* Copying and distribution of this file, with or without modification, */
/* are permitted in any medium without royalty provided the copyright */
/* notice and this notice are preserved. */
/* */
/* This file is offered as-is, without any warranty. */
/* */
/* .. _2-Clause BSD license: http://www.spdx.org/licenses/BSD-2-Clause */
/* This CSS3 stylesheet defines rules for Docutils elements without */
/* HTML equivalent. It is required to make the document semantics visible. */
/* */
/* .. _validates: http://jigsaw.w3.org/css-validator/validator$link */
/* titles */
p.topic-title,
p.admonition-title,
p.system-message-title {
font-weight: bold;
}
p.sidebar-title,
p.rubric {
font-weight: bold;
font-size: larger;
}
p.rubric {
color: maroon;
}
p.subtitle,
p.section-subtitle,
p.sidebar-subtitle {
font-weight: bold;
margin-top: -0.5em;
}
h1 + p.subtitle {
font-size: 1.6em;
}
a.toc-backref {
color: inherit;
text-decoration: none;
}
/* Warnings, Errors */
.system-messages h2,
.system-message-title,
pre.problematic,
span.problematic {
color: red;
}
/* Inline Literals */
.docutils.literal {
font-family: monospace;
white-space: pre-wrap;
}
/* do not wrap at hyphens and similar: */
.literal > span.pre { white-space: nowrap; }
/* keep line-breaks (\n) visible */
.pre-wrap { white-space: pre-wrap; }
/* Lists */
/* compact and simple lists: no margin between items */
.simple li, .simple ul, .simple ol,
.compact li, .compact ul, .compact ol,
.simple > li p, dl.simple > dd,
.compact > li p, dl.compact > dd {
margin-top: 0;
margin-bottom: 0;
}
/* Nested Paragraphs */
p:first-child { margin-top: 0; }
p:last-child { margin-bottom: 0; }
details > p:last-child { margin-bottom: 1em; }
/* Table of Contents */
.contents ul.auto-toc { /* section numbers present */
list-style-type: none;
}
/* Enumerated Lists */
ol.arabic { list-style: decimal }
ol.loweralpha { list-style: lower-alpha }
ol.upperalpha { list-style: upper-alpha }
ol.lowerroman { list-style: lower-roman }
ol.upperroman { list-style: upper-roman }
/* Definition Lists and Derivatives */
dt .classifier { font-style: italic }
dt .classifier:before {
font-style: normal;
margin: 0.5em;
content: ":";
}
/* Field Lists and similar */
/* bold field name, content starts on the same line */
dl.field-list,
dl.option-list,
dl.docinfo {
display: flow-root;
}
dl.field-list > dt,
dl.option-list > dt,
dl.docinfo > dt {
font-weight: bold;
clear: left;
float: left;
margin: 0;
padding: 0;
padding-right: 0.25em;
}
/* Offset for field content (corresponds to the --field-name-limit option) */
dl.field-list > dd,
dl.option-list > dd,
dl.docinfo > dd {
margin-left: 9em; /* ca. 14 chars in the test examples, fit all Docinfo fields */
}
/* start nested lists on new line */
dd > dl:first-child,
dd > ul:first-child,
dd > ol:first-child {
clear: left;
}
/* start field-body on a new line after long field names */
dl.field-list > dd > *:first-child,
dl.option-list > dd > *:first-child
{
display: inline-block;
width: 100%;
margin: 0;
}
/* Bibliographic Fields (docinfo) */
dl.docinfo pre.address {
font: inherit;
margin: 0.5em 0;
}
dl.docinfo > dd.authors > p { margin: 0; }
/* Option Lists */
dl.option-list > dt { font-weight: normal; }
span.option { white-space: nowrap; }
/* Footnotes and Citations */
.footnote, .citation { margin: 1em 0; } /* default paragraph skip (Firefox) */
/* hanging indent */
.citation { padding-left: 2em; }
.footnote { padding-left: 1.7em; }
.footnote.superscript { padding-left: 1.0em; }
.citation > .label { margin-left: -2em; }
.footnote > .label { margin-left: -1.7em; }
.footnote.superscript > .label { margin-left: -1.0em; }
.footnote > .label + *,
.citation > .label + * {
display: inline-block;
margin-top: 0;
vertical-align: top;
}
.footnote > .backrefs + *,
.citation > .backrefs + * {
margin-top: 0;
}
.footnote > .label + p, .footnote > .backrefs + p,
.citation > .label + p, .citation > .backrefs + p {
display: inline;
vertical-align: inherit;
}
.backrefs { user-select: none; }
.backrefs > a { font-style: italic; }
/* superscript footnotes */
a[role="doc-noteref"].superscript,
.footnote.superscript > .label,
.footnote.superscript > .backrefs {
vertical-align: super;
font-size: smaller;
line-height: 1;
}
a[role="doc-noteref"].superscript > .fn-bracket,
.footnote.superscript > .label > .fn-bracket {
/* hide brackets in display but leave for copy/paste */
display: inline-block;
width: 0;
overflow: hidden;
}
[role="doc-noteref"].superscript + [role="doc-noteref"].superscript {
padding-left: 0.15em; /* separate consecutive footnote references */
/* TODO: unfortunately, "+" also selects with text between the references. */
}
/* Alignment */
.align-left {
text-align: left;
margin-right: auto;
}
.align-center {
text-align: center;
margin-left: auto;
margin-right: auto;
}
.align-right {
text-align: right;
margin-left: auto;
}
.align-top { vertical-align: top; }
.align-middle { vertical-align: middle; }
.align-bottom { vertical-align: bottom; }
/* reset inner alignment in figures and tables */
figure.align-left, figure.align-right,
table.align-left, table.align-center, table.align-right {
text-align: inherit;
}
/* Text Blocks */
.topic { margin: 1em 2em; }
.sidebar,
.admonition,
.system-message {
margin: 1em 2em;
border: thin solid;
padding: 0.5em 1em;
}
div.line-block { display: block; }
div.line-block div.line-block, pre { margin-left: 2em; }
/* Code line numbers: dropped when copying text from the page */
pre.code .ln { display: none; }
pre.code code:before {
content: attr(data-lineno); /* …, none) fallback not supported by any browser */
color: gray;
}
/* Tables */
table {
border-collapse: collapse;
}
td, th {
border: thin solid silver;
padding: 0 1ex;
}
.borderless td, .borderless th {
border: 0;
padding: 0;
padding-right: 0.5em /* separate table cells */
}
table > caption, figcaption {
text-align: left;
margin-top: 0.2em;
margin-bottom: 0.2em;
}
table.captionbelow {
caption-side: bottom;
}
/* MathML (see "math.css" for --math-output=HTML) */
math .boldsymbol { font-weight: bold; }
math.boxed, math .boxed {padding: 0.25em; border: thin solid; }
/* style table similar to AMS "align" or "aligned" environment: */
mtable.cases > mtr > mtd { text-align: left; }
mtable.ams-align > mtr > mtd { padding-left: 0; padding-right: 0; }
mtable.ams-align > mtr > mtd:nth-child(2n) { text-align: left; }
mtable.ams-align > mtr > mtd:nth-child(2n+1) { text-align: right; }
mtable.ams-align > mtr > mtd:nth-child(2n+3) { padding-left: 2em; }
.mathscr mi, mi.mathscr {
font-family: STIX, XITSMathJax_Script, rsfs10,
"Asana Math", Garamond, cursive;
}
/* Document Header and Footer */
header { border-bottom: 1px solid black; }
footer { border-top: 1px solid black; }
/* Images are block-level by default in Docutils */
/* New HTML5 block elements: set display for older browsers */
img, svg, header, footer, main, aside, nav, section, figure, video, details {
display: block;
}
svg { width: auto; height: auto; } /* enable scaling of SVG images */
/* inline images */
p img, p svg, p video { display: inline; }
</style>
<style type="text/css">
/* CSS31_ style sheet for the output of Docutils HTML writers. */
/* Rules for easy reading and pre-defined style variants. */
/* */
/* :Author: Günter Milde, based on html4css1.css by David Goodger */
/* :Id: $Id: plain.css 9615 2024-04-06 13:28:15Z milde $ */
/* :Copyright: © 2015 Günter Milde. */
/* :License: Released under the terms of the `2-Clause BSD license`_, */
/* in short: */
/* */
/* Copying and distribution of this file, with or without modification, */
/* are permitted in any medium without royalty provided the copyright */
/* notice and this notice are preserved. */
/* */
/* This file is offered as-is, without any warranty. */
/* */
/* .. _2-Clause BSD license: http://www.spdx.org/licenses/BSD-2-Clause */
/* .. _CSS3: https://www.w3.org/Style/CSS/ */
/* Document Structure */
/* ****************** */
/* "page layout" */
body {
margin: 0;
background-color: #dbdbdb;
--field-indent: 9em; /* default indent of fields in field lists */
}
main, footer, header {
line-height:1.6;
/* avoid long lines --> better reading */
/* optimum is 45…75 characters/line <http://webtypography.net/2.1.2> */
/* OTOH: lines should not be too short because of missing hyphenation, */
max-width: 50rem;
padding: 1px 2%; /* 1px on top avoids grey bar above title (mozilla) */
margin: auto;
}
main {
counter-reset: table figure;
background-color: white;
}
footer, header {
font-size: smaller;
padding: 0.5em 2%;
border: none;
}
/* Table of Contents */
ul.auto-toc > li > p {
padding-left: 1em;
text-indent: -1em;
}
nav.contents ul {
padding-left: 1em;
}
main > nav.contents ul ul ul ul:not(.auto-toc) {
list-style-type: '\2B29\ ';
}
main > nav.contents ul ul ul ul ul:not(.auto-toc) {
list-style-type: '\2B1D\ ';
}
/* Transitions */
hr.docutils {
width: 80%;
margin-top: 1em;
margin-bottom: 1em;
clear: both;
}
/* Paragraphs */
/* vertical space (parskip) */
p, ol, ul, dl, li,
.footnote, .citation,
div > math,
table {
margin-top: 0.5em;
margin-bottom: 0.5em;
}
h1, h2, h3, h4, h5, h6,
dd, details > p:last-child {
margin-bottom: 0.5em;
}
/* Lists */
/* ===== */
/* Definition Lists */
/* Indent lists nested in definition lists */
dd > ul:only-child, dd > ol:only-child { padding-left: 1em; }
/* Description Lists */
/* styled like in most dictionaries, encyclopedias etc. */
dl.description {
display: flow-root;
}
dl.description > dt {
font-weight: bold;
clear: left;
float: left;
margin: 0;
padding: 0;
padding-right: 0.3em;
}
dl.description > dd:after {
display: table;
content: "";
clear: left; /* clearfix for empty descriptions */
}
/* Field Lists */
dl.field-list > dd,
dl.docinfo > dd {
margin-left: var(--field-indent); /* adapted in media queries or HTML */
}
/* example for custom field-name width */
dl.field-list.narrow > dd {
--field-indent: 5em;
}
/* run-in: start field-body on same line after long field names */
dl.field-list.run-in > dd p {
display: block;
}
/* Bibliographic Fields */
/* generally, bibliographic fields use dl.docinfo */
/* but dedication and abstract are placed into divs */
div.abstract p.topic-title {
text-align: center;
}
div.dedication {
margin: 2em 5em;
text-align: center;
font-style: italic;
}
div.dedication p.topic-title {
font-style: normal;
}
/* disclosures */
details { padding-left: 1em; }
summary { margin-left: -1em; }
/* Text Blocks */
/* =========== */
/* Literal Blocks */
pre.literal-block, pre.doctest-block,
pre.math, pre.code {
font-family: monospace;
}
/* Block Quotes and Topics */
bockquote { margin: 1em 2em; }
blockquote p.attribution,
.topic p.attribution {
text-align: right;
margin-left: 20%;
}
/* Tables */
/* ====== */
/* th { vertical-align: bottom; } */
table tr { text-align: left; }
/* "booktabs" style (no vertical lines) */
table.booktabs {
border: 0;
border-top: 2px solid;
border-bottom: 2px solid;
border-collapse: collapse;
}
table.booktabs * {
border: 0;
}
table.booktabs th {
border-bottom: thin solid;
}
/* numbered tables (counter defined in div.document) */
table.numbered > caption:before {
counter-increment: table;
content: "Table " counter(table) ": ";
font-weight: bold;
}
/* Explicit Markup Blocks */
/* ====================== */
/* Footnotes and Citations */
/* ----------------------- */
/* line on the left */
.footnote-list {
border-left: solid thin;
padding-left: 0.25em;
}
/* Directives */
/* ---------- */
/* Body Elements */
/* ~~~~~~~~~~~~~ */
/* Images and Figures */
/* let content flow to the side of aligned images and figures */
figure.align-left,
img.align-left,
svg.align-left,
video.align-left,
div.align-left,
object.align-left {
clear: left;
float: left;
margin-right: 1em;
}
figure.align-right,
img.align-right,
svg.align-right,
video.align-right,
div.align-right,
object.align-right {
clear: right;
float: right;
margin-left: 1em;
}
/* Stop floating sidebars, images and figures */
h1, h2, h3, h4, footer, header { clear: both; }
/* Numbered figures */
figure.numbered > figcaption > p:before {
counter-increment: figure;
content: "Figure " counter(figure) ": ";
font-weight: bold;
}
/* Admonitions and System Messages */
.caution p.admonition-title,
.attention p.admonition-title,
.danger p.admonition-title,
.error p.admonition-title,
.warning p.admonition-title,
div.error {
color: red;
}
/* Sidebar */
/* Move right. In a layout with fixed margins, */
/* it can be moved into the margin. */
aside.sidebar {
width: 30%;
max-width: 26em;
float: right;
clear: right;
margin-left: 1em;
margin-right: -1%;
background-color: #fffffa;
}
/* Code */
pre.code { padding: 0.7ex }
pre.code, code { background-color: #eeeeee }
/* basic highlighting: for a complete scheme, see */
/* https://docutils.sourceforge.io/sandbox/stylesheets/ */
pre.code .comment, code .comment { color: #5C6576 }
pre.code .keyword, code .keyword { color: #3B0D06; font-weight: bold }
pre.code .literal.string, code .literal.string { color: #0C5404 }
pre.code .name.builtin, code .name.builtin { color: #352B84 }
pre.code .deleted, code .deleted { background-color: #DEB0A1}
pre.code .inserted, code .inserted { background-color: #A3D289}
/* Epigraph */
/* Highlights */
/* Pull-Quote */
/* Compound Paragraph */
/* Container */
/* Inline Markup */
/* ============= */
sup, sub { line-height: 0.8; } /* do not add leading for lines with sup/sub */
/* Inline Literals */
/* possible values: normal, nowrap, pre, pre-wrap, pre-line */
/* span.docutils.literal { white-space: pre-wrap; } */
/* Hyperlink References */
a { text-decoration: none; }
/* External Targets */
/* span.target.external */
/* Internal Targets */
/* span.target.internal */
/* Footnote References */
/* a[role="doc-noteref"] */
/* Citation References */
/* a.citation-reference */
</style>
</head>
<body>
<main id="xaal-python-stack">
<h1 class="title">xAAL Python stack</h1>
<section id="requirements">
<h2><span class="sectnum">1 </span>Requirements</h2>
<p>To install xAAL for Python, you need Python-3 (version 3.8 or above). And limited stack exists
for Python-2, you can find more informations <a class="reference external" href="https://redmine.imt-atlantique.fr/projects/xaal/repository/xaal/show/code/Python/branches/py2-backport">here</a>.</p>
<section id="un-x-like">
<h3><span class="sectnum">1.1 </span>Un*x like</h3>
<p>Install the following packages:</p>
<ul class="simple">
<li><p>subversion</p></li>
<li><p>python3-dev</p></li>
<li><p>python3-setuptools</p></li>
<li><p>libsodium-dev</p></li>
</ul>
<p>For Debian / Ubuntu users:</p>
<pre class="code bash literal-block"><code>$ apt-get install subversion python3-dev libsodium-dev python3-setuptools gcc
<span class="comment single"># recommended
</span>$ apt-get install python3-venv python3-pip</code></pre>
</section>
<section id="windows">
<h3><span class="sectnum">1.2 </span>Windows</h3>
<p>This code can be used w/ Windows (tested w/ Win10 and Python 3.8). You can build
the virtualenv with the same way. To activate the venv, you should run Scriptsactivate.bat.
For Powershell users (recommanded), you must tweak the ExecutionPolicy to be able to run
<em>Activate.ps1</em>.</p>
<blockquote>
<pre class="code literal-block"><code>Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser</code></pre>
</blockquote>
<p>To install libsodium. You can dowload it here: <a class="reference external" href="https://download.libsodium.org/libsodium/releases/">https://download.libsodium.org/libsodium/releases/</a>
Extract the DLL from the zip file (libsodium-x.y.z-stable-msvc.ziplibsodiumx64Releasevzzzdynamic)
in the Win32 DLL folder.</p>
<p>If everything is fine, you can use exactly the same commands on Un*x and Windows. The xaal-* commands
are just renamed with an exe extension (ie: xaal-dumper.exe)</p>
<p><strong>Issues:</strong> Right now some gateways won't work on Windows due to missing libaries (openZwave ie)</p>
</section>
</section>
<section id="installation">
<h2><span class="sectnum">2 </span>Installation</h2>
<section id="manual">
<h3><span class="sectnum">2.1 </span>Manual</h3>
<p>Right now, there is no public release (pip based) of xAAL Python binding, so
you have to install things from SVN or archive.</p>
<p>You can use virtualenv (recommended).</p>
<p>First build a virtualenv :</p>
<pre class="code bash literal-block"><code>$ python3 -m venv xaal_env</code></pre>
<p>Everytime, you want to use the binding, you must source the activate script.</p>
<pre class="code bash literal-block"><code>$ <span class="name builtin">source</span> xaal_env/bin/activate</code></pre>
<p>Download sources from SVN:</p>
<pre class="code bash literal-block"><code>$ svn checkout https://redmine.imt-atlantique.fr/svn/xaal/code/Python/branches/0.7/ xaal_svn</code></pre>
<p>First, install the xaal.lib package:</p>
<pre class="code bash literal-block"><code>$ <span class="name builtin">cd</span> xaal_svn/libs/lib/
$ pip install .</code></pre>
<p>Install the monitor lib (needed by Dashboard, REST API..)</p>
<pre class="code bash literal-block"><code>$ <span class="name builtin">cd</span> xaal_svn/libs/monitor/
$ pip install -e .</code></pre>
<p>Install the schemas (needed by some devices)</p>
<pre class="code bash literal-block"><code>$ <span class="name builtin">cd</span> xaal_svn/libs/schemas/
$ pip install -e .</code></pre>
<p>Install the tools</p>
<pre class="code bash literal-block"><code>$ <span class="name builtin">cd</span> xaal_svn/apps/tools
$ pip install -e .</code></pre>
<dl class="simple">
<dt>You can remove the <em>-e</em> in pip install command , but modification in source files</dt>
<dd><p>won't be applied, you have to re-install it. Right now, <em>-e</em> is the best option.</p>
</dd>
</dl>
<p>Create the configuration file in your home directory:</p>
<pre class="code bash literal-block"><code>$ mkdir ~/.xaal/
$ cp xaal_svn/libs/lib/xaal.ini.sample ~/.xaal/xaal.ini
$ xaal-keygen</code></pre>
<p>xaal-keygen will compute an key for a given passphrase. Edit the xaal.ini
file according to your needs.</p>
</section>
<section id="automatic">
<h3><span class="sectnum">2.2 </span>Automatic</h3>
<p>Instead of manual installation of each package, you can use the <em>install.py</em> script.
This script will install allmost all packages without user interaction.</p>
</section>
<section id="docker">
<h3><span class="sectnum">2.3 </span>Docker</h3>
<p>The docker folder contains an Dockerfile to run the xALL software in a docker
container. The Dockerfile use the automatic installation script.</p>
</section>
</section>
<section id="tests">
<h2><span class="sectnum">3 </span>Tests</h2>
<p>First, you can launch a message dumper with this tools</p>
<pre class="code bash literal-block"><code>$ xaal-dumper
$ or xaal-tail</code></pre>
<p>To start an fake lamp:</p>
<pre class="code bash literal-block"><code>$ python -m xaal.dummy.lamp</code></pre>
<p>To check devices, you can use:</p>
<pre class="code bash literal-block"><code><span class="comment single"># search alive devices
</span>$ xaal-isalive
<span class="comment single"># search lamp.basic devices
</span>$ xaal-isalive -t lamp.basic
<span class="comment single"># search any kind of lamp
</span>$ xaal-isalive -t lamp.any
<span class="comment single"># display description / attribute
</span>$ xaal-info xxxxxxxxxxxxxx &lt;- uuid
<span class="comment single"># display description / attribute for all devices
</span>$ xaal-walker
<span class="comment single"># same but only for lamp devices
</span>$ xaal-walker -t lamp.any</code></pre>
<p>To turn on/off the lamp</p>
<pre class="code bash literal-block"><code><span class="comment single"># turn on the lamp
</span>$ xaal-send -d xxxxxxxxxxxxxx -r turn_off
$ xaal-send -d xxxxxxxxxxxxxx -r turn_on</code></pre>
</section>
<section id="informations">
<h2><span class="sectnum">4 </span>Informations</h2>
<section id="coding-style">
<h3><span class="sectnum">4.1 </span>Coding style</h3>
<p>Every xAAL package (device, gateway, app) use a namespace. For example, <em>xaal.rest</em>,
or <em>xaal.zwave</em>. By convention, you can run everything just by calling the namespace
module.</p>
<pre class="code bash literal-block"><code><span class="comment single"># to run the meta data sever:
</span>$ python -m xaal.metadb
<span class="comment single"># to run the dashboard (web interface)
</span>$ python -m xaal.dashboard
<span class="comment single"># to run the Open Weather Map gateway
</span>$ python -m xaal.owm</code></pre>
<p>To reduce memory footprint, you can use the <em>xaal-pkgrun</em> command. This tool will
register every package on a single Python interpreter.</p>
<pre class="code bash literal-block"><code><span class="comment single"># to run aqara and owm gateways:
</span>$ xaal-pkgrun aqara owm</code></pre>
</section>
<section id="links">
<h3><span class="sectnum">4.2 </span>Links</h3>
<ul class="simple">
<li><p>The repository contains a large number of devices, gateways and tools. You can find
the <a class="reference external" href="packages.html">packages list here</a>.</p></li>
<li><p>You can find the <a class="reference external" href="./libs/lib/README.html">xAAL lib documentation here.</a></p></li>
</ul>
</section>
<section id="notes">
<h3><span class="sectnum">4.3 </span>Notes</h3>
<ul class="simple">
<li><p>If you use xAAL on multiple hosts, take care of the system clock. xAAL use
date/time to cypher the messages. If clocks differs, you will receive an error
message about a &quot;replay attack&quot;. In production, NTP is your best friend. A window
of 1 minutes is accepted, but no more.</p></li>
</ul>
</section>
<section id="faq">
<h3><span class="sectnum">4.4 </span>FAQ</h3>
<ul>
<li><p>Configuration files are hard to read / edit. Why don't you use YAML or XML
for config ?</p>
<p>First, we need something that support nested config so we can not use
ConfigParser. Next, we tested severals YAML packages, but they are really
slow to import. We want xAAL stack to load as fast as possible, and importing
big packages (like PyYAML) take around 0.5 sec on a Raspy. This is way too
much for a simple command-line tools like xaal-info for example.
We want to provide a better user experience.</p>
</li>
</ul>
</section>
</section>
</main>
</body>
</html>
This diff is collapsed.
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment