HUB
Sign inSign up

uupascal/rest-light

By uupascal

•Updated almost 4 years ago

Simple Microservice to control 433Mhz wireless sockets over HTTP, e.g. on a RaspberryPi

Image
0

3.1K

uupascal/rest-light repository overview

REST-light Logo

REST-light is a simple microservice to control 433Mhz wireless sockets over HTTP, e.g. on a RaspberryPi. The main usage is an easy integration of 433Mhz wireless sockets in SmartHome Tools like openHAB⁠ or ioBroker⁠.

The project is an API-Wrapper around the famous 443Utils⁠ project.

⁠How to Use

The setup is very simple. There is nothing to configure, except running the container. For the app to be able to persist the API-Key, ensure the mounted volume is writeable for UID/GID 33.

  1. Install Docker on your RaspberryPi
  2. Attach a 433Mhz transmitter to WiringPi Pin 2⁠ of your RaspberryPi
  3. Run REST-light and receive the generated API-Key from docker logs on first startup.
  4. Try your first request! For an example, see section "curl request example"⁠
⁠GPIO access

For the app to be able to use the Pi's GPIO-PINs, they need to be exposed to the container. There are multiple options to do this, as explained here⁠.

From the ones available, i had the best experience using the "device-approach" as stated below.

⁠docker run
docker run -d --device /dev/gpiomem -v <your-path>/rest-light:/etc/rest-light -p 4242:4242 uupascal/rest-light:DEV-latest
⁠docker-compose
version: "3.8"

services:
  rest-light:
    container_name: REST-light
    image: "uupascal/rest-light:latest"
    restart: unless-stopped
    volumes:
        - "<your-path>/rest-light:/etc/rest-light"
    devices:
        - /dev/gpiomem
    ports:
        - 4242

⁠curl request example

curl http://127.0.0.1:4242/send \
    --data-urlencode "api_key=<key from docker logs>" \
    --data-urlencode "system_code=10000" \
    --data-urlencode "unit_code=2" \
    --data-urlencode "state=0" 

curl http://127.0.0.1:4242/codesend \
    --data-urlencode "api_key=<key from docker logs>" \
    --data-urlencode "decimalcode=500000" \
    --data-urlencode "protocol=optional" \
    --data-urlencode "pulselength=optional" \
    --data-urlencode "bitlength=optional"

⁠OpenHAB integration example for the send binary

In this example, new devices can be added by simply adding a switch to the group gREST_light, whichs name is in the format example_<SYSTEM_CODE>_<UNIT_CODE>.

The included rule receives the values from the item name, as soon as any item in the group is triggered.

RESTlight.items

Group:Switch:OR(OFF, ON)    gREST_light                 "REST-light"    <light>                            ["Location"]

Switch                      RESTLight_10000_1           "Light"         <light>   (mygroup, gREST_light)   ["Switch"]
Switch                      RESTLight_01000_3           "Light2"        <light>   (mygroup, gREST_light)   ["Switch"]
Switch                      RESTLight_00100_3           "Light3"        <light>   (mygroup, gREST_light)   ["Switch"]

RESTlight.rules

rule "REST_light"
  when
    Member of gREST_light received command
  then
    logInfo("REST_light", "Member " + triggeringItem.name + " to " + receivedCommand)

    try {
      // receive system & unit code from item name
      val sys_num = triggeringItem.name.toString.split("_").get(1)
      val unit_num = triggeringItem.name.toString.split("_").get(2)

      var String state = ""
      if(receivedCommand == ON) {
        state = "1"
      } if(receivedCommand == OFF) {
        state = "0"
      }

      var String jsonstring = (
              '{"api_key" : "<INSERT KEY HERE>", "system_code" : "' + 
              sys_num + '", "unit_code" : "' + unit_num + '", "state" : "' + state + '"}'
      )

      sendHttpPostRequest("http://<INSERT IP HERE>:4242/send", "application/json", jsonstring.toString, 5000)
      logInfo("REST_light", jsonstring.toString)
      logInfo("REST_light", "Finished command!")

    } catch(Throwable t) {
      logInfo("REST_light", "Caught exception during attempt to contact REST_light API!")
    }
end

⁠OpenHAB integration example for the codesend binary

In this example, new devices can be added by simply adding a switch to the group gREST_light, whichs name is in the format example_<DECIMALCODE FOR ON>_<DECIMALCODE FOR OFF>.

The included rule receives the values from the item name, as soon as any item in the group is triggered.

RESTlight.items

Group:Switch:OR(OFF, ON)    gREST_light                 "REST-light"    <light>                            ["Location"]

Switch                      RESTLight_10000_1           "Light"         <light>   (mygroup, gREST_light)   ["Switch"]
Switch                      RESTLight_01000_3           "Light2"        <light>   (mygroup, gREST_light)   ["Switch"]
Switch                      RESTLight_00100_3           "Light3"        <light>   (mygroup, gREST_light)   ["Switch"]

RESTlight.rules

rule "REST_light"
  when
    Member of gREST_light received command
  then
    logInfo("REST_light", "Member " + triggeringItem.name + " to " + receivedCommand)

    try {
      // receive decimal codes from item name, e.g. zap_1234567_2345678_key1
      var decimal_code = ""
      if(receivedCommand == ON) {
        decimal_code = triggeringItem.name.toString.split("_").get(1)
      } if(receivedCommand == OFF) {
        decimal_code = triggeringItem.name.toString.split("_").get(2)
      }
      
      var protocol = "1"
      var pulselength = "150"
        
      var String jsonstring = ('{"api_key" : "<INSERT KEY HERE>", "decimalcode" : "' + decimal_code + '", "protocol" : "' + protocol + '", "pulselength" : "' + pulselength + '"}')
	  
      sendHttpPostRequest("http://<INSERT IP HERE>:4242/codesend", "application/json", jsonstring.toString, 5000)
      logInfo("REST_light", jsonstring.toString)
      logInfo("REST_light", "Finished command!")

    } catch(Throwable t) {
      logInfo("REST_light", "Caught exception during attempt to contact REST_light API!")
    }
end

⁠Security considerations

Although this project was developed with current security best-practices in mind, it is still built around software which was not updated for at least 6 years. I would therefor strongly encourage you to only use this container on private & trusted networks and to never expose it to the internet. As the license implies, this software is provided without warranty of any kind.

⁠Versioning & docker tags

Use the docker tag latest to always get the latest stable image.

The images are also tagged with the current timestamp, so to pin to a static version, you can for example use the tag 2022.01.09-1746.

Unstable/Development versions are prefixed with DEV- and should only be used for testing purposes.

⁠Contribution

We love your input! For details see CONTRIBUTING.md⁠

⁠Credits

The project relies on 443Utils⁠.

Tag summary

Content type

Image

Digest

sha256:f3032157a…

Size

76.4 MB

Last updated

almost 4 years ago

docker pull uupascal/rest-light