Updated manual and documentation

This commit is contained in:
Mark Qvist 2022-09-30 00:02:15 +02:00
parent e90b2866b4
commit 3f2075da6f
31 changed files with 14719 additions and 1586 deletions

Binary file not shown.

View File

@ -1,4 +1,4 @@
# Sphinx build info version 1 # Sphinx build info version 1
# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done. # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
config: 8c9a8cd51b9d998fde994d5ba66f7d1f config: ac2d5f73ab011289e2f4e2a564ac4cac
tags: 645f666f9bcd5a90fca523b33c5a78b7 tags: 645f666f9bcd5a90fca523b33c5a78b7

View File

@ -498,7 +498,7 @@ calculated from the link request packet, into the memory of forwarding nodes,
which means that the communicating nodes can thereafter reach each other simply which means that the communicating nodes can thereafter reach each other simply
by referring to this *link id*. by referring to this *link id*.
The combined bandwidth cost of setting up a link is 3 packets totalling 265 bytes (more info in the The combined bandwidth cost of setting up a link is 3 packets totalling 297 bytes (more info in the
:ref:`Binary Packet Format<understanding-packetformat>` section). The amount of bandwidth used on keeping :ref:`Binary Packet Format<understanding-packetformat>` section). The amount of bandwidth used on keeping
a link open is practically negligible, at 0.45 bits per second. Even on a slow 1200 bits per second packet a link open is practically negligible, at 0.45 bits per second. Even on a slow 1200 bits per second packet
radio channel, 100 concurrent links will still leave 96% channel capacity for actual data. radio channel, 100 concurrent links will still leave 96% channel capacity for actual data.
@ -803,7 +803,7 @@ Wire Format
- Path Request : 51 bytes - Path Request : 51 bytes
- Announce : 157 bytes - Announce : 157 bytes
- Link Request : 83 bytes - Link Request : 83 bytes
- Link Proof : 83 bytes - Link Proof : 115 bytes
- Link RTT packet : 99 bytes - Link RTT packet : 99 bytes
- Link keepalive : 20 bytes - Link keepalive : 20 bytes

View File

@ -61,7 +61,7 @@ What does Reticulum Offer?
* Efficient link establishment * Efficient link establishment
* Total bandwidth cost of setting up a link is only 3 packets, totalling 265 bytes * Total bandwidth cost of setting up a link is only 3 packets, totalling 297 bytes
* Low cost of keeping links open at only 0.44 bits per second * Low cost of keeping links open at only 0.44 bits per second

View File

@ -0,0 +1,134 @@
/*
* _sphinx_javascript_frameworks_compat.js
* ~~~~~~~~~~
*
* Compatability shim for jQuery and underscores.js.
*
* WILL BE REMOVED IN Sphinx 6.0
* xref RemovedInSphinx60Warning
*
*/
/**
* select a different prefix for underscore
*/
$u = _.noConflict();
/**
* small helper function to urldecode strings
*
* See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURIComponent#Decoding_query_parameters_from_a_URL
*/
jQuery.urldecode = function(x) {
if (!x) {
return x
}
return decodeURIComponent(x.replace(/\+/g, ' '));
};
/**
* small helper function to urlencode strings
*/
jQuery.urlencode = encodeURIComponent;
/**
* This function returns the parsed url parameters of the
* current request. Multiple values per key are supported,
* it will always return arrays of strings for the value parts.
*/
jQuery.getQueryParameters = function(s) {
if (typeof s === 'undefined')
s = document.location.search;
var parts = s.substr(s.indexOf('?') + 1).split('&');
var result = {};
for (var i = 0; i < parts.length; i++) {
var tmp = parts[i].split('=', 2);
var key = jQuery.urldecode(tmp[0]);
var value = jQuery.urldecode(tmp[1]);
if (key in result)
result[key].push(value);
else
result[key] = [value];
}
return result;
};
/**
* highlight a given string on a jquery object by wrapping it in
* span elements with the given class name.
*/
jQuery.fn.highlightText = function(text, className) {
function highlight(node, addItems) {
if (node.nodeType === 3) {
var val = node.nodeValue;
var pos = val.toLowerCase().indexOf(text);
if (pos >= 0 &&
!jQuery(node.parentNode).hasClass(className) &&
!jQuery(node.parentNode).hasClass("nohighlight")) {
var span;
var isInSVG = jQuery(node).closest("body, svg, foreignObject").is("svg");
if (isInSVG) {
span = document.createElementNS("http://www.w3.org/2000/svg", "tspan");
} else {
span = document.createElement("span");
span.className = className;
}
span.appendChild(document.createTextNode(val.substr(pos, text.length)));
node.parentNode.insertBefore(span, node.parentNode.insertBefore(
document.createTextNode(val.substr(pos + text.length)),
node.nextSibling));
node.nodeValue = val.substr(0, pos);
if (isInSVG) {
var rect = document.createElementNS("http://www.w3.org/2000/svg", "rect");
var bbox = node.parentElement.getBBox();
rect.x.baseVal.value = bbox.x;
rect.y.baseVal.value = bbox.y;
rect.width.baseVal.value = bbox.width;
rect.height.baseVal.value = bbox.height;
rect.setAttribute('class', className);
addItems.push({
"parent": node.parentNode,
"target": rect});
}
}
}
else if (!jQuery(node).is("button, select, textarea")) {
jQuery.each(node.childNodes, function() {
highlight(this, addItems);
});
}
}
var addItems = [];
var result = this.each(function() {
highlight(this, addItems);
});
for (var i = 0; i < addItems.length; ++i) {
jQuery(addItems[i].parent).before(addItems[i].target);
}
return result;
};
/*
* backward compatibility for jQuery.browser
* This will be supported until firefox bug is fixed.
*/
if (!jQuery.browser) {
jQuery.uaMatch = function(ua) {
ua = ua.toLowerCase();
var match = /(chrome)[ \/]([\w.]+)/.exec(ua) ||
/(webkit)[ \/]([\w.]+)/.exec(ua) ||
/(opera)(?:.*version|)[ \/]([\w.]+)/.exec(ua) ||
/(msie) ([\w.]+)/.exec(ua) ||
ua.indexOf("compatible") < 0 && /(mozilla)(?:.*? rv:([\w.]+)|)/.exec(ua) ||
[];
return {
browser: match[ 1 ] || "",
version: match[ 2 ] || "0"
};
};
jQuery.browser = {};
jQuery.browser[jQuery.uaMatch(navigator.userAgent).browser] = true;
}

View File

