Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Basic edit of README documentation #17

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Basic edit of README documentation #17

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
251 changes: 162 additions & 89 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,100 +1,123 @@

# kumojs

A NodeJS server which accepts REST commands and configures Mitsubishi Airconditioners that use Kumo Gateway
A NodeJS server that accepts REST commands and configures Mitsubishi air conditioners equipped with Kumo Cloud Wi-Fi interfaces (WI1 and WI2).

# To install run.
# Getting Started

kumojs is a suite of related tools that work together to configure and run the NodeJS server.

* **kumoserver** -- a long running process that connnects to Kumo Cloud interfaces to send commands
* **kumo** -- command line interface tool that sends commands to the kumojs server
* **kumoconfig** -- generates a configuration file for the kumojs server

## Installation

To install kumojs, run the following command:
```
>npm install kumojs
> npm install kumojs
```
You will need to create a kumo.cfg file for any of the commands to work
# configuration
Once installed, you need to create a `kumo.cfg` file before any commands will work.

## Configuration
Run the following command:
```
>kumoconfig
> kumoconfig
```
this will create the kumo.cfg file that is needed for all the later commandsa
# cli
after install cli can be accessed by running "kumo"
This creates the `kumo.cfg` file needed for all kumojs commands.

## Command Line Interface (CLI)
After installation, access the CLI by running the **kumo** command. For example:
```
>kumo help
> kumo help
```
will show the different options
CLI is described in detail in the later part of the readme
# Server
To start the server run
shows the different options available. The CLI is described in detail later in this document.

## Server
To start the server, run the following command:
```
>kumoserver
> kumoserver
```
# TO Work with the Souce Repository.

## TO setup build env and packages
---------
# Work with the kumojs Source Repository

## Set up a build environment and install required packages
After cloning this repo, from the repo directory, run the following command:
```
> npm install
```
Once all dependencies are installed, you can work directly with the kumojs source files.

## TO BUILD
---------
## Build
To build your modified version of kumojs, from the repo directory, run the following command:
```
> npm run build
```

## To setup you configuraiton file.
---------
This step is important step, this is what creates the configuraiton file that has all the information about the
units. The CLI mode and the server mode will use this file to work.
When you run this, the script connects to the cloud and downloads the configuration. (Hopefully This is not going
to be disabled by the cloud folks).
The download files will be stored in kumo.cfg
## Set up configuration file

This command generates a configuration file with details of your air conditioner units.
**This step is essential.** The CLI and the server require the details from this file.

