Skip to content

Developer documentation

How Edgepad works, and how to change it.

The architecture, the wire protocol and the developer guide. The protocol tables below are generated from the same fixtures every test suite reads, so this page cannot drift from the apps. Just want to use Edgepad? See the user guide.

How it works

The split

The phone recognises; the laptop executes. That single sentence decides most of the rest of the design.

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 its own input, audio, display and media APIs (Windows' on Windows, CGEvent and Core Audio on a Mac, uinput and the desktop's sound server on Linux). 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.

How it works

Transport

Bluetooth Classic RFCOMM by default: an ordered, encrypted byte stream between two already-paired devices, with no server and no discovery. Wi-Fi and USB connections are optional and off until you turn them on.
RFCOMMBluetoothEncryptionWithAuthenticationProtocol v5
Service UUID, from protocol/actions.txt
758bb618-7b72-4cd3-9aa2-c9b88e54d555

Both sides know this one id. There is no discovery step and no service record to look up.

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

BLE GATT

Windows as a GATT server is unreliable across adapters, and GATT is datagram-shaped where an ordered stream is wanted.

Wi-Fi / LAN

Needs a shared network and a discovery step, so it was not the default. Bluetooth was also the requirement. Since 4.0.0 Wi-Fi and USB connections are an optional extra: off until you turn them on, a one-time six-digit code to pair, and the phone's half is not yet tried on real devices.

Phone as a Bluetooth HID touchpad

Windows only runs its multi-finger gestures for certified Precision Touchpad hardware, so the gestures would have to be emulated anyway.

How it works

Architecture

One product in four programs, in one repository: the Android app and the Windows, Mac and Linux apps. This is the map of them and of the single seam between them.

Android phone

Kotlin, platform views, no UI libraries

  • MainActivity

    Guide, devices, settings, layout editors, keyboard, gamepad, macros

  • ControlSurface

    One custom View that draws everything and receives every touch

  • TrackpadRecognizer · Dial x4

    Pure Kotlin, no Android types. Turns touch into semantic frames

  • LaptopLink

    RFCOMM socket: a reader thread, a writer thread, a coalescing outbox

  • LaptopState

    The laptop's last report, kept across rotation and theme changes

RFCOMM

Windows laptop

C# on .NET 10, WinForms tray, single instance

  • TrayContext

    Menu, status, run at login, macros editor, Forget

  • RfcommServer

    Advertises the service, accepts on WinRT's thread

  • Session

    One per phone, on its own above-normal-priority thread

  • FrameCodec -> Dispatcher

    Decodes, then executes from the laptop-owned action table

  • InputInjector · AudioEndpoint · BrightnessControl · MediaSessions · VirtualPad

    SendInput, Core Audio, WMI, system media transport controls, and a virtual Xbox controller where ViGEmBus is installed

The phone recognises; the laptop executes. Frames go right: pointer, button, scroll, zoom, action id, control value, key, text. State comes back left: volume, mute, microphone, brightness, refresh rate, what is playing, macro names, and the PONG the round-trip readout is measured from.

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.

The Mac app

The Mac half is a menu-bar app in Swift, split in two. EdgepadCore decides (the codec, key map, dispatcher, session and trust store) and is pure and unit-tested; Edgepad acts, through IOBluetooth, CGEvent and Core Audio. The core reaches the Mac only through small protocols, so the dispatcher and the handshake are tested with no radio and no permission.

Everything runs on the main thread, because IOBluetooth delivers on the main run loop. A session is therefore a state machine fed bytes rather than a blocking read loop, and bytes that arrive while the Trust NAME? question is open wait in a buffer until HELLO_ACK has gone out. The app polls volume, microphone and brightness twice a second instead of subscribing, so a change made on the Mac reaches the phone within half a second. Brightness uses a private framework, DisplayServices, loaded at run time; where it is missing the dial has nothing to show. Now playing and the virtual controller are not built. The README and docs/ARCHITECTURE.md in the repository say more.

The shared core

shared/Edgepad.Core holds what the Windows and Linux apps would otherwise each write: the frame codec and ids, the dispatcher, the handshake, the trust store and the PIN gate, the macro store, the stroke board that annotation draws, the log and the update check. It reaches the machine only through small interfaces such as IPlatform, so its tests run on Linux in CI with no radio and no input device. The Mac app has its own Swift core, held to the same fixtures.

The Linux app

The Linux half is a tray app in C# on .NET, in linux/, built on that core. It serves the same Bluetooth service through BlueZ over D-Bus and injects pointer, scroll, pinch, keys and typing through uinput, so it works on Wayland and on X11. The tray, the trust question, the Security window and the annotation overlay are drawn with Avalonia. Volume and the microphone go through wpctl or pactl, lock and brightness through systemd-logind, and media through MPRIS. The shortcuts behind task view, show desktop, search, notifications and switching desktops are chosen per desktop, for GNOME and KDE, and were written from memory. It is built and unit-tested in CI and has not been seen working on a Linux laptop; docs/LINUX.md in the repository lists what is unverified.

How it works

Threads and latency

Latency is the design priority after correctness. Every choice below exists to keep the path from a finger to SendInput short, and to stop a slow link from turning into a growing backlog.

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 starts as a candidate and replaces the connected phone only once its handshake and trust check succeed, just before HELLO_ACK. That lets the same phone replace its own stale link after a drop, which it does before the laptop's old socket has noticed it is dead, and lets a trusted phone take over from another, while an untrusted phone that merely connects cannot drop the connected one. A phone that was replaced is refused for 30 seconds, which outlasts its ten automatic retries, so two phones do not take the laptop back and forth. If starting Bluetooth fails, the server tries again every 30 seconds until it works, and it restarts when the PC resumes from sleep and when the Bluetooth radio is turned back on, without ending a live session. 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.