@ -4,7 +4,7 @@
* *
* Sphinx stylesheet -- basic theme. * Sphinx stylesheet -- basic theme.
* *
* :copyright: Copyright 2007-2021 by the Sphinx team, see AUTHORS. * :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
* :license: BSD, see LICENSE for details. * :license: BSD, see LICENSE for details.
* *
*/ */
@ -222,7 +222,7 @@ table.modindextable td {
/* -- general body styles --------------------------------------------------- */ /* -- general body styles --------------------------------------------------- */
div.body { div.body {
min-width: 450px; min-width: 360px;
max-width: 800px; max-width: 800px;
} }
@ -237,16 +237,6 @@ a.headerlink {
visibility: hidden; visibility: hidden;
} }
a.brackets:before,
span.brackets > a:before{
content: "[";
}
a.brackets:after,
span.brackets > a:after {
content: "]";
}
h1:hover > a.headerlink, h1:hover > a.headerlink,
h2:hover > a.headerlink, h2:hover > a.headerlink,
h3:hover > a.headerlink, h3:hover > a.headerlink,
@ -334,13 +324,15 @@ aside.sidebar {
p.sidebar-title { p.sidebar-title {
font-weight: bold; font-weight: bold;
} }
nav.contents,
aside.topic,
div.admonition, div.topic, blockquote { div.admonition, div.topic, blockquote {
clear: left; clear: left;
} }
/* -- topics ---------------------------------------------------------------- */ /* -- topics ---------------------------------------------------------------- */
nav.contents,
aside.topic,
div.topic { div.topic {
border: 1px solid #ccc; border: 1px solid #ccc;
padding: 7px; padding: 7px;
@ -379,6 +371,8 @@ div.body p.centered {
div.sidebar > :last-child, div.sidebar > :last-child,
aside.sidebar > :last-child, aside.sidebar > :last-child,
nav.contents > :last-child,
aside.topic > :last-child,
div.topic > :last-child, div.topic > :last-child,
div.admonition > :last-child { div.admonition > :last-child {
margin-bottom: 0; margin-bottom: 0;
@ -386,6 +380,8 @@ div.admonition > :last-child {
div.sidebar::after, div.sidebar::after,
aside.sidebar::after, aside.sidebar::after,
nav.contents::after,
aside.topic::after,
div.topic::after, div.topic::after,
div.admonition::after, div.admonition::after,
blockquote::after { blockquote::after {
@ -428,10 +424,6 @@ table.docutils td, table.docutils th {
border-bottom: 1px solid #aaa; border-bottom: 1px solid #aaa;
} }
table.footnote td, table.footnote th {
border: 0 !important;
}
th { th {
text-align: left; text-align: left;
padding-right: 5px; padding-right: 5px;
@ -614,20 +606,26 @@ ol.simple p,
ul.simple p { ul.simple p {
margin-bottom: 0; margin-bottom: 0;
} }
aside.footnote > span,
dl.footnote > dt, div.citation > span {
dl.citation > dt {
float: left; float: left;
margin-right: 0.5em;
} }
aside.footnote > span:last-of-type,
dl.footnote > dd, div.citation > span:last-of-type {
dl.citation > dd { padding-right: 0.5em;
}
aside.footnote > p {
margin-left: 2em;
}
div.citation > p {
margin-left: 4em;
}
aside.footnote > p:last-of-type,
div.citation > p:last-of-type {
margin-bottom: 0em; margin-bottom: 0em;
} }
aside.footnote > p:last-of-type:after,
dl.footnote > dd:after, div.citation > p:last-of-type:after {
dl.citation > dd:after {
content: ""; content: "";
clear: both; clear: both;
} }
@ -644,10 +642,6 @@ dl.field-list > dt {
padding-right: 5px; padding-right: 5px;
} }
dl.field-list > dt:after {
content: ":";
}
dl.field-list > dd { dl.field-list > dd {
padding-left: 0.5em; padding-left: 0.5em;
margin-top: 0em; margin-top: 0em;
@ -731,8 +725,9 @@ dl.glossary dt {
.classifier:before { .classifier:before {
font-style: normal; font-style: normal;
margin: 0.5em; margin: 0 0.5em;
content: ":"; content: ":";
display: inline-block;
} }
abbr, acronym { abbr, acronym {
@ -756,6 +751,7 @@ span.pre {
-ms-hyphens: none; -ms-hyphens: none;
-webkit-hyphens: none; -webkit-hyphens: none;
hyphens: none; hyphens: none;
white-space: nowrap;
} }
div[class*="highlight-"] { div[class*="highlight-"] {
@ -819,7 +815,7 @@ div.code-block-caption code {
table.highlighttable td.linenos, table.highlighttable td.linenos,
span.linenos, span.linenos,
div.doctest > div.highlight span.gp { /* gp: Generic.Prompt */ div.highlight span.gp { /* gp: Generic.Prompt */
user-select: none; user-select: none;
-webkit-user-select: text; /* Safari fallback only */ -webkit-user-select: text; /* Safari fallback only */
-webkit-user-select: none; /* Chrome/Safari */ -webkit-user-select: none; /* Chrome/Safari */

View File

@ -4,7 +4,7 @@
* *
* Sphinx stylesheet -- classic theme. * Sphinx stylesheet -- classic theme.
* *
* :copyright: Copyright 2007-2021 by the Sphinx team, see AUTHORS. * :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
* :license: BSD, see LICENSE for details. * :license: BSD, see LICENSE for details.
* *
*/ */
@ -28,6 +28,7 @@ body {
} }
div.document { div.document {
display: flex;
background-color: #1c4e63; background-color: #1c4e63;
} }
@ -204,6 +205,8 @@ div.seealso {
background-color: #ffc; background-color: #ffc;
border: 1px solid #ff6; border: 1px solid #ff6;
} }
nav.contents,
aside.topic,
div.topic { div.topic {
background-color: #eee; background-color: #eee;

View File

@ -2,320 +2,155 @@
* doctools.js * doctools.js
* ~~~~~~~~~~~ * ~~~~~~~~~~~
* *
* Sphinx JavaScript utilities for all documentation. * Base JavaScript utilities for all Sphinx HTML documentation.
* *
* :copyright: Copyright 2007-2021 by the Sphinx team, see AUTHORS. * :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
* :license: BSD, see LICENSE for details. * :license: BSD, see LICENSE for details.
* *
*/ */
"use strict";
/** const BLACKLISTED_KEY_CONTROL_ELEMENTS = new Set([
* select a different prefix for underscore "TEXTAREA",
*/ "INPUT",
$u = _.noConflict(); "SELECT",
"BUTTON",
]);
/** const _ready = (callback) => {
* make the code below compatible with browsers without if (document.readyState !== "loading") {
* an installed firebug like debugger callback();
if (!window.console || !console.firebug) { } else {
var names = ["log", "debug", "info", "warn", "error", "assert", "dir", document.addEventListener("DOMContentLoaded", callback);
"dirxml", "group", "groupEnd", "time", "timeEnd", "count", "trace",
"profile", "profileEnd"];
window.console = {};
for (var i = 0; i < names.length; ++i)
window.console[names[i]] = function() {};
}
*/
/**
* small helper function to urldecode strings
*
* See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURIComponent#Decoding_query_parameters_from_a_URL
*/
jQuery.urldecode = function(x) {
if (!x) {
return x
} }
return decodeURIComponent(x.replace(/\+/g, ' '));
}; };
/**
* small helper function to urlencode strings
*/
jQuery.urlencode = encodeURIComponent;
/**
* This function returns the parsed url parameters of the
* current request. Multiple values per key are supported,
* it will always return arrays of strings for the value parts.
*/
jQuery.getQueryParameters = function(s) {
if (typeof s === 'undefined')
s = document.location.search;
var parts = s.substr(s.indexOf('?') + 1).split('&');
var result = {};
for (var i = 0; i < parts.length; i++) {
var tmp = parts[i].split('=', 2);
var key = jQuery.urldecode(tmp[0]);
var value = jQuery.urldecode(tmp[1]);
if (key in result)
result[key].push(value);
else
result[key] = [value];
}
return result;
};
/**
* highlight a given string on a jquery object by wrapping it in
* span elements with the given class name.
*/
jQuery.fn.highlightText = function(text, className) {
function highlight(node, addItems) {
if (node.nodeType === 3) {
var val = node.nodeValue;
var pos = val.toLowerCase().indexOf(text);
if (pos >= 0 &&
!jQuery(node.parentNode).hasClass(className) &&
!jQuery(node.parentNode).hasClass("nohighlight")) {
var span;
var isInSVG = jQuery(node).closest("body, svg, foreignObject").is("svg");
if (isInSVG) {
span = document.createElementNS("http://www.w3.org/2000/svg", "tspan");
} else {
span = document.createElement("span");
span.className = className;
}
span.appendChild(document.createTextNode(val.substr(pos, text.length)));
node.parentNode.insertBefore(span, node.parentNode.insertBefore(
document.createTextNode(val.substr(pos + text.length)),
node.nextSibling));
node.nodeValue = val.substr(0, pos);
if (isInSVG) {
var rect = document.createElementNS("http://www.w3.org/2000/svg", "rect");
var bbox = node.parentElement.getBBox();
rect.x.baseVal.value = bbox.x;
rect.y.baseVal.value = bbox.y;
rect.width.baseVal.value = bbox.width;
rect.height.baseVal.value = bbox.height;
rect.setAttribute('class', className);
addItems.push({
"parent": node.parentNode,
"target": rect});
}
}
}
else if (!jQuery(node).is("button, select, textarea")) {
jQuery.each(node.childNodes, function() {
highlight(this, addItems);
});
}
}
var addItems = [];
var result = this.each(function() {
highlight(this, addItems);
});
for (var i = 0; i < addItems.length; ++i) {
jQuery(addItems[i].parent).before(addItems[i].target);
}
return result;
};
/*
* backward compatibility for jQuery.browser
* This will be supported until firefox bug is fixed.
*/
if (!jQuery.browser) {
jQuery.uaMatch = function(ua) {
ua = ua.toLowerCase();
var match = /(chrome)[ \/]([\w.]+)/.exec(ua) ||
/(webkit)[ \/]([\w.]+)/.exec(ua) ||
/(opera)(?:.*version|)[ \/]([\w.]+)/.exec(ua) ||
/(msie) ([\w.]+)/.exec(ua) ||
ua.indexOf("compatible") < 0 && /(mozilla)(?:.*? rv:([\w.]+)|)/.exec(ua) ||
[];
return {
browser: match[ 1 ] || "",
version: match[ 2 ] || "0"
};
};
jQuery.browser = {};
jQuery.browser[jQuery.uaMatch(navigator.userAgent).browser] = true;
}
/** /**
* Small JavaScript module for the documentation. * Small JavaScript module for the documentation.
*/ */
var Documentation = { const Documentation = {
init: () => {
init : function() { Documentation.initDomainIndexTable();
this.fixFirefoxAnchorBug(); Documentation.initOnKeyListeners();
this.highlightSearchWords();
this.initIndexTable();
if (DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) {
this.initOnKeyListeners();
}
}, },
/** /**
* i18n support * i18n support
*/ */
TRANSLATIONS : {}, TRANSLATIONS: {},
PLURAL_EXPR : function(n) { return n === 1 ? 0 : 1; }, PLURAL_EXPR: (n) => (n === 1 ? 0 : 1),
LOCALE : 'unknown', LOCALE: "unknown",
// gettext and ngettext don't access this so that the functions // gettext and ngettext don't access this so that the functions
// can safely bound to a different name (_ = Documentation.gettext) // can safely bound to a different name (_ = Documentation.gettext)
gettext : function(string) { gettext: (string) => {
var translated = Documentation.TRANSLATIONS[string]; const translated = Documentation.TRANSLATIONS[string];
if (typeof translated === 'undefined') switch (typeof translated) {
return string; case "undefined":
return (typeof translated === 'string') ? translated : translated[0]; return string; // no translation
case "string":
return translated; // translation exists
default:
return translated[0]; // (singular, plural) translation tuple exists
}
}, },
ngettext : function(singular, plural, n) { ngettext: (singular, plural, n) => {
var translated = Documentation.TRANSLATIONS[singular]; const translated = Documentation.TRANSLATIONS[singular];
if (typeof translated === 'undefined') if (typeof translated !== "undefined")
return (n == 1) ? singular : plural; return translated[Documentation.PLURAL_EXPR(n)];
return translated[Documentation.PLURALEXPR(n)]; return n === 1 ? singular : plural;
}, },
addTranslations : function(catalog) { addTranslations: (catalog) => {
for (var key in catalog.messages) Object.assign(Documentation.TRANSLATIONS, catalog.messages);
this.TRANSLATIONS[key] = catalog.messages[key]; Documentation.PLURAL_EXPR = new Function(
this.PLURAL_EXPR = new Function('n', 'return +(' + catalog.plural_expr + ')'); "n",
this.LOCALE = catalog.locale; `return (${catalog.plural_expr})`
);
Documentation.LOCALE = catalog.locale;
}, },
/** /**
* add context elements like header anchor links * helper function to focus on search bar
*/ */
addContextElements : function() { focusSearchBar: () => {
$('div[id] > :header:first').each(function() { document.querySelectorAll("input[name=q]")[0]?.focus();
$('<a class="headerlink">\u00B6</a>').
attr('href', '#' + this.id).
attr('title', _('Permalink to this headline')).
appendTo(this);
});
$('dt[id]').each(function() {
$('<a class="headerlink">\u00B6</a>').
attr('href', '#' + this.id).
attr('title', _('Permalink to this definition')).
appendTo(this);
});
}, },
/** /**
* workaround a firefox stupidity * Initialise the domain index toggle buttons
* see: https://bugzilla.mozilla.org/show_bug.cgi?id=645075
*/ */
fixFirefoxAnchorBug : function() { initDomainIndexTable: () => {
if (document.location.hash && $.browser.mozilla) const toggler = (el) => {
window.setTimeout(function() { const idNumber = el.id.substr(7);
document.location.href += ''; const toggledRows = document.querySelectorAll(`tr.cg-${idNumber}`);
}, 10); if (el.src.substr(-9) === "minus.png") {
}, el.src = `${el.src.substr(0, el.src.length - 9)}plus.png`;
toggledRows.forEach((el) => (el.style.display = "none"));
/** } else {
* highlight the search words provided in the url in the text el.src = `${el.src.substr(0, el.src.length - 8)}minus.png`;
*/ toggledRows.forEach((el) => (el.style.display = ""));
highlightSearchWords : function() {
var params = $.getQueryParameters();
var terms = (params.highlight) ? params.highlight[0].split(/\s+/) : [];
if (terms.length) {
var body = $('div.body');
if (!body.length) {
body = $('body');
} }
window.setTimeout(function() { };
$.each(terms, function() {
body.highlightText(this.toLowerCase(), 'highlighted'); const togglerElements = document.querySelectorAll("img.toggler");
}); togglerElements.forEach((el) =>
}, 10); el.addEventListener("click", (event) => toggler(event.currentTarget))
$('<p class="highlight-link"><a href="javascript:Documentation.' + );
'hideSearchWords()">' + _('Hide Search Matches') + '</a></p>') togglerElements.forEach((el) => (el.style.display = ""));
.appendTo($('#searchbox')); if (DOCUMENTATION_OPTIONS.COLLAPSE_INDEX) togglerElements.forEach(toggler);
}
}, },
/** initOnKeyListeners: () => {
* init the domain index toggle buttons // only install a listener if it is really needed
*/ if (
initIndexTable : function() { !DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS &&
var togglers = $('img.toggler').click(function() { !DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS
var src = $(this).attr('src'); )
var idnum = $(this).attr('id').substr(7); return;
$('tr.cg-' + idnum).toggle();
if (src.substr(-9) === 'minus.png')
$(this).attr('src', src.substr(0, src.length-9) + 'plus.png');
else
$(this).attr('src', src.substr(0, src.length-8) + 'minus.png');
}).css('display', '');
if (DOCUMENTATION_OPTIONS.COLLAPSE_INDEX) {
togglers.click();
}
},
/** document.addEventListener("keydown", (event) => {
* helper function to hide the search marks again // bail for input elements
*/ if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName)) return;
hideSearchWords : function() { // bail with special keys
$('#searchbox .highlight-link').fadeOut(300); if (event.altKey || event.ctrlKey || event.metaKey) return;
$('span.highlighted').removeClass('highlighted');
},
/** if (!event.shiftKey) {
* make the url absolute switch (event.key) {
*/ case "ArrowLeft":
makeURL : function(relativeURL) { if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) break;
return DOCUMENTATION_OPTIONS.URL_ROOT + '/' + relativeURL;
},
/** const prevLink = document.querySelector('link[rel="prev"]');
* get the current relative url if (prevLink && prevLink.href) {
*/ window.location.href = prevLink.href;
getCurrentURL : function() { event.preventDefault();
var path = document.location.pathname;
var parts = path.split(/\//);
$.each(DOCUMENTATION_OPTIONS.URL_ROOT.split(/\//), function() {
if (this === '..')
parts.pop();
});
var url = parts.join('/');
return path.substring(url.lastIndexOf('/') + 1, path.length - 1);
},
initOnKeyListeners: function() {
$(document).keydown(function(event) {
var activeElementType = document.activeElement.tagName;
// don't navigate when in search box, textarea, dropdown or button
if (activeElementType !== 'TEXTAREA' && activeElementType !== 'INPUT' && activeElementType !== 'SELECT'
&& activeElementType !== 'BUTTON' && !event.altKey && !event.ctrlKey && !event.metaKey
&& !event.shiftKey) {
switch (event.keyCode) {
case 37: // left
var prevHref = $('link[rel="prev"]').prop('href');
if (prevHref) {
window.location.href = prevHref;
return false;
} }
case 39: // right break;
var nextHref = $('link[rel="next"]').prop('href'); case "ArrowRight":
if (nextHref) { if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) break;
window.location.href = nextHref;
return false; const nextLink = document.querySelector('link[rel="next"]');
if (nextLink && nextLink.href) {
window.location.href = nextLink.href;
event.preventDefault();
} }
break;
} }
} }
// some keyboard layouts may need Shift to get /
switch (event.key) {
case "/":
if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) break;
Documentation.focusSearchBar();
event.preventDefault();
}
}); });
} },
}; };
// quick alias for translations // quick alias for translations
_ = Documentation.gettext; const _ = Documentation.gettext;
$(document).ready(function() { _ready(Documentation.init);
Documentation.init();
});

View File

@ -1,12 +1,14 @@
var DOCUMENTATION_OPTIONS = { var DOCUMENTATION_OPTIONS = {
URL_ROOT: document.getElementById("documentation_options").getAttribute('data-url_root'), URL_ROOT: document.getElementById("documentation_options").getAttribute('data-url_root'),
VERSION: '0.3.12 beta', VERSION: '0.3.12 beta',
LANGUAGE: 'None', LANGUAGE: 'en',
COLLAPSE_INDEX: false, COLLAPSE_INDEX: false,
BUILDER: 'html', BUILDER: 'html',
FILE_SUFFIX: '.html', FILE_SUFFIX: '.html',
LINK_SUFFIX: '.html', LINK_SUFFIX: '.html',
HAS_SOURCE: true, HAS_SOURCE: true,
SOURCELINK_SUFFIX: '.txt', SOURCELINK_SUFFIX: '.txt',
NAVIGATION_WITH_KEYS: false NAVIGATION_WITH_KEYS: false,
SHOW_SEARCH_SUMMARY: true,
ENABLE_SEARCH_SHORTCUTS: true,
}; };

10881
docs/manual/_static/jquery-3.6.0.js vendored Normal file

File diff suppressed because it is too large Load Diff

File diff suppressed because one or more lines are too long

View File

@ -5,12 +5,12 @@
* This script contains the language-specific data used by searchtools.js, * This script contains the language-specific data used by searchtools.js,
* namely the list of stopwords, stemmer, scorer and splitter. * namely the list of stopwords, stemmer, scorer and splitter.
* *
* :copyright: Copyright 2007-2021 by the Sphinx team, see AUTHORS. * :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
* :license: BSD, see LICENSE for details. * :license: BSD, see LICENSE for details.
* *
*/ */
var stopwords = ["a","and","are","as","at","be","but","by","for","if","in","into","is","it","near","no","not","of","on","or","such","that","the","their","then","there","these","they","this","to","was","will","with"]; var stopwords = ["a", "and", "are", "as", "at", "be", "but", "by", "for", "if", "in", "into", "is", "it", "near", "no", "not", "of", "on", "or", "such", "that", "the", "their", "then", "there", "these", "they", "this", "to", "was", "will", "with"];
/* Non-minified version is copied as a separate JS file, is available */ /* Non-minified version is copied as a separate JS file, is available */
@ -197,101 +197,3 @@ var Stemmer = function() {
} }
} }
var splitChars = (function() {
var result = {};
var singles = [96, 180, 187, 191, 215, 247, 749, 885, 903, 907, 909, 930, 1014, 1648,
1748, 1809, 2416, 2473, 2481, 2526, 2601, 2609, 2612, 2615, 2653, 2702,
2706, 2729, 2737, 2740, 2857, 2865, 2868, 2910, 2928, 2948, 2961, 2971,
2973, 3085, 3089, 3113, 3124, 3213, 3217, 3241, 3252, 3295, 3341, 3345,
3369, 3506, 3516, 3633, 3715, 3721, 3736, 3744, 3748, 3750, 3756, 3761,
3781, 3912, 4239, 4347, 4681, 4695, 4697, 4745, 4785, 4799, 4801, 4823,
4881, 5760, 5901, 5997, 6313, 7405, 8024, 8026, 8028, 8030, 8117, 8125,
8133, 8181, 8468, 8485, 8487, 8489, 8494, 8527, 11311, 11359, 11687, 11695,
11703, 11711, 11719, 11727, 11735, 12448, 12539, 43010, 43014, 43019, 43587,
43696, 43713, 64286, 64297, 64311, 64317, 64319, 64322, 64325, 65141];
var i, j, start, end;
for (i = 0; i < singles.length; i++) {
result[singles[i]] = true;
}
var ranges = [[0, 47], [58, 64], [91, 94], [123, 169], [171, 177], [182, 184], [706, 709],
[722, 735], [741, 747], [751, 879], [888, 889], [894, 901], [1154, 1161],
[1318, 1328], [1367, 1368], [1370, 1376], [1416, 1487], [1515, 1519], [1523, 1568],
[1611, 1631], [1642, 1645], [1750, 1764], [1767, 1773], [1789, 1790], [1792, 1807],
[1840, 1868], [1958, 1968], [1970, 1983], [2027, 2035], [2038, 2041], [2043, 2047],
[2070, 2073], [2075, 2083], [2085, 2087], [2089, 2307], [2362, 2364], [2366, 2383],
[2385, 2391], [2402, 2405], [2419, 2424], [2432, 2436], [2445, 2446], [2449, 2450],
[2483, 2485], [2490, 2492], [2494, 2509], [2511, 2523], [2530, 2533], [2546, 2547],
[2554, 2564], [2571, 2574], [2577, 2578], [2618, 2648], [2655, 2661], [2672, 2673],
[2677, 2692], [2746, 2748], [2750, 2767], [2769, 2783], [2786, 2789], [2800, 2820],
[2829, 2830], [2833, 2834], [2874, 2876], [2878, 2907], [2914, 2917], [2930, 2946],
[2955, 2957], [2966, 2968], [2976, 2978], [2981, 2983], [2987, 2989], [3002, 3023],
[3025, 3045], [3059, 3076], [3130, 3132], [3134, 3159], [3162, 3167], [3170, 3173],
[3184, 3191], [3199, 3204], [3258, 3260], [3262, 3293], [3298, 3301], [3312, 3332],
[3386, 3388], [3390, 3423], [3426, 3429], [3446, 3449], [3456, 3460], [3479, 3481],
[3518, 3519], [3527, 3584], [3636, 3647], [3655, 3663], [3674, 3712], [3717, 3718],
[3723, 3724], [3726, 3731], [3752, 3753], [3764, 3772], [3774, 3775], [3783, 3791],
[3802, 3803], [3806, 3839], [3841, 3871], [3892, 3903], [3949, 3975], [3980, 4095],
[4139, 4158], [4170, 4175], [4182, 4185], [4190, 4192], [4194, 4196], [4199, 4205],
[4209, 4212], [4226, 4237], [4250, 4255], [4294, 4303], [4349, 4351], [4686, 4687],
[4702, 4703], [4750, 4751], [4790, 4791], [4806, 4807], [4886, 4887], [4955, 4968],
[4989, 4991], [5008, 5023], [5109, 5120], [5741, 5742], [5787, 5791], [5867, 5869],
[5873, 5887], [5906, 5919], [5938, 5951], [5970, 5983], [6001, 6015], [6068, 6102],
[6104, 6107], [6109, 6111], [6122, 6127], [6138, 6159], [6170, 6175], [6264, 6271],
[6315, 6319], [6390, 6399], [6429, 6469], [6510, 6511], [6517, 6527], [6572, 6592],
[6600, 6607], [6619, 6655], [6679, 6687], [6741, 6783], [6794, 6799], [6810, 6822],
[6824, 6916], [6964, 6980], [6988, 6991], [7002, 7042], [7073, 7085], [7098, 7167],
[7204, 7231], [7242, 7244], [7294, 7400], [7410, 7423], [7616, 7679], [7958, 7959],
[7966, 7967], [8006, 8007], [8014, 8015], [8062, 8063], [8127, 8129], [8141, 8143],
[8148, 8149], [8156, 8159], [8173, 8177], [8189, 8303], [8306, 8307], [8314, 8318],
[8330, 8335], [8341, 8449], [8451, 8454], [8456, 8457], [8470, 8472], [8478, 8483],
[8506, 8507], [8512, 8516], [8522, 8525], [8586, 9311], [9372, 9449], [9472, 10101],
[10132, 11263], [11493, 11498], [11503, 11516], [11518, 11519], [11558, 11567],
[11622, 11630], [11632, 11647], [11671, 11679], [11743, 11822], [11824, 12292],
[12296, 12320], [12330, 12336], [12342, 12343], [12349, 12352], [12439, 12444],
[12544, 12548], [12590, 12592], [12687, 12689], [12694, 12703], [12728, 12783],
[12800, 12831], [12842, 12880], [12896, 12927], [12938, 12976], [12992, 13311],
[19894, 19967], [40908, 40959], [42125, 42191], [42238, 42239], [42509, 42511],
[42540, 42559], [42592, 42593], [42607, 42622], [42648, 42655], [42736, 42774],
[42784, 42785], [42889, 42890], [42893, 43002], [43043, 43055], [43062, 43071],
[43124, 43137], [43188, 43215], [43226, 43249], [43256, 43258], [43260, 43263],
[43302, 43311], [43335, 43359], [43389, 43395], [43443, 43470], [43482, 43519],
[43561, 43583], [43596, 43599], [43610, 43615], [43639, 43641], [43643, 43647],
[43698, 43700], [43703, 43704], [43710, 43711], [43715, 43738], [43742, 43967],
[44003, 44015], [44026, 44031], [55204, 55215], [55239, 55242], [55292, 55295],
[57344, 63743], [64046, 64047], [64110, 64111], [64218, 64255], [64263, 64274],
[64280, 64284], [64434, 64466], [64830, 64847], [64912, 64913], [64968, 65007],
[65020, 65135], [65277, 65295], [65306, 65312], [65339, 65344], [65371, 65381],
[65471, 65473], [65480, 65481], [65488, 65489], [65496, 65497]];
for (i = 0; i < ranges.length; i++) {
start = ranges[i][0];
end = ranges[i][1];
for (j = start; j <= end; j++) {
result[j] = true;
}
}
return result;
})();
function splitQuery(query) {
var result = [];
var start = -1;
for (var i = 0; i < query.length; i++) {
if (splitChars[query.charCodeAt(i)]) {
if (start !== -1) {
result.push(query.slice(start, i));
start = -1;
}
} else if (start === -1) {
start = i;
}
}
if (start !== -1) {
result.push(query.slice(start));
}
return result;
}

View File

@ -4,22 +4,24 @@
* *
* Sphinx JavaScript utilities for the full-text search. * Sphinx JavaScript utilities for the full-text search.
* *
* :copyright: Copyright 2007-2021 by the Sphinx team, see AUTHORS. * :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
* :license: BSD, see LICENSE for details. * :license: BSD, see LICENSE for details.
* *
*/ */
"use strict";
if (!Scorer) { /**
/** * Simple result scoring code.
* Simple result scoring code. */
*/ if (typeof Scorer === "undefined") {
var Scorer = { var Scorer = {
// Implement the following function to further tweak the score for each result // Implement the following function to further tweak the score for each result
// The function takes a result array [filename, title, anchor, descr, score] // The function takes a result array [docname, title, anchor, descr, score, filename]
// and returns the new score. // and returns the new score.
/* /*
score: function(result) { score: result => {
return result[4]; const [docname, title, anchor, descr, score, filename] = result
return score
}, },
*/ */
@ -28,9 +30,11 @@ if (!Scorer) {
// or matches in the last dotted part of the object name // or matches in the last dotted part of the object name
objPartialMatch: 6, objPartialMatch: 6,
// Additive scores depending on the priority of the object // Additive scores depending on the priority of the object
objPrio: {0: 15, // used to be importantResults objPrio: {
1: 5, // used to be objectResults 0: 15, // used to be importantResults
2: -5}, // used to be unimportantResults 1: 5, // used to be objectResults
2: -5, // used to be unimportantResults
},
// Used when the priority is not in the mapping. // Used when the priority is not in the mapping.
objPrioDefault: 0, objPrioDefault: 0,
@ -39,452 +43,495 @@ if (!Scorer) {
partialTitle: 7, partialTitle: 7,
// query found in terms // query found in terms
term: 5, term: 5,
partialTerm: 2 partialTerm: 2,
}; };
} }
if (!splitQuery) { const _removeChildren = (element) => {
function splitQuery(query) { while (element && element.lastChild) element.removeChild(element.lastChild);
return query.split(/\s+/); };
/**
* See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions#escaping
*/
const _escapeRegExp = (string) =>
string.replace(/[.*+\-?^${}()|[\]\\]/g, "\\$&"); // $& means the whole matched string
const _displayItem = (item, searchTerms) => {
const docBuilder = DOCUMENTATION_OPTIONS.BUILDER;
const docUrlRoot = DOCUMENTATION_OPTIONS.URL_ROOT;
const docFileSuffix = DOCUMENTATION_OPTIONS.FILE_SUFFIX;
const docLinkSuffix = DOCUMENTATION_OPTIONS.LINK_SUFFIX;
const showSearchSummary = DOCUMENTATION_OPTIONS.SHOW_SEARCH_SUMMARY;
const [docName, title, anchor, descr, score, _filename] = item;
let listItem = document.createElement("li");
let requestUrl;
let linkUrl;
if (docBuilder === "dirhtml") {
// dirhtml builder
let dirname = docName + "/";
if (dirname.match(/\/index\/$/))
dirname = dirname.substring(0, dirname.length - 6);
else if (dirname === "index/") dirname = "";
requestUrl = docUrlRoot + dirname;
linkUrl = requestUrl;
} else {
// normal html builders
requestUrl = docUrlRoot + docName + docFileSuffix;
linkUrl = docName + docLinkSuffix;
} }
let linkEl = listItem.appendChild(document.createElement("a"));
linkEl.href = linkUrl + anchor;
linkEl.dataset.score = score;
linkEl.innerHTML = title;
if (descr)
listItem.appendChild(document.createElement("span")).innerHTML =
" (" + descr + ")";
else if (showSearchSummary)
fetch(requestUrl)
.then((responseData) => responseData.text())
.then((data) => {
if (data)
listItem.appendChild(
Search.makeSearchSummary(data, searchTerms)
);
});
Search.output.appendChild(listItem);
};
const _finishSearch = (resultCount) => {
Search.stopPulse();
Search.title.innerText = _("Search Results");
if (!resultCount)
Search.status.innerText = Documentation.gettext(
"Your search did not match any documents. Please make sure that all words are spelled correctly and that you've selected enough categories."
);
else
Search.status.innerText = _(
`Search finished, found ${resultCount} page(s) matching the search query.`
);
};
const _displayNextItem = (
results,
resultCount,
searchTerms
) => {
// results left, load the summary and display it
// this is intended to be dynamic (don't sub resultsCount)
if (results.length) {
_displayItem(results.pop(), searchTerms);
setTimeout(
() => _displayNextItem(results, resultCount, searchTerms),
5
);
}
// search finished, update title and status message
else _finishSearch(resultCount);
};
/**
* Default splitQuery function. Can be overridden in ``sphinx.search`` with a
* custom function per language.
*
* The regular expression works by splitting the string on consecutive characters
* that are not Unicode letters, numbers, underscores, or emoji characters.
* This is the same as ``\W+`` in Python, preserving the surrogate pair area.
*/
if (typeof splitQuery === "undefined") {
var splitQuery = (query) => query
.split(/[^\p{Letter}\p{Number}_\p{Emoji_Presentation}]+/gu)
.filter(term => term) // remove remaining empty strings
} }
/** /**
* Search Module * Search Module
*/ */
var Search = { const Search = {
_index: null,
_queued_query: null,
_pulse_status: -1,
_index : null, htmlToText: (htmlString) => {
_queued_query : null, const htmlElement = new DOMParser().parseFromString(htmlString, 'text/html');
_pulse_status : -1, htmlElement.querySelectorAll(".headerlink").forEach((el) => { el.remove() });
const docContent = htmlElement.querySelector('[role="main"]');
htmlToText : function(htmlString) { if (docContent !== undefined) return docContent.textContent;
var virtualDocument = document.implementation.createHTMLDocument('virtual'); console.warn(
var htmlElement = $(htmlString, virtualDocument); "Content block not found. Sphinx search tries to obtain it via '[role=main]'. Could you check your theme or template."
htmlElement.find('.headerlink').remove(); );
docContent = htmlElement.find('[role=main]')[0]; return "";
if(docContent === undefined) {
console.warn("Content block not found. Sphinx search tries to obtain it " +
"via '[role=main]'. Could you check your theme or template.");
return "";
}
return docContent.textContent || docContent.innerText;
}, },
init : function() { init: () => {
var params = $.getQueryParameters(); const query = new URLSearchParams(window.location.search).get("q");
if (params.q) { document
var query = params.q[0]; .querySelectorAll('input[name="q"]')
$('input[name="q"]')[0].value = query; .forEach((el) => (el.value = query));
this.performSearch(query); if (query) Search.performSearch(query);
}
}, },
loadIndex : function(url) { loadIndex: (url) =>
$.ajax({type: "GET", url: url, data: null, (document.body.appendChild(document.createElement("script")).src = url),
dataType: "script", cache: true,
complete: function(jqxhr, textstatus) {
if (textstatus != "success") {
document.getElementById("searchindexloader").src = url;
}
}});
},
setIndex : function(index) { setIndex: (index) => {
var q; Search._index = index;
this._index = index; if (Search._queued_query !== null) {
if ((q = this._queued_query) !== null) { const query = Search._queued_query;
this._queued_query = null; Search._queued_query = null;
Search.query(q); Search.query(query);
} }
}, },
hasIndex : function() { hasIndex: () => Search._index !== null,
return this._index !== null;
},
deferQuery : function(query) { deferQuery: (query) => (Search._queued_query = query),
this._queued_query = query;
},
stopPulse : function() { stopPulse: () => (Search._pulse_status = -1),
this._pulse_status = 0;
},
startPulse : function() { startPulse: () => {
if (this._pulse_status >= 0) if (Search._pulse_status >= 0) return;
return;
function pulse() { const pulse = () => {
var i;
Search._pulse_status = (Search._pulse_status + 1) % 4; Search._pulse_status = (Search._pulse_status + 1) % 4;
var dotString = ''; Search.dots.innerText = ".".repeat(Search._pulse_status);
for (i = 0; i < Search._pulse_status; i++) if (Search._pulse_status >= 0) window.setTimeout(pulse, 500);
dotString += '.'; };
Search.dots.text(dotString);
if (Search._pulse_status > -1)
window.setTimeout(pulse, 500);
}
pulse(); pulse();
}, },
/** /**
* perform a search for something (or wait until index is loaded) * perform a search for something (or wait until index is loaded)
*/ */
performSearch : function(query) { performSearch: (query) => {
// create the required interface elements // create the required interface elements
this.out = $('#search-results'); const searchText = document.createElement("h2");
this.title = $('<h2>' + _('Searching') + '</h2>').appendTo(this.out); searchText.textContent = _("Searching");
this.dots = $('<span></span>').appendTo(this.title); const searchSummary = document.createElement("p");
this.status = $('<p class="search-summary">&nbsp;</p>').appendTo(this.out); searchSummary.classList.add("search-summary");
this.output = $('<ul class="search"/>').appendTo(this.out); searchSummary.innerText = "";
const searchList = document.createElement("ul");
searchList.classList.add("search");
$('#search-progress').text(_('Preparing search...')); const out = document.getElementById("search-results");
this.startPulse(); Search.title = out.appendChild(searchText);
Search.dots = Search.title.appendChild(document.createElement("span"));
Search.status = out.appendChild(searchSummary);
Search.output = out.appendChild(searchList);
const searchProgress = document.getElementById("search-progress");
// Some themes don't use the search progress node
if (searchProgress) {
searchProgress.innerText = _("Preparing search...");
}
Search.startPulse();
// index already loaded, the browser was quick! // index already loaded, the browser was quick!
if (this.hasIndex()) if (Search.hasIndex()) Search.query(query);
this.query(query); else Search.deferQuery(query);
else
this.deferQuery(query);
}, },
/** /**
* execute search (requires search index to be loaded) * execute search (requires search index to be loaded)
*/ */
query : function(query) { query: (query) => {
var i; const filenames = Search._index.filenames;
const docNames = Search._index.docnames;
const titles = Search._index.titles;
const allTitles = Search._index.alltitles;
const indexEntries = Search._index.indexentries;
// stem the searchterms and add them to the correct list // stem the search terms and add them to the correct list
var stemmer = new Stemmer(); const stemmer = new Stemmer();
var searchterms = []; const searchTerms = new Set();
var excluded = []; const excludedTerms = new Set();
var hlterms = []; const highlightTerms = new Set();
var tmp = splitQuery(query); const objectTerms = new Set(splitQuery(query.toLowerCase().trim()));
var objectterms = []; splitQuery(query.trim()).forEach((queryTerm) => {
for (i = 0; i < tmp.length; i++) { const queryTermLower = queryTerm.toLowerCase();
if (tmp[i] !== "") {
objectterms.push(tmp[i].toLowerCase()); // maybe skip this "word"
} // stopwords array is from language_data.js
if (
stopwords.indexOf(queryTermLower) !== -1 ||
queryTerm.match(/^\d+$/)
)
return;
if ($u.indexOf(stopwords, tmp[i].toLowerCase()) != -1 || tmp[i] === "") {
// skip this "word"
continue;
}
// stem the word // stem the word
var word = stemmer.stemWord(tmp[i].toLowerCase()); let word = stemmer.stemWord(queryTermLower);
// prevent stemmer from cutting word smaller than two chars
if(word.length < 3 && tmp[i].length >= 3) {
word = tmp[i];
}
var toAppend;
// select the correct list // select the correct list
if (word[0] == '-') { if (word[0] === "-") excludedTerms.add(word.substr(1));
toAppend = excluded;
word = word.substr(1);
}
else { else {
toAppend = searchterms; searchTerms.add(word);
hlterms.push(tmp[i].toLowerCase()); highlightTerms.add(queryTermLower);
} }
// only add if not already in the list });
if (!$u.contains(toAppend, word))
toAppend.push(word); if (SPHINX_HIGHLIGHT_ENABLED) { // set in sphinx_highlight.js
localStorage.setItem("sphinx_highlight_terms", [...highlightTerms].join(" "))
} }
var highlightstring = '?highlight=' + $.urlencode(hlterms.join(" "));
// console.debug('SEARCH: searching for:'); // console.debug("SEARCH: searching for:");
// console.info('required: ', searchterms); // console.info("required: ", [...searchTerms]);
// console.info('excluded: ', excluded); // console.info("excluded: ", [...excludedTerms]);
// prepare search // array of [docname, title, anchor, descr, score, filename]
var terms = this._index.terms; let results = [];
var titleterms = this._index.titleterms; _removeChildren(document.getElementById("search-progress"));
// array of [filename, title, anchor, descr, score] const queryLower = query.toLowerCase();
var results = []; for (const [title, foundTitles] of Object.entries(allTitles)) {
$('#search-progress').empty(); if (title.toLowerCase().includes(queryLower) && (queryLower.length >= title.length/2)) {
for (const [file, id] of foundTitles) {
let score = Math.round(100 * queryLower.length / title.length)
results.push([
docNames[file],
titles[file] !== title ? `${titles[file]} > ${title}` : title,
id !== null ? "#" + id : "",
null,
score,
filenames[file],
]);
}
}
}
// search for explicit entries in index directives
for (const [entry, foundEntries] of Object.entries(indexEntries)) {
if (entry.includes(queryLower) && (queryLower.length >= entry.length/2)) {
for (const [file, id] of foundEntries) {
let score = Math.round(100 * queryLower.length / entry.length)
results.push([
docNames[file],
titles[file],
id ? "#" + id : "",
null,
score,
filenames[file],
]);
}
}
}
// lookup as object // lookup as object
for (i = 0; i < objectterms.length; i++) { objectTerms.forEach((term) =>
var others = [].concat(objectterms.slice(0, i), results.push(...Search.performObjectSearch(term, objectTerms))
objectterms.slice(i+1, objectterms.length)); );
results = results.concat(this.performObjectSearch(objectterms[i], others));
}
// lookup as search terms in fulltext // lookup as search terms in fulltext
results = results.concat(this.performTermsSearch(searchterms, excluded, terms, titleterms)); results.push(...Search.performTermsSearch(searchTerms, excludedTerms));
// let the scorer override scores with a custom scoring function // let the scorer override scores with a custom scoring function
if (Scorer.score) { if (Scorer.score) results.forEach((item) => (item[4] = Scorer.score(item)));
for (i = 0; i < results.length; i++)
results[i][4] = Scorer.score(results[i]);
}
// now sort the results by score (in opposite order of appearance, since the // now sort the results by score (in opposite order of appearance, since the
// display function below uses pop() to retrieve items) and then // display function below uses pop() to retrieve items) and then
// alphabetically // alphabetically
results.sort(function(a, b) { results.sort((a, b) => {
var left = a[4]; const leftScore = a[4];
var right = b[4]; const rightScore = b[4];
if (left > right) { if (leftScore === rightScore) {
return 1;
} else if (left < right) {
return -1;
} else {
// same score: sort alphabetically // same score: sort alphabetically
left = a[1].toLowerCase(); const leftTitle = a[1].toLowerCase();
right = b[1].toLowerCase(); const rightTitle = b[1].toLowerCase();
return (left > right) ? -1 : ((left < right) ? 1 : 0); if (leftTitle === rightTitle) return 0;
return leftTitle > rightTitle ? -1 : 1; // inverted is intentional
} }
return leftScore > rightScore ? 1 : -1;
}); });
// remove duplicate search results
// note the reversing of results, so that in the case of duplicates, the highest-scoring entry is kept
let seen = new Set();
results = results.reverse().reduce((acc, result) => {
let resultStr = result.slice(0, 4).concat([result[5]]).map(v => String(v)).join(',');
if (!seen.has(resultStr)) {
acc.push(result);
seen.add(resultStr);
}
return acc;
}, []);
results = results.reverse();
// for debugging // for debugging
//Search.lastresults = results.slice(); // a copy //Search.lastresults = results.slice(); // a copy
//console.info('search results:', Search.lastresults); // console.info("search results:", Search.lastresults);
// print the results // print the results
var resultCount = results.length; _displayNextItem(results, results.length, searchTerms);
function displayNextItem() {
// results left, load the summary and display it
if (results.length) {
var item = results.pop();
var listItem = $('<li></li>');
var requestUrl = "";
var linkUrl = "";
if (DOCUMENTATION_OPTIONS.BUILDER === 'dirhtml') {
// dirhtml builder
var dirname = item[0] + '/';
if (dirname.match(/\/index\/$/)) {
dirname = dirname.substring(0, dirname.length-6);
} else if (dirname == 'index/') {
dirname = '';
}
requestUrl = DOCUMENTATION_OPTIONS.URL_ROOT + dirname;
linkUrl = requestUrl;
} else {
// normal html builders
requestUrl = DOCUMENTATION_OPTIONS.URL_ROOT + item[0] + DOCUMENTATION_OPTIONS.FILE_SUFFIX;
linkUrl = item[0] + DOCUMENTATION_OPTIONS.LINK_SUFFIX;
}
listItem.append($('<a/>').attr('href',
linkUrl +
highlightstring + item[2]).html(item[1]));
if (item[3]) {
listItem.append($('<span> (' + item[3] + ')</span>'));
Search.output.append(listItem);
setTimeout(function() {
displayNextItem();
}, 5);
} else if (DOCUMENTATION_OPTIONS.HAS_SOURCE) {
$.ajax({url: requestUrl,
dataType: "text",
complete: function(jqxhr, textstatus) {
var data = jqxhr.responseText;
if (data !== '' && data !== undefined) {
listItem.append(Search.makeSearchSummary(data, searchterms, hlterms));
}
Search.output.append(listItem);
setTimeout(function() {
displayNextItem();
}, 5);
}});
} else {
// no source available, just display title
Search.output.append(listItem);
setTimeout(function() {
displayNextItem();
}, 5);
}
}
// search finished, update title and status message
else {
Search.stopPulse();
Search.title.text(_('Search Results'));
if (!resultCount)
Search.status.text(_('Your search did not match any documents. Please make sure that all words are spelled correctly and that you\'ve selected enough categories.'));
else
Search.status.text(_('Search finished, found %s page(s) matching the search query.').replace('%s', resultCount));
Search.status.fadeIn(500);
}
}
displayNextItem();
}, },
/** /**
* search for object names * search for object names
*/ */
performObjectSearch : function(object, otherterms) { performObjectSearch: (object, objectTerms) => {
var filenames = this._index.filenames; const filenames = Search._index.filenames;
var docnames = this._index.docnames; const docNames = Search._index.docnames;
var objects = this._index.objects; const objects = Search._index.objects;
var objnames = this._index.objnames; const objNames = Search._index.objnames;
var titles = this._index.titles; const titles = Search._index.titles;
var i; const results = [];
var results = [];
for (var prefix in objects) { const objectSearchCallback = (prefix, match) => {
for (var name in objects[prefix]) { const name = match[4]
var fullname = (prefix ? prefix + '.' : '') + name; const fullname = (prefix ? prefix + "." : "") + name;
var fullnameLower = fullname.toLowerCase() const fullnameLower = fullname.toLowerCase();
if (fullnameLower.indexOf(object) > -1) { if (fullnameLower.indexOf(object) < 0) return;
var score = 0;
var parts = fullnameLower.split('.');
// check for different match types: exact matches of full name or
// "last name" (i.e. last dotted part)
if (fullnameLower == object || parts[parts.length - 1] == object) {
score += Scorer.objNameMatch;
// matches in last name
} else if (parts[parts.length - 1].indexOf(object) > -1) {
score += Scorer.objPartialMatch;
}
var match = objects[prefix][name];
var objname = objnames[match[1]][2];
var title = titles[match[0]];
// If more than one term searched for, we require other words to be
// found in the name/title/description
if (otherterms.length > 0) {
var haystack = (prefix + ' ' + name + ' ' +
objname + ' ' + title).toLowerCase();
var allfound = true;
for (i = 0; i < otherterms.length; i++) {
if (haystack.indexOf(otherterms[i]) == -1) {
allfound = false;
break;
}
}
if (!allfound) {
continue;
}
}
var descr = objname + _(', in ') + title;
var anchor = match[3]; let score = 0;
if (anchor === '') const parts = fullnameLower.split(".");
anchor = fullname;
else if (anchor == '-') // check for different match types: exact matches of full name or
anchor = objnames[match[1]][1] + '-' + fullname; // "last name" (i.e. last dotted part)
// add custom score for some objects according to scorer if (fullnameLower === object || parts.slice(-1)[0] === object)
if (Scorer.objPrio.hasOwnProperty(match[2])) { score += Scorer.objNameMatch;
score += Scorer.objPrio[match[2]]; else if (parts.slice(-1)[0].indexOf(object) > -1)
} else { score += Scorer.objPartialMatch; // matches in last name
score += Scorer.objPrioDefault;
} const objName = objNames[match[1]][2];
results.push([docnames[match[0]], fullname, '#'+anchor, descr, score, filenames[match[0]]]); const title = titles[match[0]];
}
// If more than one term searched for, we require other words to be
// found in the name/title/description
const otherTerms = new Set(objectTerms);
otherTerms.delete(object);
if (otherTerms.size > 0) {
const haystack = `${prefix} ${name} ${objName} ${title}`.toLowerCase();
if (
[...otherTerms].some((otherTerm) => haystack.indexOf(otherTerm) < 0)
)
return;
} }
}
let anchor = match[3];
if (anchor === "") anchor = fullname;
else if (anchor === "-") anchor = objNames[match[1]][1] + "-" + fullname;
const descr = objName + _(", in ") + title;
// add custom score for some objects according to scorer
if (Scorer.objPrio.hasOwnProperty(match[2]))
score += Scorer.objPrio[match[2]];
else score += Scorer.objPrioDefault;
results.push([
docNames[match[0]],
fullname,
"#" + anchor,
descr,
score,
filenames[match[0]],
]);
};
Object.keys(objects).forEach((prefix) =>
objects[prefix].forEach((array) =>
objectSearchCallback(prefix, array)
)
);
return results; return results;
}, },
/**
* See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions
*/
escapeRegExp : function(string) {
return string.replace(/[.*+\-?^${}()|[\]\\]/g, '\\$&'); // $& means the whole matched string
},
/** /**
* search for full-text terms in the index * search for full-text terms in the index
*/ */
performTermsSearch : function(searchterms, excluded, terms, titleterms) { performTermsSearch: (searchTerms, excludedTerms) => {
var docnames = this._index.docnames; // prepare search
var filenames = this._index.filenames; const terms = Search._index.terms;
var titles = this._index.titles; const titleTerms = Search._index.titleterms;
const filenames = Search._index.filenames;
const docNames = Search._index.docnames;
const titles = Search._index.titles;
var i, j, file; const scoreMap = new Map();
var fileMap = {}; const fileMap = new Map();
var scoreMap = {};
var results = [];
// perform the search on the required terms // perform the search on the required terms
for (i = 0; i < searchterms.length; i++) { searchTerms.forEach((word) => {
var word = searchterms[i]; const files = [];
var files = []; const arr = [
var _o = [ { files: terms[word], score: Scorer.term },
{files: terms[word], score: Scorer.term}, { files: titleTerms[word], score: Scorer.title },
{files: titleterms[word], score: Scorer.title}
]; ];
// add support for partial matches // add support for partial matches
if (word.length > 2) { if (word.length > 2) {
var word_regex = this.escapeRegExp(word); const escapedWord = _escapeRegExp(word);
for (var w in terms) { Object.keys(terms).forEach((term) => {
if (w.match(word_regex) && !terms[word]) { if (term.match(escapedWord) && !terms[word])
_o.push({files: terms[w], score: Scorer.partialTerm}) arr.push({ files: terms[term], score: Scorer.partialTerm });
} });
} Object.keys(titleTerms).forEach((term) => {
for (var w in titleterms) { if (term.match(escapedWord) && !titleTerms[word])
if (w.match(word_regex) && !titleterms[word]) { arr.push({ files: titleTerms[word], score: Scorer.partialTitle });
_o.push({files: titleterms[w], score: Scorer.partialTitle}) });
}
}
} }
// no match but word was a required one // no match but word was a required one
if ($u.every(_o, function(o){return o.files === undefined;})) { if (arr.every((record) => record.files === undefined)) return;
break;
}
// found search word in contents // found search word in contents
$u.each(_o, function(o) { arr.forEach((record) => {
var _files = o.files; if (record.files === undefined) return;
if (_files === undefined)
return
if (_files.length === undefined) let recordFiles = record.files;
_files = [_files]; if (recordFiles.length === undefined) recordFiles = [recordFiles];
files = files.concat(_files); files.push(...recordFiles);
// set score for the word in each file to Scorer.term // set score for the word in each file
for (j = 0; j < _files.length; j++) { recordFiles.forEach((file) => {
file = _files[j]; if (!scoreMap.has(file)) scoreMap.set(file, {});
if (!(file in scoreMap)) scoreMap.get(file)[word] = record.score;
scoreMap[file] = {}; });
scoreMap[file][word] = o.score;
}
}); });
// create the mapping // create the mapping
for (j = 0; j < files.length; j++) { files.forEach((file) => {
file = files[j]; if (fileMap.has(file) && fileMap.get(file).indexOf(word) === -1)
if (file in fileMap && fileMap[file].indexOf(word) === -1) fileMap.get(file).push(word);
fileMap[file].push(word); else fileMap.set(file, [word]);
else });
fileMap[file] = [word]; });
}
}
// now check if the files don't contain excluded terms // now check if the files don't contain excluded terms
for (file in fileMap) { const results = [];
var valid = true; for (const [file, wordList] of fileMap) {
// check if all requirements are matched // check if all requirements are matched
var filteredTermCount = // as search terms with length < 3 are discarded: ignore
searchterms.filter(function(term){return term.length > 2}).length // as search terms with length < 3 are discarded
const filteredTermCount = [...searchTerms].filter(
(term) => term.length > 2
).length;
if ( if (
fileMap[file].length != searchterms.length && wordList.length !== searchTerms.size &&
fileMap[file].length != filteredTermCount wordList.length !== filteredTermCount
) continue; )
continue;
// ensure that none of the excluded terms is in the search result // ensure that none of the excluded terms is in the search result
for (i = 0; i < excluded.length; i++) { if (
if (terms[excluded[i]] == file || [...excludedTerms].some(
titleterms[excluded[i]] == file || (term) =>
$u.contains(terms[excluded[i]] || [], file) || terms[term] === file ||
$u.contains(titleterms[excluded[i]] || [], file)) { titleTerms[term] === file ||
valid = false; (terms[term] || []).includes(file) ||
break; (titleTerms[term] || []).includes(file)
} )
} )
break;
// if we have still a valid result we can add it to the result list // select one (max) score for the file.
if (valid) { const score = Math.max(...wordList.map((w) => scoreMap.get(file)[w]));
// select one (max) score for the file. // add result to the result list
// for better ranking, we should calculate ranking by using words statistics like basic tf-idf... results.push([
var score = $u.max($u.map(fileMap[file], function(w){return scoreMap[file][w]})); docNames[file],
results.push([docnames[file], titles[file], '', null, score, filenames[file]]); titles[file],
} "",
null,
score,
filenames[file],
]);
} }
return results; return results;
}, },
@ -492,31 +539,28 @@ var Search = {
/** /**
* helper function to return a node containing the * helper function to return a node containing the
* search summary for a given text. keywords is a list * search summary for a given text. keywords is a list
* of stemmed words, hlwords is the list of normal, unstemmed * of stemmed words.
* words. the first one is used to find the occurrence, the
* latter for highlighting it.
*/ */
makeSearchSummary : function(htmlText, keywords, hlwords) { makeSearchSummary: (htmlText, keywords) => {
var text = Search.htmlToText(htmlText); const text = Search.htmlToText(htmlText);
var textLower = text.toLowerCase(); if (text === "") return null;
var start = 0;
$.each(keywords, function() { const textLower = text.toLowerCase();
var i = textLower.indexOf(this.toLowerCase()); const actualStartPosition = [...keywords]
if (i > -1) .map((k) => textLower.indexOf(k.toLowerCase()))
start = i; .filter((i) => i > -1)
}); .slice(-1)[0];
start = Math.max(start - 120, 0); const startWithContext = Math.max(actualStartPosition - 120, 0);
var excerpt = ((start > 0) ? '...' : '') +
$.trim(text.substr(start, 240)) + const top = startWithContext === 0 ? "" : "...";
((start + 240 - text.length) ? '...' : ''); const tail = startWithContext + 240 < text.length ? "..." : "";
var rv = $('<p class="context"></p>').text(excerpt);
$.each(hlwords, function() { let summary = document.createElement("p");
rv = rv.highlightText(this, 'highlighted'); summary.classList.add("context");
}); summary.textContent = top + text.substr(startWithContext, 240).trim() + tail;
return rv;
} return summary;
},
}; };
$(document).ready(function() { _ready(Search.init);
Search.init();
});

View File

@ -16,144 +16,55 @@
* Once the browser is closed the cookie is deleted and the position * Once the browser is closed the cookie is deleted and the position
* reset to the default (expanded). * reset to the default (expanded).
* *
* :copyright: Copyright 2007-2021 by the Sphinx team, see AUTHORS. * :copyright: Copyright 2007-2022 by the Sphinx team, see AUTHORS.
* :license: BSD, see LICENSE for details. * :license: BSD, see LICENSE for details.
* *
*/ */
$(function() { const initialiseSidebar = () => {
// global elements used by the functions. // global elements used by the functions.
// the 'sidebarbutton' element is defined as global after its const bodyWrapper = document.getElementsByClassName("bodywrapper")[0]
// creation, in the add_sidebar_button function const sidebar = document.getElementsByClassName("sphinxsidebar")[0]
var bodywrapper = $('.bodywrapper'); const sidebarWrapper = document.getElementsByClassName('sphinxsidebarwrapper')[0]
var sidebar = $('.sphinxsidebar'); const sidebarButton = document.getElementById("sidebarbutton")
var sidebarwrapper = $('.sphinxsidebarwrapper'); const sidebarArrow = sidebarButton.querySelector('span')
// for some reason, the document has no sidebar; do not run into errors // for some reason, the document has no sidebar; do not run into errors
if (!sidebar.length) return; if (typeof sidebar === "undefined") return;
// original margin-left of the bodywrapper and width of the sidebar const flipArrow = element => element.innerText = (element.innerText === "»") ? "«" : "»"
// with the sidebar expanded
var bw_margin_expanded = bodywrapper.css('margin-left');
var ssb_width_expanded = sidebar.width();
// margin-left of the bodywrapper and width of the sidebar const collapse_sidebar = () => {
// with the sidebar collapsed bodyWrapper.style.marginLeft = ".8em";
var bw_margin_collapsed = '.8em'; sidebar.style.width = ".8em"
var ssb_width_collapsed = '.8em'; sidebarWrapper.style.display = "none"
flipArrow(sidebarArrow)
// colors used by the current theme sidebarButton.title = _('Expand sidebar')
var dark_color = $('.related').css('background-color'); window.localStorage.setItem("sidebar", "collapsed")
var light_color = $('.document').css('background-color');
function sidebar_is_collapsed() {
return sidebarwrapper.is(':not(:visible)');
} }
function toggle_sidebar() { const expand_sidebar = () => {
if (sidebar_is_collapsed()) bodyWrapper.style.marginLeft = ""
expand_sidebar(); sidebar.style.removeProperty("width")
else sidebarWrapper.style.display = ""
collapse_sidebar(); flipArrow(sidebarArrow)
sidebarButton.title = _('Collapse sidebar')
window.localStorage.setItem("sidebar", "expanded")
} }
function collapse_sidebar() { sidebarButton.addEventListener("click", () => {
sidebarwrapper.hide(); (sidebarWrapper.style.display === "none") ? expand_sidebar() : collapse_sidebar()
sidebar.css('width', ssb_width_collapsed); })
bodywrapper.css('margin-left', bw_margin_collapsed);
sidebarbutton.css({
'margin-left': '0',
'height': bodywrapper.height()
});
sidebarbutton.find('span').text('»');
sidebarbutton.attr('title', _('Expand sidebar'));
document.cookie = 'sidebar=collapsed';
}
function expand_sidebar() { if (!window.localStorage.getItem("sidebar")) return
bodywrapper.css('margin-left', bw_margin_expanded); const value = window.localStorage.getItem("sidebar")
sidebar.css('width', ssb_width_expanded); if (value === "collapsed") collapse_sidebar();
sidebarwrapper.show(); else if (value === "expanded") expand_sidebar();
sidebarbutton.css({ }
'margin-left': ssb_width_expanded-12,
'height': bodywrapper.height()
});
sidebarbutton.find('span').text('«');
sidebarbutton.attr('title', _('Collapse sidebar'));
document.cookie = 'sidebar=expanded';
}
function add_sidebar_button() { if (document.readyState !== "loading") initialiseSidebar()
sidebarwrapper.css({ else document.addEventListener("DOMContentLoaded", initialiseSidebar)
'float': 'left',
'margin-right': '0',
'width': ssb_width_expanded - 28
});
// create the button
sidebar.append(
'<div id="sidebarbutton"><span>&laquo;</span></div>'
);
var sidebarbutton = $('#sidebarbutton');
light_color = sidebarbutton.css('background-color');
// find the height of the viewport to center the '<<' in the page
var viewport_height;
if (window.innerHeight)
viewport_height = window.innerHeight;
else
viewport_height = $(window).height();
sidebarbutton.find('span').css({
'display': 'block',
'margin-top': (viewport_height - sidebar.position().top - 20) / 2
});
sidebarbutton.click(toggle_sidebar);
sidebarbutton.attr('title', _('Collapse sidebar'));
sidebarbutton.css({
'color': '#FFFFFF',
'border-left': '1px solid ' + dark_color,
'font-size': '1.2em',
'cursor': 'pointer',
'height': bodywrapper.height(),
'padding-top': '1px',
'margin-left': ssb_width_expanded - 12
});
sidebarbutton.hover(
function () {
$(this).css('background-color', dark_color);
},
function () {
$(this).css('background-color', light_color);
}
);
}
function set_position_from_cookie() {
if (!document.cookie)
return;
var items = document.cookie.split(';');
for(var k=0; k<items.length; k++) {
var key_val = items[k].split('=');
var key = key_val[0].replace(/ /, ""); // strip leading spaces
if (key == 'sidebar') {
var value = key_val[1];
if ((value == 'collapsed') && (!sidebar_is_collapsed()))
collapse_sidebar();
else if ((value == 'expanded') && (sidebar_is_collapsed()))
expand_sidebar();
}
}
}
add_sidebar_button();
var sidebarbutton = $('#sidebarbutton');
set_position_from_cookie();
});

View File

@ -0,0 +1,144 @@
/* Highlighting utilities for Sphinx HTML documentation. */
"use strict";
const SPHINX_HIGHLIGHT_ENABLED = true
/**
* highlight a given string on a node by wrapping it in
* span elements with the given class name.
*/
const _highlight = (node, addItems, text, className) => {
if (node.nodeType === Node.TEXT_NODE) {
const val = node.nodeValue;
const parent = node.parentNode;
const pos = val.toLowerCase().indexOf(text);
if (
pos >= 0 &&
!parent.classList.contains(className) &&
!parent.classList.contains("nohighlight")
) {
let span;
const closestNode = parent.closest("body, svg, foreignObject");
const isInSVG = closestNode && closestNode.matches("svg");
if (isInSVG) {
span = document.createElementNS("http://www.w3.org/2000/svg", "tspan");
} else {
span = document.createElement("span");
span.classList.add(className);
}
span.appendChild(document.createTextNode(val.substr(pos, text.length)));
parent.insertBefore(
span,
parent.insertBefore(
document.createTextNode(val.substr(pos + text.length)),
node.nextSibling
)
);
node.nodeValue = val.substr(0, pos);
if (isInSVG) {
const rect = document.createElementNS(
"http://www.w3.org/2000/svg",
"rect"
);
const bbox = parent.getBBox();
rect.x.baseVal.value = bbox.x;
rect.y.baseVal.value = bbox.y;
rect.width.baseVal.value = bbox.width;
rect.height.baseVal.value = bbox.height;
rect.setAttribute("class", className);
addItems.push({ parent: parent, target: rect });
}
}
} else if (node.matches && !node.matches("button, select, textarea")) {
node.childNodes.forEach((el) => _highlight(el, addItems, text, className));
}
};
const _highlightText = (thisNode, text, className) => {
let addItems = [];
_highlight(thisNode, addItems, text, className);
addItems.forEach((obj) =>
obj.parent.insertAdjacentElement("beforebegin", obj.target)
);
};
/**
* Small JavaScript module for the documentation.
*/
const SphinxHighlight = {
/**
* highlight the search words provided in localstorage in the text
*/
highlightSearchWords: () => {
if (!SPHINX_HIGHLIGHT_ENABLED) return; // bail if no highlight
// get and clear terms from localstorage
const url = new URL(window.location);
const highlight =
localStorage.getItem("sphinx_highlight_terms")
|| url.searchParams.get("highlight")
|| "";
localStorage.removeItem("sphinx_highlight_terms")
url.searchParams.delete("highlight");
window.history.replaceState({}, "", url);
// get individual terms from highlight string
const terms = highlight.toLowerCase().split(/\s+/).filter(x => x);
if (terms.length === 0) return; // nothing to do
// There should never be more than one element matching "div.body"
const divBody = document.querySelectorAll("div.body");
const body = divBody.length ? divBody[0] : document.querySelector("body");
window.setTimeout(() => {
terms.forEach((term) => _highlightText(body, term, "highlighted"));
}, 10);
const searchBox = document.getElementById("searchbox");
if (searchBox === null) return;
searchBox.appendChild(
document
.createRange()
.createContextualFragment(
'<p class="highlight-link">' +
'<a href="javascript:SphinxHighlight.hideSearchWords()">' +
_("Hide Search Matches") +
"</a></p>"
)
);
},
/**
* helper function to hide the search marks again
*/
hideSearchWords: () => {
document
.querySelectorAll("#searchbox .highlight-link")
.forEach((el) => el.remove());
document
.querySelectorAll("span.highlighted")
.forEach((el) => el.classList.remove("highlighted"));
localStorage.removeItem("sphinx_highlight_terms")
},
initEscapeListener: () => {
// only install a listener if it is really needed
if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) return;
document.addEventListener("keydown", (event) => {
// bail for input elements
if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName)) return;
// bail with special keys
if (event.shiftKey || event.altKey || event.ctrlKey || event.metaKey) return;
if (DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS && (event.key === "Escape")) {
SphinxHighlight.hideSearchWords();
event.preventDefault();
}
});
},
};
_ready(SphinxHighlight.highlightSearchWords);
_ready(SphinxHighlight.initEscapeListener);

