205 lines
5.3 KiB
Markdown
205 lines
5.3 KiB
Markdown
# Portable Caffeine (PowerShell 5.1 + Embedded C#)
|
|
|
|
Portable Windows implementation of the Zhorn Software Caffeine utility, built as a single `caffeine.ps1` script with embedded C# (`WinForms` + Win32 API calls).
|
|
|
|
## What It Does
|
|
|
|
Prevents sleep/idle by either:
|
|
|
|
- Sending periodic key pulses (default `F15`)
|
|
- Using `SetThreadExecutionState` (`-stes`)
|
|
|
|
It also includes a tray icon app, status dialog, timers, rule-based activation, and single-instance app control commands.
|
|
|
|
## Files
|
|
|
|
- `caffeine.ps1`: main portable app
|
|
- `run-caffeine.bat`: launcher that runs with `-ExecutionPolicy Bypass -STA`
|
|
- `build-caffeine-exe.ps1`: extracts embedded C# and compiles a standalone `.exe`
|
|
- `sign-caffeine-exe.ps1`: creates/reuses a self-signed code-signing cert, optionally trusts it, and signs the `.exe`
|
|
|
|
## Requirements
|
|
|
|
- Windows
|
|
- Windows PowerShell 5.1
|
|
- Desktop session (uses `System.Windows.Forms` + tray icon)
|
|
|
|
## Quick Start
|
|
|
|
Run with the batch launcher:
|
|
|
|
```bat
|
|
run-caffeine.bat -showdlg -notify
|
|
```
|
|
|
|
Or directly:
|
|
|
|
```powershell
|
|
powershell.exe -NoProfile -ExecutionPolicy Bypass -STA -File .\caffeine.ps1 -showdlg -notify
|
|
```
|
|
|
|
## Execution Policy Note
|
|
|
|
If PowerShell blocks script execution, use the launcher (`run-caffeine.bat`) or run:
|
|
|
|
```powershell
|
|
powershell.exe -NoProfile -ExecutionPolicy Bypass -STA -File .\caffeine.ps1
|
|
```
|
|
|
|
Optional:
|
|
|
|
```powershell
|
|
Unblock-File .\caffeine.ps1
|
|
```
|
|
|
|
## Supported Features / Switches
|
|
|
|
Core:
|
|
|
|
- `-on` / `-off`
|
|
- `-activefor:N`
|
|
- `-inactivefor:N`
|
|
- `-exitafter:N`
|
|
- `-lock`
|
|
- `-notify`
|
|
- `-showdlg`
|
|
- `-ontaskbar`
|
|
- `-replace`
|
|
|
|
Single-instance app commands:
|
|
|
|
- `-appexit`
|
|
- `-appon`
|
|
- `-appoff`
|
|
- `-apptoggle`
|
|
- `-apptoggleshowdlg`
|
|
|
|
Activity methods:
|
|
|
|
- Default F15 key pulse
|
|
- `-useshift`
|
|
- `-leftshift`
|
|
- `-key:NN` / `-keypress:NN`
|
|
- `-keyshift[:NN]`
|
|
- `-stes`
|
|
- `-allowss`
|
|
|
|
Conditional activation:
|
|
|
|
- `-watchwindow:TEXT`
|
|
- `-activeperiods:RANGES`
|
|
- `-activehours:RANGES` (alias)
|
|
- `-onac`
|
|
- `-cpu:N`
|
|
|
|
Tray / icon behavior:
|
|
|
|
- Custom coffee-cup tray icon (active/inactive variants)
|
|
- `-nohicon` keeps the same tray icon in both states
|
|
- Double-click tray icon toggles active/inactive
|
|
|
|
Compatibility:
|
|
|
|
- `-allowlocal` is recognized (compatibility flag)
|
|
|
|
## Examples
|
|
|
|
```bat
|
|
run-caffeine.bat -showdlg -notify
|
|
run-caffeine.bat -activefor:30
|
|
run-caffeine.bat -watchwindow:Notepad -on
|
|
run-caffeine.bat -activeperiods:08:00-12:00,13:00-17:00
|
|
run-caffeine.bat -stes -allowss
|
|
run-caffeine.bat -apptoggle
|
|
run-caffeine.bat -replace -off
|
|
```
|
|
|
|
## Compile To EXE (Windows)
|
|
|
|
You can build a standalone executable from the embedded C# code in `caffeine.ps1`:
|
|
|
|
```powershell
|
|
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\build-caffeine-exe.ps1
|
|
```
|
|
|
|
Output (default):
|
|
|
|
- `dist\PortableCaffeine.exe`
|
|
|
|
Useful options:
|
|
|
|
```powershell
|
|
# Keep the extracted .cs file used for compilation
|
|
.\build-caffeine-exe.ps1 -KeepExtractedSource
|
|
|
|
# Build a console-targeted EXE instead of WinExe
|
|
.\build-caffeine-exe.ps1 -ConsoleTarget
|
|
|
|
# Custom output name/path
|
|
.\build-caffeine-exe.ps1 -OutputDir .\out -ExeName Caffeine.exe
|
|
```
|
|
|
|
Notes:
|
|
|
|
- The build script looks for `.NET Framework` `csc.exe` on Windows (Framework64 first, then Framework).
|
|
- The compiled EXE uses the same tray UI, switches, and behavior as the PowerShell-hosted version.
|
|
|
|
## Self-Signed Code Signing (Dev/Test)
|
|
|
|
You can sign the compiled EXE with a locally generated self-signed code-signing certificate.
|
|
|
|
Default behavior:
|
|
|
|
- Reuses an existing cert matching the configured subject (if present)
|
|
- Otherwise creates a new self-signed code-signing cert
|
|
- Exports the public cert to `dist\PortableCaffeine-dev-signing.cer`
|
|
- Installs trust in `CurrentUser\Root` and `CurrentUser\TrustedPublisher`
|
|
- Signs `dist\PortableCaffeine.exe` with `Set-AuthenticodeSignature`
|
|
|
|
Command:
|
|
|
|
```powershell
|
|
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\sign-caffeine-exe.ps1
|
|
```
|
|
|
|
Machine-wide trust (all users, requires admin):
|
|
|
|
```powershell
|
|
# Run PowerShell as Administrator
|
|
.\sign-caffeine-exe.ps1 -TrustScope LocalMachine
|
|
```
|
|
|
|
Notes on admin requirements:
|
|
|
|
- `CurrentUser` trust/store operations do not require admin.
|
|
- `LocalMachine` trust (`Root` / `TrustedPublisher`) requires an elevated PowerShell session.
|
|
- Creating the private key in `LocalMachine\My` also requires admin (`-PrivateKeyStoreScope LocalMachine`).
|
|
|
|
Useful options:
|
|
|
|
```powershell
|
|
# Force creation of a new self-signed certificate instead of reusing an existing one
|
|
.\sign-caffeine-exe.ps1 -ForceNewCertificate
|
|
|
|
# Sign without installing trust stores (signature will be present but likely untrusted)
|
|
.\sign-caffeine-exe.ps1 -TrustScope None
|
|
|
|
# Export a PFX (password required)
|
|
.\sign-caffeine-exe.ps1 -PfxExportPath .\dist\PortableCaffeine-dev-signing.pfx -PfxPassword (Read-Host -AsSecureString)
|
|
|
|
# Use a timestamp server (optional)
|
|
.\sign-caffeine-exe.ps1 -TimestampServer http://timestamp.digicert.com
|
|
```
|
|
|
|
Security note:
|
|
|
|
- Trusting a self-signed certificate in `Root` makes your machine trust anything signed by that certificate.
|
|
- Use a dedicated dev/test certificate, protect the private key, and remove trust when no longer needed.
|
|
- This is suitable for local/internal testing, not a substitute for a public CA-issued code-signing certificate.
|
|
|
|
## Notes
|
|
|
|
- This project is intended to be portable (no install required).
|
|
- The implementation targets Windows PowerShell 5.1 and Windows desktop APIs.
|
|
- Exact visual/behavioral parity with the original Zhorn Caffeine may differ slightly in some edge cases.
|