How it works

Wire protocol, version 5

A frame is one type byte followed by a payload whose length is fixed by the type, except TEXT, whose second header byte gives the length of the text that follows. All multi-byte integers are little-endian. Frames are 2 to 258 bytes.

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

TypeNamePayloadDirectionMeaning
0x01HELLOmagic EDGP, version u8phone → laptopOpens a session.
0x02HELLO_ACKversion u8laptop → phoneAccepts it. On a version mismatch the laptop sends its own version, then closes, so the phone can say which side needs updating.
0x03PIN_REQUESTattemptsLeft u8, lockedSeconds u16laptop → phoneAsks for the PIN, or says the phone is locked out and for how long. Only between the trust question and HELLO_ACK.
0x04PIN_ANSWERsix bytes, each 0 to 9phone → laptopThe PIN, one digit value per byte rather than ASCII. Only as the answer to PIN_REQUEST; a byte above 9 closes the link.
0x10MOVEdx i16, dy i16phone → laptopMove the pointer, in laptop pixels, before Windows' own pointer acceleration.
0x11BUTTONbutton u8, down u8phone → laptop0 left, 1 right, 2 middle. down is 1 or 0.
0x12SCROLLdx i16, dy i16phone → laptopWheel units. 120 is one notch; positive dy is wheel forward.
0x13ZOOMdelta i16phone → laptopCtrl+wheel units.
0x20ACTIONid u8phone → laptopRun one action from the laptop's table.
0x21SETcontrol u8, value u8phone → laptopSet a control to 0-100. The laptop drops anything above 100.
0x22KEYcode u16, down u8phone → laptopPress or release one key, by Windows virtual-key code. This is what the phone's keyboard screen sends.
0x23PAD_STATEbuttons u16, lt u8, rt u8, lx i16, ly i16, rx i16, ry i16phone → laptopThe whole virtual controller in one frame, laid out like Windows' own XINPUT_GAMEPAD so the laptop copies the fields rather than translating them. Triggers are 0-255, sticks -32768 to 32767, positive up and right. A snapshot and not a change, so a backlog of them collapses to the newest.
0x24PENx u16, y u16, state u8phone → laptopOne point of a pen stroke: state 0 is up, 1 down, 2 move. x and y span the whole u16 range, 0 the left or top edge of the laptop's screen and 65535 the right or bottom. A state above 2 decodes and is dropped and counted.
0x30PINGt i64phone → laptopThe phone's clock, in nanoseconds.
0x31PONGt i64laptop → phoneThe same value echoed back, which is what the round-trip readout measures.
0x40STATEcontrol u8, value u8, flags u8laptop → phoneA control's current value. Flags bit 0 is muted for audio controls, playing for media position.
0x41TEXTkind u8, length u8, UTF-8 bytesboth waysThe only variable-length frame: up to 255 bytes, never split inside a character.
0x50FILE_BEGINfileType u8, length u8, size u32, UTF-8 namelaptop → phoneStarts sending a capture to the phone, when the phone asked for captures to be saved there. TEXT's header shape, so the length counts the size and the name. The type is an id from the FILE_TYPE table, never a MIME string.
0x51FILE_CHUNKseq u8, length u8, byteslaptop → phoneUp to 255 bytes of the file. seq is the chunk's index mod 256, so a lost chunk shows. Paced, and slower while the phone is sending input, so the trackpad stays responsive.
0x52FILE_ENDsha256, 32 byteslaptop → phoneThe SHA-256 of the whole file. The phone keeps the file only if it matches.
0x53FILE_RESULTstatus u8phone → laptopThe phone's answer: 0 saved, 1 bad hash, 2 rejected, 3 write failed. Only 0 lets the laptop delete its copy.
0x54BLOB_BEGIN——In the fixture, not yet described on this page.
0x55BLOB_CHUNK——In the fixture, not yet described on this page.
0x56BLOB_END——In the fixture, not yet described on this page.
24 frame types, read from protocol/frames.txt.

Golden bytes

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

