Everything Edgepad does, and how.

It is for the times the laptop is across the room rather than under your hands: plugged into a television, docked on a desk you are not sitting at, parked somewhere a mouse dongle will not reach.

The alternatives are a remote app that only sends media keys, or a remote-desktop app that streams the whole screen and wants an account and a network round trip to change the volume. Edgepad is neither. The phone and the laptop pair once, the way a headset does, and after that they talk directly: no account, no Wi-Fi, no service in between that can be slow or down.

The cost is Bluetooth's own. Both ends need it, and it does not reach another room or the internet.

What it does

Pairing and first connection

1. Pair the phone with the laptop once, in Windows Settings > Bluetooth & devices. Edgepad has no pairing step of its own.
2. Keep Edgepad running in the laptop's tray. It must already be running before the phone tries to connect: there is no discovery or retry on the laptop side.
3. Open Edgepad on the phone and tap the laptop. The first time, the laptop asks Trust this phone?; choose Trust there. That phone becomes the laptop's trusted phone, and any other paired phone is refused until you choose Forget trusted phone in the tray menu.
4. The phone remembers the laptop and reconnects when the app opens. If the link drops after a completed handshake, the phone retries ten times, two seconds apart, and says so. Disconnecting on purpose does not retry.

The control surface

Default three- and four-finger gestures

Swapped from Windows' own defaults on purpose. Every one of these is changed under Settings > Gestures.

The corner dials

A dial is a ruler lying along the screen's edge, bending round the corner along the display's own rounding. The finger slides the ruler under a fixed indicator; clockwise raises the value everywhere, like turning a knob. Sliding past a small slop arms it — there is no hold — the ticks lengthen while armed, and one haptic tick fires per notch that passes. A tap without a slide runs the dial's action instead.

Seven kinds compete for four places: volume, brightness, media scrub, zoom, app switcher, microphone level and refresh rate. A corner may also hold nothing. A dial shows the laptop's real value from STATE frames, and dragging sends absolute SET frames.

Focusing and locking the pad

The middle of the five top buttons is the lock. One tap hides the dials and the media and leaves the trackpad. A second tap inside the double-tap window locks the trackpad instead and puts the dials and the media back, so the phone can sit in a pocket or under a palm and answer only its rulers. Any later tap returns the whole surface. A locked pad keeps the lock button drawn in the full ink, because a surface that silently swallows every touch reads as a crash rather than as a mode.

The mode lives in the view: it is neither stored nor offered as a setting, since a phone that came back up silently locked would read as broken.

Shapes

Press one finger on the trackpad, hold it still until it ticks, then draw without lifting. On lift the stroke is matched against the shapes drawn under Settings > Shapes, and the one it matches runs: a laptop action, a macro slot, or the pad's own focus or lock. A stroke that matches nothing does nothing, which is the right answer — the alternative is the nearest binding firing on a scrawl.

Shape mode will not arm while dragging, and stops the moment a second finger lands, so scroll, pinch and the three- and four-finger swipes are untouched. A phone with no shapes drawn behaves exactly as it did before there were any.

Macro buttons

Fifteen slots, named from the laptop's tray menu. Fifteen is what one frame can name — fifteen names at sixteen bytes with fourteen separators is 254 of the 255 bytes a TEXT frame carries — so a full grid always arrives labelled rather than trailing off into blank buttons. A macro added while the phone is connected appears at once.

The grid is no longer a fixed 5x3. Every cell is as wide as the widest label in it, so no button is a different size from its neighbour, and a row holds as many as the screen actually has room for. The count is capped by what fits rather than by how many slots are filled, so two macros are two ordinary buttons at the left of a full-width row and not two half-screen slabs.

The hub groups its rows by the thing each one configures, not by the kind of editor the row opens. Until 3.0.0 it did the opposite, which is how the keyboard's text size and the macro buttons' appearance both ended up on a page titled Background & pattern — a title that described neither.

The theme is the system's own per-app night mode, set through UiModeManager.setApplicationNightMode, so Edgepad stores no preference of its own for it. Media-piece positions are stored as fractions of the surface's width and height, so a layout made in portrait keeps its shape in landscape.