When you run this command, kumojs connects to the Kumo Cloud service and downloads configuration details, including the IP addresses for your units on your local network, and authentication tokens required to connect directly to them. (Hopefully this won't be disabled by Kumo Cloud.) The downloaded details are stored in `kumo.cfg`. Run the following commands:
```
> npm run config
> cp kumo.cfg build/
```

## To start SERVER
---------
This command will run a rest server that will accept commands by listining to a http port and sending those commands
to the airconditioner
# Run kumojs

## Start the Server
This command starts the kumoserver process. kumoserver is a long-running process providing a REST server that accepts commands on its http port, and then relays those commands to the air conditioner unit.
```
> npm run server
```
Details about how to run in server mode and the available commands are described in detail later in this document.

Detail on how to run in server mode and all the API's are provided later in the document.

## To run in cli mode
---------
## Run in CLI mode
This command runs kumojs commands directly via its CLI. For example:
```
> npm run cmd show config
```
Details about how to run in CLI mode and the available commands are described in detail later in this document.

Detail on how to run in cli mode and all the commands are provided later in the document.


## To create a container to run the package use the docker directory
---------
Build the container
## Create a container to run the package using the docker directory
To build the container, run the following commands:
```
> cp build/kumo.cfg docker/
> cd docker
> ./build_kumojs
```

## to run the container (I Use shared namespace in my case)
---------
### Run the container
This example uses a shared namespace. Run the following command:
```
> docker run --net=host -d --name kumojs --restart unless-stopped --tmpfs /run --tmpfs /run/lock sushilks/kumojs /bin/bash -c ". /root/.nvm/nvm.sh && /root/run_kumojs.sh"
```

## To attach to the running container
---------
### Attach to the running container
```
> ./attach_kumojs
```

## To view the logs from the container
---------
### View logs from the container
```
> docker logs -f kumojs
```


## Usages in CLI Mode
---------
in cli mode you can send a command to the air-conditioner form the shell.
## Use kumojs in CLI Mode
In CLI mode, you can send a command to an air conditioner unit directly from the command line.

### Help
To get help with the CLI, run the following command:
```
> npm run cmd help
or
> kumo help
```

#### Example Help Output
```
usage: kumoCmd.js room <room> mode ( off | heat | cool | dry )
kumoCmd.js room <room> fan ( quiet | low | powerful )
kumoCmd.js room <room> vent [ auto | horizontal | midhorizontal | midpoint | midvertical | vertical | swing ]
Expand All @@ -104,92 +127,142 @@ usage: kumoCmd.js room <room> mode ( off | heat | cool | dry )
kumoCmd.js show [config]
```

### To see the configuration file i.e. all the rooms and address
### View the Configuration
This command displays all of the rooms (units, or zones) and the IP addresses of configured units. Run the following command:
```
> npm run cmd show config
```

#### Example Configuration Output
```
Account Address Label
Acc:[email protected] address:192.168.2.20 label:Master Bedroom
Acc:[email protected] address:192.168.2.21 label:Kids Room
Acc:[email protected] address:192.168.2.22 label:Guest Room
```

### Get the status of one of the air con
### Get the status of an air conditioner unit
This command gets the current state of a specific air conditioner unit. Run the following command:
```
> npm run cmd room 'Guest Room' status
```
Output is returned in JSON format.

#### Example Status Output
```
Status: {"r":{"indoorUnit":{"status":{"roomTemp":19.5,"mode":"off","spCool":25.5,
"spHeat":22.5,"vaneDir":"vertical","fanSpeed":"quiet","tempSource":"unset","activeThermistor":"unset",
"filterDirty":false,"hotAdjust":false,"defrost":false,"standby":false,"runTest":0}}}}
```

### Turn on one of the air conditioner to cool
### Turn on an air conditioner and set to cool
```
> npm run cmd room 'Guest Room' mode cool
```

#### Example Result
```
{"r":{"indoorUnit":{"status":{"mode":"off"}}}}
```

### to change the fan speed in the guest room
### Change fan speed in Guest Room
```
> npm run cmd room 'Guest Room' fan powerful

```

### Turn off the air conditioner to cool in Guest room
### Turn off the air conditioner in Guest Room
```
> npm run cmd room 'Guest Room' mode off
```

## Usages when running as an API server
---------
Start the server
## Use as a REST Server

When you run kumojs as a server, you can send it commands from any device on your network using HTTP REST requests.

### Start the Server
Start the server with the following command:
```
> npm run server
```

#### Example Result
```
App is running on port: 8084
```

### Get a list of rooms
```
> curl http://127.0.0.1:8084/v0/rooms
```

```
> curl http://127.0.0.1:8084/v0/rooms
["Guest Room","Master Bedroom","Kids Room"]
```
#### Example Result
```
["Guest Room","Master Bedroom","Kids Room"]
```

### Get the status of Guest Room
```
> curl http://127.0.0.1:8084/v0/room/Guest%20Room/status
```

#### Example Result
```
{"r":{"indoorUnit":{"status":{"roomTemp":23.333334,"mode":"off","spCool":25.5,"spHeat":22.5,
"vaneDir":"horizontal","fanSpeed":"powerful","tempSource":"unset","activeThermistor":"unset",
"filterDirty":false,"hotAdjust":false,"defrost":false,"standby":false,"runTest":0}}}}
```

### Start the guest room Aircon in cooling mode
### Start the Guest Room air conditioner in cooling mode
```
> curl -XPUT http://127.0.0.1:8084/v0/room/Guest%20Room/mode/cool
```

#### Example Result
```
{"r":{"indoorUnit":{"status":{"mode":"off"}}}}
```

### Change the fan speed
```
> curl -XPUT http://127.0.0.1:8084/v0/room/Guest%20Room/speed/powerful
{"r":{"indoorUnit":{"status":{"fanSpeed":"powerful"}}}}
```

### Change the vent setting
```
curl -XPUT http://127.0.0.1:8084/v0/room/Guest%20Room/vent/swing
{"r":{"indoorUnit":{"status":{"vaneDir":"horizontal"}}}}
```

### change the temperature for cooling
```
> curl -XPUT http://127.0.0.1:8084/v0/room/Guest%20Room/cool/temp/68
{"r":{"indoorUnit":{"status":{"spCool":20}}}}
```

### change the temperature for heating
```
> curl -XPUT http://127.0.0.1:8084/v0/room/Guest%20Room/heat/temp/68
{"r":{"indoorUnit":{"status":{"spHeat":20}}}}
```


## TODO
```
> curl -XPUT http://127.0.0.1:8084/v0/room/Guest%20Room/speed/powerful
```

#### Example Result
```
{"r":{"indoorUnit":{"status":{"fanSpeed":"powerful"}}}}
```

### Change the Vent Setting
The vents or vanes control the direction of air flowing out of the air conditioner unit. To change the vent mode:
```
curl -XPUT http://127.0.0.1:8084/v0/room/Guest%20Room/vent/swing
```

#### Example Result
```
{"r":{"indoorUnit":{"status":{"vaneDir":"horizontal"}}}}
```

### Change the set temperature for cooling
```
> curl -XPUT http://127.0.0.1:8084/v0/room/Guest%20Room/cool/temp/68
```

#### Example Result
```
{"r":{"indoorUnit":{"status":{"spCool":20}}}}
```

### Change the set temperature for heating
```
> curl -XPUT http://127.0.0.1:8084/v0/room/Guest%20Room/heat/temp/68
```

#### Example Result
```
{"r":{"indoorUnit":{"status":{"spHeat":20}}}}
```

# TODO
A list of remaining tasks to do in this project. Updating this list is the first item. ;-)