Skip to content

Commit

Permalink
Add readme
Browse files Browse the repository at this point in the history
  • Loading branch information
hirschmann committed Sep 11, 2019
1 parent 22c3b7c commit eada6bb
Show file tree
Hide file tree
Showing 10 changed files with 159 additions and 0 deletions.
159 changes: 159 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,159 @@
# Power Event Provider

Power Event Provider is a Windows service which posts power events such as power scheme changes, battery status changes, display state changes, etc. into the Windows event log.
Besides for monitoring purposes, these events can also be used as triggers for the Windows task scheduler. This makes it possible to run any application or script when a power event occurs.

## Available events

Power Event Provider supports 5 groups of events. Not all events are supported on each and every system.

### Power schemes

Event | ID
-------------------------------------------------------|---------
Power scheme personality changed: **Power saver** | 1000
Power scheme personality changed: **Automatic** | 1001
Power scheme personality changed: **High performance** | 1002

### Power line status

Event | ID
-------------------------------------------------------|---------
Power line status changed: **AC power source** | 2000
Power line status changed: **Battery** | 2001
Power line status changed: **UPS power source** | 2002
Power line status changed: **Out of range** | 2003

### Notebook lid state

Event | ID
-------------------------------------------------------|---------
Notebook lid state changed: **Closed** | 3000
Notebook lid state changed: **Open** | 3001

### Battery percentage

Event | ID
-------------------------------------------------------|---------
Remaining battery percentage changed: **1%** | 4*001*
Remaining battery percentage changed: **2%** | 4*002*
...|...
Remaining battery percentage changed: **99%** | 4*099*
Remaining battery percentage changed: **100%** | 4*100*

:bulb: Battery percentage events are disabled by default to avoid spamming the event log.

### Display state

Event | ID
-------------------------------------------------------|---------
Display state changed: **Off** | 5000
Display state changed: **On** | 5001
Display state changed: **Dimmed** | 5002

## Download

You can download the PowerEventProvider setup from github: [link (github)](https://github.com/hirschmann/powereventprovider/releases)

## Configuration

You can enable/disable monitoring of event groups by editing the *PowerEventProvider.exe.config* file in the PowerEventProvider installation directory.
Just set event groups which should show in the event log to **True**.

After changing the config file, the *PowerEventProvider* service must be restarted (e.g. via Windows task manager or *services.msc*) in order for the changes to take effect.

The default configuration looks like this:

```xml
<?xml version="1.0"?>
<configuration>
<configSections>
<sectionGroup name="applicationSettings" type="System.Configuration.ApplicationSettingsGroup, System, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" >
<section name="PowerEventProviderService.Properties.Settings" type="System.Configuration.ClientSettingsSection, System, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" requirePermission="false" />
</sectionGroup>
</configSections>
<startup>
<supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.0,Profile=Client"/>
</startup>
<applicationSettings>
<PowerEventProviderService.Properties.Settings>
<setting name="MonitorBatteryPercentage" serializeAs="String">
<value>False</value>
</setting>
<setting name="MonitorDisplayState" serializeAs="String">
<value>True</value>
</setting>
<setting name="MonitorLidswitchState" serializeAs="String">
<value>True</value>
</setting>
<setting name="MonitorPowerSchemePersonality" serializeAs="String">
<value>True</value>
</setting>
<setting name="MonitorPowerSource" serializeAs="String">
<value>True</value>
</setting>
</PowerEventProviderService.Properties.Settings>
</applicationSettings>
</configuration>
```

## Viewing power events in the event log

### Powershell

You can list all PowerEventProvider event log entries by entering the following line in powershell:

```powershell
get-eventlog -logname Application -source PowerEventProvider
```

### Event Viewer

If you prefer GUI over command line, you can create a custom view for PowerEventProvider related events in the Windows Event Viewer.

Open the Windows event log (*eventvwr.msc*) and create a custom view:

![Create a custom view](images/event-viewer-create-view.png)

Select a log (*Application*) and a source (*PowerEventProvider*) to view:

![Select a log](images/event-viewer-select-source.png)

Open your custom view:

![Open the custom view](images/event-viewer.png)

## Using events as scheduled task triggers

Since PowerEventProvider was created as a companion application for [NoteBook FanControl (NBFC)](https://github.com/hirschmann/nbfc), this example shows how to switch NBFC profiles when a notebook's power source changes.

Open the Windows task scheduler (*taskschd.msc*):

![Create a task](images/task-create.png)

Give the task a name and select the user account which should be used to run the task:

![Task - general settings](images/task-general.png)

Create a new trigger and select "Begin the task: On an event". Then select a log (*Application*) and a event source (*PowerEventProvider*).
To run the task as soon as the notebook's power source switches to "battery", set the *Event ID* to *2001*:

![Task - trigger](images/task-trigger.png)

Create a new action and select "Start a program". Then put in the path to the NBFC command line interface as program to run: `"C:\Program Files (x86)\NoteBook FanControl\nbfc.exe"`

Finally, set `config --apply "<some config name>"` as arguments. In this case I wanted the fan to be more silent when the notebook is not in it's docking station, so the argument was `config --apply "HP ProBook 6465b silent"`.

![Task - action](images/task-action.png)

At last - in this case - it's important to untick all conditions, because the task should run immediately when the power source changes without any delays.

![Task - action](images/task-conditions.png)

The task settings can be left at default values:

![Task - action](images/task-settings.png)

After completing these steps, you can test if everything is working properly by unplugging your notebook. NBFC should switch to the profile you have defined in the task.

To make NBFC switch back to the default profile when you plug in your notebook, just create a second task which is triggered by event ID 2000 (instead of 2001) and sets the default configuration for your notebook (in my case: `config --apply "HP ProBook 6465b"`).
Binary file added images/event-viewer-create-view.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/event-viewer-select-source.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/event-viewer.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/task-action.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/task-conditions.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/task-create.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/task-general.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/task-settings.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/task-trigger.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit eada6bb

Please sign in to comment.