Orientation is a toggle — upright or sideways — not free rotation, and since 3.0.0 it speaks only for the control surface and the two canvases that stand in for it: the media layout editor, because a media layout has been stored per orientation since 2.3.0 and a phone turned mid-edit would quietly begin changing the other one, and the shape canvas, because a stroke is drawn at the pad's own proportions. The keyboard, the gamepad and the gamepad's editor are sideways and only sideways. Every other screen follows the phone, which is what the setting used to override for the whole app.

Where the laptop keeps things

%APPDATA%\Edgepad\trusted-phone.txt   the trusted phone's Bluetooth address
%LOCALAPPDATA%\Edgepad\edgepad.log    connections, refusals, dropped frames,
                                      and input batches Windows refused

Every touch is turned into a semantic frame on the phone — pointer moved, button pressed, scroll, zoom, run action 3, set control 0 to 55, type “hi” — and the laptop carries it out with the Windows input, audio, display and media APIs. The laptop owns the table of what each action id does. The phone can name an action; it cannot invent one.

The gamepad is the one place where the phone sends state rather than an event, and it is still not a keystroke. A PAD_STATE frame is a snapshot of a whole controller — sixteen button bits, two triggers, four axes — which the laptop copies onto the report of the virtual Xbox pad it has plugged in. The phone is describing a controller, not naming a key, which is exactly why a stick can be analog: eight compass sectors pressing WASD is what it did before, and a half push and a full push were the same key.

The laptop reports back. After the handshake it sends a snapshot of volume, microphone and brightness, then what is playing and where, then the display's available refresh rates and the macro names, and thereafter every change as it happens. The phone keeps the last report in LaptopState, which outlives the control surface, so a surface rebuilt after a rotation or a theme change starts from real values and never shows 0 for a level it has not heard. A level never reported shows an ellipsis, not a zero.

Why Windows gestures are emulated by their results

Windows only runs its native multi-finger gestures for certified Precision Touchpad hardware. Two ways round that were rejected: a virtual PTP driver, which needs a kernel driver and test-signing mode and so weakens the laptop's security, and making the phone a Bluetooth HID touchpad, which needs a PTP certification blob and depends on Android OEM support for BluetoothHidDevice. So Edgepad produces the result instead: Win+Ctrl+Left rather than a finger-following desktop slide. The cost is the animation. Alt+Tab stays interactive because Alt is genuinely held while the fingers are down.

The gamepad's virtual controller is not a counter-example to that. ViGEmBus is a signed driver the user installs deliberately and Edgepad only talks to, where a virtual touchpad would have meant shipping an unsigned driver and asking for test-signing mode. It is also optional: without it the pad sends keys.

758bb618-7b72-4cd3-9aa2-c9b88e54d555

The socket is bound at BluetoothEncryptionWithAuthentication. That means only a device already paired with the laptop can connect at all, and the stream is encrypted by the link layer rather than by anything Edgepad wrote.

What was rejected

The phone's surface

ControlSurface is a single custom View that draws everything and receives every touch. There is no view hierarchy between the finger and the recogniser. Geometry is computed once in onSizeChanged; nothing is allocated while drawing.

Perimeter models the screen's edge as one clockwise path — a rounded rectangle whose corner radius is the display's own, from WindowInsets.getRoundedCorner — so a ruler bends round a corner instead of being clipped by it. A dial's finger position is projected onto that path and its movement measured along it. Perimeter is the single place that says a screen has four corners; three files each used to carry their own copy.

TrackpadRecognizer, Dial, Shapes, PadAxis, PadMode and the gamepad's layout library are pure Kotlin with no Android types. That is what lets the gesture table, the shape matcher, the stick arithmetic, the lock button's transitions and the rules a saved layout obeys all run as plain JVM unit tests with no emulator. The stick arithmetic is there for a specific reason: it used to sit unreachable inside a View's touch handler, so nothing covered touch to output at all.

Matching a shape is a $1-style unistroke: resample to 32 points, centre, scale, compare pointwise. Two departures from $1, both deliberate. The scale is uniform, because $1's per-axis box fit makes a tall I and a round O the same blob; and there is no rotation normalisation, because a C turned around is not a C.

