Keybow Companion

A portable Flutter Windows utility for Keybow 2040 macropad automation.

Features

• No Admin Required: Runs as a standalone portable executable
• System Tray: Minimizes to tray with status indicator
• Global Hotkeys: Listens for hotkeys even when not in focus
• PowerShell Integration: Execute scripts with automatic policy bypass
• Macro Logging: Visual log of triggered macros

Project Structure

lib/
├── main.dart                    # App entry point, macro registration, UI
└── services/
    ├── services.dart            # Barrel export
    ├── hotkey_service.dart      # Global hotkey registration & management
    ├── tray_service.dart        # System tray & window management
    ├── powershell_executor.dart # PowerShell script execution helper
    └── macro_log_provider.dart  # State management for macro log

Setup

1. Install dependencies:

   flutter pub get

2. Add a tray icon: Place your icon file at assets/icons/app_icon.ico (Windows) or app_icon.png (other platforms).

   You can create a simple .ico file or use a tool like ConvertICO.

3. Run the app:

   flutter run -d windows

Adding Macros

Open lib/main.dart and find the _registerMacros() function. Add your macros like this:

await hotkeyService.registerMacro(
  id: 'my_macro',
  name: 'My Macro',
  description: 'Does something useful',
  hotKey: HotkeyService.createFunctionMacroKey(16), // Ctrl+Alt+Shift+F16
  action: () async {
    // Your logic here
    await PowerShellExecutor.execute('Your-PowerShell-Command');
  },
);

Hotkey Helpers

// Ctrl+Alt+Shift+F1 through F24
HotkeyService.createFunctionMacroKey(15)  // F15

// Ctrl+Alt+[key]
HotkeyService.createCtrlAltKey(LogicalKeyboardKey.keyM)

// Custom combination
HotKey(
  key: LogicalKeyboardKey.keyK,
  modifiers: [HotKeyModifier.control, HotKeyModifier.shift],
)

PowerShell Execution

The PowerShellExecutor handles:

• -ExecutionPolicy Bypass (no admin needed)
• -WindowStyle Hidden (no console flash)
• -NoProfile (faster startup)

Examples

// Simple command
final result = await PowerShellExecutor.execute('Get-Date');
print(result.stdout);

// Run a script file
await PowerShellExecutor.executeFile(r'C:\Scripts\myscript.ps1');

// Send keystrokes to active window
await PowerShellExecutor.sendKeys('{F5}');

// Activate a window by process name
await PowerShellExecutor.activateWindow('mstsc');  // Remote Desktop

Building for Distribution

flutter build windows --release

The portable executable will be at: build\windows\x64\runner\Release\keybow.exe

Copy the entire Release folder for distribution.

Tray Icon

You need to provide a .ico file for Windows at assets/icons/app_icon.ico.

Quick Placeholder (PowerShell)

If you don't have an icon, create a simple placeholder:

1. Create any 256x256 PNG
2. Convert to ICO using an online converter

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Open Source

This project is open source software, freely available for anyone to use, modify, and distribute under the MIT License.