unix-remotecontrol

Unix Remote Control (IOT)

Runs Scripts on Mac/Linux remotely.

Why :

I was setting up homebridge (iOS HomeKit Accesory Protocol) on my rasberryPi and after hooking up my IR Blaster, RF Transmitter and other wake-on-lan devices. I wanted my always-on OSX Laptop to also be remotely controlled by my iOS Device. So i ended up writing up a small plugin for Homebridge plugin.

I use this to play itunes, search google and bookmark search results, restart my system, get room temperature using MBP in-build Temp Sensor and adjust airconditioning accordingly, monitor my ec-2 instance stats, sync Spotify Playlist etc.

Homebridge Plugin => homebridge-unixcontrol

How it Works :

This library is directly injected into homebridge with a plugin wrapper => homebridge-unixcontrol

The plugin queries the system using HTTP API and run shell scripts. The shell requires sudo access to shutdown/reboot the system. More commands can be easily be injected. Feel free to PR.

You can ask Siri to execute commands :

Hey Siri, Shutdown my laptop

Hey Siri, play iTunes Playlist

Hey Siri, Good Morning ! // Plays Music, Backups OSX, Search for Google Alerts, Turns Off Air Conditioner

Hey Siri, Capture Laptop Webcam

Hey Siri, Who's using my laptop

Todo :

• Add Linux Support
• Add Windows Support
• Refactor With Promises
• Replace HTTP API with socket connection.
• Implement a working Example
• Security Concerns

Installation :

 $ npm install -g unix-remotecontrol

Starting Server :

 $ unixremote

Running Forever

 $ npm install -g forever
 $ git clone https://github.com/sahilchaddha/unix-remoteControl.git && cd unix-remoteControl
 $ forever start src/server.js

Configuration :

Configuration containing sudo password, port number, logLevel & sessionToken are stored in environment.js in root/src.

To Open Configuration for global module :

 $ unixremote --config

Sample Configuration :

//environment.js
var env = {
    port: '3000',
    pass: 'lol', //sudo password TODO: Secure
    logLevel: 'info',
    sessionToken: 'f64f2940-fae4-11e7-8c5f-ef356f279131'
}

module.exports = env

Config Parameters

Fields	Description
port	Port Number to run HTTP Server.
pass	System Sudo Password
logLevel	Log Level (debug, info, error)
sessionToken	Random Session Token for API Authentication.

NOTE: sessionToken needs to be set as Request Header token

Usage :

After Running the server, You can request

localhost:portNumber/commandType/command

e.g.

POST localhost:3000/power/shutdown
    {
        "time": 10
    }

curl --header "token: f64f2940-fae4-11e7-8c5f-ef356f27913" -X POST localhost:3000/power/logout

curl --header "token: f64f2940-fae4-11e7-8c5f-ef356f27913" "Content-Type: application/json" -X POST -d '{"time":10}' localhost:3000/power/restart 

curl --header "token: f64f2940-fae4-11e7-8c5f-ef356f27913" "Content-Type: application/json" -X POST -d '{"destination":"AppleMusic"}' localhost:3000/music/syncSpotify

Sample Scripts/Commands :

Power Command Type

Usage:-

localhost:3000/power/displaySleep

POST localhost:3000/power/restart
    {
        "time": 10
    }

Command	Method	Description	Params	Sudo
/ping	GET	Pings to get server state (on/off)	None	false
/halt	POST	Shutdowns immediately & forcibly (Can cause data loss)	None	true
/shutdown	POST	Shut downs the system	time (minutes) : Delays Shutdown in minutes	true
/restart	POST	Restarts the system	time (minutes) : Delays Shutdown in minutes	true
/logout	POST	Logs Out the user (OSX Only)	None	false
/sleep	POST	Turns the System to Sleep	None	false
/displaySleep	POST	Turns the Display to Sleep	None	false
/cancelShutdown	POST	Cancels Scheduled Shutdown/Restart Task	None	true

System Stats Command Type

Usage:-

localhost:3000/systemStats/temperature

localhost:3000/systemStats/ram

Command	Method	Description	Params	Sudo
/temperature	GET	Returns current Temperature of CPU	None	false
/cpuLoad	GET	Returns current CPU Load	None	false
/ram	GET	Returns current Ram Status	None	false
/storage	GET	Returns current Storage Stats	None	false
/battery	GET	Returns current Battery Information	None	false

Browser Command Type

Usage:-

localhost:3000/browser/googleChromeReset

Command	Method	Description	Params	Sudo
/googleChromeReset	POST	Clear all data of google chrome and reset	None	false
/safariClearHistory	POST	Clear histroy of safari	None	false

NOTE: For safariClearHistory you will have to add terminal or whatever command line tool you are using should be added in System Preferences -> Security & Privacy -> Privacy -> Accessibility. When you run this command for the first time there will a prompt to add command line tool in Accessibility.

Wi-fi Command Type

Usage:-

localhost:3000/wifi/on

Command	Method	Description	Params	Sudo
/status	GET	Returns Wifi Enabled/Disabled Status (OS X Only)	None	false
/on	POST	Turn on wifi (OS X Only)	None	false
/off	POST	Turn off wifi (OS X Only)	None	false
/connect	POST	Connect to wifi (OS X Only)	name: wifi name, password: wifi password	false

Bluetooth Command Type

Usage:-