The laptop's virtual controller

VirtualPad wraps ViGEmBus. It copies each PAD_STATE frame onto an Xbox 360 report field for field, because the frame already carries XInput's own layout, and submits one report per frame rather than one per field — auto-submit would push seven half-written reports for every frame, and a game sampling between two of them would read a stick that had moved and a button that had not.

A missing driver is an ordinary state here, never an exception that escapes: a tray app has no dialog to show a crash in, and an escape from the session thread would take the link and everything the phone was holding down with it. Every entry point answers with a PAD_STATUS token instead. Failures are caught by namespace rather than by a list of types, because all seventeen of the library's exceptions derive straight from Exception with no common base, and the one a list missed would be the crash the class exists to prevent. The pad is unplugged in the session's finally beside the input injector, so a phone that disappears mid-game cannot leave a controller plugged in holding a stick.

Why the laptop half is a tray app, not a service

Windows services run in session 0 and can neither inject input into the desktop nor reach the user's audio session. So Edgepad is a per-user tray app that starts at login through the HKCU Run key. It is single-instance, held by a named mutex, and a newer copy signals the running one to quit and waits for the lock rather than killing the process.

On the phone

LaptopLink.open blocks for the life of the connection on its own thread and reads there. A second thread drains the outbox and writes. send never blocks, so touch handling never waits on the link. Every callback into the activity is posted to the main thread. The link is kept across configuration changes through onRetainNonConfigurationInstance with its listener swapped to the new activity. When the app leaves the foreground, anything held down is released at once, but the link is kept for 30 seconds, so a background-image pick or a trip to Bluetooth settings does not drop it; it closes if the app is not back by then.

On the laptop

RfcommServer accepts on WinRT's thread and hands each socket to a Session on a dedicated above-normal-priority thread, where the read loop turns frames straight into input. There is no queue between the socket and SendInput.

A new connection replaces the old one rather than being refused, because after a dropped link the phone reconnects before the laptop's old socket has noticed it is dead. Audio-change notifications arrive on COM threads and brightness events on a WMI thread, so Session.Send is locked and they interleave safely with the read loop's PONGs.

The four things that make it feel immediate

1. Unbuffered touch. View.requestUnbufferedDispatch, with every historical sample read from each MotionEvent, so events arrive as they happen rather than batched to vsync.
2. One write per batch. The writer thread sends everything already queued in a single write.
3. Coalescing. A backlog of MOVE, SCROLL and ZOOM frames still waiting in the outbox is summed into one before it goes out; only the last SET per control survives, and only the newest PAD_STATE, which is a snapshot of the whole controller rather than a change to it. A slow link catches up in a single packet instead of replaying every sample it missed. KEY frames are never collapsed: a press and its release are two messages that happen to name the same key, and dropping either leaves it held on the laptop.
4. Brightness off the hot path. A WMI call is far slower than a frame, so brightness writes go to their own thread with latest-value-wins. Queueing them would make a dial drag lag further behind the finger the longer it moved.

Errors, and what is merely ignored

An unknown type byte, a wrong length, a bad magic or a flag byte other than 0 or 1 is a protocol error and closes the connection. A well-formed frame naming an action, a control or a text kind this side does not know is dropped and counted, never treated as an error. That is what lets a newer app talk to an older one until the version check says otherwise — and why new ids do not need a version bump.

Frames

Golden bytes

Each line of the fixture is a frame's fields and its exact bytes. Both test suites encode the fields and must get exactly those bytes, then decode the bytes and must get exactly those fields. Because one file drives assertions in two codebases, changing one side's codec without the other fails that side's test immediately. The fixture is what stops the two apps from drifting apart — not code review.

TEXT kinds

PAD_STATUS tokens

What the laptop sends, and when

STATE  volume, microphone, brightness
TEXT   4 the display's refresh rates
STATE  the current refresh rate
TEXT   8 whether a virtual controller can be offered
TEXT   0 now playing, 1 the app, 2 the timeline
STATE  media position
TEXT   5 the laptop's macro names