FrameFieldsBytes
HELLO101 45 44 47 50 01
HELLO201 45 44 47 50 02
HELLO301 45 44 47 50 03
HELLO401 45 44 47 50 04
HELLO501 45 44 47 50 05
HELLO_ACK102 01
PIN_REQUEST5 003 05 00 00
PIN_REQUEST2 003 02 00 00
PIN_REQUEST0 3003 00 1e 00
PIN_REQUEST0 30003 00 2c 01
PIN_REQUEST0 6553503 00 ff ff
PIN_ANSWER1 2 3 4 5 604 01 02 03 04 05 06
PIN_ANSWER0 0 0 0 0 004 00 00 00 00 00 00
PIN_ANSWER9 9 9 9 9 904 09 09 09 09 09 09
MOVE5 -310 05 00 fd ff
MOVE-32768 3276710 00 80 ff 7f
BUTTON0 111 00 01
BUTTON1 011 01 00
SCROLL0 -12012 00 00 88 ff
ZOOM24013 f0 00
ACTION320 03
ACTION3520 23
ACTION3620 24
ACTION5220 34
ACTION5320 35
ACTION5420 36
ACTION4020 28
ACTION5620 38
ACTION5720 39
ACTION5820 3a
ACTION5920 3b
ACTION9620 60
SET0 5521 00 37
SET1 10021 01 64
SET3 5021 03 32
SET5 621 05 06
SET6 021 06 00
SET6 121 06 01
SET7 121 07 01
SET7 021 07 00
SET8 2021 08 14
SET8 10021 08 64
SET9 3521 09 23
SET9 10021 09 64
KEY65 122 41 00 01
KEY112 022 70 00 00
KEY65535 122 ff ff 01
PAD_STATE0 0 0 0 0 0 023 00 00 00 00 00 00 00 00 00 00 00 00
PAD_STATE0 0 0 -32768 -32768 -32768 -3276823 00 00 00 00 00 80 00 80 00 80 00 80
PAD_STATE0 0 0 32767 32767 32767 3276723 00 00 00 00 ff 7f ff 7f ff 7f ff 7f
PAD_STATE0 255 255 0 0 0 023 00 00 ff ff 00 00 00 00 00 00 00 00
PAD_STATE12305 32 200 -1 1 256 -25623 11 30 20 c8 ff ff 01 00 00 01 00 ff
PAD_STATE63487 0 0 0 0 0 023 ff f7 00 00 00 00 00 00 00 00 00 00
PEN0 0 124 00 00 00 00 01
PEN65535 65535 024 ff ff ff ff 00
PEN32768 12345 224 00 80 39 30 02
PEN1 2 724 01 00 02 00 07
PING123456789012330 cb 04 fb 71 1f 01 00 00
PONG-131 ff ff ff ff ff ff ff ff
STATE0 42 140 00 2a 01
STATE3 42 140 03 2a 01
TEXT3 hi41 03 02 68 69
TEXT1 Song41 01 04 53 6f 6e 67
TEXT041 00 00
TEXT2 84/22741 02 06 38 34 2f 32 32 37
TEXT0 Café41 00 05 43 61 66 c3 a9
TEXT0 🎵41 00 04 f0 9f 8e b5
TEXT0 日本語41 00 09 e6 97 a5 e6 9c ac e8 aa 9e
TEXT6 0/0/1/AAAA41 06 0a 30 2f 30 2f 31 2f 41 41 41 41
TEXT741 07 00
TEXT8 ready41 08 05 72 65 61 64 79
TEXT8 no-driver41 08 09 6e 6f 2d 64 72 69 76 65 72
TEXT8 attach-failed41 08 0d 61 74 74 61 63 68 2d 66 61 69 6c 65 64
TEXT9 capture41 09 07 63 61 70 74 75 72 65
TEXT9 annotate/capture41 09 10 61 6e 6e 6f 74 61 74 65 2f 63 61 70 74 75 72 65
TEXT10 1920/108041 0a 09 31 39 32 30 2f 31 30 38 30
TEXT11 saved41 0b 05 73 61 76 65 64
TEXT12 too-large41 0c 09 74 6f 6f 2d 6c 61 72 67 65
TEXT13 00112233445566778899aabbccddeeff/windows/Desk41 0d 2d 30 30 31 31 32 32 33 33 34 34 35 35 36 36 37 37 38 38 39 39 61 61 62 62 63 63 64 64 65 65 66 66 2f 77 69 6e 64 6f 77 73 2f 44 65 73 6b
TEXT14 7.1241 0e 04 37 2e 31 32
TEXT15 added41 0f 05 61 64 64 65 64
TEXT16 -01241 10 04 2d 30 31 32
TEXT17 FF3B3041 11 06 46 46 33 42 33 30
TEXT19 laptop:87:1:Desk|headphones:60:0:AirPods41 13 28 6c 61 70 74 6f 70 3a 38 37 3a 31 3a 44 65 73 6b 7c 68 65 61 64 70 68 6f 6e 65 73 3a 36 30 3a 30 3a 41 69 72 50 6f 64 73
TEXT1941 13 00
TEXT19 laptop:50:0:Café41 13 11 6c 61 70 74 6f 70 3a 35 30 3a 30 3a 43 61 66 c3 a9
TEXT20 headphones/AirPods41 14 12 68 65 61 64 70 68 6f 6e 65 73 2f 41 69 72 50 6f 64 73
TEXT20 speaker/Speakers41 14 10 73 70 65 61 6b 65 72 2f 53 70 65 61 6b 65 72 73
FILE_BEGIN0 1234 shot.png50 00 0c d2 04 00 00 73 68 6f 74 2e 70 6e 67
FILE_BEGIN2 209715200 rec.mp450 02 0b 00 00 80 0c 72 65 63 2e 6d 70 34
FILE_CHUNK0 68656c6c6f51 00 05 68 65 6c 6c 6f
FILE_CHUNK255 ff0051 ff 02 ff 00
FILE_END2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b982452 2c f2 4d ba 5f b0 a3 0e 26 e8 3b 2a c5 b9 e2 9e 1b 16 1e 5c 1f a7 42 5e 73 04 33 62 93 8b 98 24
FILE_RESULT053 00
FILE_RESULT153 01
BLOB_BEGIN0 1234 clip54 00 08 d2 04 00 00 63 6c 69 70
BLOB_BEGIN3 8192 chrome54 03 0a 00 20 00 00 63 68 72 6f 6d 65
BLOB_BEGIN9 1 x54 09 05 01 00 00 00 78
BLOB_CHUNK0 68656c6c6f55 00 05 68 65 6c 6c 6f
BLOB_CHUNK255 ff0055 ff 02 ff 00
BLOB_END2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b982456 2c f2 4d ba 5f b0 a3 0e 26 e8 3b 2a c5 b9 e2 9e 1b 16 1e 5c 1f a7 42 5e 73 04 33 62 93 8b 98 24
Every line of protocol/frames.txt, verbatim.

