README
¶
Smart Core Building Operating System
For getting started with developing, see the dev guide
System Architecture
The system functionality is distributed among multiple components.
Building Controller
The Building Controller is responsible for management of the Smart Core installation. It is written in Go and installed in a virtual machine on a server. Over gRPC, it exposes both the Smart Core API (for device control and data collection) and private APIs for communicating with the frontend and other nodes.
It provides the following services:
- Hosting the building user interfaces
- Managing the enrollment of Area Controllers
- Certificate signing
- Smart Core CA
- Generating & distributing configuration data to other components
- Generating & distributing routing tables, which map device names to Smart Core nodes
- Tenant management
- Issuing tenant API keys
- Assigning tenants to areas
- Tenant data API
- Performing whole-building automations
- Alarm engine
Keycloak
Smart Core requires an OpenID Connect server to provide identity & access management functionality. We recommend Keycloak, an open source Identity and Access Management server. Keycloak can use an internal user database or back off to an external source such as Microsoft AD.
Keycloak hosts its own user interface (which is used as a login page), and issues OpenID Connect tokens which can be verified by the other components, in order to provide authentication.
It is hosted in a virtual machine on a server.
Database Server
The system uses the PostgreSQL RDBMS for persistent data storage. Only the App Server and Keycloak directly access the database - if any other system component requires persistent data storage, it must do so via an API exposed by the App Server.
It is hosted in a virtual machine on a server.
Gateway
The Gateway bridges the building internal network with the untrusted networks, such as a tenant network. It provides a policy enforcement point to apply extra security rules to tenant API access. It also acts as an OAuth2 server, separate from Keycloak, to issue access tokens to machines (not people).
It is hosted in a virtual machine on a server.
Area Controllers
The Area Controller is responsible for control of devices in its local area, such as a floor. Each one runs the same Area Controller service, but with different configuration. Configuration is manged centrally by the App Server.
The Area Controllers provide the following services:
- Hosting a commissioning & diagnostics user interface
- Local automations
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
bos
Command bos provides the canonical Smart Core BOS executable.
|
Command bos provides the canonical Smart Core BOS executable. |
|
pash
Command pash provides a CLI tool for generating password hashes.
|
Command pash provides a CLI tool for generating password hashes. |
|
tools/bacnet-comm-test
Command bacnet-comm-test performs a simple comm check against a BACnet device.
|
Command bacnet-comm-test performs a simple comm check against a BACnet device. |
|
tools/bacnet-multi-comm-test
Command bacnet-multi-comm-test checks the availability [bacnet] devices and objects read from [appconf] files.
|
Command bacnet-multi-comm-test checks the availability [bacnet] devices and objects read from [appconf] files. |
|
tools/bacnet-whois
Command bacnet-whois executes a BACnet WhoIs broadcast request and captures the replies in a CSV file.
|
Command bacnet-whois executes a BACnet WhoIs broadcast request and captures the replies in a CSV file. |
|
tools/client-airqualitysensor
Command client-meter provides a CLI tool for interacting with the [gen.MeterApiClient].
|
Command client-meter provides a CLI tool for interacting with the [gen.MeterApiClient]. |
|
tools/client-airtemperature
Command client-meter provides a CLI tool for interacting with the [gen.MeterApiClient].
|
Command client-meter provides a CLI tool for interacting with the [gen.MeterApiClient]. |
|
tools/client-button
Command client-button provides a CLI tool for interacting with a [gen.ButtonApiClient].
|
Command client-button provides a CLI tool for interacting with a [gen.ButtonApiClient]. |
|
tools/client-devicesmetadata
Command client-devicesmetadata provides a CLI tool for interacting with the [gen.DevicesApiClient].
|
Command client-devicesmetadata provides a CLI tool for interacting with the [gen.DevicesApiClient]. |
|
tools/client-emergency
Command client-emergency provides a CLI tool for interacting with the [traits.EmergencyApiClient].
|
Command client-emergency provides a CLI tool for interacting with the [traits.EmergencyApiClient]. |
|
tools/client-meter
Command client-meter provides a CLI tool for interacting with the [gen.MeterApiClient].
|
Command client-meter provides a CLI tool for interacting with the [gen.MeterApiClient]. |
|
tools/client-occupancy
Command client-occupancy provides a CLI tool for interacting with the [traits.OccupancySensorApiClient].
|
Command client-occupancy provides a CLI tool for interacting with the [traits.OccupancySensorApiClient]. |
|
tools/client-parent
Command client-parent provides a CLI tool for interacting with the [traits.ParentApiClient].
|
Command client-parent provides a CLI tool for interacting with the [traits.ParentApiClient]. |
|
tools/dbadd-alerts
App dbadd-alerts is a tool that creates alerts via the AlertAdminApi.
|
App dbadd-alerts is a tool that creates alerts via the AlertAdminApi. |
|
tools/dbadd-publications-sample
Command dbadd-publications-sample connects to a postgres database, creates tables, and seeds them with some sample test data.
|
Command dbadd-publications-sample connects to a postgres database, creates tables, and seeds them with some sample test data. |
|
tools/enrollment-tool
Command enrollment-tool provides a CLI tool for enrolling a node with a hub.
|
Command enrollment-tool provides a CLI tool for enrolling a node with a hub. |
|
tools/export-alerts
Command export-alerts reads alerts from [gen.AlertApiClient] and writes them to a CSV file.
|
Command export-alerts reads alerts from [gen.AlertApiClient] and writes them to a CSV file. |
|
tools/export-traits
Command export-traits reads various trait information and writes it to a CSV file.
|
Command export-traits reads various trait information and writes it to a CSV file. |
|
tools/list-occupancy-history
Command list-occupancy-history reads records from [gen.OccupancySensorHistoryClient] and writes them to a CSV file.
|
Command list-occupancy-history reads records from [gen.OccupancySensorHistoryClient] and writes them to a CSV file. |
|
tools/proxy-test
Command proxy-test is an experiment using grpc-proxy to see how applicable it would be for gateways.
|
Command proxy-test is an experiment using grpc-proxy to see how applicable it would be for gateways. |
|
tools/pull-enter-leave
Command pull-enter-leave provides a CLI tool that pulls from a [traits.EnterLeaveSensorApiClient].
|
Command pull-enter-leave provides a CLI tool that pulls from a [traits.EnterLeaveSensorApiClient]. |
|
tools/sample-tenant
Command sample-tenant provides an example tenant application, including auth.
|
Command sample-tenant provides an example tenant application, including auth. |
|
tools/tcp-conn-test
Command tcp-conn-test provides an interactive CLI terminal for testing TCP connections.
|
Command tcp-conn-test provides an interactive CLI terminal for testing TCP connections. |
|
tools/test-meteremail
Command test-meteremail tests the [meteremail] package, sending to a real email address.
|
Command test-meteremail tests the [meteremail] package, sending to a real email address. |
|
tools/test-occupancyemail
Command test-occupancyemail tests the [occupancyemail] package, sending to a real email address.
|
Command test-occupancyemail tests the [occupancyemail] package, sending to a real email address. |
|
tools/test-statusemail
Command test-statusemail tests the [statusemail] package, sending to a real email address.
|
Command test-statusemail tests the [statusemail] package, sending to a real email address. |
|
tools/xovis-push-data-sample
Command xovis-push-data-sample is an example of how to receive Xovis push data.
|
Command xovis-push-data-sample is an example of how to receive Xovis push data. |
|
internal
|
|
|
auth/keycloak
Package keycloak verifies tokens issued by the Keycloak identity server.
|
Package keycloak verifies tokens issued by the Keycloak identity server. |
|
auth/tenant
Package tenant implements issuing tenants Access Tokens based on the OAuth2 client credentials grant.
|
Package tenant implements issuing tenants Access Tokens based on the OAuth2 client credentials grant. |
|
iothub
Package iothub provides a client for Azure IoT Hub.
|
Package iothub provides a client for Azure IoT Hub. |
|
iothub/dps
Package dps implements provisioning a device using the Azure IoT Device Provisioning Service.
|
Package dps implements provisioning a device using the Azure IoT Device Provisioning Service. |
|
manage/devices
Package devices provides mechanisms for querying devices on a node.
|
Package devices provides mechanisms for querying devices on a node. |
|
pubcache
Package pubcache implements a cache of selected publications from a remote Smart Core publication server.
|
Package pubcache implements a cache of selected publications from a remote Smart Core publication server. |
|
pkg
|
|
|
app
Package app handles service lifecycle management, and other functionality necessary for the daemon-style server applications in this project.
|
Package app handles service lifecycle management, and other functionality necessary for the daemon-style server applications in this project. |
|
app/appconf
Package appconf provides runtime configuration.
|
Package appconf provides runtime configuration. |
|
app/files
Package files provides file utilities.
|
Package files provides file utilities. |
|
app/http
Package http provides http-specific configuration types and functionality.
|
Package http provides http-specific configuration types and functionality. |
|
app/sysconf
Package sysconf provides system level configuration.
|
Package sysconf provides system level configuration. |
|
auth
Package auth provides both authentication primitives and authorization policies.
|
Package auth provides both authentication primitives and authorization policies. |
|
auth/jwks
Package jwks provides both local and remote JWT Key Set access token verifiers.
|
Package jwks provides both local and remote JWT Key Set access token verifiers. |
|
auth/oidc
Package oidc provides access to remote OpenID Connect configuration.
|
Package oidc provides access to remote OpenID Connect configuration. |
|
auth/policy
Package policy provides a policy-based authorization system for gRPC services.
|
Package policy provides a policy-based authorization system for gRPC services. |
|
auth/token
Package token provides mechanisms for validating access tokens and extracting claims.
|
Package token provides mechanisms for validating access tokens and extracting claims. |
|
auto/azureiot
Package azureiot implements data upload to Azure IoT Hub.
|
Package azureiot implements data upload to Azure IoT Hub. |
|
auto/history
Package history provides an automation that pulls data from a trait and inserts them into store.
|
Package history provides an automation that pulls data from a trait and inserts them into store. |
|
auto/lights
Package lights provides automated control of lighting.
|
Package lights provides automated control of lighting. |
|
auto/meteremail
Package meteremail provides an automation that collects the instantaneous meter readings for a set of given devices.
|
Package meteremail provides an automation that collects the instantaneous meter readings for a set of given devices. |
|
auto/notificationsemail
Package notificationsemail has been made to tick a box and needs improvement.
|
Package notificationsemail has been made to tick a box and needs improvement. |
|
auto/occupancyemail
Package occupancyemail provides an automation that creates a digest email of occupancy statistics.
|
Package occupancyemail provides an automation that creates a digest email of occupancy statistics. |
|
auto/resetenterleave
Package resetenterleave provides an auto that resets enter/leave totals based on a cron-like schedule.
|
Package resetenterleave provides an auto that resets enter/leave totals based on a cron-like schedule. |
|
driver/airthings
Package airthings integrates AirThings devices into Smart Core.
|
Package airthings integrates AirThings devices into Smart Core. |
|
driver/airthings/api
Package api allows interaction with the AirThings API.
|
Package api allows interaction with the AirThings API. |
|
driver/airthings/local
Package local implements a local model of the AirThings api.
|
Package local implements a local model of the AirThings api. |
|
driver/airthings/sample
The sample application uses the AirThings API to pull sensor readings (latest samples) from a named location.
|
The sample application uses the AirThings API to pull sensor readings (latest samples) from a named location. |
|
driver/se/wiser-knx
Package wiser_knx contains a driver for Schneider Electric Wiser for KNX lighting controller.
|
Package wiser_knx contains a driver for Schneider Electric Wiser for KNX lighting controller. |
|
driver/xovis
Package xovis contains a driver for camera-based occupancy sensors produced by Xovis.
|
Package xovis contains a driver for camera-based occupancy sensors produced by Xovis. |
|
gentrait/historypb
Package historypb adds types useful for working with the generated FooHistory services.
|
Package historypb adds types useful for working with the generated FooHistory services. |
|
history
Package history provides a store for historical records.
|
Package history provides a store for historical records. |
|
history/boltstore
Package boltstore provides an implementation of history.Store with records stored in a bolthold database.
|
Package boltstore provides an implementation of history.Store with records stored in a bolthold database. |
|
history/memstore
Package memstore provides an implementation of history.Store with records stored in memory.
|
Package memstore provides an implementation of history.Store with records stored in memory. |
|
history/pgxstore
Package pgxstore provides an implementation of history.Store backed by a Postgres database.
|
Package pgxstore provides an implementation of history.Store backed by a Postgres database. |
|
manage/enrollment
Package enrollment facilitates the binding of an Area Controller to a Building Controller.
|
Package enrollment facilitates the binding of an Area Controller to a Building Controller. |
|
minibus
Package minibus implements a minimalist many-to-many event bus.
|
Package minibus implements a minimalist many-to-many event bus. |
|
system
Package system and sub packages add optional features to a controller.
|
Package system and sub packages add optional features to a controller. |
|
system/authn
Package authn provides token based authentication for gRPC requests.
|
Package authn provides token based authentication for gRPC requests. |
|
system/history
Package history provides an implementation of HistoryAdminApi backed by a history.Store.
|
Package history provides an implementation of HistoryAdminApi backed by a history.Store. |
|
system/hub
Package hub manages the enrollment process for a cohort of nodes.
|
Package hub manages the enrollment process for a cohort of nodes. |
|
task
Package task defines Task, a unit of work which can be retried if it fails.
|
Package task defines Task, a unit of work which can be retried if it fails. |
|
task/serviceapi
Package serviceapi implements gen.ServiceApi backed by a service.Map.
|
Package serviceapi implements gen.ServiceApi backed by a service.Map. |
|
util/jsontypes
Package jsontypes contains utility / wrapper types that are suitable for JSON marshalling / unmarshalling using the standard library json package.
|
Package jsontypes contains utility / wrapper types that are suitable for JSON marshalling / unmarshalling using the standard library json package. |
|
util/pull
Package pull provides a reliable way to subscribe to changes from a device.
|
Package pull provides a reliable way to subscribe to changes from a device. |
|
util/state
Package state deals with tracking, notification, and management of state and state changes.
|
Package state deals with tracking, notification, and management of state and state changes. |
|
zone
Package zone represents the concept of a physical space and what you can do with that space.
|
Package zone represents the concept of a physical space and what you can do with that space. |
|
zone/feature/lighting
Package lighting implements group lighting control for a zone.
|
Package lighting implements group lighting control for a zone. |
Click to show internal directories.
Click to hide internal directories.