localhost:3000/bluetooth/status

Command	Method	Description	Params	Sudo
/status	GET	Returns Bluetooth Enabled/Disabled Status (OS X Only)	None	false
/on	POST	Turn on Bluetooth (OS X Only)	None	false
/off	POST	Turn off Bluetooth (OS X Only)	None	false
/showPairingAlert	POST	Show pairing alert or pair with any BLE enabled device (OS X Only)	deviceName: Bluetooth name of device with percentage encoding	false
/toggle	POST	Toggle device bluetooth connection (OS X Only)	deviceName: Bluetooth name of device with percentage encoding	false

NOTE: blueutil is added as a depedancy for Bluetooth Connections. It will be automatically installed during npm install. Its added as postInstall Script in package.json. If for some reason installation of blueutil fails, you can manually install blueutil brew install blueutil

System Spy Command Type

Usage:-

localhost:3000/systemSpy/screenshot

localhost:3000/systemSpy/camRecord

localhost:3000/systemSpy/alert
    {
        "message": "Heeeyyy !!! Hooooo !!!"
    }

localhost:3000/systemSpy/notify
    {
        "title": "heyyy",
        "message": "hooo"
    }

Command	Method	Description	Params	Sudo
/screenshot	POST	Screenshots Current Screen, Saves & returns image (OSX Only)	None	false
/webcamCapture	POST	Clicks Camera Still, Saves & returns image (OSX Only)	None	false
/screenRecord	POST	Starts Screen Recording (OSX Only)	time (In Minutes): Start recording for specific time. Here time is optional if you want to run this command forever than do not pass any arguments	false
/camRecord	POST	Starts Camera Recording (OSX Only)	time (In Minutes): Start recording for specific time. Here time is optional if you want to run this command forever than do not pass any arguments	false
/alert	POST	Shows Alert to User	message: Message to Show Alert	false
/notify	POST	Shows Notification to User	title: Title For Notification, message: Message	false
/isRecording	GET	Returns Recording Status (OSX Only)	type : screen or cam type of recording	false

Music Command Type

Usage:-

localhost:3000/music/itunesPlaylist

localhost:3000/music/setVolume
    {
        "volume": 10
    }

Command	Method	Description	Params	Sudo
/youtubePlaylist	POST	Opens Youtube & Starts Playing Playlist defined in environment.js (OSX Only)	None	false
/itunesPlaylist	POST	Opens iTunes & Starts Playing Playlist defined in environment.js (OSX Only)	None	false
/setVolume	POST	Sets New Volume (OSX Only)	volume: volume to be set. Should be between 0 to 10	false
/getVolume	GET	Returns Current Volume (OSX Only)	None	false
/mute	POST	Mutes the System (OSX Only)	None	false
/unmute	POST	UnMutes the System (OSX Only)	None	false
/isMuted	GET	Returns Mute Status (OSX Only)	None	false

Todo Scripts :

• Remote System Backup
• Remote System Format (Need extra OSX Device to test. :P )

Writing Custom Scripts :

Cloning the Repo :

 $ git clone https://github.com/sahilchaddha/unix-remoteControl.git && cd unix-remoteControl
 $ node src/server.js
 or
 $ npm start

Creating Your Router :

You can create your custom router inside Routes folder.

//DummyRouter.js
var router = require('express').Router() // Create New Router
var commandService = require('../Services/CommandService.js')

router.get('/hello', function (req, res) {
  res.send('Hello')
  // Run Your npm commands
  // or call Shell Scripts using Command Service

    commandService.execute('dummy', 'sayHello', options, function(){})
})

module.exports = router

Adding your Router to Valid Routes :

Add your custom router inside routes.js

var powerRouter = require('./Routes/PowerRouter.js')
var dummyRouter = require('./Routes/DummyRouter.js')

var routes = [
    {
        url: '/power',
        routerClass: powerRouter
    },
    {
        url: '/dummy',
        routerClass: dummyRouter
    }
]

module.exports = routes

Adding Your Shell Scripts :

You can use Command Service to execute commands :

To add Commands, you can inject your commands inside Commands/commands.js

var dummyCommands = {
    sayHello: {
        command: ['say', 'hello'],
        sudo: false // Set as true if command need sudo access
    }
}

module.exports = {
    // power: powerCommands,
    dummy: dummyCommands
}

Apple Scripts

Apple scripts in format .scpt are to be injected inside AppleScripts folder.

You can add command inside commands.js

var dummyCommands = {
    sayHello: {
        command: ['say', 'hello'],
        sudo: false // Set as true if command need sudo access
    },
    runAppleScript: {
        command: ['osascript', 'src/Commands/AppleScripts/dummyAS.scpt'],
        sudo: false
    }
}

module.exports = {
    // power: powerCommands,
    dummy: dummyCommands
}

Homebridge on Raspberry Pi :

Homebridge Configuration :

WIP

On Pi :

$ ssh pi@192.168.1.2 // Your Pi Local Address
$ npm install -g homebridge
$ npm install -g homebridge-unixcontrol

// Configure Homebridge config.json

On Unix System (For Remote Access) :

$ npm install -g unix-remotecontrol
$ unixremote --config //Setup Your Configuration
$ unixremote

Credits :

Sahil Chaddha ([e-mail])

Sumit Chudasama ([e-mail])

Reference :

• HashinKit

• BlueUtil