Skip to content

Commit fa0b497

Browse files
donavanbeckerdonavanbecker
committed
BotController
1 parent f16306a commit fa0b497

25 files changed

+6793
-6156
lines changed

‎COMPOSITION_CHECKLIST.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# Composition Checklist
2+
3+
This checklist ensures that each file has been refactored to use Composition and has been properly imported into the `index.ts` file.
4+
5+
## Checklist
6+
7+
| Device | Composition Refactored | Imported in `index.ts` | OpenAPI Support | BLE Support |
8+
| ------------------------------------- | ---------------------- | ---------------------- | --------------- | ----------- |
9+
| Bot | [X] | [X] | [ ] | [ ] |
10+
| Curtain | [ ] | [ ] | [ ] | [ ] |
11+
| Curtain 3 | [ ] | [ ] | [ ] | [ ] |
12+
| Hub/Hub Plus/Hub Mini/Hub 2/Hub 3 | [ ] | [ ] | [ ] | [ ] |
13+
| Meter | [ ] | [ ] | [ ] | [ ] |
14+
| Meter Plus | [ ] | [ ] | [ ] | [ ] |
15+
| Outdoor Meter | [ ] | [ ] | [ ] | [ ] |
16+
| Meter Pro | [ ] | [ ] | [ ] | [ ] |
17+
| Meter Pro CO2 | [ ] | [ ] | [ ] | [ ] |
18+
| Lock | [ ] | [ ] | [ ] | [ ] |
19+
| Lock Pro | [ ] | [ ] | [ ] | [ ] |
20+
| Lock Ultra | [ ] | [ ] | [ ] | [ ] |
21+
| Keypad | [ ] | [ ] | [ ] | [ ] |
22+
| Keypad Touch | [ ] | [ ] | [ ] | [ ] |
23+
| Remote | [ ] | [ ] | [ ] | [ ] |
24+
| Motion Sensor | [ ] | [ ] | [ ] | [ ] |
25+
| Contact Sensor | [ ] | [ ] | [ ] | [ ] |
26+
| Water Leak Detector | [ ] | [ ] | [ ] | [ ] |
27+
| Ceiling Light | [ ] | [ ] | [ ] | [ ] |
28+
| Ceiling Light Pro | [ ] | [ ] | [ ] | [ ] |
29+
| RGBICWW Strip Light | [ ] | [ ] | [ ] | [ ] |
30+
| RGBICWW Floor Lamp | [ ] | [ ] | [ ] | [ ] |
31+
| RGBIC Neon Wire Rope Light | [ ] | [ ] | [ ] | [ ] |
32+
| Smart Radiator Thermostat | [ ] | [ ] | [ ] | [ ] |
33+
| Plug Mini (US) | [ ] | [ ] | [ ] | [ ] |
34+
| Plug Mini (JP) | [ ] | [ ] | [ ] | [ ] |
35+
| Plug Mini (EU) | [ ] | [ ] | [ ] | [ ] |
36+
| Plug | [ ] | [ ] | [ ] | [ ] |
37+
| Strip Light | [ ] | [ ] | [ ] | [ ] |
38+
| Color Bulb | [ ] | [ ] | [ ] | [ ] |
39+
| Robot Vacuum Cleaner S1 | [ ] | [ ] | [ ] | [ ] |
40+
| Robot Vacuum Cleaner S1 Plus | [ ] | [ ] | [ ] | [ ] |
41+
| Mini Robot Vacuum K10+ | [ ] | [ ] | [ ] | [ ] |
42+
| Mini Robot Vacuum K10+ Pro | [ ] | [ ] | [ ] | [ ] |
43+
| K10+ Pro Combo | [ ] | [ ] | [ ] | [ ] |
44+
| Floor Cleaning Robot S10 | [ ] | [ ] | [ ] | [ ] |
45+
| Floor Cleaning Robot S20 | [ ] | [ ] | [ ] | [ ] |
46+
| Robot Vacuum K11+ | [ ] | [ ] | [ ] | [ ] |
47+
| Multitasking Household Robot K20+ Pro | [ ] | [ ] | [ ] | [ ] |
48+
| Humidifier | [ ] | [ ] | [ ] | [ ] |
49+
| Evaporative Humidifier | [ ] | [ ] | [ ] | [ ] |
50+
| Evaporative Humidifier (Auto-refill) | [ ] | [ ] | [ ] | [ ] |
51+
| Air Purifier VOC | [ ] | [ ] | [ ] | [ ] |
52+
| Air Purifier Table VOC | [ ] | [ ] | [ ] | [ ] |
53+
| Air Purifier PM2.5 | [ ] | [ ] | [ ] | [ ] |
54+
| Air Purifier Table PM2.5 | [ ] | [ ] | [ ] | [ ] |
55+
| Indoor Cam | [ ] | [ ] | [ ] | [ ] |
56+
| Pan/Tilt Cam | [ ] | [ ] | [ ] | [ ] |
57+
| Pan/Tilt Cam 2K | [ ] | [ ] | [ ] | [ ] |
58+
| Blind Tilt | [ ] | [ ] | [ ] | [ ] |
59+
| Battery Circulator Fan | [ ] | [ ] | [ ] | [ ] |
60+
| Circulator Fan | [ ] | [ ] | [ ] | [ ] |
61+
| Roller Shade | [ ] | [ ] | [ ] | [ ] |
62+
| Relay Switch 1PM | [ ] | [ ] | [ ] | [ ] |
63+
| Relay Switch 1 | [ ] | [ ] | [ ] | [ ] |
64+
| Relay Switch 2PM | [ ] | [ ] | [ ] | [ ] |
65+
| Garage Door Opener | [ ] | [ ] | [ ] | [ ] |
66+
| Floor Lamp | [ ] | [ ] | [ ] | [ ] |
67+
| LED Strip Light 3 | [ ] | [ ] | [ ] | [ ] |
68+
| Lock Lite | [ ] | [ ] | [ ] | [ ] |
69+
| Video Doorbell | [ ] | [ ] | [ ] | [ ] |
70+
| Keypad Vision | [ ] | [ ] | [ ] | [ ] |
71+
| Virtual infrared remote devices | [ ] | [ ] | [ ] | [ ] |
72+
73+
## Instructions
74+
75+
1. Refactor the file to use Composition where applicable.
76+
2. Ensure the file is exported in `index.ts`.
77+
3. Check off the file in this list once both steps are complete.

