1. About the Development

Intoduction

SmartHome my Castle is a decentralized SmartHome framework:
Decentralized, open-source, self-sufficient, modular, independent.

Check out the Backend documentation under:
shmc.sziller.eu/app/docs

Check out project repositories under:
github.com/sziller

1.1. Motivation

Sovereignty will have to be achieved on two different levels:

1.1.1. System level

We - at sziller.eu - want to build a modular smart-home system on fully open-source basis. Our goal is to enable full control over Your home: providing You with the necessary framework to develop a truly custom-made intelligent home, enabling self developed solutions, or rely on a community developed solutions. A Home in this context is regarded as one sovereign interconnected system, where - though modular in architecture - parts of the infrastructure can intaract with eachother, use each-others measurements, computational results. As we deal with brick-and-mortar buildings, at the edge of this project you’ll always find mostly physical systems, (peripherals) such as:

  • sensors

  • appliances

  • switches (relais)

  • enegry sources

1.1.2. Control level

We strive to achieve as much decentralization and sovereignty as possible. The User of this project - You - should never have to rely on 3rd parties.

Important

Sovereignty is hard to achieve. You obviously can anytime use 3rd party software if you choose to.
The point is: you do NOT HAVE TO!

1.2. Technology

The Project intends to be usable from step 0. Right at the moment You download the server, You should be good to go. Then - as you’re ready to invest more resources - build up a more complex system module-by-module according to your preferences. Thus, the entire SmrtHome my Castle Project is organized to be modular regarding both development and deployment

1.2.1. Functionality modules

HINT

find detailed list here: <<>> We concentrate on residential buildings/ apartments. This choice more-or-less determines the functionality we target. Here are some examles we are currently implementing:

  • Room climate manager

    • environmental measurements

    • controlling local heating, humidity, lights, other appiances

  • Observatory center at entrance

    • environmental measurements

    • optical measurement

    • image recognition

    • controlling lights, locking systems

  • Food production manager

  • Bitcoin wallet

    • possible monetization of your resources

  • Central heating management

    • reading measurements provided by multiple Nodes

  • Solar energy generation

1.2.2. Hardware modules

The project is built with RaspberryPi computing hardware (simply: Nodes) in mind. We also make use of RaspberryPi related peripherals such as SenseHat, Raspberry Cameras. When it comes to Node demand of your setup, you need to consider: Functions may occupy a Node by their own, or may share a Node with other modules. We basically create a mesh network of Nodes inside a building/ apartment. Nodes are placed in several different locations strategically in the building/ apartment.

Important

Thus, setting up a Live Project is not only an IT decision. You need to look at your floorplan, energy-bills, building-construction, kids, lifestyle. You might actually want to consult an Architect with a technlogical touch.

1.2.3. Software modules

Most of the Functions receive their own Python Package. So you can install them as you go along. We also encourage you to contribute in the development. Here is a grouping of Packages based on their interaction with physical systems:

  • server:
    Central Node at the core of your System enabling you to deal with remote communication, with handling shared Databases.

  • Node managing software:
    Basic functionality running on Nodes. Client taks, local DB or file handling. Even possible local server tasks.

  • measurement management:
    Some Nodes are responsible to measure and to provide measured data to the system.

  • peripheral management:
    Some Nodes control Relais, some manage LED displays

  • background Engines:
    In case of more complex Functionality specific Engines are running locally - on dedicated Nodes.

    Timing

    The system being a mesh network of uncontrolled size/ number of Nodes, is designed to be a sluggish one. In order to be robust, redundant, safe, we prioritize these features over swiftness. We will optimize local processes for fast action, speed however will not be a priority when it comes to communication between nodes.

The communication between Nodes may or may not happen over shared Databases, or direct socket connections.

2. Function modules

As of now, the following repositories are being developed. If you cannot access some, that means, these are not opened up for public development yet. Please be patient!

3. README: _raspi_smarthome_server

TLDR

This is the Software application of the SmartHome my Castle development.

Important

Keep in mind! As the development can be used in different scopes, you may not have to deal with most of the factors we list below.
E.g.:

  • Locally run Engine only Installations, will not need any connection settings.

  • If you do not allow remote access, you can completelly avoid dealing with world-facing security, port forwarding, etc.

  • If you only run the Development with one Hardware only, you wont have to deal with the Local Network.