TEXT kinds

KindNameWhat it means
0NOW_PLAYINGWhat is playing. Laptop to phone.
1APPThe app playing it. Laptop to phone.
2TIMELINEThe timeline as seconds/length, such as 84/227. Laptop to phone.
3TYPEText to type, where \b is backspace and \n is enter. Phone to laptop.
4REFRESH_RATESThe display's available refresh rates as 60/120/144, in the order CONTROL 4 indexes them. Laptop to phone.
5MACROSThe laptop's macro names as Chrome/Spotify/Notes, in the order MACRO_BASE indexes them. A blank name keeps its slot. Laptop to phone.
6MACRO_ICONOne piece of one macro's icon as slot/chunk/chunks/base64, the base64 being part of a PNG. An icon does not fit the 255 bytes a payload holds, so it arrives in pieces. Laptop to phone.
7WANT_ICONSAsks for the macro icons, with an empty payload. Sent when the phone opens the macro grid; nothing is pushed unasked. Phone to laptop.
8PAD_STATUSWhether a virtual controller can be offered, as one of ready, no-driver or attach-failed. Sent after the handshake and in answer to PAD_ATTACH and PAD_DETACH. An unknown token reads as no-driver, so the phone falls back to the keyboard rather than sending input nothing receives. Laptop to phone.
9FEATURESThe optional features this laptop has, as tokens joined by a slash such as annotate/capture. Sent once after the handshake. A feature that is not named is off, and a token the phone does not know is ignored. Laptop to phone.
10SCREEN_SIZEThe primary display in pixels as 1920/1080. Sent after the handshake and whenever the display changes, so the phone can shape its drawing surface to the same ratio. Laptop to phone.
11SIGN_STATUSHow a SIGN_SAVE ended, as one of saved, empty or failed. Laptop to phone.
12CAPTURE_STATUSWhy a capture the phone asked for stayed on the laptop, as one of too-large, not-found or failed. Laptop to phone.
13DEVICEIn the fixture, not yet described on this page.
14APP_ADDIn the fixture, not yet described on this page.
15APP_ADD_STATUSIn the fixture, not yet described on this page.
16MACRO_OPENIn the fixture, not yet described on this page.
17PEN_RGBA stroke colour as exactly six hex digits, RRGGBB, either case. Anything else, a leading # included, is dropped and counted. It sets the colour until the next PEN_COLOR or PEN_RGB. Phone to laptop.
18INPUT_STATEIn the fixture, not yet described on this page.
19BATTERIESIn the fixture, not yet described on this page.
20OUTPUTIn the fixture, not yet described on this page.
Read from protocol/actions.txt. TEXT carries at most 255 bytes and is never split inside a character.

PAD_STATUS tokens

TokenNameWhat it means
readyREADYThe virtual controller is plugged in and PAD_STATE will be acted on. The only token that leaves the pad usable.
no-driverNO_DRIVERThe virtual-controller driver, ViGEmBus, is not installed on the laptop. The pad falls back to keys.
attach-failedATTACH_FAILEDThe driver is there but plugging the pad in did not work. The pad falls back to keys.
The whole vocabulary of TEXT kind 8, read from protocol/actions.txt. A token the phone does not know reads as no-driver.

FEATURE tokens

TokenNameWhat it means
annotateANNOTATEThe laptop can show the annotation overlay and a signing surface. The phone shows an Annotate tile only for a laptop that names this.
captureCAPTUREThe laptop can start its own screenshot and screen-recording tools. The phone shows a Capture tile only for a laptop that names this.
clipboardCLIPBOARDIn the fixture, not yet described on this page.
appsAPPSIn the fixture, not yet described on this page.
runningRUNNINGIn the fixture, not yet described on this page.
The whole vocabulary of TEXT kind 9, read from protocol/actions.txt. A feature that is not named is off, and a token the phone does not know is ignored.

SIGN_STATUS tokens

TokenNameWhat it means
savedSAVEDThe signature was exported to a PNG and put on the clipboard.
emptyEMPTYNothing had been drawn, so nothing was saved.
failedFAILEDThe file could not be saved, or every clipboard route failed.
The whole vocabulary of TEXT kind 11, read from protocol/actions.txt.

The annotation palette

IndexNameWhat it means
0BLACK#000000
1WHITE#FFFFFF
2RED#FF3B30
3ORANGE#FF9500
4YELLOW#FFCC00
5GREEN#34C759
6BLUE#0068D6
7PURPLE#AF52DE
The eight colours CONTROL 5 indexes, read from protocol/actions.txt. The laptop owns the colour; the phone shows these only as a preview.

What the laptop sends, and when

After HELLO_ACK
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
TEXT   9 which optional features it has
TEXT  10 the primary display's size in pixels

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

