homebridge-minimal-http-blinds

What is it?

homebridge-minimal-http-blinds is a minimalistic HTTP blinds or roller shutters management plugin for homebridge.

The features:

• You can control your own blinds/roller shutters apparatus with three minimalistic HTTP requests.
• The control is not a simple binary open/close: it support percentages. You can open your blinds at 50% or 65% for instance.
• Your blinds can still be manually operated. As long at the get_current_position_url returns the right value, this plugin will update iOS Home app in real time.
• Instant reporting using cached data if no recent (no_cache_duration_millis) app detected activity.

Who is it for?

Anyone who, just like me, don't know much about homebridge but still want a straightforward way to communicate with your own home-made Raspberry Pi blinds/roller shutters controller.

How to use it

1] Install it into your homebridge instance

The installation instructions differs depending on how you installed homebridge.

Usually, it's something like "add this to your homebridge's install.sh"

npm install -g homebridge-minimal-http-blinds

2] Minimal configuration

Here is an homebridge's config.json with the minimal valid configuration:

{
    "bridge": {
        "name": "DemoMinimalisticHttpBlinds",
        "username": "AA:BB:CC:DD:EE:FF",
        "port": 51826,
        "pin": "123-45-678"
    },
  
    "description": "DEV NODEJS MACBOOK",
  
    "accessories": [
        {
            "name": "Kitchen Blinds",
            "accessory": "MinimalisticHttpBlinds",
  
            "get_current_position_url": "http://192.168.1.55/get/current_position/",
            "set_target_position_url": "http://192.168.1.55/set/%position%",
            "get_current_state_url": "http://192.168.1.55/get/current_state/"
        }
  
    ],
  
    "platforms": []
}

Beware, I'm a lazy ass!
These three parameters are not checked!
(get_current_position_url, set_target_position_url, get_current_state_url)
If you forgot to write them in your accessory, the module will crash.

Also, in the set_target_position_url parameter, the placeholder %position% will be replaced by the value selected in the iPhone's Home App.

3] More configuration

There are more configuration options.
The names are self-descriptive.
Here are them all with their default values.

{
    "get_current_position_method": "GET",
    "set_target_position_method": "POST",
    "get_current_state_method": "GET",
    
    "get_current_position_expected_response_code": "200",
    "set_target_position_expected_response_code": "204",
    "get_current_state_expected_response_code": "200",
    
    "get_current_position_polling_millis": "500",
    "get_current_state_polling_millis": "500",
    "no_cache_duration_millis": "60000"
}

4] Protocol requirements

The three URLs specified in the accessory configuration must have the following data formats:

4.1] get_current_position_url

This URL must return the current blinds position in plaintext, from 0 to 100.
(0 being closed and 100 opened)

4.2] set_target_position_url

This URL must trigger the blinds movement.
(That's the part you've done with your Raspberry Pi)
The requested opening position is, once again, an integer from 0 to 100. Please note that is passed directly in the URL. (It's the %position% placeholder)

Yep, that's it.
Not a single trace of json.
Are we barbarians or are we not?

4.3] get_current_state_url

This is the trickiest URL.
It must return one of these three integers in plaintext:

• 0 if the blinds are closing
• 1 if the blinds are opening
• 2 if the blinds are idling

Once again, that's your part of the job, the one you're supposed to implement in your blind manager thingymagic.

---

Click here to see an example implementation of this HTTP server.

That's all

Enjoy