When setting up your SmartHome using the Entire feature set of the SmartHome my Castle Development, proceed as listed below:

  1. Design your smart home setup, based on building architecture, building hardware conditions, set of physical systems you want to monitor or controll. Ideally, you should consult your Building Architect and Construction Engineer to incorporate relevant decisions right from the beginning of the building design process.

  2. Install computer hardware, sensors, robots where they are needed, where these can work optimally. They sould be practically accessible to you, but not necessarly to unauthorized, unwarranted or even incompetent people. Mind necessary power supply, network connection, WiFi coverge, Provider-router access, cooling/ ventillation, etc.
    Make sure the is network connection possible between system parts on hardware level/ router level.

  3. Establish IT connection between parts of the Development, and connection between development and the outside world. Mind your DHCP, set up logical IP settings, Port system. Check necessary Port forwarding, check Internet connectivity. Allow secure connection using HTTPS.
    Install OS' onto RaspberryPis. Install necessary hardware mounted and controlled by Nodes. Enable and prepare SSH connections. (needed for both local connection and GitHub repo access): Create secure keypairs, use password protected keys.

  4. Download, install and run necessary software (e.g.: Server with routers, Message Handlers, Engines) To to so, clone repos, setup git environments.

Important

This README section of the document only deals with Point D - the software part of the Development. It is necessary to handle the software in the context of the entire system, as highlighted here at shmc.sziller.eu.

Find a detailed description of SmartHome my Castle under: shmc.sziller.eu

3.1. repository

Find actual project repo under: github.com/sziller/_raspi_smarthome_server

3.2. whom and what for?

Version: v0.0.0
Modular open-source SmartHome application for self-sovereign

3.3. how do I get started?

You will need to rename and update the following files:

  • temp-config.py must be renamed to config.py!

  • temp-config_prv.py must be renamed to config_prv!

  • .temp-env must be renamed to .env

3.3.1. Summary of set up

tbd…​

3.3.2. Configuration

tbd…​

3.3.3. Dependencies

Not much, other than what’s listed above. Run it on a Linux system, mind requirements, and use the lib directory to install additional packages.

3.3.4. Database configuration

tbd…​

3.3.5. How to run tests

tbd…​

3.3.6. Deployment instructions

tbd…​

3.3.7. Entry Point

Use one of the following Pyhton3 scripts to run the Server:

  • APP_srv_cl - instantiating a wrapped-class to run the server

  • APP_srv_fn - a function based server start - more of a tutorial style code-branch

All config.py and .env contents are compatible with both Entry-Points.

Use our checklist in order to start up a given Node: Node start-up

3.4. how can you contribute?

  • Writing tests

  • Code review

  • Comments on architecture or development decisions

  • Possible refactoring ideas

3.5. contact

Owner and developer of this Project is Sziller

4. Node start-up

This is a quick, step-by-step description on how to activate a well-set-up Node.

4.1. turn on Node

Assuming each of the units are headless:

  • turn on Raspberry / restart if running or having issues

  • check IP address

  • check if local area network sees hardware and doublecheck IP

  • ping IP from one of the locally connected Nodes

4.2. access Node

  • establish connection to Node

4.2.1. ssh

If you want to access any of the Nodes using ssh, enter:

ssh <username>@<ip-address>

Then you enter the password realted to <username>.
In the SHMC development we stick to username = pi as this is the default Raspberry username.

Important

Passwords have been changed! For local ssh login you need a different password to the one stored with id_rsa!

4.2.2. remote desktop

…​to be extended…​

4.2.3. telnet

…​to be extended…​

4.3. start tmux

Once logged in,

  • create and activate tmux session:

    tmux new -d -s <serversession>
tmux attach -t <serversession>

4.4. start https

Inside the tmux session,

  • start nginx, to forward and certify https requests:

    sudo systemctl start nginx

4.5. start server

If you want to run the server in venv:

  • Switch to local virtual environment! Then…​

  • activate virtual environment

    source ./venv/bin/activate

  • Run the server, picking one of the EntryPoints…​

    • …​either from a terminal, allowing reload on changes:

      uvicorn serverClass_SHMC:server --reload
uvicorn serverFunction_SHMC:server --reload

    • …​or by running one of the Python wrapper scripts:

      pyhton3 APP_srv_cl.py
pyhton3 APP_srv_fn.py

as <app> is a sub-api mounted under <server> when starting <server>, <app> also starts. API included here is - as of now - mosty describint <app> - the sub-api. So to access the docs of <app> you need to add the '/app' prefix.
(or redefine in config.py under APP_PATH)

5. FastAPI

5.1. Install framework

This should be installed on the system itself, NOT only in virtual environment. However: If you use it from venv, and want to have it in the venv, you can install it into the venv!

pip install "fastapi[all]"

5.2. Swagger

Use Swagger simplified Frontend to demo, test and dev-use default Endpoints:
(substitute IP:PORT to match your .env settings, under SRV_IP and SRV_PORT)

http://127.0.0.1:8000/docs
http://127.0.0.1:8000/redoc

Currently, API of <app> is documanted under:

http://127.0.0.1:8000/api/docs
http://127.0.0.1:8000/api/redoc

5.3. Online

token example
{"access_token":"---","expires_in":300,"refresh_expires_in":1800,"refresh_token":"---","token_type":"Bearer",
"not-before-policy":0,"session_state":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","scope":"email profile"}

also, CORS needed to be added to the browser Back to Smart Home my Castle