Introduction - Definitions, technologies, components and overall architecture
The Ocean Builder's Pod Management app is a complex software project that involves several components communicating with each other and it is actually an ecosystem formed by many different technologies, programming languages, code repositories and network protocols and offering a range of user experience depending on what is the user relationship with Ocean Builders, where is the user connecting from and what device is used to do so.
This documentation is intended for readers with general tech knowledge but not necessarily deep knowledge in any of the technologies involved. It will not go down to the implementation level. For details about specific implementations please check the related repositories in our GitHub organization.
In this introduction document we will give a general overview of the different components involved, how they are being implemented, what is their role in the overall system and how do they communicate with each other. We will then expand on each of those components in other documents inside this book.
Home Assistant at the core of our app's software
Home Assistant (HA from now on) is the open source home automation software that we rely on as a base for several of the features needed in our apps. It is fundamental that before digging deep into our documentation you get a basic understanding of what HA does and how it does it. We will be referencing different functionalities, code repositories, technologies and APIs related to HA all along this documentation.
Home assistant resources:
- Website: https://www.home-assistant.io/
- Github: https://github.com/home-assistant
- Demo showing HA capabilities https://home-assistant.io/demo/
- Documentation: https://www.home-assistant.io/docs/
- Tutorials: https://www.home-assistant.io/getting-started/automation/
USER ROLES
Our apps will be used by two main user groups:
- Ocean Builders customers and, in general, pod users. Users that need to manage their experience in one or more pods.
- Ocean Builders staff: administrators, customer support members and other. These are users that work for Ocean Builders and need to have supervisor or monitoring capabilities for one or more pods.
A user can also follow in both groups: a person working for Ocean Builders who also owns one or more pods and uses the same account for both their work activities and also as customer.
Ocean Builders pod users
Pod users will interact with the Pod Management app to manage their experience in one or more pods. This is a broad group of users that can have different relationships with the pods:
- Pod owner
- Pod guest
- Pod tenant
Ocean Builders staff
- Administrators
- Customer support
Architecture overview and components
There are several ways in which we can group the components of our deployment to offer different levels of description. We will start here with the most simple and simplistic classification by grouping several components into big features and we will later on offer a more in detail breakdown of each component.
User point of view
From the user point of view we are working on two main user-facing apps and everything that the user does not interact with could be considered "the servers" and every data storage system could be just referred as "storage".
- The Pod Management app: it is a fully customized version of the HA app and is the tool for users to interact with the pods. Users are not limited to manage a single pod, they can add several pods to manage and depending on their relationship with the pod and other factors, such as permissions given to them by the pod's owner or if they are inside or outside the pod, they will be able to control different devices and functionalities on those pods.
- The Ocean Builders Admin Dashboard: it is a frontend intended to be used by Ocean Builders staff only. This app gives an overview of the status of all the pods and allows to do monitoring and different levels of management of those pods. The levels of control a user can have over a pod will depend of several factors, for instance: the user role, how much management the pod's owner allows Ocean Builders to do, status of the pod (if the pod is in need of a critical action it can open a condition that allow Ocean Builders staff to do management not possible under other status.
- The servers: on a user level the servers are all those systems that are in charge of processing data and giving back data when requested. Under this simplification we could refer to types of servers:
- Local servers: this will be one or more microcomputers installed in the pods. They are used for processing all the data collected by the sensors (and any other devices producing data), for processing requests sent to actuators and other devices, for managing storage and for interacting with the database.
Currently we are planning to use one or more Raspberry Pi as servers.
When the user interacts with the app from inside a pod with no internet connection, the app will be directly communicating with the local server/s.
- Cloud servers: when the user access from outside the pod or when the user is inside a pod but need to manage other pods, the apps requests are processed in servers outside the pod. These "servers" are actually a mixture of different technologies, not just actually a bunch of servers running. All these servers and technologies are deployed on AWS and some rely heavily on AWS tech and services.
- The storage is any local or cloud-based solution to store the user data, the devices/sensors data, the pods status and information, and other data. So far we are considering the following storage components:
- The main pod (local) storage
- Other local storage
- Cloud storage
Developer point of view
The development is being split in two main areas of work:
- Pod automation system: This area of development takes care of all the hardware-software integrations that are done inside the pod. From the selection of the optimal hardware (sensors, actuators, controllers) to adding all the Home Assistant integrations to make that hardware be controlled by the app and programming different automations
- Cloud software and front-ends: This area of development is centered in the user apps / front-ends we offer for the user to interact with the pods. We work on making sure the user can interact with the pod from both inside and outside the pod and how interactions change depending on the user location and internet connectivity of the pod.
Let's look at those two areas of work more closely now.
Pod automation system
The bulk of the work consists in configurations and integrations for Home Assistant so each of the devices can be monitored or controlled from the app.
Definitions
Actuator: is a physical device that by receiving a control signal (instructing what to do) and power, they perform a task, usually involving moving mechanical parts.