VersionReleaseChange
10.1.0HELLO through STATE. TEXT kinds 0 and 1 arrived in 0.2.0 without a bump.
20.3.0TEXT kind 2. A mismatch is refused with the laptop's version.
30.6.0TEXT kind 3. Actions 31 to 34 arrived in 0.5.0, and CONTROL 4, TEXT 4 and 5 and the macro block in 1.1.0 — all without a bump.
43.0.0PAD_STATE, a new frame type, which is the one thing that forces this number. Actions 35 and 36 and TEXT kind 8 came with it and would not have needed a bump on their own — nor did TEXT 6 and 7, the macro icons, in 2.3.0.
54.0.0PIN_REQUEST and PIN_ANSWER, PEN, and FILE_BEGIN, FILE_CHUNK, FILE_END and FILE_RESULT for a capture saved on the phone, all new frame types. BLOB_BEGIN, BLOB_CHUNK and BLOB_END carry the clipboard, an app list and an app icon, both ways. Actions 40 to 55, CONTROL 5 and 6 and TEXT 9 to 12 came with them and would not have needed a bump on their own.

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 everywhere in the same commit and adds a fixture line.

How it works

Actions and controls

The laptop owns both tables. The phone names an id; the laptop decides what the id does.

The actions

IdNameWhat it means
1MUTE_TOGGLEMute key.
2PLAY_PAUSEMedia play/pause key.
3NEXT_TRACKMedia next key.
4PREVIOUS_TRACKMedia previous key.
5MIC_MUTE_TOGGLEToggles the default microphone's mute.
6LOCKLockWorkStation. Win+L cannot be injected.
20TASK_VIEWWin+Tab.
21SHOW_DESKTOPWin+D.
22SEARCHWin+S.
23NOTIFICATIONSWin+N.
24DESKTOP_LEFTWin+Ctrl+Left.
25DESKTOP_RIGHTWin+Ctrl+Right.
26APP_SWITCH_BEGINHolds Alt and presses Tab. Alt stays down until APP_SWITCH_END or the session ends.
27APP_SWITCH_NEXTTab, only while Alt is held.
28APP_SWITCH_PREVIOUSShift+Tab, only while Alt is held.
29APP_SWITCH_ENDReleases Alt.
30ZOOM_RESETCtrl+0.
31VOLUME_UPVolume-up key.
32VOLUME_DOWNVolume-down key.
33BRIGHTNESS_UPThe panel's brightness, plus 10.
34BRIGHTNESS_DOWNThe panel's brightness, minus 10.
35PAD_ATTACHAsks the laptop to plug in its virtual Xbox controller. The laptop answers with TEXT 8, so the phone learns whether it may send PAD_STATE or must fall back to the keyboard.
36PAD_DETACHAsks the laptop to unplug the virtual controller. Sent when the gamepad screen closes; the laptop also unplugs it by itself when the session ends.
40ANNOTATE_BEGINShows the annotation overlay on the laptop's primary display. PEN and the tool actions are dropped until it is shown or a signing surface is open.
41ANNOTATE_ENDRemoves the overlay and discards its strokes. A session ending does the same.
42ANNOTATE_UNDORemoves the last stroke.
43ANNOTATE_CLEARRemoves every stroke.
44TOOL_PENThe next stroke is a pen line, 0.4% of the screen height wide.
45TOOL_HIGHLIGHTERThe next stroke is a highlighter, 2% of the screen height wide at 35% opacity, stroked once per path so a loop does not darken where it crosses itself.
46TOOL_LINEThe next stroke is a straight line from the down point to the latest move.
47TOOL_ARROWAs the line, with an arrow head four times the pen width at the end.
48TOOL_RECTANGLEThe next stroke is a rectangle from the down point to the latest move.
49TOOL_ELLIPSEThe next stroke is an ellipse from the down point to the latest move.
50SIGN_BEGINOpens a signing surface that shows nothing on the laptop and accepts only the pen tool.
51SIGN_SAVEExports the strokes as a transparent PNG cropped to the ink, to the clipboard and to an Edgepad folder in Pictures, never over an earlier file, then answers with TEXT 11.
52CAPTURE_REGIONStarts a region screenshot with the laptop's own tool: Win+Shift+S on Windows, Cmd+Shift+4 on a Mac, Print on Linux. The drag happens on the laptop's screen.
53CAPTURE_SCREENTakes a screenshot of the whole screen: PrtScn on Windows, Cmd+Shift+3 on a Mac, Print on Linux.
54CAPTURE_RECORDStarts screen recording: Win+Shift+R on Windows, which needs a recent Snipping Tool and is unverified, Cmd+Shift+5 on a Mac, which opens the capture toolbar, and on Linux the desktop's own shortcut, unverified (Ctrl+Shift+Alt+R on GNOME, Meta+Alt+R on KDE).
55CAPTURE_CANCELSent when the phone leaves its capture screen. Presses Escape on the laptop, only while a region or recording overlay it opened may still be open (8 seconds).
56APPS_LISTIn the fixture, not yet described on this page.
57APPS_CANCELIn the fixture, not yet described on this page.
64MACRO_BASEThe first of 32 reserved macro slots (ids 64-95). Slot n runs as MACRO_BASE + n. The phone sends the index; the laptop's own list decides what it opens.
58MACROS_WATCHIn the fixture, not yet described on this page.
59MACROS_UNWATCHIn the fixture, not yet described on this page.
96MACRO_CLOSE_BASEIn the fixture, not yet described on this page.
45 action ids, read from protocol/actions.txt. Sent as the payload of the ACTION frame.

The shortcut each action presses is the Windows one. A Mac uses macOS's own defaults, listed in the README, and a Linux laptop chooses per desktop, listed in docs/LINUX.md; an id a laptop has no shortcut for is dropped and counted.

Controls

