Write a "definitive usage guide"

[AlexGustafsson]

A lot of issues have been posted about similar topics, such as SSH usage, devices not responding to pings, etc. My initial hope was that the documentation available in the README, along with other sources of help would suffice. It has become apparent, however, that what is lacking is a guide / step-by-step how to configure the plugin in common environments and more importantly, how to effectively troubleshoot the setup.

There's a lot of helpful information hidden in issues, discussions and as a wiki post. By combining all of this information and by adding to it, we should be able to provide a meaningful document for using the plugin.

[AlexGustafsson]

Any help on this topic is helpful. The idea is to document various setups in an isolated fashion so that the user may chose what parts to use. For example, setting up an SSH shutdown command could be a topic. I appreciate all and any help on this issue. For example, one can work on documenting how to setup a ping command for macOS, how to troubleshoot pings not working etc.

[UnbendableStraw]

Here's how I'm using it; I have Homebridge running on a Hyper-V vm, and various windows PCs with various software running on them that I'd like to know whether it's running, as well as start and stop it.

To start, I run miners on my and my wife's PC when we're not using them. There's a few things that need done when starting or stopping mining like setting the gpu settings and restarting the gpu driver before running the actual miner. I've gotten all of these steps down to a start.bat and stop.bat on each local miner.

I enabled the OpenSSH-Server feature for Windows 10 on each miner, started the OpenSSH service, and used the Homebridge-UI terminal to test that I can ssh into the desired windows miners and execute the batch file with a simple command like sshpass -p 'password' ssh [email protected] -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no 'cmd.exe /c C:\Users\wifey\Desktop\start.bat'

Now that I have a way of talking to windows from homebridge, I created switches using the plugin for each windows miner like so;

       {
            "name": "Nic Miner",
            "ip": "192.168.1.241",
            "mac": "MAC:ADDRESS",
            "host": "192.168.1.241",
            "pingInterval": 2,
            "pingsToChange": 5,
            "pingTimeout": 1,
            "pingCommand": "nc -vz 192.168.1.241 4028 2>&1 | grep -i 'open'",
            "pingCommandTimeout": 3,
            "startCommandTimeout": 5,
            "wakeGraceTime": 1,
            "wakeCommandTimeout": 5,
            "wakeCommand": "sshpass -p 'password' ssh [email protected] -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no 'cmd.exe /c C:\\Users\\UnbendableStraw\\Desktop\\start.bat'",
            "shutdownGraceTime": 1,
            "shutdownCommandTimeout": 5,
            "shutdownCommand": "sshpass -p 'password' ssh [email protected] -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no 'cmd.exe /c C:\\Users\\UnbendableStraw\\Desktop\\stop.bat'",
            "log": true,
            "logPinger": false,
            "debugLog": false,
            "returnEarly": true,
            "accessory": "NetworkDevice"
        },
        {
            "name": "Wifey Miner",
            "ip": "192.168.1.148",
            "mac": "MAC:ADDRESS",
            "host": "192.168.1.148",
            "pingInterval": 2,
            "pingsToChange": 5,
            "pingTimeout": 1,
            "pingCommand": "nc -vz 192.168.1.148 4028 2>&1 | grep -i 'open'",
            "pingCommandTimeout": 3,
            "startCommandTimeout": 5,
            "wakeGraceTime": 1,
            "wakeCommandTimeout": 5,
            "wakeCommand": "sshpass -p 'password' ssh [email protected] -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no 'cmd.exe /c C:\\Users\\wifey\\Desktop\\start.bat'",
            "shutdownGraceTime": 1,
            "shutdownCommandTimeout": 5,
            "shutdownCommand": "sshpass -p 'password' ssh [email protected] -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no 'cmd.exe /c C:\\Users\\wifey\\Desktop\\stop.bat'",
            "log": true,
            "logPinger": false,
            "debugLog": false,
            "returnEarly": true,
            "accessory": "NetworkDevice"
        }

Explanation of some of my settings:

"pingCommand": "nc -vz 192.168.1.241 4028 2>&1 | grep -i 'open'", ping the specific port the mining software uses so the switch status reflect the status of the miner

