![Logo](resources/bshb-logo.jpg)

[![NPM version](http://img.shields.io/npm/v/bosch-smart-home-bridge.svg)](https://www.npmjs.com/package/bosch-smart-home-bridge)
[![Downloads](https://img.shields.io/npm/dm/bosch-smart-home-bridge.svg)](https://www.npmjs.com/package/bosch-smart-home-bridge)
[![Main](https://github.com/holomekc/bosch-smart-home-bridge/actions/workflows/test.yml/badge.svg)](https://github.com/holomekc/bosch-smart-home-bridge/actions/workflows/test.yml)
[![Known Vulnerabilities](https://snyk.io/test/github/holomekc/bosch-smart-home-bridge/badge.svg)](https://snyk.io/test/github/holomekc/bosch-smart-home-bridge)

[![NPM](https://nodei.co/npm/bosch-smart-home-bridge.png)](https://nodei.co/npm/bosch-smart-home-bridge/)

# bosch-smart-home-bridge

Allows communication to Bosch Smart Home Controller (BSHC)

[Bosch Smart Home Controller](https://www.bosch-smarthome.com/de/de/produkte/smart-system-solutions/smart-home-controller)

[Bosch Smart Home Controller Local REST API](https://github.com/BoschSmartHome/bosch-shc-api-docs).

## 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)

```typescript
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

```typescript
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:

```typescript
bshb.getBshcClient();
```

## Long Polling

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

```typescript
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.

```typescript
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
   ```typescript
   bshb.getBshcClient().createBackup('SystemPassword', 'encryptionPassword');
   ```
2. Wait for backup status READY
   ```typescript
   bshb.getBshcClient().getBackupStatus();
   ```
3. Download backup file
   ```typescript
   bshb.getBshcClient().getBackup();
   ```
4. Upload restore file
   ```typescript
   bshb.getBshcClient().uploadRestoreFile(binaryData);
   ```
5. Wait for restore status BACKUP_UPLOADED
   ```typescript
   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
   ```typescript
   bshb.getBshcClient().getRestoreStatus();
   ```
8. Start restore process
   ```typescript
   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.
   ```typescript
   bshb.getBshcClient().getRestoreStatus();
   ```
10. Check partner restore status (Only possible if status is in RESTORED\*)

```typescript
bshb.getBshcClient().getPartnerRestoreStatus();
```

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

```typescript
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.