IdNameWhat it means
0VOLUMESET sets the default speakers' level; STATE reports the level and a muted flag.
1BRIGHTNESSSET sets the built-in panel's brightness through WMI; STATE reports the level.
2MIC_LEVELSET sets the default microphone's level; STATE reports the level and a muted flag.
3MEDIA_POSITIONSET seeks the current track to that percent, where the player allows it; STATE reports the percent and a playing flag.
4REFRESH_RATESET switches the display to the rate at that index of the TEXT 4 list; STATE reports the current rate's index. Never a rate in hertz.
5PEN_COLORSET picks the stroke colour by index into the eight-colour palette in protocol/actions.txt. An index of 8 or more is dropped and counted. A colour outside the palette is TEXT 17.
6CAPTURE_TARGETWhere a capture ends up: 0 the laptop keeps it, 1 the laptop sends it to the phone and deletes its copy only once the phone says it saved it. Sent on connect and whenever the setting changes.
7CLIPBOARDIn the fixture, not yet described on this page.
8PEN_WIDTHSET sets the width of new pen-tool strokes, 1 to 100, as 0.02% of the screen's height per step: 5 is 0.1%, 20 is the default 0.4% and 100 is 2.0%. The highlighter is always 5 times the pen's width. 0 or more than 100 is dropped and counted. Forgotten when the session ends.
9PEN_OPACITYSET sets the opacity of new strokes in percent, 10 to 100. The highlighter multiplies its own 35% by it. Anything else is dropped and counted. Forgotten when the session ends.
10 control ids, read from protocol/actions.txt. Carried by SET (phone to laptop) and STATE (laptop to phone).

Gamepad buttons

MaskNameWhat it means
0NONENothing held. What PAD_STATE carries the moment the last button comes up.
1DPAD_UPD-pad up.
2DPAD_DOWND-pad down.
4DPAD_LEFTD-pad left.
8DPAD_RIGHTD-pad right.
16STARTStart, the menu button.
32BACKBack, the view button.
64LEFT_THUMBLeft stick pressed in.
128RIGHT_THUMBRight stick pressed in.
256LEFT_SHOULDERLeft bumper.
512RIGHT_SHOULDERRight bumper.
1024GUIDEThe Xbox button.
4096AA.
8192BB.
16384XX.
32768YY.
The bits of PAD_STATE's buttons field, read from protocol/actions.txt. XInput's own wButtons values, in decimal.

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.

How it works

Security and trust

Edgepad lets a phone drive a laptop, so its boundaries matter. There are three layers, and one common misreading of them.

The layers

Pairing

On Windows, enforced by the socket's protection level. The link is bound at BluetoothEncryptionWithAuthentication, so a device not already bonded with the laptop cannot connect at all, and the stream is encrypted by the link layer. The Mac app checks the pairing itself, as below.

Trust on first use

Enforced by TrustStore. Any paired phone that is not yet trusted makes the tray ask Trust NAME? once it completes the handshake, and HELLO_ACK waits for the answer. Trust adds its Bluetooth address to trusted-phone.txt (in %APPDATA%\Edgepad on Windows), one address per line, so several phones can be trusted; Don't trust, or no answer within 60 s, closes the connection. A phone the owner said no to is not asked about again for 30 seconds. The Security… window's Forget all… hangs up on the connected phone and takes no connection while it asks; a yes clears every trusted phone and keeps refusing for 30 seconds, and a Forget clicked while a question is open wins over a yes given after it. Every phone you trust has full keyboard-level control, so trust only your own.

Security level and PIN

Chosen on the laptop under Security…, never from the phone. Level 1 is the trust question alone. Level 2 also asks each phone for a six-digit PIN the first time, level 3 on every connection. The phone asks on its own keypad, never stores the PIN, and its screen cannot be captured. After five wrong answers the laptop refuses that phone for 30 seconds, doubling with each further five, up to an hour; the counters are kept in memory, so quitting the laptop app resets them. A six-digit PIN is only a million values, so what stops guessing is that lock-out. It does not protect against someone who can copy the laptop's settings file, and the laptop keeps only a salted hash of the PIN. A forgotten PIN can only be reset on the laptop, which also forgets every trusted phone.

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 the possible causes: Trust not yet answered on the laptop, a laptop app older than the phone's, or another phone that has just taken over the laptop.

At level 2 or 3 the laptop sends PIN_REQUEST between the trust check and HELLO_ACK, carrying the attempts left or the seconds the phone is locked out for, and the phone answers with PIN_ANSWER. Each digit goes as a value from 0 to 9, never as text, and a PIN frame after HELLO_ACK is dropped and counted. A PIN's digits never reach a log or a debug print on any platform.

