rainbird
Version:
The Rainbird library allows you to access your RainBird Controller.
254 lines (176 loc) • 6.71 kB
Markdown
# API Guide
This guide describes the methods, properties & events of the RainBird service.
## Methods
- `RainBirdService({
address: string,
password: string,
refreshRate?: number,
showRequestResponse: boolean,
syncTime: boolean})`
Instantiates the RainBirdService class.
Parameters:
- `address`: controller's local IP Address. Mandatory
- `password`: controller's password. Mandatory
- `refreshRate`: how often to request status from controller (in secords). Optional. Default is 0 (never check)
- `showRequestResponse`: include requests & responses in log events. Mandatory
- `syncTime`: sync the machine time to the controller. Mandatory
```typescript
import { RainBirdService, LogLevel, EventType } from 'RainBird';
// Create the RainBird service
const rainbird = new RainBirdService({
address: '10.0.0.123',
password: 'mypassword',
refreshRate: 90,
showRequestResponse: true,
syncTime: true,
});
```
- `init(): Promise<RainBirdMetaData>`
Performs various initialisations for the service. This is typically done once immediately after instantiating the service. It performs the following:
- Retrieves the RainBird's model, version, serial number & available zones
- Checks that its in the correct state to be controlled
- Sets up the status & sync time jobs
- Returns various metadata about the RainBird
```typescript
// Initialise the RainBird service
var metadata = await rainbird.init();
```
- `isActive(zone?: number): boolean`
Returns true if the specified zone is active (i.e. currently running or queued to run). If no zone number is supplied then will check if any zone is active.
Parameters:
- `zone`: zone number. Optional
```typescript
// Is Zone 1 currently running or queued to run
var isZone1Active = rainbird.isActive(1);
```
- `isInUse(zone?: number): boolean`
Returns true if the specified zone is currently running (does not check if it's queued). If no zone number is supplied then will check if any zone is running.
Parameters:
- `zone`: zone number. Optional
```typescript
// Is Zone 1 current running?
var isZone1Running = rainbird.isInUse(1);
```
- `remainingDuration(zone?: number): number`
Returns the amount of time (in seconds) remaining for the specified zone. If no zone number is supplied then will return the total for all active zones.
Parameters:
- `zone`: zone number. Optional
```typescript
// Get the remaining time for Zone 1
var zone1TimeLeft = rainbird.remainingDuration(1);
```
- `activateZone(zone: number, duration: number): void`
Places the specified zone and duration into a queue. The zone will begin running for the specified duration once all other zones ahead in the queue have completed.
Parameters:
- `zone`: zone number. Mandatory
- `duration`: The amount of time (in seconds) for the zone to run. Mandatory.
```typescript
// Active Zone 1 for 10 minutes (600 seconds)
rainbird.activateZone(1, 600);
```
- `deactivateZone(zone: number): Promise<void>`
Stops the specified zone or removes it from the queue.
Parameters:
- `zone`: zone number. Mandatory
```typescript
// Stop Zone 1 if its running or remove it from the queue
await rainbird.deactivateZone(1);
```
- `deactivateAllZones(): void`
Stops the currently running zone and removes any others that are in the queue.
```typescript
// Stop all zones
await rainbird.deactivateAllZones(1);
```
- `startProgram(programId: string): Promise<void>`
Starts the specified RainBird program.
Parameters:
- `programId`: The program identifier (letters A - D). Mandatory
```typescript
// Start program A
await rainbird.startProgram('A');
```
- `isProgramRunning(programId: string): boolean | undefined`
Returns true if the specified program is currently running.
Parameters:
- `programId`: The program identifier (letters A - D). Mandatory
```typescript
// Is program A running?
var isProgramArunning = await rainbird.isProgramRunning('A');
```
- `stopIrrigation(): Promise<void>`
Performs a Stop Irrigation command on the RainBird.
```typescript
// Stop Irrigation
await rainbird.stopIrrigation();
```
- `getIrrigatinDelay(): Promise<number>`
Returns the Irrigation Delay remaining (in days).
```typescript
// Get Irrigation Delay days remaining
var delayDaysLeft = await rainbird.getIrrigatinDelay();
```
- `setIrrigationDelay(days: number): Promise<void>`
Set the number of days to delay the irrigation.
Parameters:
- `days`: number of days to delay irrigation (1 - 14). Mandatory
```typescript
// Set Irrigation Delay to 5 days
await rainbird.setIrrigationDelay(5);
```
## Properties
- `model: string`
Returns the model number of the RainBird controller.
```typescript
// Get the RainBird model number
var model = rainbird.model;
```
- `version: string`
Returns the version of the RainBird controller.
```typescript
// Get the RainBird version number
var version = rainbird.version;
```
- `serialNumber: string`
Returns the serial number of the RainBird controller.
```typescript
// Get the RainBird serial number
var serialNumber = rainbird.serialNumber;
```
- `zones: number[]`
Returns the available zones of the RainBird controller in an array.
```typescript
// Get the RainBird zones
var zones = rainbird.zones;
```
- `rainSetPointReached: boolean`
Returns true if the rain sensor's set point has been reached.
```typescript
// Is the rain sensor's set point reached?
var setPointReached = rainbird.rainSetPointReached;
```
## Events
- `log`
Raised when API wants to notify client of a specific log level & message.
```typescript
// Handle log events
rainbird.on(EventType.LOG, (log) => {
console.log(`${log.level}: ${log.message}`);
});
```
- `status`
Raised when API wants to notify client of a status change
```typescript
// Handle status events
rainbird.on(EventType.STATUS, () => {
console.log('RainBird status changed');
});
```
- `rain_sensor_state`
Raised when API wants to notify client of a change to the rain sensor's state
```typescript
// Handle status events
rainbird.on(EventType.RAIN_SENSOR_STATE, () => {
console.log('Rain sensor state has changed');
});
```