‎Controllers.md‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
# Using the Controllers
2+
3+
The `Controllers` document provides an overview of managing SwitchBot devices using various controllers. Currently, it includes the `BotController` class, which combines Bluetooth Low Energy (BLE) and OpenAPI functionality. This document will be updated as new controllers are added.
4+
5+
## BotController
6+
7+
### Features
8+
9+
- **BLE-First Logic**: Attempts to use BLE for device control first, falling back to OpenAPI if BLE is unavailable.
10+
- **Mode Selection**: Allows forcing BLE-only or OpenAPI-only modes.
11+
- **Unified Interface**: Provides a single interface for controlling SwitchBot devices.
12+
13+
### Installation
14+
15+
Ensure you have the required dependencies installed:
16+
17+
```bash
18+
npm install
19+
```
20+
21+
Build the project:
22+
23+
```bash
24+
npm run build
25+
```
26+
27+
### Importing the BotController
28+
29+
To use the `BotController`, import it along with the required dependencies:
30+
31+
```typescript
32+
import { BotController } from './devices/bot-controller.js'
33+
import { SwitchBotBLE } from './switchbot-ble.js'
34+
import { SwitchBotOpenAPI } from './switchbot-openapi.js'
35+
```
36+
37+
### Initialization
38+
39+
Create instances of `SwitchBotBLE` and `SwitchBotOpenAPI`, then initialize the `BotController`:
40+
41+
```typescript
42+
const ble = new SwitchBotBLE()
43+
const openAPI = new SwitchBotOpenAPI('your-token', 'your-secret')
44+
45+
new BotController(openAPI, ble, {
46+
useBLEOnly: false, // Optional: Force BLE-only mode
47+
useOpenAPIOnly: false, // Optional: Force OpenAPI-only mode
48+
})
49+
```
50+
51+
### Methods
52+
53+
#### `turnOn(deviceId: string): Promise<void>`
54+
55+
Turns on a SwitchBot device.
56+
57+
```typescript
58+
await botController.turnOn('device-id')
59+
```
60+
61+
#### `turnOff(deviceId: string): Promise<void>`
62+
63+
Turns off a SwitchBot device.
64+
65+
```typescript
66+
await botController.turnOff('device-id')
67+
```
68+
69+
#### `press(deviceId: string): Promise<void>`
70+
71+
Simulates a press action on a SwitchBot device.
72+
73+
```typescript
74+
await botController.press('device-id')
75+
```
76+
77+
### Mode Selection
78+
79+
#### BLE-Only Mode
80+
81+
To force BLE-only mode, set `useBLEOnly` to `true` during initialization:
82+
83+
```typescript
84+
new BotController(openAPI, ble, {
85+
useBLEOnly: true,
86+
})
87+
```
88+
89+
#### OpenAPI-Only Mode
90+
91+
To force OpenAPI-only mode, set `useOpenAPIOnly` to `true` during initialization:
92+
93+
```typescript
94+
new BotController(openAPI, ble, {
95+
useOpenAPIOnly: true,
96+
})
97+
```
98+
99+
### Error Handling
100+
101+
The `BotController` automatically falls back to OpenAPI if BLE fails. However, you can handle errors explicitly:
102+
103+
```typescript
104+
try {
105+
await botController.turnOn('device-id')
106+
} catch (error) {
107+
console.error('Failed to control device:', error)
108+
}
109+
```
110+
111+
### Conclusion
112+
113+
The `BotController` class simplifies the process of managing SwitchBot devices by combining BLE and OpenAPI functionality into a single interface. Use the provided methods and options to control your devices effectively.
114+
115+
## Future Updates
116+
117+
This document will be updated as new controllers are added to the project.