The Mac app checks that the connecting phone is paired and requires requestAuthentication() to succeed before starting a session, and logs how long that took. The socket Android asks for is not a protection, because an attacker chooses their own socket. The laptop-side gates are that the phone is paired, that the link authenticates (on Windows, the socket's protection level), and the owner's yes. The Mac relies on the Bluetooth stack for encryption. Its trusted phones are kept in ~/Library/Application Support/Edgepad/trusted-phone.txt.

The Linux app asks the same trust question, and the PIN at levels 2 and 3. Its trusted phones are kept in ~/.config/edgepad/trusted-phone.txt.

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 phones' Bluetooth addresses sit in plain text in trusted-phone.txt: under %APPDATA%\Edgepad on Windows, under ~/Library/Application Support/Edgepad on a Mac and under ~/.config/edgepad (or $XDG_CONFIG_HOME/edgepad) on Linux, the last two readable by their owner only. Anyone who can write that file can change which phones are 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.
  • The Mac app is ad hoc signed and not notarised, so macOS refuses it until you choose Open Anyway, and the input-control permission has to be granted again after each update. It has been compiled and unit-tested in CI but has not yet been run on a real Mac.
  • Mac and Linux are still in testing. Please use them at your own risk. The Windows app is the one that has been run on a real laptop, and the Linux app has not been seen working on a Linux laptop yet; docs/LINUX.md lists what is unverified.
  • 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 server, no account, no telemetry. With the optional Wi-Fi link on, they talk over the local network and nowhere else. 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.

Developing

Repository layout

A monorepo. One slug, one repository, a phone app and three laptop apps that must ship together.
PathWhat
android/The phone app. Kotlin, Android platform views, no UI libraries. JUnit 4 is the only dependency.
windows/The laptop tray app. C# on .NET 10, WinForms for the tray, WinRT for Bluetooth and media, NAudio for volume, WMI for brightness, ViGEmBus for the virtual controller.
shared/The core every .NET laptop app shares: the protocol, the dispatcher, trust and the PIN, the handshake, the macro store, the stroke board and the update check, with its own tests.
linux/The Linux tray app. C# on .NET, Avalonia for the tray and windows, BlueZ over D-Bus for Bluetooth, uinput for input.
macos/The Mac menu-bar app. Swift, AppKit, IOBluetooth for RFCOMM, CGEvent for input, Core Audio for volume and microphone. No third-party dependencies; Swift Package Manager, no Xcode project.
protocol/The wire format and the id tables as plain-text fixtures. Every test suite reads them, so the apps cannot drift apart.
scripts/The quality gate and the release-key script.
docs/Architecture and protocol.
site/This documentation site. Next.js; its own gate, run by site.yml and not part of check.ps1.

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.

PackageWhatTestable
surface/Gesture recognition, the dials, the corner geometry, the ruler painter, the shape matcher, the pad's focus and lock table.Pure
protocol/Frame and id coding.Pure
link/The RFCOMM socket, coalescing, the laptop-state model, round-trip stats.Pure
gamepad/Gamepad layout, control geometry, which bindings fit which kind of control, the stick and trigger arithmetic, the layout library and its store.Pure
screens/Every screen: guide, devices, settings and its per-control pages, layout editors, shapes, Controls, keyboard, gamepad, capture, annotate and sign, macros, the PIN keypad.Needs a device

Inside the laptop app

Under windows/src/Edgepad.

FolderWhatTestable
Dispatch/WindowsPlatform: what each action id does on Windows. The dispatcher itself, the frame coding and trust are in shared/.Needs hardware
Bluetooth/RfcommServer and Session. Needs a live socket to verify.Needs hardware
Injection/InputBuilder, InputInjector and the SendInput interop.Needs hardware
Controls/Audio, brightness, display modes, media sessions, the on-screen level overlay.Needs hardware
Gamepad/VirtualPad: the ViGEmBus controller, and the PAD_STATUS answer when there is no driver.Needs hardware
Annotation/The click-through annotation overlay, the pen, and the signature export.Needs hardware
Trust/SecurityWindow: the security level and the PIN.Needs hardware
Macros/The macro editor, the icons and the launcher.Needs hardware

Developing

Prerequisites

Either half can be worked on alone. You do not need both toolchains to contribute to one app.

Phone app

  • JDK 17.
  • The Android SDK with platform 37 and build tools 37.0.0.
  • The Gradle wrapper fetches Gradle itself — nothing to install for that.

Laptop app

  • The .NET SDK version pinned in global.json: 10.0.401, withrollForward: latestFeature.
  • Windows 10 version 2004 or later for the Windows app, because it builds against the Windows SDK projection for Bluetooth.
  • The Linux app and the shared core build and test on Linux with the same SDK.
  • For the Mac app: a Mac with Xcode (Swift 5.9 or later). Its gate runs only on a Mac.

Developing

The quality gate

One script checks every half: format, lint, build, test. CI runs the same script in its non-mutating mode, so the local gate and CI cannot disagree.
The gate
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 core       # the shared core: dotnet format, build, tests
pwsh scripts/check.ps1 -Only windows    # dotnet format, build, tests
pwsh scripts/check.ps1 -Only linux      # dotnet format, build, tests
pwsh scripts/check.ps1 -Only macos      # swift format lint, build, tests; Mac only
pwsh scripts/check.ps1 -Ci              # what CI runs: fails on unformatted code

It writes locally because fixing your formatting is useful. CI must not write to your branch, so it fails instead of quietly reformatting the pull request.

What it actually runs

HalfStepLocal / CI
androidKotlin formattingktlintFormat / ktlintCheck
androidAndroid lint, then the unit testssame
coreC# formatting, build, then testsame commands as windows, on shared/
windowsC# formattingdotnet format / --verify-no-changes
windowsBuild, then testdotnet build -warnaserror; dotnet test
linuxC# formatting, build, then testsame commands as windows, on linux/
macosSwift formattingswift format lint --strict
macosBuild, then testswift build, warnings as errors; swift test

What CI does on top

.github/workflows/ci.yml runs on every push to main and every pull request, in six jobs. Each of android, core, windows, linux and macos runs the gate in -Ci mode: Android on ubuntu-latest with Temurin 17 and Gradle wrapper validation, core and linux on ubuntu-latest, Windows on windows-latest with the SDK from global.json, and the Mac on macos-latest. The sixth, lockfiles, only regenerates the NuGet lock files and uploads them as an artifact to commit; it checks nothing. The Android, Linux, Windows and Mac jobs also upload an artifact: a debug APK, the Linux archive, the self-contained exe and the Mac app.

Developing

Running it locally

Build each half directly, without the gate, while iterating.

Laptop

Run the tray app
dotnet run --project windows/src/Edgepad

It must already be running before the phone tries to connect: there is no discovery or retry on the laptop side, only the phone reconnects.

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

A self-contained single file, the same shape a release ships. Compression takes it from roughly 143 MB to 58.5 MB.

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

Linux

Run the tray app, or build the archive
dotnet run --project linux/src/Edgepad.Linux
dotnet publish linux/src/Edgepad.Linux/Edgepad.Linux.csproj -c Release \
  -r linux-x64 --self-contained -p:PublishSingleFile=true \
  -p:IncludeNativeLibrariesForSelfExtract=true \
  -p:EnableCompressionInSingleFile=true -o publish
sh linux/packaging/pack.sh 0.0.0-dev publish Edgepad-linux-x64.tar.gz

The same flags CI publishes with. pack.sh builds the release archive from the publish folder. The app has not been seen working on a Linux laptop yet.

Mac

Run the menu-bar app, or build the app bundle
cd macos && swift run
bash macos/bundle.sh 0.0.0-dev out

swift run starts it unbundled. bundle.sh wraps the binary into Edgepad.app in the directory you name. It has not been run on a real Mac.

Phone

Install a debug build on a connected device
cd android && ./gradlew installDebug

Uninstall any release build first: debug builds are versioned 0.0.0-dev and signed with the debug key, so they will not install over a release.

Build only
cd android && ./gradlew assembleDebug

Together

  1. Pair the phone with the laptop in its Bluetooth settings.
  2. Start the tray app with dotnet run, or swift run on a Mac.
  3. Install and open the phone app, then tap the laptop.
  4. Read %LOCALAPPDATA%\Edgepad\edgepad.log (on Linux ~/.local/share/Edgepad/edgepad.log, on a Mac ~/Library/Logs/Edgepad/edgepad.log) for dropped frames or refused input batches.

This site

Documentation 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

Biome owns formatting and import order, ESLint owns React hooks and the Next.js rules, tsc owns types. It reads ../protocol/*.txt at build time, so it must be built from inside the repository. It is not part of any app's quality gate; .github/workflows/site.yml runs npm run check:ci and npm run build on it.

Developing

Tests

Every suite reads the same fixtures. None sends real input, opens a real Bluetooth socket, or touches a device.
Run them
cd android && ./gradlew testDebugUnitTest
cd shared && dotnet test --solution Edgepad.Core.slnx
cd windows && dotnet test --solution Edgepad.slnx
cd linux && dotnet test --solution Edgepad.Linux.slnx
cd macos && swift test

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 in shared/Edgepad.Core.Tests for the .NET apps, parse those same files at run time rather than copying them into any codebase; the Mac suite in macos/Tests/EdgepadCoreTests reads them too.

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

Above the fixtures

Android

The gesture recogniser and the whole finger table, assignable actions, natural scrolling, the dials (arming, slop, snapping, steppers, haptic notches), the corner and perimeter geometry, coalescing, round-trip stats, the gamepad layout, the modifier latch and the laptop-state model. 3.0.0 adds ShapesTest for the unistroke matcher, PadAxisTest for the dead zone and the stick scaling, PadModeTest for the lock button's transitions, and GamepadStoreTest for what a name collision costs and what is left playing after a deletion. All pure Kotlin, so it runs with no emulator.

Windows

Input batching, display modes, the level overlay, the media-session title mapping, the signature export and VirtualPadTests. The dispatcher, trust and the macro store are tested in shared/.

Shared core

The dispatcher's drop paths and action table, the handshake and its refusals, trust, the PIN gate and its store, the macro store, the stroke board and the update check. CI runs these on Linux.

Linux

Admission, the PIN entry and the trust prompt, the key map, typing, uinput, the virtual pad, audio, backlight, MPRIS, the per-desktop shortcuts, the macro launcher, annotate and the XDG paths. None of it has been seen working on a Linux laptop.

Mac

The stream reassembler, the key map, the dispatcher's drop paths and action table, the trust store, the handshake and its refusals, and the update-version parsing. Nothing that touches Bluetooth, CGEvent, Core Audio or the display is tested, and none of it has run on a real Mac.

Developing

Contributing

Edgepad is small on purpose. The bar for a change is that it makes the product better for someone using it, and that it passes the same gate CI runs.

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

Get the code
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 apps in step. A protocol change edits protocol/frames.txt or protocol/actions.txt, the codec and enums in shared/, on the phone and on the Mac, and bumps the protocol version on every side — 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 (opens in a new tab) 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 every half, 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 in the Windows app beyond NAudio, System.Management and Nefarius.ViGEm.Client, none in the Linux app beyond Avalonia and Tmds.DBus.Protocol, and none at all on the Mac. 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 (opens in a new tab), not a public issue.

Developing

Releases

Releases are published by the maintainer, and built by CI rather than by hand. A pull request never cuts one: its line under Unreleased ships with the next release.

Each release carries a signed APK and a compressed self-contained exe, named for the version, Edgepad-4.0.0.apk and Edgepad-4.0.0.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. From 3.4.0 a release also carries Edgepad-x.y.z-mac.zip, built by macos/bundle.sh, and from 4.0.0 Edgepad-x.y.z-linux-x64.tar.gz, packed by linux/packaging/pack.sh; both are listed in SHA256SUMS.txt and the provenance attestation.