then every change as it happens.
Media position is refreshed once a second while playing.
TEXT 6, the macro icons, arrive only after the phone asks with TEXT 7.

Versioning

Only a new frame type forces a version, because an unknown type closes the connection. The refresh-rate dial and the macro buttons both arrived without a bump, which is the rule working rather than being broken. Nothing in the existing frame set could express an axis — SET carries a u8 the laptop rejects above 100, and the only pair of signed i16s belongs to the mouse — so a real gamepad needed a type of its own, and a new type is the one thing that moves the version. This number moves only in a major release, and any change to what a frame means bumps it on both sides in the same commit and adds a fixture line.

Actions

Controls

Gamepad buttons

The laptop copies the field straight into an XINPUT_GAMEPAD rather than remapping it, so a table of Edgepad's own would be a second definition to keep in step with Microsoft's. 0x0800, between GUIDE and A, is unused by XInput and stays unused here.

The two layers

The handshake also carries the protocol version. A mismatch is refused with the laptop's version in the reply, so the phone can say which side needs updating instead of misreading frames. A refusal before HELLO_ACK names both possible causes: a laptop app older than the phone's, or a laptop that trusts a different phone.

What the action table is, and is not

3.0.0 gives the phone a second way to reach the laptop's input stack and does not move that boundary. PAD_STATE drives a virtual Xbox controller, which games read and the desktop largely does not; it can press A and push a stick, and it cannot type a command line. The same phone's keyboard screen already could. What is worth saying plainly instead is that the controller needs a third-party signed kernel driver, ViGEmBus, which you install and Edgepad only talks to — see Known limits for what that costs.

The line Windows draws

SendInput is silently refused when an elevated window, a UAC prompt or the secure desktop has focus. This is Windows protecting them and the app cannot cross it. The laptop counts those refusals and logs them once per session, so a gesture that appears to do nothing has a recorded reason.

Known limits

• The trusted phone's Bluetooth address is stored in plain text under %APPDATA%\Edgepad. Anyone who can write that file can change which phone is trusted — and that person can already run programs as you.
• Edgepad.exe is not code-signed, so SmartScreen warns on first run. Verify the download came from the project's own Releases page.
• Text typed from the phone goes wherever the laptop's focus is, exactly as a keyboard would.
• The virtual controller is ViGEmBus, a third-party kernel driver you install yourself. It is signed, and its author archived it in November 2023, so it receives no updates. Edgepad neither ships it nor installs it, and works without it.
• Nothing leaves the two devices: no network, no server, no account, no telemetry. The laptop writes a local log of connections and errors and nothing else.
• Release builds are signed, and every release is signed with the same key, so a phone will refuse an update that was not built by this project.

Inside the phone app

Under android/app/src/main/java/me/akshitbansal/edgepad. The packages marked pure have no Android platform types and run as plain JVM unit tests.

Inside the laptop app

Under windows/src/Edgepad.

pwsh scripts/check.ps1                  # formats in place, then checks everything
pwsh scripts/check.ps1 -Only android    # ktlint, Android lint, unit tests
pwsh scripts/check.ps1 -Only windows    # dotnet format, build, tests
pwsh scripts/check.ps1 -Ci              # what CI runs: fails on unformatted code

What it actually runs

What CI does on top

.github/workflows/ci.yml runs on every push to main and every pull request, in two jobs: Android on ubuntu-latest with Temurin 17 and Gradle wrapper validation, Windows on windows-latest with the SDK from global.json. Each runs the gate in -Ci mode and then uploads an artifact — a debug APK and the self-contained exe.

Laptop

dotnet run --project windows/src/Edgepad

dotnet publish windows/src/Edgepad -c Release -r win-x64 --self-contained \
  -p:PublishSingleFile=true \
  -p:IncludeNativeLibrariesForSelfExtract=true \
  -p:EnableCompressionInSingleFile=true

cd windows && dotnet build Edgepad.slnx -c Release

Phone

cd android && ./gradlew installDebug

cd android && ./gradlew assembleDebug

Together

1. Pair the phone and the laptop in Windows Settings.
2. Start the tray app with dotnet run.
3. Install and open the phone app, then tap the laptop.
4. Read %LOCALAPPDATA%\Edgepad\edgepad.log for dropped frames or refused input batches.

