HomeSpan Documentation

If your specific motor driver chip is not supported by existing classes, you can create a custom driver by inheriting from the StepperControl abstract class. The core logic for background movement is already handled by the base class; you only need to implement the hardware-specific pin toggling.

Required Method:

• void onStep(boolean direction): Logic to advance the motor by a single step based on the direction parameter.

Optional Methods (implement if applicable to your hardware):

• void onEnable(): Logic to enable the motor driver.
• void onDisable(): Logic to disable the motor driver.
• void onBrake(): Logic to put the motor into a short brake state.
• StepperControl *setStepType(int mode): Logic to set the step type mode (e.g., Full Step, Half Step) based on the mode parameter.

Implementation Example (Stepper_A3967):

struct Stepper_A3967 : StepperControl {
  // ... constructor and pin definitions ...

  void onStep(boolean direction) override {
    digitalWrite(dirPin,direction);
    digitalWrite(stepPin,HIGH);
    digitalWrite(stepPin,LOW);      
  }

  void onEnable() override {
    digitalWrite(enablePin,0);
  }

  void onDisable() override {
    digitalWrite(enablePin,1);
  }

  StepperControl *setStepType(int mode) override {
    switch(mode){
      case FULL_STEP_TWO_PHASE:
        digitalWrite(m1Pin,LOW);
        digitalWrite(m2Pin,LOW);
        break;
      // ... other cases ...
    }
    return(this);
  }
};

#include "HomeSpan.h"

//////////////////////////
 
struct Stepper_A3967 : StepperControl {

  int m1Pin;
  int m2Pin;
  int stepPin;
  int dirPin;
  int enablePin;

//////////////////////////

  Stepper_A3967(int m1Pin, int m2Pin, int stepPin, int dirPin, int enablePin, std::pair<uint32_t, uint32_t> taskParams = {1,0}) : StepperControl(taskParams.first,taskParams.second){
    this->m1Pin=m1Pin;
    this->m2Pin=m2Pin;
    this->stepPin=stepPin;
    this->dirPin=dirPin;
    this->enablePin=enablePin;

    pinMode(m1Pin,OUTPUT);
    pinMode(m2Pin,OUTPUT);
    pinMode(stepPin,OUTPUT);
    pinMode(dirPin,OUTPUT);
    pinMode(enablePin,OUTPUT);

    setStepType(FULL_STEP_TWO_PHASE);
  }

//////////////////////////

  void onStep(boolean direction) override {
    digitalWrite(dirPin,direction);
    digitalWrite(stepPin,HIGH);
    digitalWrite(stepPin,LOW);      
  }

//////////////////////////

  void onEnable() override {
    digitalWrite(enablePin,0);
  }

//////////////////////////

  void onDisable() override {
    digitalWrite(enablePin,1);
  }

//////////////////////////

  StepperControl *setStepType(int mode) override {
    switch(mode){
      case FULL_STEP_TWO_PHASE:
        digitalWrite(m1Pin,LOW);
        digitalWrite(m2Pin,LOW);
        break;
      case HALF_STEP:
        digitalWrite(m1Pin,HIGH);
        digitalWrite(m2Pin,LOW);
        break;
      case QUARTER_STEP:
        digitalWrite(m1Pin,LOW);
        digitalWrite(m2Pin,HIGH);
        break;
      case EIGHTH_STEP:
        digitalWrite(m1Pin,HIGH);
        digitalWrite(m2Pin,HIGH);
        break;
      default:
        ESP_LOGE(STEPPER_TAG,"Unknown StepType=%d",mode);
    }
    return(this);
  }
  
};

The RFControl class interfaces with the ESP32 RMT peripheral to drive RF or IR transmitters. You can use it to control appliances directly from the Home App or Siri.

There are two primary ways to use RFControl:

1. Internal Memory Method: Use clear(), add(), or phase() to build a pulse train in the object's internal memory, then call start() to transmit it. This is best for pulse trains created on-the-fly.
2. External Array Method: Pre-compute pulse trains in external 32-bit arrays using the RF_PULSE(highTicks, lowTicks) macro, then call start() with a pointer to that array. This is best for pre-defined, static signals and must use RAM (not PSRAM).

RFControl rf(11);  // create an instance of RFControl

// Method 1: Internal Memory
rf.clear();        // clear the internal memory structure
rf.add(100,50);    // create pulse of 100 ticks HIGH followed by 50 ticks LOW
rf.start(4,1000);  // start transmission; repeat 4 cycles; 1 tick = 1000µs 

// Method 2: External Array
uint32_t pulseTrain[] = {RF_PULSE(100,50), RF_PULSE(100,50), RF_PULSE(25,500)};
rf.start(pulseTrain,3,4,1000);  // start transmission using the same parameters

HomeSpan uses a declarative approach to define the HAP (HomeKit Accessory Protocol) Accessory Attribute Database. Instead of managing complex object trees, you instantiate objects in a specific order, and HomeSpan automatically handles the registration and hierarchy.

The Hierarchy Rules

1. SpanAccessory: The top-level container. Instantiating new SpanAccessory() creates a new accessory and registers it with the global homeSpan object.
2. Service: Services are defined in the Service:: namespace. Instantiating a service (e.g., new Service::LightBulb()) automatically attaches it to the last instantiated SpanAccessory.
3. Characteristic: Characteristics are defined in the Characteristic:: namespace. Instantiating a characteristic (e.g., new Characteristic::On()) automatically attaches it to the last instantiated Service.

Critical Note: The order of instantiation is vital. If you instantiate objects in the wrong order, the hierarchy will be incorrect. HomeSpan performs validation at startup; if an accessory is missing required services or characteristics (like Service::AccessoryInformation or Characteristic::Identify), HomeSpan will report errors and halt the program.