bosch-smart-home-bridge

Allows communication to Bosch Smart Home Controller (BSHC)

Bosch Smart Home Controller

Bosch Smart Home Controller Local REST API.

Getting started

You need to create a new instance of BoschSmartHomeBridge (BSHB). Therefore, you need to use BoschSmartHomeBridgeBuilder. The builder will force you to set every mandatory properties:

• host name / ip address of BSHC
• client certificate (base64 encoded)
• client private key (base64 encoded, 2048bit)
• a logger which implements the interface which is defined in this library (optional)

const certificate = BshbUtils.generateClientCertificate();
const bshb = BoschSmartHomeBridgeBuilder.builder()
    .withHost('192.168.0.10')
    .withClientCert(certificate.cert)
    .withClientPrivateKey(certificate.private)
    .build();

Pairing

Then you need to start the pairing process. Therefore, you need:

• name of the client
• a unique identifier for the new client (uuid is ok but can be any string)
• system password of BSHC

const identifier = BshbUtils.generateIdentifier();
bshb.pairIfNeeded('name', identifier, 'systemPassword');

Communication

After that you can use BSHB to communicate with BSHC. Therefore, just use the provided client which provides some helpful methods:

bshb.getBshcClient();

Long Polling

If you are interested in updates from bshc you can use long polling. Therefore, you need to do the following:

bshb
    .getBshcClient()
    .subscribe()
    .subscribe(response => {
        bshb
            .getBshcClient()
            .longPolling(response.parsedResponse.result)
            .subscribe(info => {
                // do something with the information
                // also you need to call longPolling again after connection close
            });
    });

Do not forget to unsubscribe. E.g. in error case or on application end.

bshb
    .getBshcClient()
    .unsubscribe(response.parsedResponse.result)
    .subscribe(() => {
    });

Backup & Restore

With this new feature provided by bosch you can automate the backup process. Some of the backup operations are not allowed by a restricted client. The restricted client is the default client when pairing with this library. You can change the client permissions in the Bosch App. Check the mobile devices section and change the permissions of the client of your choice.

Example can be found in the e2e test of the test folder.

The workflow is:

1. Create a backup

   bshb.getBshcClient().createBackup('SystemPassword', 'encryptionPassword');

2. Wait for backup status READY

   bshb.getBshcClient().getBackupStatus();

3. Download backup file

   bshb.getBshcClient().getBackup();

4. Upload restore file

   bshb.getBshcClient().uploadRestoreFile(binaryData);

5. Wait for restore status BACKUP_UPLOADED

   bshb.getBshcClient().getRestoreStatus();

6. Press pairing button on controller. Once for Controller II and 3s for Controller I
7. Wait for restore status RESTORE_AUTHORIZED

   bshb.getBshcClient().getRestoreStatus();

8. Start restore process

   bshb.getBshcClient().startRestoreProcess('encryptionPassword');

9. Wait for restore status RESTORED. The status might be in RESTORING for a while, and due to the restart the controller might not be available for some time as well.

   bshb.getBshcClient().getRestoreStatus();

10. Check partner restore status (Only possible if status is in RESTORED*)

bshb.getBshcClient().getPartnerRestoreStatus();

11. Complete the process or cancel the process (except if in RESTORING) via

bshb.getBshcClient().deleteRestoreFile();
bshb.getBshcClient().deleteBackup();

See api documentation for further details.

Uploading incomplete files might end up in a timeout, where the Controller appears to be stuck in RESTORING. If this is the case wait until the controller is changing the status to ERROR, and then restart the controller. During my tests without the restart the complete backup and restore feature is not working properly anymore.

Examples

You can find an example in test directory. Npm arguments must be set manually.

Disclaimer

By using this software, you acknowledge and accept the following terms:

1. Bosch Smart Home Controller:

   The use of this software with the Bosch Smart Home Controller I and II is at your own risk. The developer is not liable for any damage to the hardware, including but not limited to physical damage, malfunction, or failure of the Bosch Smart Home Controller. Users are advised to handle the devices with care and follow all manufacturer guidelines and recommendations.

2. Data Loss:

   While efforts have been made to ensure the reliability of the backup and restore functionality, the developer cannot guarantee the safety of your data. By using the backup and restore features, you understand and accept that there is a risk of data loss. This may include, but is not limited to, loss of settings, configurations, or other user data stored on the Bosch Smart Home Controller. It is strongly recommended that users perform regular backups and store them in a secure location. The developer shall not be held responsible for any data loss or corruption arising from the use of these features.