wakeCommand and shutdownCommand - I'm using the wake command for the time being instead of startCommand because I'm probably using it wrong and that didn't work as expected (errors out, see the issue Alex mentioned)

sshpass - this is temporary until I can get ssh keys working between homebridge and windows.

Example start.bat on the windows miner:

# forcefully set the amd driver mode to "Compute" which gives a much higher hashrate for mining
REG ADD "HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Class\{4d36e968-e325-11ce-bfc1-08002be10318}\0001" /v "KMD_EnableInternalLargePage" /t REG_DWORD /d 2 /f
# set the gpu overclock settings via cmdline tool
C:\Users\UnbendableStraw\Desktop\OverdriveNTool.exe -p00
# cmdline restart the gpu driver so the compute mode change takes effect, restarting the gpu driver after using the system for some time also gives better mining results as opposed to rebooting the whole machine
C:\Users\UnbendableStraw\Desktop\restart64.exe /q
# it takes about 8 seconds for the gpu driver to fully restart, so wait 10 seconds before starting the miner
SLEEP 10
# run the miner. also `>NUL` at the end to not output the miner's console in the homebridge console lol
C:\Users\UnbendableStraw\Documents\phoenixminer_5.5c_windows_incl_nvrtc_1\PhoenixMiner_5.5c_Windows\PhoenixMiner.exe  -pool us2.ethermine.org:4444 -wdog 1 -rmode 0 -cdm 2 -cdmport 4028 -wal ETHADDRESS >NUL

And an example of my stop.bat

# kill the miner process
taskkill /IM "PhoenixMiner.exe" /F
# change the gpu driver back to "Gaming" mode to get precious fps back
REG ADD "HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Class\{4d36e968-e325-11ce-bfc1-08002be10318}\0001" /v "KMD_EnableInternalLargePage" /t REG_DWORD /d 0 /f
# set the gpu overclock settings back to stock
C:\Users\UnbendableStraw\Desktop\OverdriveNTool.exe -p0stock
# restart the gpu driver to take Gaming setting into effect
C:\Users\UnbendableStraw\Desktop\restart64.exe /q
# zzz
SLEEP 10

Now with the tap of a button, I can start and stop our miners, and now I know how to set this up for other applications I run that expose network ports I can ping for a status and kill / run on demand from anywhere!

[UnbendableStraw]

woops, accidentally posted in the wrong bug. I have another use case.

I have a few other hyperv vms I'd like to start and stop with this plugin. I'm using my plex vm as an example.

Similar to before, I installed openssh-server on my hyperv server, then added the info to my plugin;

{
    "name": "Plex VM",
    "ip": "192.168.1.172",
    "pingInterval": 10,
    "pingsToChange": 2,
    "pingTimeout": 1,
    "pingCommand": "nc -vz 192.168.1.105 32400 2>&1 | grep -i 'open'",
    "pingCommandTimeout": 1,
    "mac": "MAC:ADDRESS",
    "startCommandTimeout": 2,
    "wakeGraceTime": 1,
    "wakeCommandTimeout": 1,
    "wakeCommand": "sshpass -p 'password' ssh [email protected] -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no 'powershell -Command Start-VM -Name Plex'",
    "shutdownCommand": "sshpass -p 'password' ssh [email protected] -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no 'powershell -Command Stop-VM -Name Plex'",
    "shutdownGraceTime": 5,
    "shutdownCommandTimeout": 2,
    "log": true,
    "logPinger": false,
    "debugLog": false,
    "returnEarly": false,
    "accessory": "NetworkDevice"
}

Explanation:

"ip": "192.168.1.172", - IP of the hyperv host

"pingCommand": "nc -vz 192.168.1.105 32400 2>&1 | grep -i 'open'", - ping the plex port for the switch status. ping the actual plex server ip to reflect correct switch status

wakecommand and shutdowncommand - ssh into the windows hyperv host, then run a powershell command to start or stop the vm.

The only odd behavior is when powering on, the switch will turn on, then back off until the vm actually starts. I think I need some sort of startcommandgracetime or help figuring out the correct timeouts we do have

[AlexGustafsson]

We should also describe usage with docker containers - see #153.

[AlexGustafsson]

We should make sure that we mention the required config on Windows PCs. See #246.