Configuration

Modules

CORS Module

Config-Name: cors

Name	Description
trustedOrigins arraystringoptional	List of all trusted origins. Will have no effect if `disable` is set to true. Default: []
allowTools booleanoptional	Whenever to allow tools e.g. curl or postman. Tools that are no browser so to say. Default: true
disable booleanoptional	Whenever to allow requests from all origins.

IAM Module

Config-Name: iam

Name	Description
initialAdminAccount objectoptional	An object that contains all information required to create an initial admin. This object can be deleted once an initial admin has been created. Will not overwrite an existing account.
initialAdminAccount.group string	The group for the initial admin. Will be created if not present.
initialAdminAccount.role string	The role for the initial admin. Will be created if not present.
initialAdminAccount.user string	The name for the initial account that will be the admin.
initialAdminAccount.password string	The password for the initial admin account.
enableOAuthProvider booleanoptional	The backend comes with its own OAuth provider. In the event, that only external OAuth provider are used, you can disable the internal provider. Default: true
provider arrayoptional	External OAuth provider. Currently supported are `Okta` and `Viessmann` within the coldwave-backend-environment by default. Default: []
refreshTokenDurationMS integeroptional	The refresh token lifetime in milliseconds. Defaults to a day. Default: 86400000
twoFactorAuth objectoptional	This object contains settings regarding two-factor-authentication. Default: { "name": "Coldwave 2FA Login" }
twoFactorAuth.name stringoptional	The name of the application. This name will be shown in the users 2FA manager. Default: Coldwave 2FA Login
enforceSecureDevicePairing booleanoptional	Only allows secure pairings of devices with a token signature that will be checked by the backend. In other words, the user who wants to pair the device to their account must have local access to the device.

DEVICELINK Module

Config-Name: deviceLink

Name	Description
portStart integer	The beginning of the port range. Every client facing socket will be bound to a port greater or equal than the value set.
portEnd integer	The end of the port range. Every client facing socket will be bound to a port lesser or equal than the value set.
maxConcurrentConnections integer	The maximum amount of concurrent connections. Once this amount has been reached, no more sockets are opened until resources are available again.
defaultPort integeroptional	The port any package should be sent to on the device. This value is optional. However, if it is not set in the config, it is required in the endpoint that creates a device link.
defaultTimeout integeroptional	The default timeout in milliseconds after which a UDP socket is closed. If unset, and unspecified when creating a device link via the API, the socket does never timeout. In this case, the client needs to free up any remaining resources, which is highly advised against.
networkSeparation objectoptional	This object can be used to separate the private and the public part of the network. If set will bind the specific sockets to the specific interfaces.
networkSeparation.privateBindingAddress string	The address on which to bind the private facing socket to.
networkSeparation.publicBindingAddress string	The address on which to bind the public facing socket to.

LOGGER Module

Config-Name: logger

Name	Description
initialLogLevel stringoptionalenum	The available log level of the current logger implementation. Default: info Possible values: error, warn, info, verbose, debug, trace, protocol
namespaces arraystringoptional	The namespaces to activate. Topics not present in this list will be set to silent. If the key is omitted, all topics will be set to log messages.

UPDATES Module

Config-Name: updates

Name	Description
auth	The auth object that contains the means to authenticate this backend against the update server.
Alternative 1object
auth.type stringconstant	Constant value: API_KEY
auth.key string	The API key used to sign requests to the update server with.
Alternative 2object
auth.type stringconstant	Constant value: USER
auth.name string	The name of the user for the update server.
auth.password string	The password for the user for the update server.
url string	The URL the backend will communicate with the update server. This should be the full path, so as of right now it should end with `api/v1`.
hostname stringoptional	The hostname that will be transmitted to the device in order for the device to verify the hostname. If not set, will be the URL without the path. E.g if the address is `https://path.to.server/api/v1` the hostname will be `path.to.server`.
webHookUrl stringoptional	The webhook URL parameter should contain the address of this specific server or in more detail the address where the update server can reach this backend. If set, the webhook will be used to automatically update the status for the devices.
autoUpdate stringoptional	This field allows for cron-like updates on a interval basis and expects a cron-like scheduler expression such as 0 0 * * * *, which means every hour on the full hour. For more references please check out the library documentation: https://github.com/kelektiv/node-cron#readme. The library at hand does support a granularity of seconds.
checkRequestDelay integeroptional	The delay in milliseconds between each check request. They are handled in a serialized manner, but this parameter allows for further throttling of the requests.
bookRequestDelay integeroptional	The delay in milliseconds between each book request. They are handled in a serialized manner, but this parameter allows for further throttling of the requests. Default: 1000
outOfResourcesDelay integeroptional	The delay in milliseconds of how long to wait until retrying a firmware update after the update server has responded with a 429 on a book request. Indicating that all server resources are currently in use. Default: 300000
disableConnectUpdate booleanoptional	Whenever or not to disable a connect update. Devices might connect and have an update available. Setting this option to true will not trigger an update in the case an update is available.
pinOnlyWebhook booleanoptional	Set this to true to not trigger updates over the webhook when a rollout starts. This is useful if you want to enable time based updates, e.g. at midnight, and do want to start rollouts beforehand. Without this set to false rollouts would start immediately.