File diff suppressed because it is too large Load Diff

File diff suppressed because one or more lines are too long

View File

@ -1,10 +1,11 @@
<!DOCTYPE html> <!DOCTYPE html>
<html> <html lang="en">
<head> <head>
<meta charset="utf-8" /> <meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />
<title>Code Examples &#8212; Reticulum Network Stack 0.3.12 beta documentation</title> <title>Code Examples &#8212; Reticulum Network Stack 0.3.12 beta documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css" /> <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="_static/classic.css" /> <link rel="stylesheet" type="text/css" href="_static/classic.css" />
@ -12,7 +13,9 @@
<script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
<script src="_static/jquery.js"></script> <script src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script> <script src="_static/underscore.js"></script>
<script src="_static/_sphinx_javascript_frameworks_compat.js"></script>
<script src="_static/doctools.js"></script> <script src="_static/doctools.js"></script>
<script src="_static/sphinx_highlight.js"></script>
<link rel="index" title="Index" href="genindex.html" /> <link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" /> <link rel="search" title="Search" href="search.html" />
@ -41,12 +44,12 @@
<div class="bodywrapper"> <div class="bodywrapper">
<div class="body" role="main"> <div class="body" role="main">
<div class="section" id="code-examples"> <section id="code-examples">
<span id="examples-main"></span><h1>Code Examples<a class="headerlink" href="#code-examples" title="Permalink to this headline"></a></h1> <span id="examples-main"></span><h1>Code Examples<a class="headerlink" href="#code-examples" title="Permalink to this heading"></a></h1>
<p>A number of examples are included in the source distribution of Reticulum. <p>A number of examples are included in the source distribution of Reticulum.
You can use these examples to learn how to write your own programs.</p> You can use these examples to learn how to write your own programs.</p>
<div class="section" id="minimal"> <section id="minimal">
<span id="example-minimal"></span><h2>Minimal<a class="headerlink" href="#minimal" title="Permalink to this headline"></a></h2> <span id="example-minimal"></span><h2>Minimal<a class="headerlink" href="#minimal" title="Permalink to this heading"></a></h2>
<p>The <em>Minimal</em> example demonstrates the bare-minimum setup required to connect to <p>The <em>Minimal</em> example demonstrates the bare-minimum setup required to connect to
a Reticulum network from your program. In about five lines of code, you will a Reticulum network from your program. In about five lines of code, you will
have the Reticulum Network Stack initialised, and ready to pass traffic in your have the Reticulum Network Stack initialised, and ready to pass traffic in your
@ -155,9 +158,9 @@ program.</p>
</pre></div> </pre></div>
</div> </div>
<p>This example can also be found at <a class="reference external" href="https://github.com/markqvist/Reticulum/blob/master/Examples/Minimal.py">https://github.com/markqvist/Reticulum/blob/master/Examples/Minimal.py</a>.</p> <p>This example can also be found at <a class="reference external" href="https://github.com/markqvist/Reticulum/blob/master/Examples/Minimal.py">https://github.com/markqvist/Reticulum/blob/master/Examples/Minimal.py</a>.</p>
</div> </section>
<div class="section" id="announce"> <section id="announce">
<span id="example-announce"></span><h2>Announce<a class="headerlink" href="#announce" title="Permalink to this headline"></a></h2> <span id="example-announce"></span><h2>Announce<a class="headerlink" href="#announce" title="Permalink to this heading"></a></h2>
<p>The <em>Announce</em> example builds upon the previous example by exploring how to <p>The <em>Announce</em> example builds upon the previous example by exploring how to
announce a destination on the network, and how to let your program receive announce a destination on the network, and how to let your program receive
notifications about announces from relevant destinations.</p> notifications about announces from relevant destinations.</p>
@ -334,9 +337,9 @@ notifications about announces from relevant destinations.</p>
</pre></div> </pre></div>
</div> </div>
<p>This example can also be found at <a class="reference external" href="https://github.com/markqvist/Reticulum/blob/master/Examples/Announce.py">https://github.com/markqvist/Reticulum/blob/master/Examples/Announce.py</a>.</p> <p>This example can also be found at <a class="reference external" href="https://github.com/markqvist/Reticulum/blob/master/Examples/Announce.py">https://github.com/markqvist/Reticulum/blob/master/Examples/Announce.py</a>.</p>
</div> </section>
<div class="section" id="broadcast"> <section id="broadcast">
<span id="example-broadcast"></span><h2>Broadcast<a class="headerlink" href="#broadcast" title="Permalink to this headline"></a></h2> <span id="example-broadcast"></span><h2>Broadcast<a class="headerlink" href="#broadcast" title="Permalink to this heading"></a></h2>
<p>The <em>Broadcast</em> example explores how to transmit plaintext broadcast messages <p>The <em>Broadcast</em> example explores how to transmit plaintext broadcast messages
over the network.</p> over the network.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1">##########################################################</span> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1">##########################################################</span>
@ -463,9 +466,9 @@ over the network.</p>
</pre></div> </pre></div>
</div> </div>
<p>This example can also be found at <a class="reference external" href="https://github.com/markqvist/Reticulum/blob/master/Examples/Broadcast.py">https://github.com/markqvist/Reticulum/blob/master/Examples/Broadcast.py</a>.</p> <p>This example can also be found at <a class="reference external" href="https://github.com/markqvist/Reticulum/blob/master/Examples/Broadcast.py">https://github.com/markqvist/Reticulum/blob/master/Examples/Broadcast.py</a>.</p>
</div> </section>
<div class="section" id="echo"> <section id="echo">
<span id="example-echo"></span><h2>Echo<a class="headerlink" href="#echo" title="Permalink to this headline"></a></h2> <span id="example-echo"></span><h2>Echo<a class="headerlink" href="#echo" title="Permalink to this heading"></a></h2>
<p>The <em>Echo</em> example demonstrates communication between two destinations using <p>The <em>Echo</em> example demonstrates communication between two destinations using
the Packet interface.</p> the Packet interface.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1">##########################################################</span> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1">##########################################################</span>
@ -801,9 +804,9 @@ the Packet interface.</p>
</pre></div> </pre></div>
</div> </div>
<p>This example can also be found at <a class="reference external" href="https://github.com/markqvist/Reticulum/blob/master/Examples/Echo.py">https://github.com/markqvist/Reticulum/blob/master/Examples/Echo.py</a>.</p> <p>This example can also be found at <a class="reference external" href="https://github.com/markqvist/Reticulum/blob/master/Examples/Echo.py">https://github.com/markqvist/Reticulum/blob/master/Examples/Echo.py</a>.</p>
</div> </section>
<div class="section" id="link"> <section id="link">
<span id="example-link"></span><h2>Link<a class="headerlink" href="#link" title="Permalink to this headline"></a></h2> <span id="example-link"></span><h2>Link<a class="headerlink" href="#link" title="Permalink to this heading"></a></h2>
<p>The <em>Link</em> example explores establishing an encrypted link to a remote <p>The <em>Link</em> example explores establishing an encrypted link to a remote
destination, and passing traffic back and forth over the link.</p> destination, and passing traffic back and forth over the link.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1">##########################################################</span> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1">##########################################################</span>
@ -1100,9 +1103,9 @@ destination, and passing traffic back and forth over the link.</p>
</pre></div> </pre></div>
</div> </div>
<p>This example can also be found at <a class="reference external" href="https://github.com/markqvist/Reticulum/blob/master/Examples/Link.py">https://github.com/markqvist/Reticulum/blob/master/Examples/Link.py</a>.</p> <p>This example can also be found at <a class="reference external" href="https://github.com/markqvist/Reticulum/blob/master/Examples/Link.py">https://github.com/markqvist/Reticulum/blob/master/Examples/Link.py</a>.</p>
</div> </section>
<div class="section" id="example-identify"> <section id="example-identify">
<span id="identification"></span><h2>Identification<a class="headerlink" href="#example-identify" title="Permalink to this headline"></a></h2> <span id="identification"></span><h2>Identification<a class="headerlink" href="#example-identify" title="Permalink to this heading"></a></h2>
<p>The <em>Identify</em> example explores identifying an intiator of a link, once <p>The <em>Identify</em> example explores identifying an intiator of a link, once
the link has been established.</p> the link has been established.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1">##########################################################</span> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1">##########################################################</span>
@ -1422,9 +1425,9 @@ the link has been established.</p>
</pre></div> </pre></div>
</div> </div>
<p>This example can also be found at <a class="reference external" href="https://github.com/markqvist/Reticulum/blob/master/Examples/Identify.py">https://github.com/markqvist/Reticulum/blob/master/Examples/Identify.py</a>.</p> <p>This example can also be found at <a class="reference external" href="https://github.com/markqvist/Reticulum/blob/master/Examples/Identify.py">https://github.com/markqvist/Reticulum/blob/master/Examples/Identify.py</a>.</p>
</div> </section>
<div class="section" id="requests-responses"> <section id="requests-responses">
<span id="example-request"></span><h2>Requests &amp; Responses<a class="headerlink" href="#requests-responses" title="Permalink to this headline"></a></h2> <span id="example-request"></span><h2>Requests &amp; Responses<a class="headerlink" href="#requests-responses" title="Permalink to this heading"></a></h2>
<p>The <em>Request</em> example explores sendig requests and receiving responses.</p> <p>The <em>Request</em> example explores sendig requests and receiving responses.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1">##########################################################</span> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1">##########################################################</span>
<span class="c1"># This RNS example demonstrates how to set perform #</span> <span class="c1"># This RNS example demonstrates how to set perform #</span>
@ -1716,9 +1719,9 @@ the link has been established.</p>
</pre></div> </pre></div>
</div> </div>
<p>This example can also be found at <a class="reference external" href="https://github.com/markqvist/Reticulum/blob/master/Examples/Request.py">https://github.com/markqvist/Reticulum/blob/master/Examples/Request.py</a>.</p> <p>This example can also be found at <a class="reference external" href="https://github.com/markqvist/Reticulum/blob/master/Examples/Request.py">https://github.com/markqvist/Reticulum/blob/master/Examples/Request.py</a>.</p>
</div> </section>
<div class="section" id="filetransfer"> <section id="filetransfer">
<span id="example-filetransfer"></span><h2>Filetransfer<a class="headerlink" href="#filetransfer" title="Permalink to this headline"></a></h2> <span id="example-filetransfer"></span><h2>Filetransfer<a class="headerlink" href="#filetransfer" title="Permalink to this heading"></a></h2>
<p>The <em>Filetransfer</em> example implements a basic file-server program that <p>The <em>Filetransfer</em> example implements a basic file-server program that
allow clients to connect and download files. The program uses the Resource allow clients to connect and download files. The program uses the Resource
interface to efficiently pass files of any size over a Reticulum <a class="reference internal" href="reference.html#api-link"><span class="std std-ref">Link</span></a>.</p> interface to efficiently pass files of any size over a Reticulum <a class="reference internal" href="reference.html#api-link"><span class="std std-ref">Link</span></a>.</p>
@ -2330,8 +2333,8 @@ interface to efficiently pass files of any size over a Reticulum <a class="refer
</pre></div> </pre></div>
</div> </div>
<p>This example can also be found at <a class="reference external" href="https://github.com/markqvist/Reticulum/blob/master/Examples/Filetransfer.py">https://github.com/markqvist/Reticulum/blob/master/Examples/Filetransfer.py</a>.</p> <p>This example can also be found at <a class="reference external" href="https://github.com/markqvist/Reticulum/blob/master/Examples/Filetransfer.py">https://github.com/markqvist/Reticulum/blob/master/Examples/Filetransfer.py</a>.</p>
</div> </section>
</div> </section>
<div class="clearer"></div> <div class="clearer"></div>
@ -2340,8 +2343,9 @@ interface to efficiently pass files of any size over a Reticulum <a class="refer
</div> </div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation"> <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper"> <div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table of Contents</a></h3> <div>
<ul> <h3><a href="index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Code Examples</a><ul> <li><a class="reference internal" href="#">Code Examples</a><ul>
<li><a class="reference internal" href="#minimal">Minimal</a></li> <li><a class="reference internal" href="#minimal">Minimal</a></li>
<li><a class="reference internal" href="#announce">Announce</a></li> <li><a class="reference internal" href="#announce">Announce</a></li>
@ -2355,12 +2359,17 @@ interface to efficiently pass files of any size over a Reticulum <a class="refer
</li> </li>
</ul> </ul>
<h4>Previous topic</h4> </div>
<p class="topless"><a href="reference.html" <div>
title="previous chapter">API Reference</a></p> <h4>Previous topic</h4>
<h4>Next topic</h4> <p class="topless"><a href="reference.html"
<p class="topless"><a href="support.html" title="previous chapter">API Reference</a></p>
title="next chapter">Support Reticulum</a></p> </div>
<div>
<h4>Next topic</h4>
<p class="topless"><a href="support.html"
title="next chapter">Support Reticulum</a></p>
</div>
<div role="note" aria-label="source link"> <div role="note" aria-label="source link">
<h3>This Page</h3> <h3>This Page</h3>
<ul class="this-page-menu"> <ul class="this-page-menu">
@ -2372,12 +2381,12 @@ interface to efficiently pass files of any size over a Reticulum <a class="refer
<h3 id="searchlabel">Quick search</h3> <h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper"> <div class="searchformwrapper">
<form class="search" action="search.html" method="get"> <form class="search" action="search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" /> <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" /> <input type="submit" value="Go" />
</form> </form>
</div> </div>
</div> </div>
<script>$('#searchbox').show(0);</script> <script>document.getElementById('searchbox').style.display = "block"</script>
</div> </div>
</div> </div>
<div class="clearer"></div> <div class="clearer"></div>
@ -2400,7 +2409,7 @@ interface to efficiently pass files of any size over a Reticulum <a class="refer
</div> </div>
<div class="footer" role="contentinfo"> <div class="footer" role="contentinfo">
&#169; Copyright 2022, Mark Qvist. &#169; Copyright 2022, Mark Qvist.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.1. Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 5.2.2.
</div> </div>
</body> </body>
</html> </html>

View File

@ -1,7 +1,7 @@
<!DOCTYPE html> <!DOCTYPE html>
<html> <html lang="en">
<head> <head>
<meta charset="utf-8" /> <meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" />
@ -12,7 +12,9 @@
<script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
<script src="_static/jquery.js"></script> <script src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script> <script src="_static/underscore.js"></script>
<script src="_static/_sphinx_javascript_frameworks_compat.js"></script>
<script src="_static/doctools.js"></script> <script src="_static/doctools.js"></script>
<script src="_static/sphinx_highlight.js"></script>
<link rel="index" title="Index" href="#" /> <link rel="index" title="Index" href="#" />
<link rel="search" title="Search" href="search.html" /> <link rel="search" title="Search" href="search.html" />
@ -424,12 +426,12 @@
<h3 id="searchlabel">Quick search</h3> <h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper"> <div class="searchformwrapper">
<form class="search" action="search.html" method="get"> <form class="search" action="search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" /> <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" /> <input type="submit" value="Go" />
</form> </form>
</div> </div>
</div> </div>
<script>$('#searchbox').show(0);</script> <script>document.getElementById('searchbox').style.display = "block"</script>
</div> </div>
</div> </div>
<div class="clearer"></div> <div class="clearer"></div>
@ -446,7 +448,7 @@
</div> </div>
<div class="footer" role="contentinfo"> <div class="footer" role="contentinfo">
&#169; Copyright 2022, Mark Qvist. &#169; Copyright 2022, Mark Qvist.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.1. Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 5.2.2.
</div> </div>
</body> </body>
</html> </html>

View File