‎OpenAPI.md‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,8 @@ The `SwitchBotOpenAPI` class allows you to interact with SwitchBot devices using
1414
- [`deleteWebhook()` Method](#deletewebhook-method)
1515
- [Logging](#logging)
1616
- [Supported Devices](#supported-devices)
17+
- [Robot Vacuum Methods](#robot-vacuum-methods)
18+
- [Bot Controller Methods](#bot-controller-methods)
1719

1820
## OpenAPI
1921

@@ -181,6 +183,72 @@ The following devices are supported.
181183
| SwitchBot Color Bulb | Yes | Yes |
182184
| SwitchBot LED Strip Light | Yes | Yes |
183185

186+
### Robot Vacuum Methods
187+
188+
#### `controlRobotVacuum` Method
189+
190+
Controls a Robot Vacuum with predefined commands. This method is now part of the `RobotVacuumController` class, which uses the `SwitchBotOpenAPI` instance.
191+
192+
```typescript
193+
import { RobotVacuumController, SwitchBotOpenAPI } from 'node-switchbot'
194+
195+
const api = new SwitchBotOpenAPI('your-token', 'your-secret')
196+
const vacuum = new RobotVacuumController(api)
197+
198+
vacuum.controlRobotVacuum('device-id', 'startCleaning', { suctionLevel: 3 })
199+
.then(response => console.log('Robot Vacuum Controlled:', response))
200+
.catch(error => console.error('Error:', error))
201+
```
202+
203+
#### `getRobotVacuumStatus` Method
204+
205+
Retrieves the status of a Robot Vacuum. This method is now part of the `RobotVacuumController` class, which uses the `SwitchBotOpenAPI` instance.
206+
207+
```typescript
208+
import { RobotVacuumController, SwitchBotOpenAPI } from 'node-switchbot'
209+
210+
const api = new SwitchBotOpenAPI('your-token', 'your-secret')
211+
const vacuum = new RobotVacuumController(api)
212+
213+
vacuum.getRobotVacuumStatus('device-id')
214+
.then(status => console.log('Robot Vacuum Status:', status))
215+
.catch(error => console.error('Error:', error))
216+
```
217+
218+
### Bot Controller Methods
219+
220+
#### `turnOn`, `turnOff`, and `press` Methods
221+
222+
The `BotController` class provides methods to control SwitchBot Bots using the `SwitchBotOpenAPI` instance. These methods include `turnOn`, `turnOff`, and `press`.
223+
224+
```typescript
225+
import { BotController, SwitchBotOpenAPI } from 'node-switchbot'
226+
227+
const api = new SwitchBotOpenAPI('your-token', 'your-secret')
228+
const botController = new BotController(api)
229+
230+
// Turn on the bot
231+
botController.turnOn('device-id')
232+
.then(() => console.log('Bot turned on'))
233+
.catch(error => console.error('Error:', error))
234+
235+
// Turn off the bot
236+
botController.turnOff('device-id')
237+
.then(() => console.log('Bot turned off'))
238+
.catch(error => console.error('Error:', error))
239+
240+
// Press the bot
241+
botController.press('device-id')
242+
.then(() => console.log('Bot pressed'))
243+
.catch(error => console.error('Error:', error))
244+
```
245+
246+
### Notes on Refactoring
247+
248+
The `controlRobotVacuum` and `getRobotVacuumStatus` methods have been moved to the `RobotVacuum` class. This class uses the Composition pattern, taking a `SwitchBotOpenAPI` instance as a dependency. This approach improves modularity and future-proofing by separating the robot vacuum logic from the `SwitchBotOpenAPI` class.
249+
250+
The `turnOn`, `turnOff`, and `press` methods have been moved to the `BotController` class. This class uses the Composition pattern, taking a `SwitchBotOpenAPI` instance as a dependency. This approach improves modularity and future-proofing by separating the bot control logic from the `SwitchBotOpenAPI` class.
251+
184252
### Summary
185253

186254
The `SwitchBotOpenAPI` class provides a powerful way to interact with your SwitchBot devices programmatically. By following the examples provided, you can easily integrate SwitchBot device control and monitoring into your applications.

0 commit comments

Comments
 (0)