This site

cd site
npm install
npm run dev        # http://localhost:3000
npm run check      # Biome -> ESLint -> tsc, the site's own gate
npm run check:ci   # the same, non-mutating

cd android && ./gradlew testDebugUnitTest
cd windows && dotnet test --solution Edgepad.slnx

The fixture layer

protocol/frames.txt holds every frame type as golden bytes, and protocol/actions.txt the action, control and text-kind ids. FrameFixtureTest and IdsFixtureTest on the phone, and FrameFixtureTests and IdsFixtureTests on the laptop, parse those same files at run time rather than copying them into either codebase.

A protocol change therefore always touches a fixture file and both codecs in the same commit. Change one side's codec without the other and that side's test fails immediately.

Above the fixtures

Fork the repository on GitHub and clone your fork. Your work lives on your fork, and reaches this repository as a pull request.

git clone https://github.com/<you>/edgepad.git
cd edgepad
git remote add upstream https://github.com/akshit-bansal11/edgepad.git

1. Bring your fork's main up to date with upstream/main, then branch from it on your fork.
2. Keep the two apps in step. A protocol change edits protocol/frames.txt or protocol/actions.txt, both codecs or both enums, and bumps the protocol version on both sides — all in one commit.
3. Add or change a test when you add logic or a branch, or fix a bug. Prefer the pure layers over anything that needs a device.
4. Run pwsh scripts/check.ps1 until it is clean.
5. Commit with a Conventional Commits subject and a body saying what changed and why, including what you rejected.
6. Add a line under Unreleased in CHANGELOG.md.
7. Push the branch to your fork and open a pull request against main here. CI runs the same gate on both halves, and the site's gate when site/ or protocol/ changed. The maintainer reviews and merges.

Style

• No UI libraries on the phone. No third-party packages on the laptop beyond NAudio, System.Management and Nefarius.ViGEm.Client. A new dependency needs a reason in the pull request.
• Constants are named. A number that appears twice is a constant.
• Doc comments say why, not what the next line already says.
• Nothing runs on the input path that could block: no logging, no allocation while drawing, no I/O on the session thread beyond the socket.

Bug reports and feature requests use the issue templates in .github/ISSUE_TEMPLATE. Open an issue for anything bigger than a fix, so the design can be talked through before code exists. Report anything exploitable through a security advisory, not a public issue.

Each release carries a signed APK and a compressed self-contained exe, named for the version, Edgepad-3.1.1.apk and Edgepad-3.1.1.exe, so several downloads on one phone or laptop can be told apart. The app's versionName comes from the release tag and its versionCode from a number that only increases, so an update always installs over the previous one.

Not goals

No account, no server, no telemetry, and no web deployment: Edgepad ships as two native binaries from GitHub Releases and there is nothing to host. The link does not reach another room or the internet, and it is not meant to.

• Icons are Lucide, ISC licence; the few that came from Feather are MIT. Both apps draw Lucide's own paths, and the licence text ships inside the APK as assets/licenses/Lucide-LICENSE.txt and inside the exe beside the icons.
• The typeface is Lato, by Łukasz Dziedzic, SIL Open Font License 1.1. Both apps bundle it, and its licence ships inside the APK as assets/licenses/Lato-OFL.txt and inside the exe beside the fonts. This site also sets code in JetBrains Mono, under the same licence.
• The media players' logos — Spotify, Netflix, YouTube and the rest — are trademarks of their owners. The phone shows one only to say which app is playing on the laptop; that implies no endorsement by, or affiliation with, any of them. The SVG files were supplied by the maintainer and are drawn as supplied.
• The laptop app depends on NAudio (for volume, MIT), System.Management (for WMI brightness) and Nefarius.ViGEm.Client (the client for the virtual controller, MIT), and nothing else. The phone app depends on AndroidSVG (to draw the mark and the logos, Apache 2.0), and on JUnit for its tests only.
• The virtual controller itself is ViGEmBus, BSD 3-Clause licence, by Benjamin Höglinger-Stelzer. It is a separate install and is not distributed with Edgepad.