@ -1,10 +1,11 @@
<!DOCTYPE html> <!DOCTYPE html>
<html> <html lang="en">
<head> <head>
<meta charset="utf-8" /> <meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />
<title>Getting Started Fast &#8212; Reticulum Network Stack 0.3.12 beta documentation</title> <title>Getting Started Fast &#8212; Reticulum Network Stack 0.3.12 beta documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css" /> <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="_static/classic.css" /> <link rel="stylesheet" type="text/css" href="_static/classic.css" />
@ -12,7 +13,9 @@
<script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
<script src="_static/jquery.js"></script> <script src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script> <script src="_static/underscore.js"></script>
<script src="_static/_sphinx_javascript_frameworks_compat.js"></script>
<script src="_static/doctools.js"></script> <script src="_static/doctools.js"></script>
<script src="_static/sphinx_highlight.js"></script>
<link rel="index" title="Index" href="genindex.html" /> <link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" /> <link rel="search" title="Search" href="search.html" />
@ -41,13 +44,13 @@
<div class="bodywrapper"> <div class="bodywrapper">
<div class="body" role="main"> <div class="body" role="main">
<div class="section" id="getting-started-fast"> <section id="getting-started-fast">
<h1>Getting Started Fast<a class="headerlink" href="#getting-started-fast" title="Permalink to this headline"></a></h1> <h1>Getting Started Fast<a class="headerlink" href="#getting-started-fast" title="Permalink to this heading"></a></h1>
<p>The best way to get started with the Reticulum Network Stack depends on what <p>The best way to get started with the Reticulum Network Stack depends on what
you want to do. This guide will outline sensible starting paths for different you want to do. This guide will outline sensible starting paths for different
scenarios.</p> scenarios.</p>
<div class="section" id="try-using-a-reticulum-based-program"> <section id="try-using-a-reticulum-based-program">
<h2>Try Using a Reticulum-based Program<a class="headerlink" href="#try-using-a-reticulum-based-program" title="Permalink to this headline"></a></h2> <h2>Try Using a Reticulum-based Program<a class="headerlink" href="#try-using-a-reticulum-based-program" title="Permalink to this heading"></a></h2>
<p>If you simply want to try using a program built with Reticulum, a few different <p>If you simply want to try using a program built with Reticulum, a few different
programs exist that allow basic communication and a range of other useful functions programs exist that allow basic communication and a range of other useful functions
over even extremely low-bandwidth Reticulum networks.</p> over even extremely low-bandwidth Reticulum networks.</p>
@ -58,8 +61,8 @@ over local WiFi, wired Ethernet, the Internet, or any combination.</p>
transceivers or infrastructure just to try it out. Launching the programs on separate transceivers or infrastructure just to try it out. Launching the programs on separate
devices connected to the same WiFi network is enough to get started, and physical devices connected to the same WiFi network is enough to get started, and physical
radio interfaces can then be added later.</p> radio interfaces can then be added later.</p>
<div class="section" id="nomad-network"> <section id="nomad-network">
<h3>Nomad Network<a class="headerlink" href="#nomad-network" title="Permalink to this headline"></a></h3> <h3>Nomad Network<a class="headerlink" href="#nomad-network" title="Permalink to this heading"></a></h3>
<p>The terminal-based program <a class="reference external" href="https://github.com/markqvist/nomadnet">Nomad Network</a> <p>The terminal-based program <a class="reference external" href="https://github.com/markqvist/nomadnet">Nomad Network</a>
provides a complete encrypted communications suite built with Reticulum. It features provides a complete encrypted communications suite built with Reticulum. It features
encrypted messaging (both direct and delayed-delivery for offline users), file sharing, encrypted messaging (both direct and delayed-delivery for offline users), file sharing,
@ -81,19 +84,19 @@ for the messaging and information-sharing protocol
on your system, you might need to reboot your system for your program to become on your system, you might need to reboot your system for your program to become
available. If you get a “command not found” error or similar when running the available. If you get a “command not found” error or similar when running the
program, reboot your system and try again.</p> program, reboot your system and try again.</p>
</div> </section>
<div class="section" id="sideband"> <section id="sideband">
<h3>Sideband<a class="headerlink" href="#sideband" title="Permalink to this headline"></a></h3> <h3>Sideband<a class="headerlink" href="#sideband" title="Permalink to this heading"></a></h3>
<p>If you would rather use a program with a graphical user interface, you can take <p>If you would rather use a program with a graphical user interface, you can take
a look at <a class="reference external" href="https://unsigned.io/sideband">Sideband</a>, which is available for Android, a look at <a class="reference external" href="https://unsigned.io/sideband">Sideband</a>, which is available for Android,
Linux and macOS.</p> Linux and macOS.</p>
<a class="reference external image-reference" href="_images/sideband_1.png"><img alt="_images/sideband_1.png" class="align-center" src="_images/sideband_1.png" /></a> <a class="reference external image-reference" href="_images/sideband_1.png"><img alt="_images/sideband_1.png" class="align-center" src="_images/sideband_1.png" /></a>
<p>Sideband is currently in the early stages of development, but already provides basic <p>Sideband is currently in the early stages of development, but already provides basic
communication features, and interoperates with Nomad Network, or any other LXMF client.</p> communication features, and interoperates with Nomad Network, or any other LXMF client.</p>
</div> </section>
</div> </section>
<div class="section" id="using-the-included-utilities"> <section id="using-the-included-utilities">
<h2>Using the Included Utilities<a class="headerlink" href="#using-the-included-utilities" title="Permalink to this headline"></a></h2> <h2>Using the Included Utilities<a class="headerlink" href="#using-the-included-utilities" title="Permalink to this heading"></a></h2>
<p>Reticulum comes with a range of included utilities that make it easier to <p>Reticulum comes with a range of included utilities that make it easier to
manage your network, check connectivity and make Reticulum available to other manage your network, check connectivity and make Reticulum available to other
programs on your system.</p> programs on your system.</p>
@ -102,9 +105,9 @@ and the <code class="docutils literal notranslate"><span class="pre">rnstatus</s
network status and connectivity.</p> network status and connectivity.</p>
<p>To learn more about these utility programs, have a look at the <p>To learn more about these utility programs, have a look at the
<a class="reference internal" href="using.html#using-main"><span class="std std-ref">Using Reticulum on Your System</span></a> chapter of this manual.</p> <a class="reference internal" href="using.html#using-main"><span class="std std-ref">Using Reticulum on Your System</span></a> chapter of this manual.</p>
</div> </section>
<div class="section" id="creating-a-network-with-reticulum"> <section id="creating-a-network-with-reticulum">
<h2>Creating a Network With Reticulum<a class="headerlink" href="#creating-a-network-with-reticulum" title="Permalink to this headline"></a></h2> <h2>Creating a Network With Reticulum<a class="headerlink" href="#creating-a-network-with-reticulum" title="Permalink to this heading"></a></h2>
<p>To create a network, you will need to specify one or more <em>interfaces</em> for <p>To create a network, you will need to specify one or more <em>interfaces</em> for
Reticulum to use. This is done in the Reticulum configuration file, which by Reticulum to use. This is done in the Reticulum configuration file, which by
default is located at <code class="docutils literal notranslate"><span class="pre">~/.config/reticulum/config</span></code>. You can edit this file by hand, default is located at <code class="docutils literal notranslate"><span class="pre">~/.config/reticulum/config</span></code>. You can edit this file by hand,
@ -131,9 +134,9 @@ network just using the default (<a class="reference internal" href="interfaces.h
<p>Possibly, the examples in the config file are enough to get you started. If <p>Possibly, the examples in the config file are enough to get you started. If
you want more information, you can read the <a class="reference internal" href="networks.html#networks-main"><span class="std std-ref">Building Networks</span></a> you want more information, you can read the <a class="reference internal" href="networks.html#networks-main"><span class="std std-ref">Building Networks</span></a>
and <a class="reference internal" href="interfaces.html#interfaces-main"><span class="std std-ref">Interfaces</span></a> chapters of this manual.</p> and <a class="reference internal" href="interfaces.html#interfaces-main"><span class="std std-ref">Interfaces</span></a> chapters of this manual.</p>
</div> </section>
<div class="section" id="connecting-reticulum-instances-over-the-internet"> <section id="connecting-reticulum-instances-over-the-internet">
<h2>Connecting Reticulum Instances Over the Internet<a class="headerlink" href="#connecting-reticulum-instances-over-the-internet" title="Permalink to this headline"></a></h2> <h2>Connecting Reticulum Instances Over the Internet<a class="headerlink" href="#connecting-reticulum-instances-over-the-internet" title="Permalink to this heading"></a></h2>
<p>Reticulum currently offers two interfaces suitable for connecting instances over the Internet: <a class="reference internal" href="interfaces.html#interfaces-tcps"><span class="std std-ref">TCP</span></a> <p>Reticulum currently offers two interfaces suitable for connecting instances over the Internet: <a class="reference internal" href="interfaces.html#interfaces-tcps"><span class="std std-ref">TCP</span></a>
and <a class="reference internal" href="interfaces.html#interfaces-i2p"><span class="std std-ref">I2P</span></a>. Each interface offers a different set of features, and Reticulum and <a class="reference internal" href="interfaces.html#interfaces-i2p"><span class="std std-ref">I2P</span></a>. Each interface offers a different set of features, and Reticulum
users should carefully choose the interface which best suites their needs.</p> users should carefully choose the interface which best suites their needs.</p>
@ -159,9 +162,9 @@ deep-packet-inspection much more difficult.</p>
<p>In general it is recommended to use an I2P node if you want to host a publicly accessible <p>In general it is recommended to use an I2P node if you want to host a publicly accessible
instance, while preserving anonymity. If you care more about performance, and a slightly instance, while preserving anonymity. If you care more about performance, and a slightly
easier setup, use TCP.</p> easier setup, use TCP.</p>
</div> </section>
<div class="section" id="connect-to-the-public-testnet"> <section id="connect-to-the-public-testnet">
<h2>Connect to the Public Testnet<a class="headerlink" href="#connect-to-the-public-testnet" title="Permalink to this headline"></a></h2> <h2>Connect to the Public Testnet<a class="headerlink" href="#connect-to-the-public-testnet" title="Permalink to this heading"></a></h2>
<p>An experimental public testnet has been made accessible over both I2P and TCP. You can join it <p>An experimental public testnet has been made accessible over both I2P and TCP. You can join it
by adding one of the following interfaces to your <code class="docutils literal notranslate"><span class="pre">.reticulum/config</span></code> file:</p> by adding one of the following interfaces to your <code class="docutils literal notranslate"><span class="pre">.reticulum/config</span></code> file:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># TCP/IP interface to the Dublin hub</span> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># TCP/IP interface to the Dublin hub</span>
@ -189,9 +192,9 @@ by adding one of the following interfaces to your <code class="docutils literal
via other entry points if you know them. There is absolutely no control over the network via other entry points if you know them. There is absolutely no control over the network
topography, usage or what types of instances connect. It will also occasionally be used topography, usage or what types of instances connect. It will also occasionally be used
to test various failure scenarios, and there are no availability or service guarantees.</p> to test various failure scenarios, and there are no availability or service guarantees.</p>
</div> </section>
<div class="section" id="adding-radio-interfaces"> <section id="adding-radio-interfaces">
<h2>Adding Radio Interfaces<a class="headerlink" href="#adding-radio-interfaces" title="Permalink to this headline"></a></h2> <h2>Adding Radio Interfaces<a class="headerlink" href="#adding-radio-interfaces" title="Permalink to this heading"></a></h2>
<p>Once you have Reticulum installed and working, you can add radio interfaces with <p>Once you have Reticulum installed and working, you can add radio interfaces with
any compatible hardware you have available. Reticulum supports a wide range of radio any compatible hardware you have available. Reticulum supports a wide range of radio
hardware, and if you already have any available, it is very likely that it will hardware, and if you already have any available, it is very likely that it will
@ -215,9 +218,9 @@ refer to these additional external resources:</p>
<a class="reference internal" href="interfaces.html#interfaces-main"><span class="std std-ref">existing interface types</span></a>, but you think would be suitable for use with Reticulum, <a class="reference internal" href="interfaces.html#interfaces-main"><span class="std std-ref">existing interface types</span></a>, but you think would be suitable for use with Reticulum,
you are welcome to head over to the <a class="reference external" href="https://github.com/markqvist/Reticulum/discussions">GitHub discussion pages</a> you are welcome to head over to the <a class="reference external" href="https://github.com/markqvist/Reticulum/discussions">GitHub discussion pages</a>
and propose adding an interface for the hardware.</p> and propose adding an interface for the hardware.</p>
</div> </section>
<div class="section" id="develop-a-program-with-reticulum"> <section id="develop-a-program-with-reticulum">
<h2>Develop a Program with Reticulum<a class="headerlink" href="#develop-a-program-with-reticulum" title="Permalink to this headline"></a></h2> <h2>Develop a Program with Reticulum<a class="headerlink" href="#develop-a-program-with-reticulum" title="Permalink to this heading"></a></h2>
<p>If you want to develop programs that use Reticulum, the easiest way to get <p>If you want to develop programs that use Reticulum, the easiest way to get
started is to install the latest release of Reticulum via pip:</p> started is to install the latest release of Reticulum via pip:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pip3</span> <span class="n">install</span> <span class="n">rns</span> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pip3</span> <span class="n">install</span> <span class="n">rns</span>
@ -231,9 +234,9 @@ likely be to look at some <a class="reference internal" href="examples.html#exam
</pre></div> </pre></div>
</div> </div>
<p>Further information can be found in the <a class="reference internal" href="reference.html#api-main"><span class="std std-ref">API Reference</span></a>.</p> <p>Further information can be found in the <a class="reference internal" href="reference.html#api-main"><span class="std std-ref">API Reference</span></a>.</p>
</div> </section>
<div class="section" id="participate-in-reticulum-development"> <section id="participate-in-reticulum-development">
<h2>Participate in Reticulum Development<a class="headerlink" href="#participate-in-reticulum-development" title="Permalink to this headline"></a></h2> <h2>Participate in Reticulum Development<a class="headerlink" href="#participate-in-reticulum-development" title="Permalink to this heading"></a></h2>
<p>If you want to participate in the development of Reticulum and associated <p>If you want to participate in the development of Reticulum and associated
utilities, youll want to get the latest source from GitHub. In that case, utilities, youll want to get the latest source from GitHub. In that case,
dont use pip, but try this recipe:</p> dont use pip, but try this recipe:</p>
@ -271,9 +274,9 @@ dont use pip, but try this recipe:</p>
</div> </div>
<p>When you have experimented with the basic examples, its time to go read the <p>When you have experimented with the basic examples, its time to go read the
<a class="reference internal" href="understanding.html#understanding-main"><span class="std std-ref">Understanding Reticulum</span></a> chapter.</p> <a class="reference internal" href="understanding.html#understanding-main"><span class="std std-ref">Understanding Reticulum</span></a> chapter.</p>
</div> </section>
<div class="section" id="reticulum-on-arm64"> <section id="reticulum-on-arm64">
<h2>Reticulum on ARM64<a class="headerlink" href="#reticulum-on-arm64" title="Permalink to this headline"></a></h2> <h2>Reticulum on ARM64<a class="headerlink" href="#reticulum-on-arm64" title="Permalink to this heading"></a></h2>
<p>On some architectures, including ARM64, not all dependencies have precompiled <p>On some architectures, including ARM64, not all dependencies have precompiled
binaries. On such systems, you will need to install <code class="docutils literal notranslate"><span class="pre">python3-dev</span></code> before binaries. On such systems, you will need to install <code class="docutils literal notranslate"><span class="pre">python3-dev</span></code> before
installing Reticulum or programs that depend on Reticulum.</p> installing Reticulum or programs that depend on Reticulum.</p>
@ -285,9 +288,9 @@ installing Reticulum or programs that depend on Reticulum.</p>
<span class="n">python3</span> <span class="o">-</span><span class="n">m</span> <span class="n">pip</span> <span class="n">install</span> <span class="n">rns</span> <span class="n">python3</span> <span class="o">-</span><span class="n">m</span> <span class="n">pip</span> <span class="n">install</span> <span class="n">rns</span>
</pre></div> </pre></div>
</div> </div>
</div> </section>
<div class="section" id="reticulum-on-android"> <section id="reticulum-on-android">
<h2>Reticulum on Android<a class="headerlink" href="#reticulum-on-android" title="Permalink to this headline"></a></h2> <h2>Reticulum on Android<a class="headerlink" href="#reticulum-on-android" title="Permalink to this heading"></a></h2>
<p>Reticulum can be used on Android in different ways. The easiest way to get <p>Reticulum can be used on Android in different ways. The easiest way to get
started is using an app like <a class="reference external" href="https://unsigned.io/sideband">Sideband</a>.</p> started is using an app like <a class="reference external" href="https://unsigned.io/sideband">Sideband</a>.</p>
<p>For more control and features, you can use Reticulum and related programs via <p>For more control and features, you can use Reticulum and related programs via
@ -327,9 +330,9 @@ and a few extra commands are required.</p>
<p>It is also possible to include Reticulum in apps compiled and distributed as <p>It is also possible to include Reticulum in apps compiled and distributed as
Android APKs. A detailed tutorial and example source code will be included Android APKs. A detailed tutorial and example source code will be included
here at a later point.</p> here at a later point.</p>
</div> </section>
<div class="section" id="pure-python-reticulum"> <section id="pure-python-reticulum">
<h2>Pure-Python Reticulum<a class="headerlink" href="#pure-python-reticulum" title="Permalink to this headline"></a></h2> <h2>Pure-Python Reticulum<a class="headerlink" href="#pure-python-reticulum" title="Permalink to this heading"></a></h2>
<p>In some rare cases, and on more obscure system types, it is not possible to <p>In some rare cases, and on more obscure system types, it is not possible to
install one or more dependencies</p> install one or more dependencies</p>
<p>On more unusual systems, and in some rare cases, it might not be possible to <p>On more unusual systems, and in some rare cases, it might not be possible to
@ -348,8 +351,8 @@ All other available modules will still be loaded when needed.</p>
do not support <a class="reference external" href="https://github.com/pyca/cryptography">PyCA/cryptography</a>, it is do not support <a class="reference external" href="https://github.com/pyca/cryptography">PyCA/cryptography</a>, it is
important that you read and understand the <a class="reference internal" href="understanding.html#understanding-primitives"><span class="std std-ref">Cryptographic Primitives</span></a> important that you read and understand the <a class="reference internal" href="understanding.html#understanding-primitives"><span class="std std-ref">Cryptographic Primitives</span></a>
section of this manual.</p> section of this manual.</p>
</div> </section>
</div> </section>
<div class="clearer"></div> <div class="clearer"></div>
@ -358,8 +361,9 @@ section of this manual.</p>
</div> </div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation"> <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper"> <div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table of Contents</a></h3> <div>
<ul> <h3><a href="index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Getting Started Fast</a><ul> <li><a class="reference internal" href="#">Getting Started Fast</a><ul>
<li><a class="reference internal" href="#try-using-a-reticulum-based-program">Try Using a Reticulum-based Program</a><ul> <li><a class="reference internal" href="#try-using-a-reticulum-based-program">Try Using a Reticulum-based Program</a><ul>
<li><a class="reference internal" href="#nomad-network">Nomad Network</a></li> <li><a class="reference internal" href="#nomad-network">Nomad Network</a></li>
@ -380,12 +384,17 @@ section of this manual.</p>
</li> </li>
</ul> </ul>
<h4>Previous topic</h4> </div>
<p class="topless"><a href="whatis.html" <div>
title="previous chapter">What is Reticulum?</a></p> <h4>Previous topic</h4>
<h4>Next topic</h4> <p class="topless"><a href="whatis.html"
<p class="topless"><a href="using.html" title="previous chapter">What is Reticulum?</a></p>
title="next chapter">Using Reticulum on Your System</a></p> </div>
<div>
<h4>Next topic</h4>
<p class="topless"><a href="using.html"
title="next chapter">Using Reticulum on Your System</a></p>
</div>
<div role="note" aria-label="source link"> <div role="note" aria-label="source link">
<h3>This Page</h3> <h3>This Page</h3>
<ul class="this-page-menu"> <ul class="this-page-menu">
@ -397,12 +406,12 @@ section of this manual.</p>
<h3 id="searchlabel">Quick search</h3> <h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper"> <div class="searchformwrapper">
<form class="search" action="search.html" method="get"> <form class="search" action="search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" /> <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" /> <input type="submit" value="Go" />
</form> </form>
</div> </div>
</div> </div>
<script>$('#searchbox').show(0);</script> <script>document.getElementById('searchbox').style.display = "block"</script>
</div> </div>
</div> </div>
<div class="clearer"></div> <div class="clearer"></div>
@ -425,7 +434,7 @@ section of this manual.</p>
</div> </div>
<div class="footer" role="contentinfo"> <div class="footer" role="contentinfo">
&#169; Copyright 2022, Mark Qvist. &#169; Copyright 2022, Mark Qvist.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.1. Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 5.2.2.
</div> </div>
</body> </body>
</html> </html>

View File

@ -1,10 +1,11 @@
<!DOCTYPE html> <!DOCTYPE html>
<html> <html lang="en">
<head> <head>
<meta charset="utf-8" /> <meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />
<title>Communications Hardware &#8212; Reticulum Network Stack 0.3.12 beta documentation</title> <title>Communications Hardware &#8212; Reticulum Network Stack 0.3.12 beta documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css" /> <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="_static/classic.css" /> <link rel="stylesheet" type="text/css" href="_static/classic.css" />
@ -12,7 +13,9 @@
<script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
<script src="_static/jquery.js"></script> <script src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script> <script src="_static/underscore.js"></script>
<script src="_static/_sphinx_javascript_frameworks_compat.js"></script>
<script src="_static/doctools.js"></script> <script src="_static/doctools.js"></script>
<script src="_static/sphinx_highlight.js"></script>
<link rel="index" title="Index" href="genindex.html" /> <link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" /> <link rel="search" title="Search" href="search.html" />
@ -41,8 +44,8 @@
<div class="bodywrapper"> <div class="bodywrapper">
<div class="body" role="main"> <div class="body" role="main">
<div class="section" id="communications-hardware"> <section id="communications-hardware">
<span id="hardware-main"></span><h1>Communications Hardware<a class="headerlink" href="#communications-hardware" title="Permalink to this headline"></a></h1> <span id="hardware-main"></span><h1>Communications Hardware<a class="headerlink" href="#communications-hardware" title="Permalink to this heading"></a></h1>
<p>One of the truly valuable aspects of Reticulum is the ability to use it over <p>One of the truly valuable aspects of Reticulum is the ability to use it over
almost any conceivable kind of communications medium. The <a class="reference internal" href="interfaces.html#interfaces-main"><span class="std std-ref">interface types</span></a> almost any conceivable kind of communications medium. The <a class="reference internal" href="interfaces.html#interfaces-main"><span class="std std-ref">interface types</span></a>
available for configuration in Reticulum are flexible enough to cover the use available for configuration in Reticulum are flexible enough to cover the use
@ -64,8 +67,8 @@ and effort. Two fundamental devices categories will be covered, <em>RNodes</em>
<p>While there are many other device categories that are useful in building Reticulum <p>While there are many other device categories that are useful in building Reticulum
networks, knowing how to employ just these two will make it possible to build networks, knowing how to employ just these two will make it possible to build
a wide range of useful networks with little effort.</p> a wide range of useful networks with little effort.</p>
<div class="section" id="rnode"> <section id="rnode">
<span id="rnode-main"></span><h2>RNode<a class="headerlink" href="#rnode" title="Permalink to this headline"></a></h2> <span id="rnode-main"></span><h2>RNode<a class="headerlink" href="#rnode" title="Permalink to this heading"></a></h2>
<p>Reliable and general-purpose long-range digital radio transceiver systems are <p>Reliable and general-purpose long-range digital radio transceiver systems are
commonly either very expensive, difficult to set up and operate, hard to source, commonly either very expensive, difficult to set up and operate, hard to source,
power-hungry, or all of the above at the same time. In an attempt to alleviate power-hungry, or all of the above at the same time. In an attempt to alleviate
@ -83,8 +86,8 @@ does not use, and has nothing to do with the <em>LoRaWAN</em> protocol and stand
used for centrally controlled IoT devices. RNodes use <em>raw LoRa modulation</em>, without used for centrally controlled IoT devices. RNodes use <em>raw LoRa modulation</em>, without
any additional protocol overhead. All high-level protocol functionality is handled any additional protocol overhead. All high-level protocol functionality is handled
directly by Reticulum.</p> directly by Reticulum.</p>
<div class="section" id="creating-rnodes"> <section id="creating-rnodes">
<span id="rnode-creating"></span><h3>Creating RNodes<a class="headerlink" href="#creating-rnodes" title="Permalink to this headline"></a></h3> <span id="rnode-creating"></span><h3>Creating RNodes<a class="headerlink" href="#creating-rnodes" title="Permalink to this heading"></a></h3>
<p>RNode has been designed as a system that is easy to replicate across time and <p>RNode has been designed as a system that is easy to replicate across time and
space. You can put together a functioning transceiver using commonly available space. You can put together a functioning transceiver using commonly available
components, and a few open source software tools. While you can design and build RNodes components, and a few open source software tools. While you can design and build RNodes
@ -99,13 +102,13 @@ LoRa development boards. This approach can be boiled down to two simple steps:</
is ready to use with any software that supports RNodes, including Reticulum. is ready to use with any software that supports RNodes, including Reticulum.
The device can be used with Reticulum by adding an <a class="reference internal" href="interfaces.html#interfaces-rnode"><span class="std std-ref">RNodeInterface</span></a> The device can be used with Reticulum by adding an <a class="reference internal" href="interfaces.html#interfaces-rnode"><span class="std std-ref">RNodeInterface</span></a>
to the configuration.</p> to the configuration.</p>
</div> </section>
<div class="section" id="supported-boards"> <section id="supported-boards">
<span id="rnode-supported"></span><h3>Supported Boards<a class="headerlink" href="#supported-boards" title="Permalink to this headline"></a></h3> <span id="rnode-supported"></span><h3>Supported Boards<a class="headerlink" href="#supported-boards" title="Permalink to this heading"></a></h3>
<p>To create one or more RNodes, you will need to obtain supported development <p>To create one or more RNodes, you will need to obtain supported development
boards. The following boards are supported by the auto-installer.</p> boards. The following boards are supported by the auto-installer.</p>
<div class="section" id="lilygo-lora32-v2-1"> <section id="lilygo-lora32-v2-1">
<h4>LilyGO LoRa32 v2.1<a class="headerlink" href="#lilygo-lora32-v2-1" title="Permalink to this headline"></a></h4> <h4>LilyGO LoRa32 v2.1<a class="headerlink" href="#lilygo-lora32-v2-1" title="Permalink to this heading"></a></h4>
<a class="reference internal image-reference" href="_images/board_t3v21.png"><img alt="_images/board_t3v21.png" class="align-center" src="_images/board_t3v21.png" style="width: 46%;" /></a> <a class="reference internal image-reference" href="_images/board_t3v21.png"><img alt="_images/board_t3v21.png" class="align-center" src="_images/board_t3v21.png" style="width: 46%;" /></a>
<ul class="simple"> <ul class="simple">
<li><p><strong>Supported Firmware Lines</strong> v1.x &amp; v2.x</p></li> <li><p><strong>Supported Firmware Lines</strong> v1.x &amp; v2.x</p></li>
@ -113,9 +116,9 @@ boards. The following boards are supported by the auto-installer.</p>
<li><p><strong>Device Platform</strong> ESP32</p></li> <li><p><strong>Device Platform</strong> ESP32</p></li>
<li><p><strong>Manufacturer</strong> <a class="reference external" href="https://lilygo.cn">LilyGO</a></p></li> <li><p><strong>Manufacturer</strong> <a class="reference external" href="https://lilygo.cn">LilyGO</a></p></li>
</ul> </ul>
</div> </section>
<div class="section" id="lilygo-lora32-v2-0"> <section id="lilygo-lora32-v2-0">
<h4>LilyGO LoRa32 v2.0<a class="headerlink" href="#lilygo-lora32-v2-0" title="Permalink to this headline"></a></h4> <h4>LilyGO LoRa32 v2.0<a class="headerlink" href="#lilygo-lora32-v2-0" title="Permalink to this heading"></a></h4>
<a class="reference internal image-reference" href="_images/board_t3v20.png"><img alt="_images/board_t3v20.png" class="align-center" src="_images/board_t3v20.png" style="width: 46%;" /></a> <a class="reference internal image-reference" href="_images/board_t3v20.png"><img alt="_images/board_t3v20.png" class="align-center" src="_images/board_t3v20.png" style="width: 46%;" /></a>
<ul class="simple"> <ul class="simple">
<li><p><strong>Supported Firmware Lines</strong> v1.x &amp; v2.x</p></li> <li><p><strong>Supported Firmware Lines</strong> v1.x &amp; v2.x</p></li>
@ -123,9 +126,9 @@ boards. The following boards are supported by the auto-installer.</p>
<li><p><strong>Device Platform</strong> ESP32</p></li> <li><p><strong>Device Platform</strong> ESP32</p></li>
<li><p><strong>Manufacturer</strong> <a class="reference external" href="https://lilygo.cn">LilyGO</a></p></li> <li><p><strong>Manufacturer</strong> <a class="reference external" href="https://lilygo.cn">LilyGO</a></p></li>
</ul> </ul>
</div> </section>
<div class="section" id="lilygo-t-beam"> <section id="lilygo-t-beam">
<h4>LilyGO T-Beam<a class="headerlink" href="#lilygo-t-beam" title="Permalink to this headline"></a></h4> <h4>LilyGO T-Beam<a class="headerlink" href="#lilygo-t-beam" title="Permalink to this heading"></a></h4>
<a class="reference internal image-reference" href="_images/board_tbeam.png"><img alt="_images/board_tbeam.png" class="align-center" src="_images/board_tbeam.png" style="width: 75%;" /></a> <a class="reference internal image-reference" href="_images/board_tbeam.png"><img alt="_images/board_tbeam.png" class="align-center" src="_images/board_tbeam.png" style="width: 75%;" /></a>
<ul class="simple"> <ul class="simple">
<li><p><strong>Supported Firmware Lines</strong> v1.x &amp; v2.x</p></li> <li><p><strong>Supported Firmware Lines</strong> v1.x &amp; v2.x</p></li>
@ -133,9 +136,9 @@ boards. The following boards are supported by the auto-installer.</p>
<li><p><strong>Device Platform</strong> ESP32</p></li> <li><p><strong>Device Platform</strong> ESP32</p></li>
<li><p><strong>Manufacturer</strong> <a class="reference external" href="https://lilygo.cn">LilyGO</a></p></li> <li><p><strong>Manufacturer</strong> <a class="reference external" href="https://lilygo.cn">LilyGO</a></p></li>
</ul> </ul>
</div> </section>
<div class="section" id="heltec-lora32-v2-0"> <section id="heltec-lora32-v2-0">
<h4>Heltec LoRa32 v2.0<a class="headerlink" href="#heltec-lora32-v2-0" title="Permalink to this headline"></a></h4> <h4>Heltec LoRa32 v2.0<a class="headerlink" href="#heltec-lora32-v2-0" title="Permalink to this heading"></a></h4>
<a class="reference internal image-reference" href="_images/board_heltec32.png"><img alt="_images/board_heltec32.png" class="align-center" src="_images/board_heltec32.png" style="width: 58%;" /></a> <a class="reference internal image-reference" href="_images/board_heltec32.png"><img alt="_images/board_heltec32.png" class="align-center" src="_images/board_heltec32.png" style="width: 58%;" /></a>
<ul class="simple"> <ul class="simple">
<li><p><strong>Supported Firmware Lines</strong> v1.x &amp; v2.x</p></li> <li><p><strong>Supported Firmware Lines</strong> v1.x &amp; v2.x</p></li>
@ -143,9 +146,9 @@ boards. The following boards are supported by the auto-installer.</p>
<li><p><strong>Device Platform</strong> ESP32</p></li> <li><p><strong>Device Platform</strong> ESP32</p></li>
<li><p><strong>Manufacturer</strong> <a class="reference external" href="https://heltec.org">Heltec Automation</a></p></li> <li><p><strong>Manufacturer</strong> <a class="reference external" href="https://heltec.org">Heltec Automation</a></p></li>
</ul> </ul>
</div> </section>
<div class="section" id="unsigned-rnode-v2-x"> <section id="unsigned-rnode-v2-x">
<h4>Unsigned RNode v2.x<a class="headerlink" href="#unsigned-rnode-v2-x" title="Permalink to this headline"></a></h4> <h4>Unsigned RNode v2.x<a class="headerlink" href="#unsigned-rnode-v2-x" title="Permalink to this heading"></a></h4>
<a class="reference internal image-reference" href="_images/board_rnodev2.png"><img alt="_images/board_rnodev2.png" class="align-center" src="_images/board_rnodev2.png" style="width: 58%;" /></a> <a class="reference internal image-reference" href="_images/board_rnodev2.png"><img alt="_images/board_rnodev2.png" class="align-center" src="_images/board_rnodev2.png" style="width: 58%;" /></a>
<ul class="simple"> <ul class="simple">
<li><p><strong>Supported Firmware Lines</strong> v1.x &amp; v2.x</p></li> <li><p><strong>Supported Firmware Lines</strong> v1.x &amp; v2.x</p></li>
@ -153,9 +156,9 @@ boards. The following boards are supported by the auto-installer.</p>
<li><p><strong>Device Platform</strong> ESP32</p></li> <li><p><strong>Device Platform</strong> ESP32</p></li>
<li><p><strong>Manufacturer</strong> <a class="reference external" href="https://unsigned.io">unsigned.io</a></p></li> <li><p><strong>Manufacturer</strong> <a class="reference external" href="https://unsigned.io">unsigned.io</a></p></li>
</ul> </ul>
</div> </section>
<div class="section" id="unsigned-rnode-v1-x"> <section id="unsigned-rnode-v1-x">
<h4>Unsigned RNode v1.x<a class="headerlink" href="#unsigned-rnode-v1-x" title="Permalink to this headline"></a></h4> <h4>Unsigned RNode v1.x<a class="headerlink" href="#unsigned-rnode-v1-x" title="Permalink to this heading"></a></h4>
<a class="reference internal image-reference" href="_images/board_rnode.png"><img alt="_images/board_rnode.png" class="align-center" src="_images/board_rnode.png" style="width: 50%;" /></a> <a class="reference internal image-reference" href="_images/board_rnode.png"><img alt="_images/board_rnode.png" class="align-center" src="_images/board_rnode.png" style="width: 50%;" /></a>
<ul class="simple"> <ul class="simple">
<li><p><strong>Supported Firmware Lines</strong> v1.x</p></li> <li><p><strong>Supported Firmware Lines</strong> v1.x</p></li>
@ -163,10 +166,10 @@ boards. The following boards are supported by the auto-installer.</p>
<li><p><strong>Device Platform</strong> AVR ATmega1284p</p></li> <li><p><strong>Device Platform</strong> AVR ATmega1284p</p></li>
<li><p><strong>Manufacturer</strong> <a class="reference external" href="https://unsigned.io">unsigned.io</a></p></li> <li><p><strong>Manufacturer</strong> <a class="reference external" href="https://unsigned.io">unsigned.io</a></p></li>
</ul> </ul>
</div> </section>
</div> </section>
<div class="section" id="installation"> <section id="installation">
<span id="rnode-installation"></span><h3>Installation<a class="headerlink" href="#installation" title="Permalink to this headline"></a></h3> <span id="rnode-installation"></span><h3>Installation<a class="headerlink" href="#installation" title="Permalink to this heading"></a></h3>
<p>Once you have obtained compatible boards, you can install the <a class="reference external" href="https://github.com/markqvist/RNode_Firmware">RNode Firmware</a> <p>Once you have obtained compatible boards, you can install the <a class="reference external" href="https://github.com/markqvist/RNode_Firmware">RNode Firmware</a>
using the <a class="reference external" href="https://github.com/markqvist/rnodeconfigutil">RNode Configuration Utility</a>. using the <a class="reference external" href="https://github.com/markqvist/rnodeconfigutil">RNode Configuration Utility</a>.
Make sure that <code class="docutils literal notranslate"><span class="pre">Python3</span></code> and <code class="docutils literal notranslate"><span class="pre">pip</span></code> is installed on your system, and then install Make sure that <code class="docutils literal notranslate"><span class="pre">Python3</span></code> and <code class="docutils literal notranslate"><span class="pre">pip</span></code> is installed on your system, and then install
@ -186,24 +189,24 @@ auto-install and configure your devices</p>
even though the v2.x line is available for early testing. The v2.x line should still be even though the v2.x line is available for early testing. The v2.x line should still be
considered an experimental pre-release. Only use the v2.x firmware line if you want to test considered an experimental pre-release. Only use the v2.x firmware line if you want to test
out the absolutely newest version, and dont care about stability.</p> out the absolutely newest version, and dont care about stability.</p>
</div> </section>
<div class="section" id="usage-with-reticulum"> <section id="usage-with-reticulum">
<span id="rnode-usage"></span><h3>Usage with Reticulum<a class="headerlink" href="#usage-with-reticulum" title="Permalink to this headline"></a></h3> <span id="rnode-usage"></span><h3>Usage with Reticulum<a class="headerlink" href="#usage-with-reticulum" title="Permalink to this heading"></a></h3>
<p>When the devices have been installed and provisioned, you can use them with Reticulum <p>When the devices have been installed and provisioned, you can use them with Reticulum
by adding the <a class="reference internal" href="interfaces.html#interfaces-rnode"><span class="std std-ref">relevant interface section</span></a> to the configuration by adding the <a class="reference internal" href="interfaces.html#interfaces-rnode"><span class="std std-ref">relevant interface section</span></a> to the configuration
file of Reticulum. For v1.x firmwares, you will have to specify all interface parameters, file of Reticulum. For v1.x firmwares, you will have to specify all interface parameters,
such as serial port and on-air parameters. For v2.x firmwares, you just need to specify such as serial port and on-air parameters. For v2.x firmwares, you just need to specify
the Connection ID of the RNode, and Reticulum will automatically locate and connect to the the Connection ID of the RNode, and Reticulum will automatically locate and connect to the
RNode, using the parameters stored in the RNode itself.</p> RNode, using the parameters stored in the RNode itself.</p>
</div> </section>
<div class="section" id="suppliers"> <section id="suppliers">
<span id="rnode-suppliers"></span><h3>Suppliers<a class="headerlink" href="#suppliers" title="Permalink to this headline"></a></h3> <span id="rnode-suppliers"></span><h3>Suppliers<a class="headerlink" href="#suppliers" title="Permalink to this heading"></a></h3>
<p>Get in touch if you want to have your RNode supplier listed here, or if you want help to <p>Get in touch if you want to have your RNode supplier listed here, or if you want help to
get started with producing RNodes.</p> get started with producing RNodes.</p>
</div> </section>
</div> </section>
<div class="section" id="wifi-based-hardware"> <section id="wifi-based-hardware">
<h2>WiFi-based Hardware<a class="headerlink" href="#wifi-based-hardware" title="Permalink to this headline"></a></h2> <h2>WiFi-based Hardware<a class="headerlink" href="#wifi-based-hardware" title="Permalink to this heading"></a></h2>
<p>It is possible to use all kinds of both short- and long-range WiFi-based hardware <p>It is possible to use all kinds of both short- and long-range WiFi-based hardware
with Reticulum. Any kind of hardware that fully supports bridged Ethernet over the with Reticulum. Any kind of hardware that fully supports bridged Ethernet over the
WiFi interface will work with the <a class="reference internal" href="interfaces.html#interfaces-auto"><span class="std std-ref">AutoInterface</span></a> in Reticulum. WiFi interface will work with the <a class="reference internal" href="interfaces.html#interfaces-auto"><span class="std std-ref">AutoInterface</span></a> in Reticulum.
@ -225,16 +228,16 @@ Reticulum links over long distances:</p>
that is relatively cheap while providing long range and high capacity for Reticulum that is relatively cheap while providing long range and high capacity for Reticulum
networks. As in all other cases, it is also possible for Reticulum to co-exist with IP networks. As in all other cases, it is also possible for Reticulum to co-exist with IP
networks running concurrently on such devices.</p> networks running concurrently on such devices.</p>
</div> </section>
<div class="section" id="combining-hardware-types"> <section id="combining-hardware-types">
<h2>Combining Hardware Types<a class="headerlink" href="#combining-hardware-types" title="Permalink to this headline"></a></h2> <h2>Combining Hardware Types<a class="headerlink" href="#combining-hardware-types" title="Permalink to this heading"></a></h2>
<p>It is useful to combine different link and hardware types when designing and <p>It is useful to combine different link and hardware types when designing and
building a network. One useful design pattern is to employ high-capacity point-to-point building a network. One useful design pattern is to employ high-capacity point-to-point
links based on WiFi or millimeter-wave radios (with high-gain directional antennas) links based on WiFi or millimeter-wave radios (with high-gain directional antennas)
for the network backbone, and using LoRa-based RNodes for covering large areas with for the network backbone, and using LoRa-based RNodes for covering large areas with
connectivity for client devices.</p> connectivity for client devices.</p>
</div> </section>
</div> </section>
<div class="clearer"></div> <div class="clearer"></div>
@ -243,8 +246,9 @@ connectivity for client devices.</p>
</div> </div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation"> <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper"> <div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table of Contents</a></h3> <div>
<ul> <h3><a href="index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Communications Hardware</a><ul> <li><a class="reference internal" href="#">Communications Hardware</a><ul>
<li><a class="reference internal" href="#rnode">RNode</a><ul> <li><a class="reference internal" href="#rnode">RNode</a><ul>
<li><a class="reference internal" href="#creating-rnodes">Creating RNodes</a></li> <li><a class="reference internal" href="#creating-rnodes">Creating RNodes</a></li>
@ -268,12 +272,17 @@ connectivity for client devices.</p>
</li> </li>
</ul> </ul>
<h4>Previous topic</h4> </div>
<p class="topless"><a href="understanding.html" <div>
title="previous chapter">Understanding Reticulum</a></p> <h4>Previous topic</h4>
<h4>Next topic</h4> <p class="topless"><a href="understanding.html"
<p class="topless"><a href="interfaces.html" title="previous chapter">Understanding Reticulum</a></p>
title="next chapter">Supported Interfaces</a></p> </div>
<div>
<h4>Next topic</h4>
<p class="topless"><a href="interfaces.html"
title="next chapter">Supported Interfaces</a></p>
</div>
<div role="note" aria-label="source link"> <div role="note" aria-label="source link">
<h3>This Page</h3> <h3>This Page</h3>
<ul class="this-page-menu"> <ul class="this-page-menu">
@ -285,12 +294,12 @@ connectivity for client devices.</p>
<h3 id="searchlabel">Quick search</h3> <h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper"> <div class="searchformwrapper">
<form class="search" action="search.html" method="get"> <form class="search" action="search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" /> <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" /> <input type="submit" value="Go" />
</form> </form>
</div> </div>
</div> </div>
<script>$('#searchbox').show(0);</script> <script>document.getElementById('searchbox').style.display = "block"</script>
</div> </div>
</div> </div>
<div class="clearer"></div> <div class="clearer"></div>
@ -313,7 +322,7 @@ connectivity for client devices.</p>
</div> </div>
<div class="footer" role="contentinfo"> <div class="footer" role="contentinfo">
&#169; Copyright 2022, Mark Qvist. &#169; Copyright 2022, Mark Qvist.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.1. Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 5.2.2.
</div> </div>
</body> </body>
</html> </html>

View File

@ -1,10 +1,11 @@
<!DOCTYPE html> <!DOCTYPE html>
<html> <html lang="en">
<head> <head>
<meta charset="utf-8" /> <meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />
<title>Reticulum Network Stack Manual &#8212; Reticulum Network Stack 0.3.12 beta documentation</title> <title>Reticulum Network Stack Manual &#8212; Reticulum Network Stack 0.3.12 beta documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css" /> <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="_static/classic.css" /> <link rel="stylesheet" type="text/css" href="_static/classic.css" />
@ -12,7 +13,9 @@
<script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
<script src="_static/jquery.js"></script> <script src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script> <script src="_static/underscore.js"></script>
<script src="_static/_sphinx_javascript_frameworks_compat.js"></script>
<script src="_static/doctools.js"></script> <script src="_static/doctools.js"></script>
<script src="_static/sphinx_highlight.js"></script>
<link rel="index" title="Index" href="genindex.html" /> <link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" /> <link rel="search" title="Search" href="search.html" />
@ -37,8 +40,8 @@
<div class="bodywrapper"> <div class="bodywrapper">
<div class="body" role="main"> <div class="body" role="main">
<div class="section" id="reticulum-network-stack-manual"> <section id="reticulum-network-stack-manual">
<h1>Reticulum Network Stack Manual<a class="headerlink" href="#reticulum-network-stack-manual" title="Permalink to this headline"></a></h1> <h1>Reticulum Network Stack Manual<a class="headerlink" href="#reticulum-network-stack-manual" title="Permalink to this heading"></a></h1>
<p>This manual aims to provide you with all the information you need to <p>This manual aims to provide you with all the information you need to
understand Reticulum, build networks or develop programs using it, or understand Reticulum, build networks or develop programs using it, or
to participate in the development of Reticulum itself.</p> to participate in the development of Reticulum itself.</p>
@ -189,14 +192,14 @@ to participate in the development of Reticulum itself.</p>
</li> </li>
</ul> </ul>
</div> </div>
<div class="section" id="indices-and-tables"> <section id="indices-and-tables">
<h2>Indices and Tables<a class="headerlink" href="#indices-and-tables" title="Permalink to this headline"></a></h2> <h2>Indices and Tables<a class="headerlink" href="#indices-and-tables" title="Permalink to this heading"></a></h2>
<ul class="simple"> <ul class="simple">
<li><p><a class="reference internal" href="genindex.html"><span class="std std-ref">Index</span></a></p></li> <li><p><a class="reference internal" href="genindex.html"><span class="std std-ref">Index</span></a></p></li>
<li><p><a class="reference internal" href="search.html"><span class="std std-ref">Search Page</span></a></p></li> <li><p><a class="reference internal" href="search.html"><span class="std std-ref">Search Page</span></a></p></li>
</ul> </ul>
</div> </section>
</div> </section>
<div class="clearer"></div> <div class="clearer"></div>
@ -205,17 +208,21 @@ to participate in the development of Reticulum itself.</p>
</div> </div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation"> <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper"> <div class="sphinxsidebarwrapper">
<h3><a href="#">Table of Contents</a></h3> <div>
<ul> <h3><a href="#">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Reticulum Network Stack Manual</a><ul> <li><a class="reference internal" href="#">Reticulum Network Stack Manual</a><ul>
<li><a class="reference internal" href="#indices-and-tables">Indices and Tables</a></li> <li><a class="reference internal" href="#indices-and-tables">Indices and Tables</a></li>
</ul> </ul>
</li> </li>
</ul> </ul>
<h4>Next topic</h4> </div>
<p class="topless"><a href="whatis.html" <div>
title="next chapter">What is Reticulum?</a></p> <h4>Next topic</h4>
<p class="topless"><a href="whatis.html"
title="next chapter">What is Reticulum?</a></p>
</div>
<div role="note" aria-label="source link"> <div role="note" aria-label="source link">
<h3>This Page</h3> <h3>This Page</h3>
<ul class="this-page-menu"> <ul class="this-page-menu">
@ -227,12 +234,12 @@ to participate in the development of Reticulum itself.</p>
<h3 id="searchlabel">Quick search</h3> <h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper"> <div class="searchformwrapper">
<form class="search" action="search.html" method="get"> <form class="search" action="search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" /> <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" /> <input type="submit" value="Go" />
</form> </form>
</div> </div>
</div> </div>
<script>$('#searchbox').show(0);</script> <script>document.getElementById('searchbox').style.display = "block"</script>
</div> </div>
</div> </div>
<div class="clearer"></div> <div class="clearer"></div>
@ -252,7 +259,7 @@ to participate in the development of Reticulum itself.</p>
</div> </div>
<div class="footer" role="contentinfo"> <div class="footer" role="contentinfo">
&#169; Copyright 2022, Mark Qvist. &#169; Copyright 2022, Mark Qvist.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.1. Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 5.2.2.
</div> </div>
</body> </body>
</html> </html>

View File

@ -1,10 +1,11 @@
<!DOCTYPE html> <!DOCTYPE html>
<html> <html lang="en">
<head> <head>
<meta charset="utf-8" /> <meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />
<title>Supported Interfaces &#8212; Reticulum Network Stack 0.3.12 beta documentation</title> <title>Supported Interfaces &#8212; Reticulum Network Stack 0.3.12 beta documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css" /> <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="_static/classic.css" /> <link rel="stylesheet" type="text/css" href="_static/classic.css" />
@ -12,7 +13,9 @@
<script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
<script src="_static/jquery.js"></script> <script src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script> <script src="_static/underscore.js"></script>
<script src="_static/_sphinx_javascript_frameworks_compat.js"></script>
<script src="_static/doctools.js"></script> <script src="_static/doctools.js"></script>
<script src="_static/sphinx_highlight.js"></script>
<link rel="index" title="Index" href="genindex.html" /> <link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" /> <link rel="search" title="Search" href="search.html" />
@ -41,8 +44,8 @@
<div class="bodywrapper"> <div class="bodywrapper">
<div class="body" role="main"> <div class="body" role="main">
<div class="section" id="supported-interfaces"> <section id="supported-interfaces">
<span id="interfaces-main"></span><h1>Supported Interfaces<a class="headerlink" href="#supported-interfaces" title="Permalink to this headline"></a></h1> <span id="interfaces-main"></span><h1>Supported Interfaces<a class="headerlink" href="#supported-interfaces" title="Permalink to this heading"></a></h1>
<p>Reticulum supports using many kinds of devices as networking interfaces, and <p>Reticulum supports using many kinds of devices as networking interfaces, and
allows you to mix and match them in any way you choose. The number of distinct allows you to mix and match them in any way you choose. The number of distinct
network topologies you can create with Reticulum is more or less endless, but network topologies you can create with Reticulum is more or less endless, but
@ -53,8 +56,8 @@ and gives example configurations for the respective interface types.</p>
<p>For a high-level overview of how networks can be formed over different interface <p>For a high-level overview of how networks can be formed over different interface
types, have a look at the <a class="reference internal" href="networks.html#networks-main"><span class="std std-ref">Building Networks</span></a> chapter of this types, have a look at the <a class="reference internal" href="networks.html#networks-main"><span class="std std-ref">Building Networks</span></a> chapter of this
manual.</p> manual.</p>
<div class="section" id="auto-interface"> <section id="auto-interface">
<span id="interfaces-auto"></span><h2>Auto Interface<a class="headerlink" href="#auto-interface" title="Permalink to this headline"></a></h2> <span id="interfaces-auto"></span><h2>Auto Interface<a class="headerlink" href="#auto-interface" title="Permalink to this heading"></a></h2>
<p>The Auto Interface enables communication with other discoverable Reticulum <p>The Auto Interface enables communication with other discoverable Reticulum
nodes over autoconfigured IPv6 and UDP. It does not need any functional IP nodes over autoconfigured IPv6 and UDP. It does not need any functional IP
infrastructure like routers or DHCP servers, but will require at least some infrastructure like routers or DHCP servers, but will require at least some
@ -106,9 +109,9 @@ the discovery scope by setting it to one of <code class="docutils literal notran
<span class="n">data_port</span> <span class="o">=</span> <span class="mi">49555</span> <span class="n">data_port</span> <span class="o">=</span> <span class="mi">49555</span>
</pre></div> </pre></div>
</div> </div>
</div> </section>
<div class="section" id="i2p-interface"> <section id="i2p-interface">
<span id="interfaces-i2p"></span><h2>I2P Interface<a class="headerlink" href="#i2p-interface" title="Permalink to this headline"></a></h2> <span id="interfaces-i2p"></span><h2>I2P Interface<a class="headerlink" href="#i2p-interface" title="Permalink to this heading"></a></h2>
<p>The I2P interface lets you connect Reticulum instances over the <p>The I2P interface lets you connect Reticulum instances over the
<a class="reference external" href="https://i2pd.website">Invisible Internet Protocol</a>. This can be <a class="reference external" href="https://i2pd.website">Invisible Internet Protocol</a>. This can be
especially useful in cases where you want to host a globally reachable especially useful in cases where you want to host a globally reachable
@ -159,9 +162,9 @@ You can use the I2PInterface to connect to a TCPServerInterface that
was manually tunneled over I2P, for example. This offers a high degree was manually tunneled over I2P, for example. This offers a high degree
of flexibility in network setup, while retaining ease of use in simpler of flexibility in network setup, while retaining ease of use in simpler
use-cases.</p> use-cases.</p>
</div> </section>
<div class="section" id="tcp-server-interface"> <section id="tcp-server-interface">
<span id="interfaces-tcps"></span><h2>TCP Server Interface<a class="headerlink" href="#tcp-server-interface" title="Permalink to this headline"></a></h2> <span id="interfaces-tcps"></span><h2>TCP Server Interface<a class="headerlink" href="#tcp-server-interface" title="Permalink to this heading"></a></h2>
<p>The TCP Server interface is suitable for allowing other peers to connect over <p>The TCP Server interface is suitable for allowing other peers to connect over
the Internet or private IP networks. When a TCP server interface has been the Internet or private IP networks. When a TCP server interface has been
configured, other Reticulum peers can connect to it with a TCP Client interface.</p> configured, other Reticulum peers can connect to it with a TCP Client interface.</p>
@ -176,7 +179,7 @@ configured, other Reticulum peers can connect to it with a TCP Client interface.
<span class="c1"># This configuration will listen on all IP</span> <span class="c1"># This configuration will listen on all IP</span>
<span class="c1"># interfaces on port 4242</span> <span class="c1"># interfaces on port 4242</span>
<span class="n">listen_ip</span> <span class="o">=</span> <span class="mf">0.0</span><span class="o">.</span><span class="mf">0.0</span> <span class="n">listen_ip</span> <span class="o">=</span> <span class="mf">0.0.0.0</span>
<span class="n">listen_port</span> <span class="o">=</span> <span class="mi">4242</span> <span class="n">listen_port</span> <span class="o">=</span> <span class="mi">4242</span>
<span class="c1"># Alternatively you can bind to a specific IP</span> <span class="c1"># Alternatively you can bind to a specific IP</span>
@ -195,16 +198,16 @@ you must use the i2p_tunneled option:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[[</span><span class="n">TCP</span> <span class="n">Server</span> <span class="n">on</span> <span class="n">I2P</span><span class="p">]]</span> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[[</span><span class="n">TCP</span> <span class="n">Server</span> <span class="n">on</span> <span class="n">I2P</span><span class="p">]]</span>
<span class="nb">type</span> <span class="o">=</span> <span class="n">TCPServerInterface</span> <span class="nb">type</span> <span class="o">=</span> <span class="n">TCPServerInterface</span>
<span class="n">interface_enabled</span> <span class="o">=</span> <span class="n">yes</span> <span class="n">interface_enabled</span> <span class="o">=</span> <span class="n">yes</span>
<span class="n">listen_ip</span> <span class="o">=</span> <span class="mf">127.0</span><span class="o">.</span><span class="mf">0.1</span> <span class="n">listen_ip</span> <span class="o">=</span> <span class="mf">127.0.0.1</span>
<span class="n">listen_port</span> <span class="o">=</span> <span class="mi">5001</span> <span class="n">listen_port</span> <span class="o">=</span> <span class="mi">5001</span>
<span class="n">i2p_tunneled</span> <span class="o">=</span> <span class="n">yes</span> <span class="n">i2p_tunneled</span> <span class="o">=</span> <span class="n">yes</span>
</pre></div> </pre></div>
</div> </div>
<p>In almost all cases, it is easier to use the dedicated <code class="docutils literal notranslate"><span class="pre">I2PInterface</span></code>, but for complete <p>In almost all cases, it is easier to use the dedicated <code class="docutils literal notranslate"><span class="pre">I2PInterface</span></code>, but for complete
control, and using I2P routers running on external systems, this option also exists.</p> control, and using I2P routers running on external systems, this option also exists.</p>
</div> </section>
<div class="section" id="tcp-client-interface"> <section id="tcp-client-interface">
<span id="interfaces-tcpc"></span><h2>TCP Client Interface<a class="headerlink" href="#tcp-client-interface" title="Permalink to this headline"></a></h2> <span id="interfaces-tcpc"></span><h2>TCP Client Interface<a class="headerlink" href="#tcp-client-interface" title="Permalink to this heading"></a></h2>
<p>To connect to a TCP server interface, you would naturally use the TCP client <p>To connect to a TCP server interface, you would naturally use the TCP client
interface. Many TCP Client interfaces from different peers can connect to the interface. Many TCP Client interfaces from different peers can connect to the
same TCP Server interface at the same time.</p> same TCP Server interface at the same time.</p>
@ -217,7 +220,7 @@ and restore connectivity after a failure, once the other end of a TCP interface
<span class="p">[[</span><span class="n">TCP</span> <span class="n">Client</span> <span class="n">Interface</span><span class="p">]]</span> <span class="p">[[</span><span class="n">TCP</span> <span class="n">Client</span> <span class="n">Interface</span><span class="p">]]</span>
<span class="nb">type</span> <span class="o">=</span> <span class="n">TCPClientInterface</span> <span class="nb">type</span> <span class="o">=</span> <span class="n">TCPClientInterface</span>
<span class="n">interface_enabled</span> <span class="o">=</span> <span class="kc">True</span> <span class="n">interface_enabled</span> <span class="o">=</span> <span class="kc">True</span>
<span class="n">target_host</span> <span class="o">=</span> <span class="mf">127.0</span><span class="o">.</span><span class="mf">0.1</span> <span class="n">target_host</span> <span class="o">=</span> <span class="mf">127.0.0.1</span>
<span class="n">target_port</span> <span class="o">=</span> <span class="mi">4242</span> <span class="n">target_port</span> <span class="o">=</span> <span class="mi">4242</span>
</pre></div> </pre></div>
</div> </div>
@ -231,7 +234,7 @@ software-based soundmodems. To do this, use the <code class="docutils literal no
<span class="nb">type</span> <span class="o">=</span> <span class="n">TCPClientInterface</span> <span class="nb">type</span> <span class="o">=</span> <span class="n">TCPClientInterface</span>
<span class="n">interface_enabled</span> <span class="o">=</span> <span class="kc">True</span> <span class="n">interface_enabled</span> <span class="o">=</span> <span class="kc">True</span>
<span class="n">kiss_framing</span> <span class="o">=</span> <span class="kc">True</span> <span class="n">kiss_framing</span> <span class="o">=</span> <span class="kc">True</span>
<span class="n">target_host</span> <span class="o">=</span> <span class="mf">127.0</span><span class="o">.</span><span class="mf">0.1</span> <span class="n">target_host</span> <span class="o">=</span> <span class="mf">127.0.0.1</span>
<span class="n">target_port</span> <span class="o">=</span> <span class="mi">8001</span> <span class="n">target_port</span> <span class="o">=</span> <span class="mi">8001</span>
</pre></div> </pre></div>
</div> </div>
@ -246,14 +249,14 @@ you must use the i2p_tunneled option:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[[</span><span class="n">TCP</span> <span class="n">Client</span> <span class="n">over</span> <span class="n">I2P</span><span class="p">]]</span> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[[</span><span class="n">TCP</span> <span class="n">Client</span> <span class="n">over</span> <span class="n">I2P</span><span class="p">]]</span>
<span class="nb">type</span> <span class="o">=</span> <span class="n">TCPClientInterface</span> <span class="nb">type</span> <span class="o">=</span> <span class="n">TCPClientInterface</span>
<span class="n">interface_enabled</span> <span class="o">=</span> <span class="n">yes</span> <span class="n">interface_enabled</span> <span class="o">=</span> <span class="n">yes</span>
<span class="n">target_host</span> <span class="o">=</span> <span class="mf">127.0</span><span class="o">.</span><span class="mf">0.1</span> <span class="n">target_host</span> <span class="o">=</span> <span class="mf">127.0.0.1</span>
<span class="n">target_port</span> <span class="o">=</span> <span class="mi">5001</span> <span class="n">target_port</span> <span class="o">=</span> <span class="mi">5001</span>
<span class="n">i2p_tunneled</span> <span class="o">=</span> <span class="n">yes</span> <span class="n">i2p_tunneled</span> <span class="o">=</span> <span class="n">yes</span>
</pre></div> </pre></div>
</div> </div>
</div> </section>
<div class="section" id="udp-interface"> <section id="udp-interface">
<span id="interfaces-udp"></span><h2>UDP Interface<a class="headerlink" href="#udp-interface" title="Permalink to this headline"></a></h2> <span id="interfaces-udp"></span><h2>UDP Interface<a class="headerlink" href="#udp-interface" title="Permalink to this heading"></a></h2>
<p>A UDP interface can be useful for communicating over IP networks, both <p>A UDP interface can be useful for communicating over IP networks, both
private and the internet. It can also allow broadcast communication private and the internet. It can also allow broadcast communication
over IP networks, so it can provide an easy way to enable connectivity over IP networks, so it can provide an easy way to enable connectivity
@ -270,9 +273,9 @@ easier to use.</p>
<span class="nb">type</span> <span class="o">=</span> <span class="n">UDPInterface</span> <span class="nb">type</span> <span class="o">=</span> <span class="n">UDPInterface</span>
<span class="n">interface_enabled</span> <span class="o">=</span> <span class="kc">True</span> <span class="n">interface_enabled</span> <span class="o">=</span> <span class="kc">True</span>
<span class="n">listen_ip</span> <span class="o">=</span> <span class="mf">0.0</span><span class="o">.</span><span class="mf">0.0</span> <span class="n">listen_ip</span> <span class="o">=</span> <span class="mf">0.0.0.0</span>
<span class="n">listen_port</span> <span class="o">=</span> <span class="mi">4242</span> <span class="n">listen_port</span> <span class="o">=</span> <span class="mi">4242</span>
<span class="n">forward_ip</span> <span class="o">=</span> <span class="mf">255.255</span><span class="o">.</span><span class="mf">255.255</span> <span class="n">forward_ip</span> <span class="o">=</span> <span class="mf">255.255.255.255</span>
<span class="n">forward_port</span> <span class="o">=</span> <span class="mi">4242</span> <span class="n">forward_port</span> <span class="o">=</span> <span class="mi">4242</span>
<span class="c1"># The above configuration will allow communication</span> <span class="c1"># The above configuration will allow communication</span>
@ -306,9 +309,9 @@ easier to use.</p>
<span class="c1"># forward_port = 4242</span> <span class="c1"># forward_port = 4242</span>
</pre></div> </pre></div>
</div> </div>
</div> </section>
<div class="section" id="rnode-lora-interface"> <section id="rnode-lora-interface">
<span id="interfaces-rnode"></span><h2>RNode LoRa Interface<a class="headerlink" href="#rnode-lora-interface" title="Permalink to this headline"></a></h2> <span id="interfaces-rnode"></span><h2>RNode LoRa Interface<a class="headerlink" href="#rnode-lora-interface" title="Permalink to this heading"></a></h2>
<p>To use Reticulum over LoRa, the <a class="reference external" href="https://unsigned.io/rnode/">RNode</a> interface <p>To use Reticulum over LoRa, the <a class="reference external" href="https://unsigned.io/rnode/">RNode</a> interface
can be used, and offers full control over LoRa parameters.</p> can be used, and offers full control over LoRa parameters.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Here&#39;s an example of how to add a LoRa interface</span> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Here&#39;s an example of how to add a LoRa interface</span>
@ -357,9 +360,9 @@ can be used, and offers full control over LoRa parameters.</p>
<span class="n">flow_control</span> <span class="o">=</span> <span class="kc">False</span> <span class="n">flow_control</span> <span class="o">=</span> <span class="kc">False</span>
</pre></div> </pre></div>
</div> </div>
</div> </section>
<div class="section" id="serial-interface"> <section id="serial-interface">
<span id="interfaces-serial"></span><h2>Serial Interface<a class="headerlink" href="#serial-interface" title="Permalink to this headline"></a></h2> <span id="interfaces-serial"></span><h2>Serial Interface<a class="headerlink" href="#serial-interface" title="Permalink to this heading"></a></h2>
<p>Reticulum can be used over serial ports directly, or over any device with a <p>Reticulum can be used over serial ports directly, or over any device with a
serial port, that will transparently pass data. Useful for communicating serial port, that will transparently pass data. Useful for communicating
directly over a wire-pair, or for using devices such as data radios and lasers.</p> directly over a wire-pair, or for using devices such as data radios and lasers.</p>
@ -378,9 +381,9 @@ directly over a wire-pair, or for using devices such as data radios and lasers.<
<span class="n">stopbits</span> <span class="o">=</span> <span class="mi">1</span> <span class="n">stopbits</span> <span class="o">=</span> <span class="mi">1</span>
</pre></div> </pre></div>
</div> </div>
</div> </section>
<div class="section" id="pipe-interface"> <section id="pipe-interface">
<span id="interfaces-pipe"></span><h2>Pipe Interface<a class="headerlink" href="#pipe-interface" title="Permalink to this headline"></a></h2> <span id="interfaces-pipe"></span><h2>Pipe Interface<a class="headerlink" href="#pipe-interface" title="Permalink to this heading"></a></h2>
<p>Using this interface, Reticulum can use any program as an interface via <cite>stdin</cite> and <p>Using this interface, Reticulum can use any program as an interface via <cite>stdin</cite> and
<cite>stdout</cite>. This can be used to easily create virtual interfaces, or to interface with <cite>stdout</cite>. This can be used to easily create virtual interfaces, or to interface with
custom hardware or other systems.</p> custom hardware or other systems.</p>
@ -398,9 +401,9 @@ custom hardware or other systems.</p>
<p>Reticulum will write all packets to <cite>stdin</cite> of the <code class="docutils literal notranslate"><span class="pre">command</span></code> option, and will <p>Reticulum will write all packets to <cite>stdin</cite> of the <code class="docutils literal notranslate"><span class="pre">command</span></code> option, and will
continuously read and scan its <cite>stdout</cite> for Reticulum packets. If <code class="docutils literal notranslate"><span class="pre">EOF</span></code> is reached, continuously read and scan its <cite>stdout</cite> for Reticulum packets. If <code class="docutils literal notranslate"><span class="pre">EOF</span></code> is reached,
Reticulum will try to respawn the program after waiting for <code class="docutils literal notranslate"><span class="pre">respawn_interval</span></code> seconds.</p> Reticulum will try to respawn the program after waiting for <code class="docutils literal notranslate"><span class="pre">respawn_interval</span></code> seconds.</p>
</div> </section>
<div class="section" id="kiss-interface"> <section id="kiss-interface">
<span id="interfaces-kiss"></span><h2>KISS Interface<a class="headerlink" href="#kiss-interface" title="Permalink to this headline"></a></h2> <span id="interfaces-kiss"></span><h2>KISS Interface<a class="headerlink" href="#kiss-interface" title="Permalink to this heading"></a></h2>
<p>With the KISS interface, you can use Reticulum over a variety of packet <p>With the KISS interface, you can use Reticulum over a variety of packet
radio modems and TNCs, including <a class="reference external" href="https://unsigned.io/openmodem/">OpenModem</a>. radio modems and TNCs, including <a class="reference external" href="https://unsigned.io/openmodem/">OpenModem</a>.
KISS interfaces can also be configured to periodically send out beacons KISS interfaces can also be configured to periodically send out beacons
@ -450,9 +453,9 @@ for station identification purposes.</p>
<span class="n">flow_control</span> <span class="o">=</span> <span class="n">false</span> <span class="n">flow_control</span> <span class="o">=</span> <span class="n">false</span>
</pre></div> </pre></div>
</div> </div>
</div> </section>
<div class="section" id="ax-25-kiss-interface"> <section id="ax-25-kiss-interface">
<span id="interfaces-ax25"></span><h2>AX.25 KISS Interface<a class="headerlink" href="#ax-25-kiss-interface" title="Permalink to this headline"></a></h2> <span id="interfaces-ax25"></span><h2>AX.25 KISS Interface<a class="headerlink" href="#ax-25-kiss-interface" title="Permalink to this heading"></a></h2>
<p>If youre using Reticulum on amateur radio spectrum, you might want to <p>If youre using Reticulum on amateur radio spectrum, you might want to
use the AX.25 KISS interface. This way, Reticulum will automatically use the AX.25 KISS interface. This way, Reticulum will automatically
encapsulate its traffic in AX.25 and also identify your stations encapsulate its traffic in AX.25 and also identify your stations
@ -462,7 +465,7 @@ layer for anything, and it incurs extra overhead on every packet to
encapsulate in AX.25.</p> encapsulate in AX.25.</p>
<p>A more efficient way is to use the plain KISS interface with the <p>A more efficient way is to use the plain KISS interface with the
beaconing functionality described above.</p> beaconing functionality described above.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[[</span><span class="n">Packet</span> <span class="n">Radio</span> <span class="n">AX</span><span class="o">.</span><span class="mi">25</span> <span class="n">KISS</span> <span class="n">Interface</span><span class="p">]]</span> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[[</span><span class="n">Packet</span> <span class="n">Radio</span> <span class="n">AX</span><span class="mf">.25</span> <span class="n">KISS</span> <span class="n">Interface</span><span class="p">]]</span>
<span class="nb">type</span> <span class="o">=</span> <span class="n">AX25KISSInterface</span> <span class="nb">type</span> <span class="o">=</span> <span class="n">AX25KISSInterface</span>
<span class="c1"># Set the station callsign and SSID</span> <span class="c1"># Set the station callsign and SSID</span>
@ -506,9 +509,9 @@ beaconing functionality described above.</p>
<span class="n">flow_control</span> <span class="o">=</span> <span class="n">false</span> <span class="n">flow_control</span> <span class="o">=</span> <span class="n">false</span>
</pre></div> </pre></div>
</div> </div>
</div> </section>
<div class="section" id="common-interface-options"> <section id="common-interface-options">
<span id="interfaces-options"></span><h2>Common Interface Options<a class="headerlink" href="#common-interface-options" title="Permalink to this headline"></a></h2> <span id="interfaces-options"></span><h2>Common Interface Options<a class="headerlink" href="#common-interface-options" title="Permalink to this heading"></a></h2>
<p>A number of general configuration options are available on most interfaces. <p>A number of general configuration options are available on most interfaces.
These can be used to control various aspects of interface behaviour.</p> These can be used to control various aspects of interface behaviour.</p>
<blockquote> <blockquote>
@ -602,9 +605,9 @@ option, to set the interface speed in <em>bits per second</em>.</div>
</li> </li>
</ul> </ul>
</div></blockquote> </div></blockquote>
</div> </section>
<div class="section" id="interface-modes"> <section id="interface-modes">
<span id="interfaces-modes"></span><h2>Interface Modes<a class="headerlink" href="#interface-modes" title="Permalink to this headline"></a></h2> <span id="interfaces-modes"></span><h2>Interface Modes<a class="headerlink" href="#interface-modes" title="Permalink to this heading"></a></h2>
<p>The optional <code class="docutils literal notranslate"><span class="pre">mode</span></code> setting is available on all interfaces, and allows <p>The optional <code class="docutils literal notranslate"><span class="pre">mode</span></code> setting is available on all interfaces, and allows
selecting the high-level behaviour of the interface from a number of modes. selecting the high-level behaviour of the interface from a number of modes.
These modes affect how Reticulum selects paths in the network, how announces These modes affect how Reticulum selects paths in the network, how announces
@ -694,9 +697,9 @@ connecting over the Internet should be set to <code class="docutils literal notr
</div></blockquote> </div></blockquote>
<p>For a table describing the impact of all modes on announce propagation, <p>For a table describing the impact of all modes on announce propagation,
please see the <a class="reference internal" href="understanding.html#understanding-announcepropagation"><span class="std std-ref">Announce Propagation Rules</span></a> section.</p> please see the <a class="reference internal" href="understanding.html#understanding-announcepropagation"><span class="std std-ref">Announce Propagation Rules</span></a> section.</p>
</div> </section>
<div class="section" id="announce-rate-control"> <section id="announce-rate-control">
<span id="interfaces-announcerates"></span><h2>Announce Rate Control<a class="headerlink" href="#announce-rate-control" title="Permalink to this headline"></a></h2> <span id="interfaces-announcerates"></span><h2>Announce Rate Control<a class="headerlink" href="#announce-rate-control" title="Permalink to this heading"></a></h2>
<p>The built-in announce control mechanisms and the default <code class="docutils literal notranslate"><span class="pre">announce_cap</span></code> <p>The built-in announce control mechanisms and the default <code class="docutils literal notranslate"><span class="pre">announce_cap</span></code>
option described above are sufficient most of the time, but in some cases, especially on fast option described above are sufficient most of the time, but in some cases, especially on fast
interfaces, it may be useful to control the target announce rate. Using the interfaces, it may be useful to control the target announce rate. Using the
@ -742,8 +745,8 @@ rates. Slower networks will naturally tend towards using less frequent announces
conserve bandwidth, while very fast networks can support applications that conserve bandwidth, while very fast networks can support applications that
need very frequent announces. Reticulum implements these mechanisms to ensure need very frequent announces. Reticulum implements these mechanisms to ensure
that a large span of network types can seamlessly <em>co-exist</em> and interconnect.</p> that a large span of network types can seamlessly <em>co-exist</em> and interconnect.</p>
</div> </section>
</div> </section>
<div class="clearer"></div> <div class="clearer"></div>
@ -752,8 +755,9 @@ that a large span of network types can seamlessly <em>co-exist</em> and intercon
</div> </div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation"> <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper"> <div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table of Contents</a></h3> <div>
<ul> <h3><a href="index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Supported Interfaces</a><ul> <li><a class="reference internal" href="#">Supported Interfaces</a><ul>
<li><a class="reference internal" href="#auto-interface">Auto Interface</a></li> <li><a class="reference internal" href="#auto-interface">Auto Interface</a></li>
<li><a class="reference internal" href="#i2p-interface">I2P Interface</a></li> <li><a class="reference internal" href="#i2p-interface">I2P Interface</a></li>
@ -772,12 +776,17 @@ that a large span of network types can seamlessly <em>co-exist</em> and intercon
</li> </li>
</ul> </ul>
<h4>Previous topic</h4> </div>
<p class="topless"><a href="hardware.html" <div>
title="previous chapter">Communications Hardware</a></p> <h4>Previous topic</h4>
<h4>Next topic</h4> <p class="topless"><a href="hardware.html"
<p class="topless"><a href="networks.html" title="previous chapter">Communications Hardware</a></p>
title="next chapter">Building Networks</a></p> </div>
<div>
<h4>Next topic</h4>
<p class="topless"><a href="networks.html"
title="next chapter">Building Networks</a></p>
</div>
<div role="note" aria-label="source link"> <div role="note" aria-label="source link">
<h3>This Page</h3> <h3>This Page</h3>
<ul class="this-page-menu"> <ul class="this-page-menu">
@ -789,12 +798,12 @@ that a large span of network types can seamlessly <em>co-exist</em> and intercon
<h3 id="searchlabel">Quick search</h3> <h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper"> <div class="searchformwrapper">
<form class="search" action="search.html" method="get"> <form class="search" action="search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" /> <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" /> <input type="submit" value="Go" />
</form> </form>
</div> </div>
</div> </div>
<script>$('#searchbox').show(0);</script> <script>document.getElementById('searchbox').style.display = "block"</script>
</div> </div>
</div> </div>
<div class="clearer"></div> <div class="clearer"></div>
@ -817,7 +826,7 @@ that a large span of network types can seamlessly <em>co-exist</em> and intercon
</div> </div>
<div class="footer" role="contentinfo"> <div class="footer" role="contentinfo">
&#169; Copyright 2022, Mark Qvist. &#169; Copyright 2022, Mark Qvist.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.1. Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 5.2.2.
</div> </div>
</body> </body>
</html> </html>

View File

@ -1,10 +1,11 @@
<!DOCTYPE html> <!DOCTYPE html>
<html> <html lang="en">
<head> <head>
<meta charset="utf-8" /> <meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />
<title>Building Networks &#8212; Reticulum Network Stack 0.3.12 beta documentation</title> <title>Building Networks &#8212; Reticulum Network Stack 0.3.12 beta documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css" /> <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="_static/classic.css" /> <link rel="stylesheet" type="text/css" href="_static/classic.css" />
@ -12,7 +13,9 @@
<script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
<script src="_static/jquery.js"></script> <script src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script> <script src="_static/underscore.js"></script>
<script src="_static/_sphinx_javascript_frameworks_compat.js"></script>
<script src="_static/doctools.js"></script> <script src="_static/doctools.js"></script>
<script src="_static/sphinx_highlight.js"></script>
<link rel="index" title="Index" href="genindex.html" /> <link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" /> <link rel="search" title="Search" href="search.html" />
@ -41,8 +44,8 @@
<div class="bodywrapper"> <div class="bodywrapper">
<div class="body" role="main"> <div class="body" role="main">
<div class="section" id="building-networks"> <section id="building-networks">
<span id="networks-main"></span><h1>Building Networks<a class="headerlink" href="#building-networks" title="Permalink to this headline"></a></h1> <span id="networks-main"></span><h1>Building Networks<a class="headerlink" href="#building-networks" title="Permalink to this heading"></a></h1>
<p>This chapter will provide you with the knowledge needed to build networks with <p>This chapter will provide you with the knowledge needed to build networks with
Reticulum, which can often be easier than using traditional stacks, since you Reticulum, which can often be easier than using traditional stacks, since you
dont have to worry about coordinating addresses, subnets and routing for an dont have to worry about coordinating addresses, subnets and routing for an
@ -50,8 +53,8 @@ entire network that you might not know how will evolve in the future. With
Reticulum, you can simply add more segments to your network when it becomes Reticulum, you can simply add more segments to your network when it becomes
necessary, and Reticulum will handle the convergence of the entire network necessary, and Reticulum will handle the convergence of the entire network
automatically.</p> automatically.</p>
<div class="section" id="concepts-overview"> <section id="concepts-overview">
<h2>Concepts &amp; Overview<a class="headerlink" href="#concepts-overview" title="Permalink to this headline"></a></h2> <h2>Concepts &amp; Overview<a class="headerlink" href="#concepts-overview" title="Permalink to this heading"></a></h2>
<p>There are important points that need to be kept in mind when building networks <p>There are important points that need to be kept in mind when building networks
with Reticulum:</p> with Reticulum:</p>
<blockquote> <blockquote>
@ -144,13 +147,13 @@ chapter of this manual for interface configuration examples.</p>
<p>Any number of interfaces can be configured, and Reticulum will automatically <p>Any number of interfaces can be configured, and Reticulum will automatically
decide which are suitable to use in any given situation, depending on where decide which are suitable to use in any given situation, depending on where
traffic needs to flow.</p> traffic needs to flow.</p>
</div> </section>
<div class="section" id="example-scenarios"> <section id="example-scenarios">
<h2>Example Scenarios<a class="headerlink" href="#example-scenarios" title="Permalink to this headline"></a></h2> <h2>Example Scenarios<a class="headerlink" href="#example-scenarios" title="Permalink to this heading"></a></h2>
<p>This section illustrates a few example scenarios, and how they would, in general <p>This section illustrates a few example scenarios, and how they would, in general
terms, be planned, implemented and configured.</p> terms, be planned, implemented and configured.</p>
<div class="section" id="interconnected-lora-sites"> <section id="interconnected-lora-sites">
<h3>Interconnected LoRa Sites<a class="headerlink" href="#interconnected-lora-sites" title="Permalink to this headline"></a></h3> <h3>Interconnected LoRa Sites<a class="headerlink" href="#interconnected-lora-sites" title="Permalink to this heading"></a></h3>
<p>An organisation wants to provide communication and information services to its <p>An organisation wants to provide communication and information services to its
members, which are located mainly in three separate areas. Three suitable hill-top members, which are located mainly in three separate areas. Three suitable hill-top
locations are found, where the organisation can install equipment: Site A, B and C.</p> locations are found, where the organisation can install equipment: Site A, B and C.</p>
@ -177,9 +180,9 @@ with a Reticulum configuration file, that contains the right parameters for
communicating with the LoRa radios installed at the gateway sites.</p> communicating with the LoRa radios installed at the gateway sites.</p>
<p>Once users connect to the network, anyone will be able to communicate with anyone <p>Once users connect to the network, anyone will be able to communicate with anyone
else across all three sites.</p> else across all three sites.</p>
</div> </section>
<div class="section" id="bridging-over-the-internet"> <section id="bridging-over-the-internet">
<h3>Bridging Over the Internet<a class="headerlink" href="#bridging-over-the-internet" title="Permalink to this headline"></a></h3> <h3>Bridging Over the Internet<a class="headerlink" href="#bridging-over-the-internet" title="Permalink to this heading"></a></h3>
<p>As the organisation grows, several new communities form in places too far away <p>As the organisation grows, several new communities form in places too far away
from the core network to be reachable over WiFi links. New gateways similar to those from the core network to be reachable over WiFi links. New gateways similar to those
previously installed are set up for the new communities at the new sites D and E, but previously installed are set up for the new communities at the new sites D and E, but
@ -194,9 +197,9 @@ enabled Internet interface on the gateway at site A. Dori is now connected to bo
all the nodes at her own local site (through the hill-top LoRa gateway), and all the all the nodes at her own local site (through the hill-top LoRa gateway), and all the
combined users of sites A, B and C. She then enables transport on her node, and combined users of sites A, B and C. She then enables transport on her node, and
traffic from site D can now reach everyone at site A, B and C, and vice versa.</p> traffic from site D can now reach everyone at site A, B and C, and vice versa.</p>
</div> </section>
<div class="section" id="growth-and-convergence"> <section id="growth-and-convergence">
<h3>Growth and Convergence<a class="headerlink" href="#growth-and-convergence" title="Permalink to this headline"></a></h3> <h3>Growth and Convergence<a class="headerlink" href="#growth-and-convergence" title="Permalink to this heading"></a></h3>
<p>As the organisation grows, more gateways are added to keep up with the growing user <p>As the organisation grows, more gateways are added to keep up with the growing user
base. Some local gateways even add VHF radios and packet modems to reach outlying users base. Some local gateways even add VHF radios and packet modems to reach outlying users
and communities that are out of reach for the LoRa radios and WiFi backhauls.</p> and communities that are out of reach for the LoRa radios and WiFi backhauls.</p>
@ -208,9 +211,9 @@ space or routing tables.</p>
the original internet bridged interfaces are no longer utilised. The network has the original internet bridged interfaces are no longer utilised. The network has
converged to be completely self-connected, and the sites that were once poorly converged to be completely self-connected, and the sites that were once poorly
connected outliers are now an integral part of the network.</p> connected outliers are now an integral part of the network.</p>
</div> </section>
</div> </section>
</div> </section>
<div class="clearer"></div> <div class="clearer"></div>
@ -219,8 +222,9 @@ connected outliers are now an integral part of the network.</p>
</div> </div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation"> <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper"> <div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table of Contents</a></h3> <div>
<ul> <h3><a href="index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Building Networks</a><ul> <li><a class="reference internal" href="#">Building Networks</a><ul>
<li><a class="reference internal" href="#concepts-overview">Concepts &amp; Overview</a></li> <li><a class="reference internal" href="#concepts-overview">Concepts &amp; Overview</a></li>
<li><a class="reference internal" href="#example-scenarios">Example Scenarios</a><ul> <li><a class="reference internal" href="#example-scenarios">Example Scenarios</a><ul>
@ -233,12 +237,17 @@ connected outliers are now an integral part of the network.</p>
</li> </li>
</ul> </ul>
<h4>Previous topic</h4> </div>
<p class="topless"><a href="interfaces.html" <div>
title="previous chapter">Supported Interfaces</a></p> <h4>Previous topic</h4>
<h4>Next topic</h4> <p class="topless"><a href="interfaces.html"
<p class="topless"><a href="reference.html" title="previous chapter">Supported Interfaces</a></p>
title="next chapter">API Reference</a></p> </div>
<div>
<h4>Next topic</h4>
<p class="topless"><a href="reference.html"
title="next chapter">API Reference</a></p>
</div>
<div role="note" aria-label="source link"> <div role="note" aria-label="source link">
<h3>This Page</h3> <h3>This Page</h3>
<ul class="this-page-menu"> <ul class="this-page-menu">
@ -250,12 +259,12 @@ connected outliers are now an integral part of the network.</p>
<h3 id="searchlabel">Quick search</h3> <h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper"> <div class="searchformwrapper">
<form class="search" action="search.html" method="get"> <form class="search" action="search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" /> <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" /> <input type="submit" value="Go" />
</form> </form>
</div> </div>
</div> </div>
<script>$('#searchbox').show(0);</script> <script>document.getElementById('searchbox').style.display = "block"</script>
</div> </div>
</div> </div>
<div class="clearer"></div> <div class="clearer"></div>
@ -278,7 +287,7 @@ connected outliers are now an integral part of the network.</p>
</div> </div>
<div class="footer" role="contentinfo"> <div class="footer" role="contentinfo">
&#169; Copyright 2022, Mark Qvist. &#169; Copyright 2022, Mark Qvist.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.1. Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 5.2.2.
</div> </div>
</body> </body>
</html> </html>

File diff suppressed because it is too large Load Diff

View File

@ -1,7 +1,7 @@
<!DOCTYPE html> <!DOCTYPE html>
<html> <html lang="en">
<head> <head>
<meta charset="utf-8" /> <meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" />
@ -13,7 +13,9 @@
<script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
<script src="_static/jquery.js"></script> <script src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script> <script src="_static/underscore.js"></script>
<script src="_static/_sphinx_javascript_frameworks_compat.js"></script>
<script src="_static/doctools.js"></script> <script src="_static/doctools.js"></script>
<script src="_static/sphinx_highlight.js"></script>
<script src="_static/searchtools.js"></script> <script src="_static/searchtools.js"></script>
<script src="_static/language_data.js"></script> <script src="_static/language_data.js"></script>
@ -41,13 +43,14 @@
<h1 id="search-documentation">Search</h1> <h1 id="search-documentation">Search</h1>
<div id="fallback" class="admonition warning"> <noscript>
<script>$('#fallback').hide();</script> <div class="admonition warning">
<p> <p>
Please activate JavaScript to enable the search Please activate JavaScript to enable the search
functionality. functionality.
</p> </p>
</div> </div>
</noscript>
<p> <p>
@ -57,7 +60,7 @@
<form action="" method="get"> <form action="" method="get">
<input type="text" name="q" aria-labelledby="search-documentation" value="" /> <input type="text" name="q" aria-labelledby="search-documentation" value="" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="search" /> <input type="submit" value="search" />
<span id="search-progress" style="padding-left: 10px"></span> <span id="search-progress" style="padding-left: 10px"></span>
</form> </form>
@ -91,7 +94,7 @@
</div> </div>
<div class="footer" role="contentinfo"> <div class="footer" role="contentinfo">
&#169; Copyright 2022, Mark Qvist. &#169; Copyright 2022, Mark Qvist.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.1. Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 5.2.2.
</div> </div>
</body> </body>
</html> </html>

File diff suppressed because one or more lines are too long

View File

@ -1,10 +1,11 @@
<!DOCTYPE html> <!DOCTYPE html>
<html> <html lang="en">
<head> <head>
<meta charset="utf-8" /> <meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />
<title>Support Reticulum &#8212; Reticulum Network Stack 0.3.12 beta documentation</title> <title>Support Reticulum &#8212; Reticulum Network Stack 0.3.12 beta documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css" /> <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="_static/classic.css" /> <link rel="stylesheet" type="text/css" href="_static/classic.css" />
@ -12,7 +13,9 @@
<script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
<script src="_static/jquery.js"></script> <script src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script> <script src="_static/underscore.js"></script>
<script src="_static/_sphinx_javascript_frameworks_compat.js"></script>
<script src="_static/doctools.js"></script> <script src="_static/doctools.js"></script>
<script src="_static/sphinx_highlight.js"></script>
<link rel="index" title="Index" href="genindex.html" /> <link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" /> <link rel="search" title="Search" href="search.html" />
@ -37,12 +40,12 @@
<div class="bodywrapper"> <div class="bodywrapper">
<div class="body" role="main"> <div class="body" role="main">
<div class="section" id="support-reticulum"> <section id="support-reticulum">
<span id="support-main"></span><h1>Support Reticulum<a class="headerlink" href="#support-reticulum" title="Permalink to this headline"></a></h1> <span id="support-main"></span><h1>Support Reticulum<a class="headerlink" href="#support-reticulum" title="Permalink to this heading"></a></h1>
<p>You can help support the continued development of open, free and private communications <p>You can help support the continued development of open, free and private communications
systems by donating, providing feedback and contributing code and learning resources.</p> systems by donating, providing feedback and contributing code and learning resources.</p>
<div class="section" id="donations"> <section id="donations">
<h2>Donations<a class="headerlink" href="#donations" title="Permalink to this headline"></a></h2> <h2>Donations<a class="headerlink" href="#donations" title="Permalink to this heading"></a></h2>
<p>Donations are gratefully accepted via the following channels:</p> <p>Donations are gratefully accepted via the following channels:</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>Monero: <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>Monero:
84FpY1QbxHcgdseePYNmhTHcrgMX4nFfBYtz2GKYToqHVVhJp8Eaw1Z1EedRnKD19b3B8NiLCGVxzKV17UMmmeEsCrPyA5w 84FpY1QbxHcgdseePYNmhTHcrgMX4nFfBYtz2GKYToqHVVhJp8Eaw1Z1EedRnKD19b3B8NiLCGVxzKV17UMmmeEsCrPyA5w
@ -59,21 +62,21 @@ https://ko-fi.com/markqvist
</div> </div>
<p>Are certain features in the development roadmap are important to you or your <p>Are certain features in the development roadmap are important to you or your
organisation? Make them a reality quickly by sponsoring their implementation.</p> organisation? Make them a reality quickly by sponsoring their implementation.</p>
</div> </section>
<div class="section" id="provide-feedback"> <section id="provide-feedback">
<h2>Provide Feedback<a class="headerlink" href="#provide-feedback" title="Permalink to this headline"></a></h2> <h2>Provide Feedback<a class="headerlink" href="#provide-feedback" title="Permalink to this heading"></a></h2>
<p>All feedback on the usage, functioning and potential dysfunctioning of any and <p>All feedback on the usage, functioning and potential dysfunctioning of any and
all components of the system is very valuable to the continued development and all components of the system is very valuable to the continued development and
improvement of Reticulum. Absolutely no automated analytics, telemetry, error improvement of Reticulum. Absolutely no automated analytics, telemetry, error
reporting or statistics is collected and reported by Reticulum under any reporting or statistics is collected and reported by Reticulum under any
circumstances, so we rely on old-fashioned human feedback.</p> circumstances, so we rely on old-fashioned human feedback.</p>
</div> </section>
<div class="section" id="contribute-code"> <section id="contribute-code">
<h2>Contribute Code<a class="headerlink" href="#contribute-code" title="Permalink to this headline"></a></h2> <h2>Contribute Code<a class="headerlink" href="#contribute-code" title="Permalink to this heading"></a></h2>
<p>Join us on <a class="reference external" href="https://github.com/markqvist/reticulum">the GitHub repository</a> to <p>Join us on <a class="reference external" href="https://github.com/markqvist/reticulum">the GitHub repository</a> to
report issues, suggest functionality and contribute code to Reticulum.</p> report issues, suggest functionality and contribute code to Reticulum.</p>
</div> </section>
</div> </section>
<div class="clearer"></div> <div class="clearer"></div>
@ -82,8 +85,9 @@ report issues, suggest functionality and contribute code to Reticulum.</p>
</div> </div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation"> <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper"> <div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table of Contents</a></h3> <div>
<ul> <h3><a href="index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Support Reticulum</a><ul> <li><a class="reference internal" href="#">Support Reticulum</a><ul>
<li><a class="reference internal" href="#donations">Donations</a></li> <li><a class="reference internal" href="#donations">Donations</a></li>
<li><a class="reference internal" href="#provide-feedback">Provide Feedback</a></li> <li><a class="reference internal" href="#provide-feedback">Provide Feedback</a></li>
@ -92,9 +96,12 @@ report issues, suggest functionality and contribute code to Reticulum.</p>
</li> </li>
</ul> </ul>
<h4>Previous topic</h4> </div>
<p class="topless"><a href="examples.html" <div>
title="previous chapter">Code Examples</a></p> <h4>Previous topic</h4>
<p class="topless"><a href="examples.html"
title="previous chapter">Code Examples</a></p>
</div>
<div role="note" aria-label="source link"> <div role="note" aria-label="source link">
<h3>This Page</h3> <h3>This Page</h3>
<ul class="this-page-menu"> <ul class="this-page-menu">
@ -106,12 +113,12 @@ report issues, suggest functionality and contribute code to Reticulum.</p>
<h3 id="searchlabel">Quick search</h3> <h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper"> <div class="searchformwrapper">
<form class="search" action="search.html" method="get"> <form class="search" action="search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" /> <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" /> <input type="submit" value="Go" />
</form> </form>
</div> </div>
</div> </div>
<script>$('#searchbox').show(0);</script> <script>document.getElementById('searchbox').style.display = "block"</script>
</div> </div>
</div> </div>
<div class="clearer"></div> <div class="clearer"></div>
@ -131,7 +138,7 @@ report issues, suggest functionality and contribute code to Reticulum.</p>
</div> </div>
<div class="footer" role="contentinfo"> <div class="footer" role="contentinfo">
&#169; Copyright 2022, Mark Qvist. &#169; Copyright 2022, Mark Qvist.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.1. Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 5.2.2.
</div> </div>
</body> </body>
</html> </html>

View File

@ -1,10 +1,11 @@
<!DOCTYPE html> <!DOCTYPE html>
<html> <html lang="en">
<head> <head>
<meta charset="utf-8" /> <meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />
<title>Understanding Reticulum &#8212; Reticulum Network Stack 0.3.12 beta documentation</title> <title>Understanding Reticulum &#8212; Reticulum Network Stack 0.3.12 beta documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css" /> <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="_static/classic.css" /> <link rel="stylesheet" type="text/css" href="_static/classic.css" />
@ -12,7 +13,9 @@
<script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
<script src="_static/jquery.js"></script> <script src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script> <script src="_static/underscore.js"></script>
<script src="_static/_sphinx_javascript_frameworks_compat.js"></script>
<script src="_static/doctools.js"></script> <script src="_static/doctools.js"></script>
<script src="_static/sphinx_highlight.js"></script>
<link rel="index" title="Index" href="genindex.html" /> <link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" /> <link rel="search" title="Search" href="search.html" />
@ -41,8 +44,8 @@
<div class="bodywrapper"> <div class="bodywrapper">
<div class="body" role="main"> <div class="body" role="main">
<div class="section" id="understanding-reticulum"> <section id="understanding-reticulum">
<span id="understanding-main"></span><h1>Understanding Reticulum<a class="headerlink" href="#understanding-reticulum" title="Permalink to this headline"></a></h1> <span id="understanding-main"></span><h1>Understanding Reticulum<a class="headerlink" href="#understanding-reticulum" title="Permalink to this heading"></a></h1>
<p>This chapter will briefly describe the overall purpose and operating principles of Reticulum. <p>This chapter will briefly describe the overall purpose and operating principles of Reticulum.
It should give you an overview of how the stack works, and an understanding of how to It should give you an overview of how the stack works, and an understanding of how to
develop networked applications using Reticulum.</p> develop networked applications using Reticulum.</p>
@ -56,8 +59,8 @@ operates, what it can achieve, and how you can use it yourself. If you want to h
development, this is also the place to start, since it will provide a pretty clear overview of the development, this is also the place to start, since it will provide a pretty clear overview of the
sentiments and the philosophy behind Reticulum, what problems it seeks to solve, and how it sentiments and the philosophy behind Reticulum, what problems it seeks to solve, and how it
approaches those solutions.</p> approaches those solutions.</p>
<div class="section" id="motivation"> <section id="motivation">
<span id="understanding-motivation"></span><h2>Motivation<a class="headerlink" href="#motivation" title="Permalink to this headline"></a></h2> <span id="understanding-motivation"></span><h2>Motivation<a class="headerlink" href="#motivation" title="Permalink to this heading"></a></h2>
<p>The primary motivation for designing and implementing Reticulum has been the current lack of <p>The primary motivation for designing and implementing Reticulum has been the current lack of
reliable, functional and secure minimal-infrastructure modes of digital communication. It is my reliable, functional and secure minimal-infrastructure modes of digital communication. It is my
belief that it is highly desirable to create a reliable and efficient way to set up long-range digital belief that it is highly desirable to create a reliable and efficient way to set up long-range digital
@ -83,9 +86,9 @@ cheap and easy to cover vast areas with a myriad of independent, interconnectabl
Reticulum <strong>is not</strong> <em>one network</em>, it <strong>is a tool</strong> to build <em>thousands of networks</em>. Networks without Reticulum <strong>is not</strong> <em>one network</em>, it <strong>is a tool</strong> to build <em>thousands of networks</em>. Networks without
kill-switches, surveillance, censorship and control. Networks that can freely interoperate, associate and disassociate kill-switches, surveillance, censorship and control. Networks that can freely interoperate, associate and disassociate
with each other, and require no central oversight. Networks for human beings. <em>Networks for the people</em>.</p> with each other, and require no central oversight. Networks for human beings. <em>Networks for the people</em>.</p>
</div> </section>
<div class="section" id="goals"> <section id="goals">
<span id="understanding-goals"></span><h2>Goals<a class="headerlink" href="#goals" title="Permalink to this headline"></a></h2> <span id="understanding-goals"></span><h2>Goals<a class="headerlink" href="#goals" title="Permalink to this heading"></a></h2>
<p>To be as widely usable and efficient to deploy as possible, the following goals have been used to <p>To be as widely usable and efficient to deploy as possible, the following goals have been used to
guide the design of Reticulum:</p> guide the design of Reticulum:</p>
<ul class="simple"> <ul class="simple">
@ -154,9 +157,9 @@ needs to be purchased.</p>
</dl> </dl>
</li> </li>
</ul> </ul>
</div> </section>
<div class="section" id="introduction-basic-functionality"> <section id="introduction-basic-functionality">
<span id="understanding-basicfunctionality"></span><h2>Introduction &amp; Basic Functionality<a class="headerlink" href="#introduction-basic-functionality" title="Permalink to this headline"></a></h2> <span id="understanding-basicfunctionality"></span><h2>Introduction &amp; Basic Functionality<a class="headerlink" href="#introduction-basic-functionality" title="Permalink to this heading"></a></h2>
<p>Reticulum is a networking stack suited for high-latency, low-bandwidth links. Reticulum is at its <p>Reticulum is a networking stack suited for high-latency, low-bandwidth links. Reticulum is at its
core a <em>message oriented</em> system. It is suited for both local point-to-point or point-to-multipoint core a <em>message oriented</em> system. It is suited for both local point-to-point or point-to-multipoint
scenarios where all nodes are within range of each other, as well as scenarios where packets need scenarios where all nodes are within range of each other, as well as scenarios where packets need
@ -188,8 +191,8 @@ unencrypted packets for local broadcast purposes.</p>
<p>Reticulum can connect to a variety of interfaces such as radio modems, data radios and serial ports, <p>Reticulum can connect to a variety of interfaces such as radio modems, data radios and serial ports,
and offers the possibility to easily tunnel Reticulum traffic over IP links such as the Internet or and offers the possibility to easily tunnel Reticulum traffic over IP links such as the Internet or
private IP networks.</p> private IP networks.</p>
<div class="section" id="destinations"> <section id="destinations">
<span id="understanding-destinations"></span><h3>Destinations<a class="headerlink" href="#destinations" title="Permalink to this headline"></a></h3> <span id="understanding-destinations"></span><h3>Destinations<a class="headerlink" href="#destinations" title="Permalink to this heading"></a></h3>
<p>To receive and send data with the Reticulum stack, an application needs to create one or more <p>To receive and send data with the Reticulum stack, an application needs to create one or more
destinations. Reticulum uses three different basic destination types, and one special:</p> destinations. Reticulum uses three different basic destination types, and one special:</p>
<ul class="simple"> <ul class="simple">
@ -231,8 +234,8 @@ out requests and responses, large data transfers and more.</p>
</dl> </dl>
</li> </li>
</ul> </ul>
<div class="section" id="destination-naming"> <section id="destination-naming">
<span id="understanding-destinationnaming"></span><h4>Destination Naming<a class="headerlink" href="#destination-naming" title="Permalink to this headline"></a></h4> <span id="understanding-destinationnaming"></span><h4>Destination Naming<a class="headerlink" href="#destination-naming" title="Permalink to this heading"></a></h4>
<p>Destinations are created and named in an easy to understand dotted notation of <em>aspects</em>, and <p>Destinations are created and named in an easy to understand dotted notation of <em>aspects</em>, and
represented on the network as a hash of this value. The hash is a SHA-256 truncated to 128 bits. The represented on the network as a hash of this value. The hash is a SHA-256 truncated to 128 bits. The
top level aspect should always be a unique identifier for the application using the destination. top level aspect should always be a unique identifier for the application using the destination.
@ -296,10 +299,10 @@ of public keys.</p>
built-in <em>announce</em> functionality, and that it is therefore not required to use the <em>announce</em> and <em>path request</em> built-in <em>announce</em> functionality, and that it is therefore not required to use the <em>announce</em> and <em>path request</em>
functionality to obtain public keys. It is by far the easiest though, and should definitely be used functionality to obtain public keys. It is by far the easiest though, and should definitely be used
if there is not a very good reason for doing it differently.</p> if there is not a very good reason for doing it differently.</p>
</div> </section>
</div> </section>
<div class="section" id="public-key-announcements"> <section id="public-key-announcements">
<span id="understanding-keyannouncements"></span><h3>Public Key Announcements<a class="headerlink" href="#public-key-announcements" title="Permalink to this headline"></a></h3> <span id="understanding-keyannouncements"></span><h3>Public Key Announcements<a class="headerlink" href="#public-key-announcements" title="Permalink to this heading"></a></h3>
<p>An <em>announce</em> will send a special packet over any relevant interfaces, containing all needed <p>An <em>announce</em> will send a special packet over any relevant interfaces, containing all needed
information about the destination hash and public key, and can also contain some additional, information about the destination hash and public key, and can also contain some additional,
application specific data. The entire packet is signed by the sender to ensure authenticity. It is not application specific data. The entire packet is signed by the sender to ensure authenticity. It is not
@ -331,9 +334,9 @@ of the network, and <em>can even be moved to other Reticulum networks</em> than
still become reachable. To update its reachability, a destination simply needs to send an announce on any still become reachable. To update its reachability, a destination simply needs to send an announce on any
networks it is part of. After a short while, it will be globally reachable in the network.</p> networks it is part of. After a short while, it will be globally reachable in the network.</p>
<p>Seeing how <em>single</em> destinations are always tied to a private/public key pair leads us to the next topic.</p> <p>Seeing how <em>single</em> destinations are always tied to a private/public key pair leads us to the next topic.</p>
</div> </section>
<div class="section" id="understanding-identities"> <section id="understanding-identities">
<span id="identities"></span><h3>Identities<a class="headerlink" href="#understanding-identities" title="Permalink to this headline"></a></h3> <span id="identities"></span><h3>Identities<a class="headerlink" href="#understanding-identities" title="Permalink to this heading"></a></h3>
<p>In Reticulum, an <em>identity</em> does not necessarily represent a personal identity, but is an abstraction that <p>In Reticulum, an <em>identity</em> does not necessarily represent a personal identity, but is an abstraction that
can represent any kind of <em>verifiable entity</em>. This could very well be a person, but it could also be the can represent any kind of <em>verifiable entity</em>. This could very well be a person, but it could also be the
control interface of a machine, a program, robot, computer, sensor or something else entirely. In control interface of a machine, a program, robot, computer, sensor or something else entirely. In
@ -349,18 +352,18 @@ Destinations can then be created by this identity to allow communication to reac
In all cases it is of great importance to store the private keys associated with any In all cases it is of great importance to store the private keys associated with any
Reticulum Identity securely and privately, since obtaining access to the identity keys equals Reticulum Identity securely and privately, since obtaining access to the identity keys equals
obtaining access and controlling reachability to any destinations created by that identity.</p> obtaining access and controlling reachability to any destinations created by that identity.</p>
</div> </section>
<div class="section" id="getting-further"> <section id="getting-further">
<span id="understanding-gettingfurther"></span><h3>Getting Further<a class="headerlink" href="#getting-further" title="Permalink to this headline"></a></h3> <span id="understanding-gettingfurther"></span><h3>Getting Further<a class="headerlink" href="#getting-further" title="Permalink to this heading"></a></h3>
<p>The above functions and principles form the core of Reticulum, and would suffice to create <p>The above functions and principles form the core of Reticulum, and would suffice to create
functional networked applications in local clusters, for example over radio links where all interested functional networked applications in local clusters, for example over radio links where all interested
nodes can directly hear each other. But to be truly useful, we need a way to direct traffic over multiple nodes can directly hear each other. But to be truly useful, we need a way to direct traffic over multiple
hops in the network.</p> hops in the network.</p>
<p>In the following sections, two concepts that allow this will be introduced, <em>paths</em> and <em>links</em>.</p> <p>In the following sections, two concepts that allow this will be introduced, <em>paths</em> and <em>links</em>.</p>
</div> </section>
</div> </section>
<div class="section" id="reticulum-transport"> <section id="reticulum-transport">
<span id="understanding-transport"></span><h2>Reticulum Transport<a class="headerlink" href="#reticulum-transport" title="Permalink to this headline"></a></h2> <span id="understanding-transport"></span><h2>Reticulum Transport<a class="headerlink" href="#reticulum-transport" title="Permalink to this heading"></a></h2>
<p>The methods of routing used in traditional networks are fundamentally incompatible with the physical medium <p>The methods of routing used in traditional networks are fundamentally incompatible with the physical medium
types and circumstances that Reticulum was designed to handle. These mechanisms mostly assume trust at the physical layer, types and circumstances that Reticulum was designed to handle. These mechanisms mostly assume trust at the physical layer,
and often needs a lot more bandwidth than Reticulum can assume is available. Since Reticulum is designed to and often needs a lot more bandwidth than Reticulum can assume is available. Since Reticulum is designed to
@ -370,8 +373,8 @@ implement the concept of <em>paths</em> that allow discovery of how to get infor
destination. It is important to note that no single node in a Reticulum network knows the complete destination. It is important to note that no single node in a Reticulum network knows the complete
path to a destination. Every Transport node participating in a Reticulum network will only path to a destination. Every Transport node participating in a Reticulum network will only
know the most direct way to get a packet one hop closer to its destination.</p> know the most direct way to get a packet one hop closer to its destination.</p>
<div class="section" id="node-types"> <section id="node-types">
<span id="understanding-nodetypes"></span><h3>Node Types<a class="headerlink" href="#node-types" title="Permalink to this headline"></a></h3> <span id="understanding-nodetypes"></span><h3>Node Types<a class="headerlink" href="#node-types" title="Permalink to this heading"></a></h3>
<p>Currently, Reticulum distinguishes between two types of network nodes. All nodes on a Reticulum network <p>Currently, Reticulum distinguishes between two types of network nodes. All nodes on a Reticulum network
are <em>Reticulum Instances</em>, and some are also <em>Transport Nodes</em>. If a system running Reticulum is fixed in are <em>Reticulum Instances</em>, and some are also <em>Transport Nodes</em>. If a system running Reticulum is fixed in
one place, and is intended to be kept available most of the time, it is a good contender to be a <em>Transport Node</em>.</p> one place, and is intended to be kept available most of the time, it is a good contender to be a <em>Transport Node</em>.</p>
@ -381,9 +384,9 @@ network will help forward traffic, and what nodes rely on other nodes for wider
<p>If a node is an <em>Instance</em> it should be given the configuration directive <code class="docutils literal notranslate"><span class="pre">enable_transport</span> <span class="pre">=</span> <span class="pre">No</span></code>, which <p>If a node is an <em>Instance</em> it should be given the configuration directive <code class="docutils literal notranslate"><span class="pre">enable_transport</span> <span class="pre">=</span> <span class="pre">No</span></code>, which
is the default setting.</p> is the default setting.</p>
<p>If it is a <em>Transport Node</em>, it should be given the configuration directive <code class="docutils literal notranslate"><span class="pre">enable_transport</span> <span class="pre">=</span> <span class="pre">Yes</span></code>.</p> <p>If it is a <em>Transport Node</em>, it should be given the configuration directive <code class="docutils literal notranslate"><span class="pre">enable_transport</span> <span class="pre">=</span> <span class="pre">Yes</span></code>.</p>
</div> </section>
<div class="section" id="the-announce-mechanism-in-detail"> <section id="the-announce-mechanism-in-detail">
<span id="understanding-announce"></span><h3>The Announce Mechanism in Detail<a class="headerlink" href="#the-announce-mechanism-in-detail" title="Permalink to this headline"></a></h3> <span id="understanding-announce"></span><h3>The Announce Mechanism in Detail<a class="headerlink" href="#the-announce-mechanism-in-detail" title="Permalink to this heading"></a></h3>
<p>When an <em>announce</em> for a destination is transmitted by from a Reticulum instance, it will be forwarded by <p>When an <em>announce</em> for a destination is transmitted by from a Reticulum instance, it will be forwarded by
any transport node receiving it, but according to some specific rules:</p> any transport node receiving it, but according to some specific rules:</p>
<ul> <ul>
@ -446,9 +449,9 @@ and quickly converging end-to-end connectivity for their local, slower segments.
<p>In general, even extremely complex networks, that utilize the maximum 128 hops will converge to full <p>In general, even extremely complex networks, that utilize the maximum 128 hops will converge to full
end-to-end connectivity in about one minute, given there is enough bandwidth available to process end-to-end connectivity in about one minute, given there is enough bandwidth available to process
the required amount of announces.</p> the required amount of announces.</p>
</div> </section>
<div class="section" id="reaching-the-destination"> <section id="reaching-the-destination">
<span id="understanding-paths"></span><h3>Reaching the Destination<a class="headerlink" href="#reaching-the-destination" title="Permalink to this headline"></a></h3> <span id="understanding-paths"></span><h3>Reaching the Destination<a class="headerlink" href="#reaching-the-destination" title="Permalink to this heading"></a></h3>
<p>In networks with changing topology and trustless connectivity, nodes need a way to establish <p>In networks with changing topology and trustless connectivity, nodes need a way to establish
<em>verified connectivity</em> with each other. Since the network is assumed to be trustless, Reticulum <em>verified connectivity</em> with each other. Since the network is assumed to be trustless, Reticulum
must provide a way to guarantee that the peer you are communicating with is actually who you must provide a way to guarantee that the peer you are communicating with is actually who you
@ -551,12 +554,12 @@ suitable to the application. The procedure also inserts the <em>link id</em> , a
calculated from the link request packet, into the memory of forwarding nodes, calculated from the link request packet, into the memory of forwarding nodes,
which means that the communicating nodes can thereafter reach each other simply which means that the communicating nodes can thereafter reach each other simply
by referring to this <em>link id</em>.</p> by referring to this <em>link id</em>.</p>
<p>The combined bandwidth cost of setting up a link is 3 packets totalling 265 bytes (more info in the <p>The combined bandwidth cost of setting up a link is 3 packets totalling 297 bytes (more info in the
<a class="reference internal" href="#understanding-packetformat"><span class="std std-ref">Binary Packet Format</span></a> section). The amount of bandwidth used on keeping <a class="reference internal" href="#understanding-packetformat"><span class="std std-ref">Binary Packet Format</span></a> section). The amount of bandwidth used on keeping
a link open is practically negligible, at 0.45 bits per second. Even on a slow 1200 bits per second packet a link open is practically negligible, at 0.45 bits per second. Even on a slow 1200 bits per second packet
radio channel, 100 concurrent links will still leave 96% channel capacity for actual data.</p> radio channel, 100 concurrent links will still leave 96% channel capacity for actual data.</p>
<div class="section" id="link-establishment-in-detail"> <section id="link-establishment-in-detail">
<h4>Link Establishment in Detail<a class="headerlink" href="#link-establishment-in-detail" title="Permalink to this headline"></a></h4> <h4>Link Establishment in Detail<a class="headerlink" href="#link-establishment-in-detail" title="Permalink to this heading"></a></h4>
<p>After exploring the basics of the announce mechanism, finding a path through the network, and an overview <p>After exploring the basics of the announce mechanism, finding a path through the network, and an overview
of the link establishment procedure, this section will go into greater detail about the Reticulum link of the link establishment procedure, this section will go into greater detail about the Reticulum link
establishment process.</p> establishment process.</p>
@ -626,10 +629,10 @@ that is used to encrypt the channel. Information can now be exchanged reliably a
reveal any identifying information about itself. The link initiator remains completely anonymous.</p> reveal any identifying information about itself. The link initiator remains completely anonymous.</p>
<p>When using <em>links</em>, Reticulum will automatically verify all data sent over the link, and can also <p>When using <em>links</em>, Reticulum will automatically verify all data sent over the link, and can also
automate retransmissions if <em>Resources</em> are used.</p> automate retransmissions if <em>Resources</em> are used.</p>
</div> </section>
</div> </section>
<div class="section" id="resources"> <section id="resources">
<span id="understanding-resources"></span><h3>Resources<a class="headerlink" href="#resources" title="Permalink to this headline"></a></h3> <span id="understanding-resources"></span><h3>Resources<a class="headerlink" href="#resources" title="Permalink to this heading"></a></h3>
<p>For exchanging small amounts of data over a Reticulum network, the <a class="reference internal" href="reference.html#api-packet"><span class="std std-ref">Packet</span></a> interface <p>For exchanging small amounts of data over a Reticulum network, the <a class="reference internal" href="reference.html#api-packet"><span class="std std-ref">Packet</span></a> interface
is sufficient, but for exchanging data that would require many packets, an efficient way to coordinate is sufficient, but for exchanging data that would require many packets, an efficient way to coordinate
the transfer is needed.</p> the transfer is needed.</p>
@ -640,10 +643,10 @@ the transfer, integrity verification and reassembling the data on the other end.
<p><a class="reference internal" href="reference.html#api-resource"><span class="std std-ref">Resources</span></a> are programmatically very simple to use, and only requires a few lines <p><a class="reference internal" href="reference.html#api-resource"><span class="std std-ref">Resources</span></a> are programmatically very simple to use, and only requires a few lines
of codes to reliably transfer any amount of data. They can be used to transfer data stored in memory, of codes to reliably transfer any amount of data. They can be used to transfer data stored in memory,
or stream data directly from files.</p> or stream data directly from files.</p>
</div> </section>
</div> </section>
<div class="section" id="reference-setup"> <section id="reference-setup">
<span id="understanding-referencesystem"></span><h2>Reference Setup<a class="headerlink" href="#reference-setup" title="Permalink to this headline"></a></h2> <span id="understanding-referencesystem"></span><h2>Reference Setup<a class="headerlink" href="#reference-setup" title="Permalink to this heading"></a></h2>
<p>This section will detail a recommended <em>Reference Setup</em> for Reticulum. It is important to <p>This section will detail a recommended <em>Reference Setup</em> for Reticulum. It is important to
note that Reticulum is designed to be usable on more or less any computing device, and over more note that Reticulum is designed to be usable on more or less any computing device, and over more
or less any medium that allows you to send and receive data, which satisfies some very low or less any medium that allows you to send and receive data, which satisfies some very low
@ -709,20 +712,20 @@ get or make such a device is available on the <a class="reference external" href
even if you have none of the hardware already, and need to purchase everything.</p> even if you have none of the hardware already, and need to purchase everything.</p>
<p>This reference setup is of course just a recommendation for getting started easily, and you should <p>This reference setup is of course just a recommendation for getting started easily, and you should
tailor it to your own specific needs, or whatever hardware you have available.</p> tailor it to your own specific needs, or whatever hardware you have available.</p>
</div> </section>
<div class="section" id="protocol-specifics"> <section id="protocol-specifics">
<span id="understanding-protocolspecifics"></span><h2>Protocol Specifics<a class="headerlink" href="#protocol-specifics" title="Permalink to this headline"></a></h2> <span id="understanding-protocolspecifics"></span><h2>Protocol Specifics<a class="headerlink" href="#protocol-specifics" title="Permalink to this heading"></a></h2>
<p>This chapter will detail protocol specific information that is essential to the implementation of <p>This chapter will detail protocol specific information that is essential to the implementation of
Reticulum, but non critical in understanding how the protocol works on a general level. It should be Reticulum, but non critical in understanding how the protocol works on a general level. It should be
treated more as a reference than as essential reading.</p> treated more as a reference than as essential reading.</p>
<div class="section" id="packet-prioritisation"> <section id="packet-prioritisation">
<h3>Packet Prioritisation<a class="headerlink" href="#packet-prioritisation" title="Permalink to this headline"></a></h3> <h3>Packet Prioritisation<a class="headerlink" href="#packet-prioritisation" title="Permalink to this heading"></a></h3>
<p>Currently, Reticulum is completely priority-agnostic regarding general traffic. All traffic is handled <p>Currently, Reticulum is completely priority-agnostic regarding general traffic. All traffic is handled
on a first-come, first-serve basis. Announce re-transmission are handled according to the re-transmission on a first-come, first-serve basis. Announce re-transmission are handled according to the re-transmission
times and priorities described earlier in this chapter.</p> times and priorities described earlier in this chapter.</p>
</div> </section>
<div class="section" id="interface-access-codes"> <section id="interface-access-codes">
<h3>Interface Access Codes<a class="headerlink" href="#interface-access-codes" title="Permalink to this headline"></a></h3> <h3>Interface Access Codes<a class="headerlink" href="#interface-access-codes" title="Permalink to this heading"></a></h3>
<p>Reticulum can create named virtual networks, and networks that are only accessible by knowing a preshared <p>Reticulum can create named virtual networks, and networks that are only accessible by knowing a preshared
passphrase. The configuration of this is detailed in the <a class="reference internal" href="interfaces.html#interfaces-options"><span class="std std-ref">Common Interface Options</span></a> passphrase. The configuration of this is detailed in the <a class="reference internal" href="interfaces.html#interfaces-options"><span class="std std-ref">Common Interface Options</span></a>
section. To implement these feature, Reticulum uses the concept of Interface Access Codes, that are calculated section. To implement these feature, Reticulum uses the concept of Interface Access Codes, that are calculated
@ -735,9 +738,9 @@ Configured IFAC length can be inspected for all interfaces with the <code class=
<p>Upon receipt, the interface will check that the signature matches the expected value, and drop the packet if it <p>Upon receipt, the interface will check that the signature matches the expected value, and drop the packet if it
does not. This ensures that only packets sent with the correct naming and/or passphrase parameters are allowed to does not. This ensures that only packets sent with the correct naming and/or passphrase parameters are allowed to
pass onto the network.</p> pass onto the network.</p>
</div> </section>
<div class="section" id="wire-format"> <section id="wire-format">
<span id="understanding-packetformat"></span><h3>Wire Format<a class="headerlink" href="#wire-format" title="Permalink to this headline"></a></h3> <span id="understanding-packetformat"></span><h3>Wire Format<a class="headerlink" href="#wire-format" title="Permalink to this heading"></a></h3>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>== Reticulum Wire Format ====== <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>== Reticulum Wire Format ======
A Reticulum packet is composed of the following fields: A Reticulum packet is composed of the following fields:
@ -857,23 +860,23 @@ but excluding any interface access codes.
- Path Request : 51 bytes - Path Request : 51 bytes
- Announce : 157 bytes - Announce : 157 bytes
- Link Request : 83 bytes - Link Request : 83 bytes
- Link Proof : 83 bytes - Link Proof : 115 bytes
- Link RTT packet : 99 bytes - Link RTT packet : 99 bytes
- Link keepalive : 20 bytes - Link keepalive : 20 bytes
</pre></div> </pre></div>
</div> </div>
</div> </section>
<div class="section" id="announce-propagation-rules"> <section id="announce-propagation-rules">
<span id="understanding-announcepropagation"></span><h3>Announce Propagation Rules<a class="headerlink" href="#announce-propagation-rules" title="Permalink to this headline"></a></h3> <span id="understanding-announcepropagation"></span><h3>Announce Propagation Rules<a class="headerlink" href="#announce-propagation-rules" title="Permalink to this heading"></a></h3>
<p>The following table illustrates the rules for automatically propagating announces <p>The following table illustrates the rules for automatically propagating announces
from one interface type to another, for all possible combinations. For the purpose from one interface type to another, for all possible combinations. For the purpose
of announce propagation, the <em>Full</em> and <em>Gateway</em> modes are identical.</p> of announce propagation, the <em>Full</em> and <em>Gateway</em> modes are identical.</p>
<img alt="_images/if_mode_graph_b.png" src="_images/if_mode_graph_b.png" /> <img alt="_images/if_mode_graph_b.png" src="_images/if_mode_graph_b.png" />
<p>See the <a class="reference internal" href="interfaces.html#interfaces-modes"><span class="std std-ref">Interface Modes</span></a> section for a conceptual overview <p>See the <a class="reference internal" href="interfaces.html#interfaces-modes"><span class="std std-ref">Interface Modes</span></a> section for a conceptual overview
of the different interface modes, and how they are configured.</p> of the different interface modes, and how they are configured.</p>
</div> </section>
<div class="section" id="cryptographic-primitives"> <section id="cryptographic-primitives">
<span id="understanding-primitives"></span><h3>Cryptographic Primitives<a class="headerlink" href="#cryptographic-primitives" title="Permalink to this headline"></a></h3> <span id="understanding-primitives"></span><h3>Cryptographic Primitives<a class="headerlink" href="#cryptographic-primitives" title="Permalink to this heading"></a></h3>
<p>Reticulum has been designed to use a simple suite of efficient, strong and modern <p>Reticulum has been designed to use a simple suite of efficient, strong and modern
cryptographic primitives, with widely available implementations that can be used cryptographic primitives, with widely available implementations that can be used
both on general-purpose CPUs and on microcontrollers. The necessary primitives are:</p> both on general-purpose CPUs and on microcontrollers. The necessary primitives are:</p>
@ -911,9 +914,9 @@ testing and review as those from OpenSSL.</p>
<p>If you want to use the internal pure-python primitives, it is <strong>highly advisable</strong> that you <p>If you want to use the internal pure-python primitives, it is <strong>highly advisable</strong> that you
have a good understanding of the risks that this pose, and make an informed decision on whether have a good understanding of the risks that this pose, and make an informed decision on whether
those risks are acceptable to you.</p> those risks are acceptable to you.</p>
</div> </section>
</div> </section>
</div> </section>
<div class="clearer"></div> <div class="clearer"></div>
@ -922,8 +925,9 @@ those risks are acceptable to you.</p>
</div> </div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation"> <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper"> <div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table of Contents</a></h3> <div>
<ul> <h3><a href="index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Understanding Reticulum</a><ul> <li><a class="reference internal" href="#">Understanding Reticulum</a><ul>
<li><a class="reference internal" href="#motivation">Motivation</a></li> <li><a class="reference internal" href="#motivation">Motivation</a></li>
<li><a class="reference internal" href="#goals">Goals</a></li> <li><a class="reference internal" href="#goals">Goals</a></li>
@ -960,12 +964,17 @@ those risks are acceptable to you.</p>
</li> </li>
</ul> </ul>
<h4>Previous topic</h4> </div>
<p class="topless"><a href="using.html" <div>
title="previous chapter">Using Reticulum on Your System</a></p> <h4>Previous topic</h4>
<h4>Next topic</h4> <p class="topless"><a href="using.html"
<p class="topless"><a href="hardware.html" title="previous chapter">Using Reticulum on Your System</a></p>
title="next chapter">Communications Hardware</a></p> </div>
<div>
<h4>Next topic</h4>
<p class="topless"><a href="hardware.html"
title="next chapter">Communications Hardware</a></p>
</div>
<div role="note" aria-label="source link"> <div role="note" aria-label="source link">
<h3>This Page</h3> <h3>This Page</h3>
<ul class="this-page-menu"> <ul class="this-page-menu">
@ -977,12 +986,12 @@ those risks are acceptable to you.</p>
<h3 id="searchlabel">Quick search</h3> <h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper"> <div class="searchformwrapper">
<form class="search" action="search.html" method="get"> <form class="search" action="search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" /> <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" /> <input type="submit" value="Go" />
</form> </form>
</div> </div>
</div> </div>
<script>$('#searchbox').show(0);</script> <script>document.getElementById('searchbox').style.display = "block"</script>
</div> </div>
</div> </div>
<div class="clearer"></div> <div class="clearer"></div>
@ -1005,7 +1014,7 @@ those risks are acceptable to you.</p>
</div> </div>
<div class="footer" role="contentinfo"> <div class="footer" role="contentinfo">
&#169; Copyright 2022, Mark Qvist. &#169; Copyright 2022, Mark Qvist.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.1. Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 5.2.2.
</div> </div>
</body> </body>
</html> </html>

View File

@ -1,10 +1,11 @@
<!DOCTYPE html> <!DOCTYPE html>
<html> <html lang="en">
<head> <head>
<meta charset="utf-8" /> <meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />
<title>Using Reticulum on Your System &#8212; Reticulum Network Stack 0.3.12 beta documentation</title> <title>Using Reticulum on Your System &#8212; Reticulum Network Stack 0.3.12 beta documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css" /> <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="_static/classic.css" /> <link rel="stylesheet" type="text/css" href="_static/classic.css" />
@ -12,7 +13,9 @@
<script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
<script src="_static/jquery.js"></script> <script src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script> <script src="_static/underscore.js"></script>
<script src="_static/_sphinx_javascript_frameworks_compat.js"></script>
<script src="_static/doctools.js"></script> <script src="_static/doctools.js"></script>
<script src="_static/sphinx_highlight.js"></script>
<link rel="index" title="Index" href="genindex.html" /> <link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" /> <link rel="search" title="Search" href="search.html" />
@ -41,8 +44,8 @@
<div class="bodywrapper"> <div class="bodywrapper">
<div class="body" role="main"> <div class="body" role="main">
<div class="section" id="using-reticulum-on-your-system"> <section id="using-reticulum-on-your-system">
<span id="using-main"></span><h1>Using Reticulum on Your System<a class="headerlink" href="#using-reticulum-on-your-system" title="Permalink to this headline"></a></h1> <span id="using-main"></span><h1>Using Reticulum on Your System<a class="headerlink" href="#using-reticulum-on-your-system" title="Permalink to this heading"></a></h1>
<p>Reticulum is not installed as a driver or kernel module, as one might expect <p>Reticulum is not installed as a driver or kernel module, as one might expect
of a networking stack. Instead, Reticulum is distributed as a Python module. of a networking stack. Instead, Reticulum is distributed as a Python module.
This means that no special privileges are required to install or use it. It This means that no special privileges are required to install or use it. It
@ -56,8 +59,8 @@ program starts up and also wants access to the same Reticulum network, the
instance is simply shared. This works for any number of programs running instance is simply shared. This works for any number of programs running
concurrently, and is very easy to use, but depending on your use case, there concurrently, and is very easy to use, but depending on your use case, there
are other options.</p> are other options.</p>
<div class="section" id="configuration-data"> <section id="configuration-data">
<h2>Configuration &amp; Data<a class="headerlink" href="#configuration-data" title="Permalink to this headline"></a></h2> <h2>Configuration &amp; Data<a class="headerlink" href="#configuration-data" title="Permalink to this heading"></a></h2>
<p>A Reticulum stores all information that it needs to function in a single file- <p>A Reticulum stores all information that it needs to function in a single file-
system directory. By default, this directory is <code class="docutils literal notranslate"><span class="pre">~/.config/reticulum</span></code>, but you can system directory. By default, this directory is <code class="docutils literal notranslate"><span class="pre">~/.config/reticulum</span></code>, but you can
use any directory you wish. You can also run multiple separate Reticulum use any directory you wish. You can also run multiple separate Reticulum
@ -166,9 +169,9 @@ order to communicate with other systems. It is a good idea to read the comments
and explanations in the above default config. It will teach you the basic and explanations in the above default config. It will teach you the basic
concepts you need to understand to configure your network. Once you have done that, concepts you need to understand to configure your network. Once you have done that,
take a look at the <a class="reference internal" href="interfaces.html#interfaces-main"><span class="std std-ref">Interfaces</span></a> chapter of this manual.</p> take a look at the <a class="reference internal" href="interfaces.html#interfaces-main"><span class="std std-ref">Interfaces</span></a> chapter of this manual.</p>
</div> </section>
<div class="section" id="included-utility-programs"> <section id="included-utility-programs">
<h2>Included Utility Programs<a class="headerlink" href="#included-utility-programs" title="Permalink to this headline"></a></h2> <h2>Included Utility Programs<a class="headerlink" href="#included-utility-programs" title="Permalink to this heading"></a></h2>
<p>Reticulum includes a range of useful utilities, both for managing your Reticulum <p>Reticulum includes a range of useful utilities, both for managing your Reticulum
networks, and for carrying out common tasks over Reticulum networks, such as networks, and for carrying out common tasks over Reticulum networks, such as
transferring files to remote systems, and executing commands and programs remotely.</p> transferring files to remote systems, and executing commands and programs remotely.</p>
@ -176,8 +179,8 @@ transferring files to remote systems, and executing commands and programs remote
Reticulum to stay available all the time, for example if you are hosting Reticulum to stay available all the time, for example if you are hosting
a transport node, you might want to run Reticulum as a separate service that a transport node, you might want to run Reticulum as a separate service that
other programs, applications and services can utilise.</p> other programs, applications and services can utilise.</p>
<div class="section" id="the-rnsd-utility"> <section id="the-rnsd-utility">
<h3>The rnsd Utility<a class="headerlink" href="#the-rnsd-utility" title="Permalink to this headline"></a></h3> <h3>The rnsd Utility<a class="headerlink" href="#the-rnsd-utility" title="Permalink to this heading"></a></h3>
<p>It is very easy to run Reticulum as a service. Simply run the included <code class="docutils literal notranslate"><span class="pre">rnsd</span></code> command. <p>It is very easy to run Reticulum as a service. Simply run the included <code class="docutils literal notranslate"><span class="pre">rnsd</span></code> command.
When <code class="docutils literal notranslate"><span class="pre">rnsd</span></code> is running, it will keep all configured interfaces open, handle transport if When <code class="docutils literal notranslate"><span class="pre">rnsd</span></code> is running, it will keep all configured interfaces open, handle transport if
it is enabled, and allow any other programs to immediately utilise the it is enabled, and allow any other programs to immediately utilise the
@ -204,9 +207,9 @@ optional arguments:
</pre></div> </pre></div>
</div> </div>
<p>You can easily add <code class="docutils literal notranslate"><span class="pre">rnsd</span></code> as an always-on service by <a class="reference internal" href="#using-systemd"><span class="std std-ref">configuring a service</span></a>.</p> <p>You can easily add <code class="docutils literal notranslate"><span class="pre">rnsd</span></code> as an always-on service by <a class="reference internal" href="#using-systemd"><span class="std std-ref">configuring a service</span></a>.</p>
</div> </section>
<div class="section" id="the-rnstatus-utility"> <section id="the-rnstatus-utility">
<h3>The rnstatus Utility<a class="headerlink" href="#the-rnstatus-utility" title="Permalink to this headline"></a></h3> <h3>The rnstatus Utility<a class="headerlink" href="#the-rnstatus-utility" title="Permalink to this heading"></a></h3>
<p>Using the <code class="docutils literal notranslate"><span class="pre">rnstatus</span></code> utility, you can view the status of configured Reticulum <p>Using the <code class="docutils literal notranslate"><span class="pre">rnstatus</span></code> utility, you can view the status of configured Reticulum
interfaces, similar to the <code class="docutils literal notranslate"><span class="pre">ifconfig</span></code> program.</p> interfaces, similar to the <code class="docutils literal notranslate"><span class="pre">ifconfig</span></code> program.</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span># Run rnstatus <div class="highlight-text notranslate"><div class="highlight"><pre><span></span># Run rnstatus
@ -258,9 +261,9 @@ optional arguments:
-v, --verbose -v, --verbose
</pre></div> </pre></div>
</div> </div>
</div> </section>
<div class="section" id="the-rnpath-utility"> <section id="the-rnpath-utility">
<h3>The rnpath Utility<a class="headerlink" href="#the-rnpath-utility" title="Permalink to this headline"></a></h3> <h3>The rnpath Utility<a class="headerlink" href="#the-rnpath-utility" title="Permalink to this heading"></a></h3>
<p>With the <code class="docutils literal notranslate"><span class="pre">rnpath</span></code> utility, you can look up and view paths for <p>With the <code class="docutils literal notranslate"><span class="pre">rnpath</span></code> utility, you can look up and view paths for
destinations on the Reticulum network.</p> destinations on the Reticulum network.</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span># Run rnpath <div class="highlight-text notranslate"><div class="highlight"><pre><span></span># Run rnpath
@ -289,9 +292,9 @@ optional arguments:
-v, --verbose -v, --verbose
</pre></div> </pre></div>
</div> </div>
</div> </section>
<div class="section" id="the-rnprobe-utility"> <section id="the-rnprobe-utility">
<h3>The rnprobe Utility<a class="headerlink" href="#the-rnprobe-utility" title="Permalink to this headline"></a></h3> <h3>The rnprobe Utility<a class="headerlink" href="#the-rnprobe-utility" title="Permalink to this heading"></a></h3>
<p>The <code class="docutils literal notranslate"><span class="pre">rnprobe</span></code> utility lets you probe a destination for connectivity, similar <p>The <code class="docutils literal notranslate"><span class="pre">rnprobe</span></code> utility lets you probe a destination for connectivity, similar
to the <code class="docutils literal notranslate"><span class="pre">ping</span></code> program. Please note that probes will only be answered if the to the <code class="docutils literal notranslate"><span class="pre">ping</span></code> program. Please note that probes will only be answered if the
specified destination is configured to send proofs for received packets. Many specified destination is configured to send proofs for received packets. Many
@ -320,9 +323,9 @@ optional arguments:
-v, --verbose -v, --verbose
</pre></div> </pre></div>
</div> </div>
</div> </section>
<div class="section" id="the-rncp-utility"> <section id="the-rncp-utility">
<h3>The rncp Utility<a class="headerlink" href="#the-rncp-utility" title="Permalink to this headline"></a></h3> <h3>The rncp Utility<a class="headerlink" href="#the-rncp-utility" title="Permalink to this heading"></a></h3>
<p>The <code class="docutils literal notranslate"><span class="pre">rncp</span></code> utility is a simple file transfer tool. Using it, you can transfer <p>The <code class="docutils literal notranslate"><span class="pre">rncp</span></code> utility is a simple file transfer tool. Using it, you can transfer
files through Reticulum.</p> files through Reticulum.</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span># Run rncp on the receiving system, specifying which identities <div class="highlight-text notranslate"><div class="highlight"><pre><span></span># Run rncp on the receiving system, specifying which identities
@ -357,9 +360,9 @@ optional arguments:
-v, --verbose -v, --verbose
</pre></div> </pre></div>
</div> </div>
</div> </section>
<div class="section" id="the-rnx-utility"> <section id="the-rnx-utility">
<h3>The rnx Utility<a class="headerlink" href="#the-rnx-utility" title="Permalink to this headline"></a></h3> <h3>The rnx Utility<a class="headerlink" href="#the-rnx-utility" title="Permalink to this heading"></a></h3>
<p>The <code class="docutils literal notranslate"><span class="pre">rnx</span></code> utility is a basic remote command execution program. It allows you to <p>The <code class="docutils literal notranslate"><span class="pre">rnx</span></code> utility is a basic remote command execution program. It allows you to
execute commands on remote systems over Reticulum, and to view returned command execute commands on remote systems over Reticulum, and to view returned command
output.</p> output.</p>
@ -413,15 +416,15 @@ optional arguments:
--version show program&#39;s version number and exit --version show program&#39;s version number and exit
</pre></div> </pre></div>
</div> </div>
</div> </section>
</div> </section>
<div class="section" id="improving-system-configuration"> <section id="improving-system-configuration">
<h2>Improving System Configuration<a class="headerlink" href="#improving-system-configuration" title="Permalink to this headline"></a></h2> <h2>Improving System Configuration<a class="headerlink" href="#improving-system-configuration" title="Permalink to this heading"></a></h2>
<p>If you are setting up a system for permanent use with Reticulum, there is a <p>If you are setting up a system for permanent use with Reticulum, there is a
few system configuration changes that can make this easier to administrate. few system configuration changes that can make this easier to administrate.
These changes will be detailed here.</p> These changes will be detailed here.</p>
<div class="section" id="fixed-serial-port-names"> <section id="fixed-serial-port-names">
<h3>Fixed Serial Port Names<a class="headerlink" href="#fixed-serial-port-names" title="Permalink to this headline"></a></h3> <h3>Fixed Serial Port Names<a class="headerlink" href="#fixed-serial-port-names" title="Permalink to this heading"></a></h3>
<p>On a Reticulum instance with several serial port based interfaces, it can be <p>On a Reticulum instance with several serial port based interfaces, it can be
beneficial to use the fixed device names for the serial ports, instead beneficial to use the fixed device names for the serial ports, instead
of the dynamically allocated shorthands such as <code class="docutils literal notranslate"><span class="pre">/dev/ttyUSB0</span></code>. Under most of the dynamically allocated shorthands such as <code class="docutils literal notranslate"><span class="pre">/dev/ttyUSB0</span></code>. Under most
@ -447,9 +450,9 @@ Here is an example of a packet radio TNC configured as such:</p>
<p>Using this methodology avoids potential naming mix-ups where physical devices <p>Using this methodology avoids potential naming mix-ups where physical devices
might be plugged and unplugged in different orders, or when device name might be plugged and unplugged in different orders, or when device name
assignment varies from one boot to another.</p> assignment varies from one boot to another.</p>
</div> </section>
<div class="section" id="reticulum-as-a-system-service"> <section id="reticulum-as-a-system-service">
<span id="using-systemd"></span><h3>Reticulum as a System Service<a class="headerlink" href="#reticulum-as-a-system-service" title="Permalink to this headline"></a></h3> <span id="using-systemd"></span><h3>Reticulum as a System Service<a class="headerlink" href="#reticulum-as-a-system-service" title="Permalink to this heading"></a></h3>
<p>Instead of starting Reticulum manually, you can install <code class="docutils literal notranslate"><span class="pre">rnsd</span></code> as a system <p>Instead of starting Reticulum manually, you can install <code class="docutils literal notranslate"><span class="pre">rnsd</span></code> as a system
service and have it start automatically at boot.</p> service and have it start automatically at boot.</p>
<p>If you installed Reticulum with <code class="docutils literal notranslate"><span class="pre">pip</span></code>, the <code class="docutils literal notranslate"><span class="pre">rnsd</span></code> program will most likely <p>If you installed Reticulum with <code class="docutils literal notranslate"><span class="pre">pip</span></code>, the <code class="docutils literal notranslate"><span class="pre">rnsd</span></code> program will most likely
@ -491,9 +494,9 @@ WantedBy=multi-user.target
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>sudo systemctl enable rnsd <div class="highlight-text notranslate"><div class="highlight"><pre><span></span>sudo systemctl enable rnsd
</pre></div> </pre></div>
</div> </div>
</div> </section>
</div> </section>
</div> </section>
<div class="clearer"></div> <div class="clearer"></div>
@ -502,8 +505,9 @@ WantedBy=multi-user.target
</div> </div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation"> <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper"> <div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table of Contents</a></h3> <div>
<ul> <h3><a href="index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Using Reticulum on Your System</a><ul> <li><a class="reference internal" href="#">Using Reticulum on Your System</a><ul>
<li><a class="reference internal" href="#configuration-data">Configuration &amp; Data</a></li> <li><a class="reference internal" href="#configuration-data">Configuration &amp; Data</a></li>
<li><a class="reference internal" href="#included-utility-programs">Included Utility Programs</a><ul> <li><a class="reference internal" href="#included-utility-programs">Included Utility Programs</a><ul>
@ -524,12 +528,17 @@ WantedBy=multi-user.target
</li> </li>
</ul> </ul>
<h4>Previous topic</h4> </div>
<p class="topless"><a href="gettingstartedfast.html" <div>
title="previous chapter">Getting Started Fast</a></p> <h4>Previous topic</h4>
<h4>Next topic</h4> <p class="topless"><a href="gettingstartedfast.html"
<p class="topless"><a href="understanding.html" title="previous chapter">Getting Started Fast</a></p>
title="next chapter">Understanding Reticulum</a></p> </div>
<div>
<h4>Next topic</h4>
<p class="topless"><a href="understanding.html"
title="next chapter">Understanding Reticulum</a></p>
</div>
<div role="note" aria-label="source link"> <div role="note" aria-label="source link">
<h3>This Page</h3> <h3>This Page</h3>
<ul class="this-page-menu"> <ul class="this-page-menu">
@ -541,12 +550,12 @@ WantedBy=multi-user.target
<h3 id="searchlabel">Quick search</h3> <h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper"> <div class="searchformwrapper">
<form class="search" action="search.html" method="get"> <form class="search" action="search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" /> <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" /> <input type="submit" value="Go" />
</form> </form>
</div> </div>
</div> </div>
<script>$('#searchbox').show(0);</script> <script>document.getElementById('searchbox').style.display = "block"</script>
</div> </div>
</div> </div>
<div class="clearer"></div> <div class="clearer"></div>
@ -569,7 +578,7 @@ WantedBy=multi-user.target
</div> </div>
<div class="footer" role="contentinfo"> <div class="footer" role="contentinfo">
&#169; Copyright 2022, Mark Qvist. &#169; Copyright 2022, Mark Qvist.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.1. Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 5.2.2.
</div> </div>
</body> </body>
</html> </html>

View File

@ -1,10 +1,11 @@
<!DOCTYPE html> <!DOCTYPE html>
<html> <html lang="en">
<head> <head>
<meta charset="utf-8" /> <meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />
<title>What is Reticulum? &#8212; Reticulum Network Stack 0.3.12 beta documentation</title> <title>What is Reticulum? &#8212; Reticulum Network Stack 0.3.12 beta documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css" /> <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="_static/classic.css" /> <link rel="stylesheet" type="text/css" href="_static/classic.css" />
@ -12,7 +13,9 @@
<script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script> <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
<script src="_static/jquery.js"></script> <script src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script> <script src="_static/underscore.js"></script>
<script src="_static/_sphinx_javascript_frameworks_compat.js"></script>
<script src="_static/doctools.js"></script> <script src="_static/doctools.js"></script>
<script src="_static/sphinx_highlight.js"></script>
<link rel="index" title="Index" href="genindex.html" /> <link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" /> <link rel="search" title="Search" href="search.html" />
@ -41,8 +44,8 @@
<div class="bodywrapper"> <div class="bodywrapper">
<div class="body" role="main"> <div class="body" role="main">
<div class="section" id="what-is-reticulum"> <section id="what-is-reticulum">
<h1>What is Reticulum?<a class="headerlink" href="#what-is-reticulum" title="Permalink to this headline"></a></h1> <h1>What is Reticulum?<a class="headerlink" href="#what-is-reticulum" title="Permalink to this heading"></a></h1>
<p>Reticulum is a cryptography-based networking stack for building wide-area <p>Reticulum is a cryptography-based networking stack for building wide-area
networks with readily available hardware, that can continue to operate even networks with readily available hardware, that can continue to operate even
with extremely low bandwidth and very high latency.</p> with extremely low bandwidth and very high latency.</p>
@ -59,15 +62,15 @@ networks.</p>
<p>No kernel modules or drivers are required. Reticulum runs completely in <p>No kernel modules or drivers are required. Reticulum runs completely in
userland, and can run on practically any system that runs Python 3. Reticulum userland, and can run on practically any system that runs Python 3. Reticulum
runs well even on small single-board computers like the Pi Zero.</p> runs well even on small single-board computers like the Pi Zero.</p>
<div class="section" id="current-status"> <section id="current-status">
<h2>Current Status<a class="headerlink" href="#current-status" title="Permalink to this headline"></a></h2> <h2>Current Status<a class="headerlink" href="#current-status" title="Permalink to this heading"></a></h2>
<p>Reticulum should currently be considered beta software. All core protocol <p>Reticulum should currently be considered beta software. All core protocol
features are implemented and functioning, but additions will probably occur as features are implemented and functioning, but additions will probably occur as
real-world use is explored. There will be bugs. The API and wire-format can be real-world use is explored. There will be bugs. The API and wire-format can be
considered stable at the moment, but could change if absolutely warranted.</p> considered stable at the moment, but could change if absolutely warranted.</p>
</div> </section>
<div class="section" id="what-does-reticulum-offer"> <section id="what-does-reticulum-offer">
<h2>What does Reticulum Offer?<a class="headerlink" href="#what-does-reticulum-offer" title="Permalink to this headline"></a></h2> <h2>What does Reticulum Offer?<a class="headerlink" href="#what-does-reticulum-offer" title="Permalink to this heading"></a></h2>
<ul class="simple"> <ul class="simple">
<li><p>Coordination-less globally unique addressing and identification</p></li> <li><p>Coordination-less globally unique addressing and identification</p></li>
<li><p>Fully self-configuring multi-hop routing</p></li> <li><p>Fully self-configuring multi-hop routing</p></li>
@ -87,7 +90,7 @@ considered stable at the moment, but could change if absolutely warranted.</p>
<li><p>An intuitive and developer-friendly API</p></li> <li><p>An intuitive and developer-friendly API</p></li>
<li><p>Efficient link establishment</p> <li><p>Efficient link establishment</p>
<ul> <ul>
<li><p>Total bandwidth cost of setting up a link is only 3 packets, totalling 265 bytes</p></li> <li><p>Total bandwidth cost of setting up a link is only 3 packets, totalling 297 bytes</p></li>
<li><p>Low cost of keeping links open at only 0.44 bits per second</p></li> <li><p>Low cost of keeping links open at only 0.44 bits per second</p></li>
</ul> </ul>
</li> </li>
@ -101,9 +104,9 @@ considered stable at the moment, but could change if absolutely warranted.</p>
<li><p>Authentication and virtual network segmentation on all supported interface types</p></li> <li><p>Authentication and virtual network segmentation on all supported interface types</p></li>
<li><p>Flexible scalability allowing extremely low-bandwidth networks to co-exist and interoperate with large, high-bandwidth networks</p></li> <li><p>Flexible scalability allowing extremely low-bandwidth networks to co-exist and interoperate with large, high-bandwidth networks</p></li>
</ul> </ul>
</div> </section>
<div class="section" id="where-can-reticulum-be-used"> <section id="where-can-reticulum-be-used">
<h2>Where can Reticulum be Used?<a class="headerlink" href="#where-can-reticulum-be-used" title="Permalink to this headline"></a></h2> <h2>Where can Reticulum be Used?<a class="headerlink" href="#where-can-reticulum-be-used" title="Permalink to this heading"></a></h2>
<p>Over practically any medium that can support at least a half-duplex channel <p>Over practically any medium that can support at least a half-duplex channel
with 500 bits per second throughput, and an MTU of 500 bytes. Data radios, with 500 bits per second throughput, and an MTU of 500 bytes. Data radios,
modems, LoRa radios, serial lines, AX.25 TNCs, amateur radio digital modes, modems, LoRa radios, serial lines, AX.25 TNCs, amateur radio digital modes,
@ -123,9 +126,9 @@ LoRa radio, a packet radio TNC and a WiFi network. Once the interfaces are
added, Reticulum will take care of the rest, and any device on the WiFi added, Reticulum will take care of the rest, and any device on the WiFi
network can communicate with nodes on the LoRa and packet radio sides of the network can communicate with nodes on the LoRa and packet radio sides of the
network, and vice versa.</p> network, and vice versa.</p>
</div> </section>
<div class="section" id="interface-types-and-devices"> <section id="interface-types-and-devices">
<h2>Interface Types and Devices<a class="headerlink" href="#interface-types-and-devices" title="Permalink to this headline"></a></h2> <h2>Interface Types and Devices<a class="headerlink" href="#interface-types-and-devices" title="Permalink to this heading"></a></h2>
<p>Reticulum implements a range of generalised interface types that covers the communications hardware that Reticulum can run over. If your hardware is not supported, its relatively simple to implement an interface class. Currently, Reticulum can use the following devices and communication mediums:</p> <p>Reticulum implements a range of generalised interface types that covers the communications hardware that Reticulum can run over. If your hardware is not supported, its relatively simple to implement an interface class. Currently, Reticulum can use the following devices and communication mediums:</p>
<ul class="simple"> <ul class="simple">
<li><p>Any Ethernet device</p> <li><p>Any Ethernet device</p>
@ -161,17 +164,17 @@ network, and vice versa.</p>
</li> </li>
</ul> </ul>
<p>For a full list and more details, see the <a class="reference internal" href="interfaces.html#interfaces-main"><span class="std std-ref">Supported Interfaces</span></a> chapter.</p> <p>For a full list and more details, see the <a class="reference internal" href="interfaces.html#interfaces-main"><span class="std std-ref">Supported Interfaces</span></a> chapter.</p>
</div> </section>
<div class="section" id="caveat-emptor"> <section id="caveat-emptor">
<h2>Caveat Emptor<a class="headerlink" href="#caveat-emptor" title="Permalink to this headline"></a></h2> <h2>Caveat Emptor<a class="headerlink" href="#caveat-emptor" title="Permalink to this heading"></a></h2>
<p>Reticulum is an experimental networking stack, and should be considered as <p>Reticulum is an experimental networking stack, and should be considered as
such. While it has been built with cryptography best-practices very foremost in such. While it has been built with cryptography best-practices very foremost in
mind, it has not been externally security audited, and there could very well be mind, it has not been externally security audited, and there could very well be
privacy-breaking bugs. To be considered secure, Reticulum needs a thorough privacy-breaking bugs. To be considered secure, Reticulum needs a thorough
security review by independent cryptographers and security researchers. If you security review by independent cryptographers and security researchers. If you
want to help out, or help sponsor an audit, please do get in touch.</p> want to help out, or help sponsor an audit, please do get in touch.</p>
</div> </section>
</div> </section>
<div class="clearer"></div> <div class="clearer"></div>
@ -180,8 +183,9 @@ want to help out, or help sponsor an audit, please do get in touch.</p>
</div> </div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation"> <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper"> <div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table of Contents</a></h3> <div>
<ul> <h3><a href="index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">What is Reticulum?</a><ul> <li><a class="reference internal" href="#">What is Reticulum?</a><ul>
<li><a class="reference internal" href="#current-status">Current Status</a></li> <li><a class="reference internal" href="#current-status">Current Status</a></li>
<li><a class="reference internal" href="#what-does-reticulum-offer">What does Reticulum Offer?</a></li> <li><a class="reference internal" href="#what-does-reticulum-offer">What does Reticulum Offer?</a></li>
@ -192,12 +196,17 @@ want to help out, or help sponsor an audit, please do get in touch.</p>
</li> </li>
</ul> </ul>
<h4>Previous topic</h4> </div>
<p class="topless"><a href="index.html" <div>
title="previous chapter">Reticulum Network Stack Manual</a></p> <h4>Previous topic</h4>
<h4>Next topic</h4> <p class="topless"><a href="index.html"
<p class="topless"><a href="gettingstartedfast.html" title="previous chapter">Reticulum Network Stack Manual</a></p>
title="next chapter">Getting Started Fast</a></p> </div>
<div>
<h4>Next topic</h4>
<p class="topless"><a href="gettingstartedfast.html"
title="next chapter">Getting Started Fast</a></p>
</div>
<div role="note" aria-label="source link"> <div role="note" aria-label="source link">
<h3>This Page</h3> <h3>This Page</h3>
<ul class="this-page-menu"> <ul class="this-page-menu">
@ -209,12 +218,12 @@ want to help out, or help sponsor an audit, please do get in touch.</p>
<h3 id="searchlabel">Quick search</h3> <h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper"> <div class="searchformwrapper">
<form class="search" action="search.html" method="get"> <form class="search" action="search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" /> <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" /> <input type="submit" value="Go" />
</form> </form>
</div> </div>
</div> </div>
<script>$('#searchbox').show(0);</script> <script>document.getElementById('searchbox').style.display = "block"</script>
</div> </div>
</div> </div>
<div class="clearer"></div> <div class="clearer"></div>
@ -237,7 +246,7 @@ want to help out, or help sponsor an audit, please do get in touch.</p>
</div> </div>
<div class="footer" role="contentinfo"> <div class="footer" role="contentinfo">
&#169; Copyright 2022, Mark Qvist. &#169; Copyright 2022, Mark Qvist.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 4.0.1. Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 5.2.2.
</div> </div>
</body> </body>
</html> </html>