/pimodule-express-api

A node package to expose your UPS PIco HV3.0A/B/B+ HAT features on an express api

Primary LanguageJavaScript

PiModule express API

A node package to expose your UPS PIco HV3.0A/B/B+ HAT features on an express api.

This library was not developped by the PiModules(R) UPSPIco company. Any query/issue concerning their product won't find answers here, sorry :/ Feel free to refer to their official github repo: https://github.com/modmypi/PiModules

The main goal of this module is to expose PiModule features on your local network. I would recommand against exposing this API to the world. If you really need to, I would use a reverse proxy like nginx.

Getting Started

This server is just a REST wrapper of the PiModule Helper library. Once the server is up and running, you should be able to use PiModule main features.

GET:

  • pimodule temperature
  • powering mode (battery or power)
  • battery level
  • buzzer state
  • relay state
  • pimodule running state
  • auxiliary power state
  • leds state
  • fan running, fan mode, fan speed, fan temperature threshold

SET:

  • shutdown timer, stop shutdown
  • powering mode (battery or power)
  • backed auxiliary power
  • buzzer
  • generate sounds
  • bistable relay state
  • leds (orange, green, blue)
  • fan mode (automatic, manual, disabled), fan speed, fan temperature threshold

Prerequisites

You'll need a UPS PIco HV3.0A/B/B+ HAT, you can order it here: https://pimodules.com/plus-advanced

You'll also need to get the installation process right. This process is described in the pimodule library: https://github.com/RomeHein/pimodule It's possible to use the same process directly with this module by running npm install every time your clone this repo. This will install the pimodule library depency and then give you access to the installation scripts via node_module/pimodule.

Two ways: via Ansible, or via the provided installer.sh script

  • Ansible

Make it easy to reproduce via Ansible in case your rasperry pi fails! To use the playbook provided, just clone this repository on your dev machine:

    git clone https://github.com/RomeHein/pimodule-express-api.git

Then run npm i into it. You will also need Ansible installed. Make sure to change your raspberry pi local address/user in the following command:

    cd node_module/pimodule/ansible
    ANSIBLE_HOST_KEY_CHECKING=false ansible-playbook pimodule.yml -i raspberrypi.local, --user=pi --ask-pass
  • Installer.sh

Just copy paste the script present in the pimodule library on your raspberry pi. Make sure you have the right permissions to run the script:

    chmod +x installer.sh

And run it with sudo:

sudo ./installer.sh

Installing

Depending on your requirements, three possibilities:

  • Use directly from code

This is not the best method, but the less dependant on other technologies. Clone the repo in the folder of your choice:

git clone https://github.com/RomeHein/pimodule-express-api.git

cd into the folder and then:

    npm i

Run the server with:

    npm start

Too easy!

  • Docker

This is in my opinion a more robust solution. You'll need docker and docker-compose installed on your Raspberrypi. You still need to clone the repo:

git clone https://github.com/RomeHein/pimodule-express-api.git

Then:

docker build -t pimodule-api .

Once done, run the container just created:

docker-compose up -d

☝️ Some customizations are needed here!

Three env variables are available:

  • API_PORT: define the port exposed by the api. Default to 7070.
  • ADDRESS_TYPE: define addresses that should be used by the UPS PIco HV3.0A/B/B+ HAT. Three are available: 'default', 'alternate', 'noRtc'. If you don't know what I2C means, this variable should not be used.
  • PASS: if you want to slightly secure your api, you can provide a pass. Your non-hashed password should be used with env variable PASS. The hashed pass (token) should be used when requests are made to the api, in the Authorization header. The server will just make a quick bcrypt.compare check before reading any incoming requests. The token will be printed in the log of the server. You can of course use any bcrypt online generator. Note that any person who has access to your local network could see your header and find your token. If you really want to secure this api you'll need a reverse proxy like nginx that will handle https requests:
PORT=8080 ADDRESS_TYPE=alternate HASHED_PASSED=$2y$12$IaMsT4MWiLkPI1IUVtO0GuDHoDxuh4RllAwGcaz7KFnKGtvbJa22m docker-compose up -d

Usage

Connect to your local network and then via postman or any web browser:

    http://raspberrypi.local:7070/pimodule/state

That should tell you if the PiModule is running properly.

You can have access to the full API documentation directly via (once you've got your server running):

    http://raspberrypi.local:7070/doc

Running the tests

npm run test

Contributing

All pull requests/suggestions are welcome.

Authors

  • Romain Cayzac

License

This project is licensed under the MIT License - see the LICENSE.md file for details