SERVICE Module

Config-Name: service

Name	Description
keepStateWhenOffline booleanoptional	Whenever to keep the service state when the device is goes offline or not. Default: true

TIMESTREAM Module

Config-Name: timestream

Name	Description
retention objectoptional	Retention information that handle the duration of data storage.
retention.memoryStoreRetentionPeriodInHours integeroptional	The duration data should be stored in the write-optimized memory store. Default: 6
retention.magneticStoreRetentionPeriodInDays integeroptional	The duration data should be stored in the read-optimized magnetic store. Default: 73000
writeConfig objectoptional	If the default write endpoint is not available, use this config to setup the write endpoint by hand.
writeConfig.region string	The region the endpoint is located in.
writeConfig.endpoint string	The url for the endpoint.
queryConfig objectoptional	If the default query endpoint is not available, use this config to setup the query endpoint by hand.
queryConfig.region string	The region the endpoint is located in.
queryConfig.endpoint string	The url for the endpoint.
tablePrefix string	The prefix for the table. Required in order to support multiple tables in the same database.
databaseName string	The database name the data will be stored in.
credentials objectoptional	Credentials required to connect to the timestream service. Optional only if auto resolve is set to `true`.
credentials.accessKeyId string	The key id for the aws key in order to connect to the timestream service.
credentials.secretAccessKey string	The value for the access key in order to connect to the timestream service.
enableCostSaving booleanoptional	The minimum billable unit for AWS Timestream writes is 1KB. Therefore, it is advised to sent properties once this threshold has been reached. However, this might not be an option for small demo projects that only contain a few devices and reach that 1KB threshold very slowly. Default: true
checkInterval integeroptional	The timestream module periodically checks if data should be send to AWS. A smaller interval will lead to more but smaller messages. Unit is milliseconds. Only applicable when cost saving is disabled. Default: 5000
filter optional	Option to filter certain properties.
Alternative 1object
filter.type stringconstant	Constant value: blacklist
filter.properties arraynumber	List of properties that should not be monitored and stored historically. All other properties will be handled as expected.
Alternative 2object
filter.type stringconstant	Constant value: whitelist
filter.properties arraynumber	List of properties that should be monitored and stored historically.
createEntities booleanoptional	DEPRECATED - The application itself will check (if possible) whenever or not the database and tables have been already created.
handleEvents booleanoptional	Whenever or not to store event data like alarm entries or device connectivity information. Default: true
handleData booleanoptional	Whenever or not to store data events in AWS timestream. This config parameter will be used to transition from the first iteration of the timestream module to the second and allows the backend to use both the v1 and the v2 version while only the first version will pollute the data part of AWS Timestream.. It will be removed in parallel to the v1 timestream module. Default: true
batchSize numberoptional	The amount of requests to batch between AWS timestream and the backend before the result is sent to the client. A greater batch size means more RAM usage on the backend and an increases duration for an answer to the client, while reducing the overhead of sending lots of messages between the client and the backend. Default: 10
resolveCredentialsFromInstanceProfile booleanoptional	While running within an EC2 instance one might want to resolve the credentials from the instance profile. Setting this config parameter to true, the credentials config parameter will not be checkend and an [internal aws function](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-credential-providers/#fromcontainermetadata-and-frominstancemetadata) will be called.

ALARM Module

Config-Name: alarm

Name	Description
storeState booleanoptional	Whenever or not to store the current state to every alarm occurrence. Setting this to true will drastically increase the amount of data stored in the database.
maxStatusEntries numberoptional	The amount of status entries to store. Note that one entry is a status change. Meaning to store e.g. one hundred occurrence you have a max entries of two hundred. Default: 100
apn arrayoptional	Options for the Apple Push Notification service. Default: []
apn.[ ].key	The connection key in order to use the APN service.
Alternative 1string	The filename for the key to load from disk.
Alternative 2	A Buffer-Object. Best practice is to use `fs.readFileSync` to generate this buffer directly inside the config.
apn.[ ].keyId string	The key ID for the key.
apn.[ ].teamId string	The teamId to use for the push notification service.
apn.[ ].production boolean	Whenever to run in production mode
apn.[ ].pfx optional	File path for private key, certificate and CA certs in PFX or PKCS12 format, or a Buffer containing the PFX data. If supplied will always be used instead of certificate and key above.
Alternative 1string	The filename for the pfx file to load from disk.
Alternative 2	A Buffer-Object. Best practice is to use `fs.readFileSync` to generate this buffer directly inside the config.
apn.[ ].topic string	The topic the push notification will be published at.
apn.[ ].sound stringoptional	An optional sound name to play when the notification is sent.
gcm arrayoptional	[DEPRECATED] Options for the Google Cloud Messaging service. Default: []
gcm.[ ].sender string	Sender information for the google cloud messaging service.
gcm.[ ].link string	Link information for the google cloud messaging service.
gcm.[ ].icon stringoptional	The icon to show within the notification.
fcm arrayoptional	Options for the Firebase Cloud Messaging service. Default: []
fcm.[ ].link string	Link information for the firebase cloud messaging service.
fcm.[ ].icon stringoptional	The icon to show within the notification.
fcm.[ ].jsonPath string	The path to the json file to use for authentication.

UI Module

Config-Name: ui

Name	Description

REMOTE Module

Config-Name: remote

Name	Description
wire objectoptional	Default: { "port": 9982, "protocol": "TCP" }
wire.port numberoptional	Default: 9986
wire.host stringoptional
wire.protocol stringenum	Possible values: UDP, TCP
provider arrayoptional	Default: []

ALEXA Module

Config-Name: alexa

Name	Description
setup optional	The alexa handler settings
provider arrayoptional	Auth provider to be able to interact with alexa. Default: []
identifier string	The skill identifier. Used to sent events proactively to the AWS cloud.
secret string	The skill secret. Used to sent events proactively to the AWS cloud.
serviceIdentifier string	The service identifier for a service of the device. Can be seen as the interface name where services with the same identifier contain the same properties.
properties arraynumber	Property identifier to track.
path stringoptional	Path option to overwrite the default path property. Useful, when dealing with multiple smart home applications
name stringoptional	Name property can be used to add multiple google smart home modules. Each needs a unique name. Note: The underlying pairings for user-devices will be stored inside a database with the name as the prefix. Changing the name in production WILL render active smart home users unable to use their devices. Handle with care, you have been warned! Default: alexa

GOOGLE Module

Config-Name: google

Name	Description
setup optional	The alexa handler settings
serviceIdentifier string	The service identifier for a service of the device. Can be seen as the interface name where services with the same identifier contain the same properties.
serviceWorkerFilePath stringoptional	Path to the service worker file in order to ensure that events can be sent proactively to google.
properties arraynumber	Property identifier to track.
path stringoptional	Path option to overwrite the default path property. Useful, when dealing with multiple smart home applications
name stringoptional	Name property can be used to add multiple google smart home modules. Each needs a unique name. Note: The underlying pairings for user-devices will be stored inside a database with the name as the prefix. Changing the name in production WILL render active smart home users unable to use their devices. Handle with care, you have been warned! Default: google

SLACK Module

Config-Name: slack

Name	Description
instanceName string	The instance name that will be used in Slack messages.
webhook string	The webhook that will be used to send messages.

GEOLOCATION Module

Config-Name: geolocation

Name	Description
informationSource arrayoptional	Array that includes property information regarding properties that are cell ids. Default: []
informationSource.[ ].serviceIdentifier string	The service identifier for a service of the device. Can be seen as the interface name where services with the same identifier contain the same properties.
informationSource.[ ].properties object	Object containing all required mobile network information
informationSource.[ ].properties.cellId number	The identifier of the property that represents the cell id.
informationSource.[ ].properties.mobileCountryCode number	The identifier of the property that represents the mobile country code.
informationSource.[ ].properties.mobileNetworkCode number	The identifier of the property that represents the mobile network code.
informationSource.[ ].properties.locationAreaCode number	The identifier of the property that represents location area code.
key string	The key that will be used to identify against the google geolocation API.
cacheDuration numberoptional	The duration Default: 31536000000

Build

Name	Description
basePath stringoptional	Base path that can be used by the modules to further specify their routes. Default: /api/v1
port numberoptional	Port the API will be available at Default: 8080
enableDefaultAccess booleanoptional	Whenever to use the access property of each path. Can be left as is. Access will be granted by default unless the access management module is used Default: true
useReduxDevtools booleanoptional
devtoolsOptions objectoptional
devtoolsOptions.realtime booleanoptional	Specifies whether to allow remote monitoring. Defaults to NODE_ENV === development
devtoolsOptions.hostname stringoptional	Used to specify host for remotedev-server. If port is specified, default value is localhost.
devtoolsOptions.port numberoptional	Used to specify the host port for remotedev-server
devtoolsOptions.secure booleanoptional	Specifies whether to use https protocol for remotedev-server.
devtoolsOptions.maxAge numberoptional	Maximum allowed actions to be stored in the history tree. The oldest actions are removed once maxAge is reached. It is critical for performance.

Database

Name	Description
connectionString stringoptional	https://www.mongodb.com/docs/manual/reference/connection-string/ Default: mongodb://127.0.0.1:27017
databaseName stringoptional	Default: database
persistenceInterval numberoptional	Milliseconds interval in where an event is triggered that allows modules to persist their data.
clientOptions objectoptional
clientOptions.tlsCAFile stringoptional
clientOptions.connectTimeoutMS numberoptional

Adapter

Name	Description