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
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
758bb618-7b72-4cd3-9aa2-c9b88e54d555Both 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
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
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'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
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
- Unbuffered touch.
View.requestUnbufferedDispatch, with every historical sample read from eachMotionEvent, so events arrive as they happen rather than batched to vsync. - One write per batch. The writer thread sends everything already queued in a single write.
- Coalescing. A backlog of
MOVE,SCROLLandZOOMframes still waiting in the outbox is summed into one before it goes out; only the lastSETper control survives, and only the newestPAD_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.KEYframes 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. - 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
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
| Type | Name | Payload | Direction | Meaning |
|---|---|---|---|---|
| 0x01 | HELLO | magic EDGP, version u8 | phone → laptop | Opens a session. |
| 0x02 | HELLO_ACK | version u8 | laptop → phone | Accepts it. On a version mismatch the laptop sends its own version, then closes, so the phone can say which side needs updating. |
| 0x03 | PIN_REQUEST | attemptsLeft u8, lockedSeconds u16 | laptop → phone | Asks for the PIN, or says the phone is locked out and for how long. Only between the trust question and HELLO_ACK. |
| 0x04 | PIN_ANSWER | six bytes, each 0 to 9 | phone → laptop | The PIN, one digit value per byte rather than ASCII. Only as the answer to PIN_REQUEST; a byte above 9 closes the link. |
| 0x10 | MOVE | dx i16, dy i16 | phone → laptop | Move the pointer, in laptop pixels, before Windows' own pointer acceleration. |
| 0x11 | BUTTON | button u8, down u8 | phone → laptop | 0 left, 1 right, 2 middle. down is 1 or 0. |
| 0x12 | SCROLL | dx i16, dy i16 | phone → laptop | Wheel units. 120 is one notch; positive dy is wheel forward. |
| 0x13 | ZOOM | delta i16 | phone → laptop | Ctrl+wheel units. |
| 0x20 | ACTION | id u8 | phone → laptop | Run one action from the laptop's table. |
| 0x21 | SET | control u8, value u8 | phone → laptop | Set a control to 0-100. The laptop drops anything above 100. |
| 0x22 | KEY | code u16, down u8 | phone → laptop | Press or release one key, by Windows virtual-key code. This is what the phone's keyboard screen sends. |
| 0x23 | PAD_STATE | buttons u16, lt u8, rt u8, lx i16, ly i16, rx i16, ry i16 | phone → laptop | The 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. |
| 0x24 | PEN | x u16, y u16, state u8 | phone → laptop | One 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. |
| 0x30 | PING | t i64 | phone → laptop | The phone's clock, in nanoseconds. |
| 0x31 | PONG | t i64 | laptop → phone | The same value echoed back, which is what the round-trip readout measures. |
| 0x40 | STATE | control u8, value u8, flags u8 | laptop → phone | A control's current value. Flags bit 0 is muted for audio controls, playing for media position. |
| 0x41 | TEXT | kind u8, length u8, UTF-8 bytes | both ways | The only variable-length frame: up to 255 bytes, never split inside a character. |
| 0x50 | FILE_BEGIN | fileType u8, length u8, size u32, UTF-8 name | laptop → phone | Starts 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. |
| 0x51 | FILE_CHUNK | seq u8, length u8, bytes | laptop → phone | Up 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. |
| 0x52 | FILE_END | sha256, 32 bytes | laptop → phone | The SHA-256 of the whole file. The phone keeps the file only if it matches. |
| 0x53 | FILE_RESULT | status u8 | phone → laptop | The phone's answer: 0 saved, 1 bad hash, 2 rejected, 3 write failed. Only 0 lets the laptop delete its copy. |
| 0x54 | BLOB_BEGIN | — | — | In the fixture, not yet described on this page. |
| 0x55 | BLOB_CHUNK | — | — | In the fixture, not yet described on this page. |
| 0x56 | BLOB_END | — | — | In the fixture, not yet described on this page. |
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.
| Frame | Fields | Bytes |
|---|---|---|
| HELLO | 1 | 01 45 44 47 50 01 |
| HELLO | 2 | 01 45 44 47 50 02 |
| HELLO | 3 | 01 45 44 47 50 03 |
| HELLO | 4 | 01 45 44 47 50 04 |
| HELLO | 5 | 01 45 44 47 50 05 |
| HELLO_ACK | 1 | 02 01 |
| PIN_REQUEST | 5 0 | 03 05 00 00 |
| PIN_REQUEST | 2 0 | 03 02 00 00 |
| PIN_REQUEST | 0 30 | 03 00 1e 00 |
| PIN_REQUEST | 0 300 | 03 00 2c 01 |
| PIN_REQUEST | 0 65535 | 03 00 ff ff |
| PIN_ANSWER | 1 2 3 4 5 6 | 04 01 02 03 04 05 06 |
| PIN_ANSWER | 0 0 0 0 0 0 | 04 00 00 00 00 00 00 |
| PIN_ANSWER | 9 9 9 9 9 9 | 04 09 09 09 09 09 09 |
| MOVE | 5 -3 | 10 05 00 fd ff |
| MOVE | -32768 32767 | 10 00 80 ff 7f |
| BUTTON | 0 1 | 11 00 01 |
| BUTTON | 1 0 | 11 01 00 |
| SCROLL | 0 -120 | 12 00 00 88 ff |
| ZOOM | 240 | 13 f0 00 |
| ACTION | 3 | 20 03 |
| ACTION | 35 | 20 23 |
| ACTION | 36 | 20 24 |
| ACTION | 52 | 20 34 |
| ACTION | 53 | 20 35 |
| ACTION | 54 | 20 36 |
| ACTION | 40 | 20 28 |
| ACTION | 56 | 20 38 |
| ACTION | 57 | 20 39 |
| ACTION | 58 | 20 3a |
| ACTION | 59 | 20 3b |
| ACTION | 96 | 20 60 |
| SET | 0 55 | 21 00 37 |
| SET | 1 100 | 21 01 64 |
| SET | 3 50 | 21 03 32 |
| SET | 5 6 | 21 05 06 |
| SET | 6 0 | 21 06 00 |
| SET | 6 1 | 21 06 01 |
| SET | 7 1 | 21 07 01 |
| SET | 7 0 | 21 07 00 |
| SET | 8 20 | 21 08 14 |
| SET | 8 100 | 21 08 64 |
| SET | 9 35 | 21 09 23 |
| SET | 9 100 | 21 09 64 |
| KEY | 65 1 | 22 41 00 01 |
| KEY | 112 0 | 22 70 00 00 |
| KEY | 65535 1 | 22 ff ff 01 |
| PAD_STATE | 0 0 0 0 0 0 0 | 23 00 00 00 00 00 00 00 00 00 00 00 00 |
| PAD_STATE | 0 0 0 -32768 -32768 -32768 -32768 | 23 00 00 00 00 00 80 00 80 00 80 00 80 |
| PAD_STATE | 0 0 0 32767 32767 32767 32767 | 23 00 00 00 00 ff 7f ff 7f ff 7f ff 7f |
| PAD_STATE | 0 255 255 0 0 0 0 | 23 00 00 ff ff 00 00 00 00 00 00 00 00 |
| PAD_STATE | 12305 32 200 -1 1 256 -256 | 23 11 30 20 c8 ff ff 01 00 00 01 00 ff |
| PAD_STATE | 63487 0 0 0 0 0 0 | 23 ff f7 00 00 00 00 00 00 00 00 00 00 |
| PEN | 0 0 1 | 24 00 00 00 00 01 |
| PEN | 65535 65535 0 | 24 ff ff ff ff 00 |
| PEN | 32768 12345 2 | 24 00 80 39 30 02 |
| PEN | 1 2 7 | 24 01 00 02 00 07 |
| PING | 1234567890123 | 30 cb 04 fb 71 1f 01 00 00 |
| PONG | -1 | 31 ff ff ff ff ff ff ff ff |
| STATE | 0 42 1 | 40 00 2a 01 |
| STATE | 3 42 1 | 40 03 2a 01 |
| TEXT | 3 hi | 41 03 02 68 69 |
| TEXT | 1 Song | 41 01 04 53 6f 6e 67 |
| TEXT | 0 | 41 00 00 |
| TEXT | 2 84/227 | 41 02 06 38 34 2f 32 32 37 |
| TEXT | 0 Café | 41 00 05 43 61 66 c3 a9 |
| TEXT | 0 🎵 | 41 00 04 f0 9f 8e b5 |
| TEXT | 0 日本語 | 41 00 09 e6 97 a5 e6 9c ac e8 aa 9e |
| TEXT | 6 0/0/1/AAAA | 41 06 0a 30 2f 30 2f 31 2f 41 41 41 41 |
| TEXT | 7 | 41 07 00 |
| TEXT | 8 ready | 41 08 05 72 65 61 64 79 |
| TEXT | 8 no-driver | 41 08 09 6e 6f 2d 64 72 69 76 65 72 |
| TEXT | 8 attach-failed | 41 08 0d 61 74 74 61 63 68 2d 66 61 69 6c 65 64 |
| TEXT | 9 capture | 41 09 07 63 61 70 74 75 72 65 |
| TEXT | 9 annotate/capture | 41 09 10 61 6e 6e 6f 74 61 74 65 2f 63 61 70 74 75 72 65 |
| TEXT | 10 1920/1080 | 41 0a 09 31 39 32 30 2f 31 30 38 30 |
| TEXT | 11 saved | 41 0b 05 73 61 76 65 64 |
| TEXT | 12 too-large | 41 0c 09 74 6f 6f 2d 6c 61 72 67 65 |
| TEXT | 13 00112233445566778899aabbccddeeff/windows/Desk | 41 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 |
| TEXT | 14 7.12 | 41 0e 04 37 2e 31 32 |
| TEXT | 15 added | 41 0f 05 61 64 64 65 64 |
| TEXT | 16 -012 | 41 10 04 2d 30 31 32 |
| TEXT | 17 FF3B30 | 41 11 06 46 46 33 42 33 30 |
| TEXT | 19 laptop:87:1:Desk|headphones:60:0:AirPods | 41 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 |
| TEXT | 19 | 41 13 00 |
| TEXT | 19 laptop:50:0:Café | 41 13 11 6c 61 70 74 6f 70 3a 35 30 3a 30 3a 43 61 66 c3 a9 |
| TEXT | 20 headphones/AirPods | 41 14 12 68 65 61 64 70 68 6f 6e 65 73 2f 41 69 72 50 6f 64 73 |
| TEXT | 20 speaker/Speakers | 41 14 10 73 70 65 61 6b 65 72 2f 53 70 65 61 6b 65 72 73 |
| FILE_BEGIN | 0 1234 shot.png | 50 00 0c d2 04 00 00 73 68 6f 74 2e 70 6e 67 |
| FILE_BEGIN | 2 209715200 rec.mp4 | 50 02 0b 00 00 80 0c 72 65 63 2e 6d 70 34 |
| FILE_CHUNK | 0 68656c6c6f | 51 00 05 68 65 6c 6c 6f |
| FILE_CHUNK | 255 ff00 | 51 ff 02 ff 00 |
| FILE_END | 2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 | 52 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_RESULT | 0 | 53 00 |
| FILE_RESULT | 1 | 53 01 |
| BLOB_BEGIN | 0 1234 clip | 54 00 08 d2 04 00 00 63 6c 69 70 |
| BLOB_BEGIN | 3 8192 chrome | 54 03 0a 00 20 00 00 63 68 72 6f 6d 65 |
| BLOB_BEGIN | 9 1 x | 54 09 05 01 00 00 00 78 |
| BLOB_CHUNK | 0 68656c6c6f | 55 00 05 68 65 6c 6c 6f |
| BLOB_CHUNK | 255 ff00 | 55 ff 02 ff 00 |
| BLOB_END | 2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 | 56 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 |
TEXT kinds
| Kind | Name | What it means |
|---|---|---|
| 0 | NOW_PLAYING | What is playing. Laptop to phone. |
| 1 | APP | The app playing it. Laptop to phone. |
| 2 | TIMELINE | The timeline as seconds/length, such as 84/227. Laptop to phone. |
| 3 | TYPE | Text to type, where \b is backspace and \n is enter. Phone to laptop. |
| 4 | REFRESH_RATES | The display's available refresh rates as 60/120/144, in the order CONTROL 4 indexes them. Laptop to phone. |
| 5 | MACROS | The laptop's macro names as Chrome/Spotify/Notes, in the order MACRO_BASE indexes them. A blank name keeps its slot. Laptop to phone. |
| 6 | MACRO_ICON | One 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. |
| 7 | WANT_ICONS | Asks for the macro icons, with an empty payload. Sent when the phone opens the macro grid; nothing is pushed unasked. Phone to laptop. |
| 8 | PAD_STATUS | Whether 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. |
| 9 | FEATURES | The 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. |
| 10 | SCREEN_SIZE | The 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. |
| 11 | SIGN_STATUS | How a SIGN_SAVE ended, as one of saved, empty or failed. Laptop to phone. |
| 12 | CAPTURE_STATUS | Why a capture the phone asked for stayed on the laptop, as one of too-large, not-found or failed. Laptop to phone. |
| 13 | DEVICE | In the fixture, not yet described on this page. |
| 14 | APP_ADD | In the fixture, not yet described on this page. |
| 15 | APP_ADD_STATUS | In the fixture, not yet described on this page. |
| 16 | MACRO_OPEN | In the fixture, not yet described on this page. |
| 17 | PEN_RGB | A 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. |
| 18 | INPUT_STATE | In the fixture, not yet described on this page. |
| 19 | BATTERIES | In the fixture, not yet described on this page. |
| 20 | OUTPUT | In the fixture, not yet described on this page. |
PAD_STATUS tokens
| Token | Name | What it means |
|---|---|---|
| ready | READY | The virtual controller is plugged in and PAD_STATE will be acted on. The only token that leaves the pad usable. |
| no-driver | NO_DRIVER | The virtual-controller driver, ViGEmBus, is not installed on the laptop. The pad falls back to keys. |
| attach-failed | ATTACH_FAILED | The driver is there but plugging the pad in did not work. The pad falls back to keys. |
FEATURE tokens
| Token | Name | What it means |
|---|---|---|
| annotate | ANNOTATE | The laptop can show the annotation overlay and a signing surface. The phone shows an Annotate tile only for a laptop that names this. |
| capture | CAPTURE | The laptop can start its own screenshot and screen-recording tools. The phone shows a Capture tile only for a laptop that names this. |
| clipboard | CLIPBOARD | In the fixture, not yet described on this page. |
| apps | APPS | In the fixture, not yet described on this page. |
| running | RUNNING | In the fixture, not yet described on this page. |
SIGN_STATUS tokens
| Token | Name | What it means |
|---|---|---|
| saved | SAVED | The signature was exported to a PNG and put on the clipboard. |
| empty | EMPTY | Nothing had been drawn, so nothing was saved. |
| failed | FAILED | The file could not be saved, or every clipboard route failed. |
The annotation palette
| Index | Name | What it means |
|---|---|---|
| 0 | BLACK | #000000 |
| 1 | WHITE | #FFFFFF |
| 2 | RED | #FF3B30 |
| 3 | ORANGE | #FF9500 |
| 4 | YELLOW | #FFCC00 |
| 5 | GREEN | #34C759 |
| 6 | BLUE | #0068D6 |
| 7 | PURPLE | #AF52DE |
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
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
| Version | Release | Change |
|---|---|---|
| 1 | 0.1.0 | HELLO through STATE. TEXT kinds 0 and 1 arrived in 0.2.0 without a bump. |
| 2 | 0.3.0 | TEXT kind 2. A mismatch is refused with the laptop's version. |
| 3 | 0.6.0 | TEXT 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. |
| 4 | 3.0.0 | PAD_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. |
| 5 | 4.0.0 | PIN_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 actions
| Id | Name | What it means |
|---|---|---|
| 1 | MUTE_TOGGLE | Mute key. |
| 2 | PLAY_PAUSE | Media play/pause key. |
| 3 | NEXT_TRACK | Media next key. |
| 4 | PREVIOUS_TRACK | Media previous key. |
| 5 | MIC_MUTE_TOGGLE | Toggles the default microphone's mute. |
| 6 | LOCK | LockWorkStation. Win+L cannot be injected. |
| 20 | TASK_VIEW | Win+Tab. |
| 21 | SHOW_DESKTOP | Win+D. |
| 22 | SEARCH | Win+S. |
| 23 | NOTIFICATIONS | Win+N. |
| 24 | DESKTOP_LEFT | Win+Ctrl+Left. |
| 25 | DESKTOP_RIGHT | Win+Ctrl+Right. |
| 26 | APP_SWITCH_BEGIN | Holds Alt and presses Tab. Alt stays down until APP_SWITCH_END or the session ends. |
| 27 | APP_SWITCH_NEXT | Tab, only while Alt is held. |
| 28 | APP_SWITCH_PREVIOUS | Shift+Tab, only while Alt is held. |
| 29 | APP_SWITCH_END | Releases Alt. |
| 30 | ZOOM_RESET | Ctrl+0. |
| 31 | VOLUME_UP | Volume-up key. |
| 32 | VOLUME_DOWN | Volume-down key. |
| 33 | BRIGHTNESS_UP | The panel's brightness, plus 10. |
| 34 | BRIGHTNESS_DOWN | The panel's brightness, minus 10. |
| 35 | PAD_ATTACH | Asks 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. |
| 36 | PAD_DETACH | Asks the laptop to unplug the virtual controller. Sent when the gamepad screen closes; the laptop also unplugs it by itself when the session ends. |
| 40 | ANNOTATE_BEGIN | Shows 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. |
| 41 | ANNOTATE_END | Removes the overlay and discards its strokes. A session ending does the same. |
| 42 | ANNOTATE_UNDO | Removes the last stroke. |
| 43 | ANNOTATE_CLEAR | Removes every stroke. |
| 44 | TOOL_PEN | The next stroke is a pen line, 0.4% of the screen height wide. |
| 45 | TOOL_HIGHLIGHTER | The 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. |
| 46 | TOOL_LINE | The next stroke is a straight line from the down point to the latest move. |
| 47 | TOOL_ARROW | As the line, with an arrow head four times the pen width at the end. |
| 48 | TOOL_RECTANGLE | The next stroke is a rectangle from the down point to the latest move. |
| 49 | TOOL_ELLIPSE | The next stroke is an ellipse from the down point to the latest move. |
| 50 | SIGN_BEGIN | Opens a signing surface that shows nothing on the laptop and accepts only the pen tool. |
| 51 | SIGN_SAVE | Exports 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. |
| 52 | CAPTURE_REGION | Starts 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. |
| 53 | CAPTURE_SCREEN | Takes a screenshot of the whole screen: PrtScn on Windows, Cmd+Shift+3 on a Mac, Print on Linux. |
| 54 | CAPTURE_RECORD | Starts 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). |
| 55 | CAPTURE_CANCEL | Sent 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). |
| 56 | APPS_LIST | In the fixture, not yet described on this page. |
| 57 | APPS_CANCEL | In the fixture, not yet described on this page. |
| 64 | MACRO_BASE | The 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. |
| 58 | MACROS_WATCH | In the fixture, not yet described on this page. |
| 59 | MACROS_UNWATCH | In the fixture, not yet described on this page. |
| 96 | MACRO_CLOSE_BASE | In the fixture, not yet described on this page. |
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
| Id | Name | What it means |
|---|---|---|
| 0 | VOLUME | SET sets the default speakers' level; STATE reports the level and a muted flag. |
| 1 | BRIGHTNESS | SET sets the built-in panel's brightness through WMI; STATE reports the level. |
| 2 | MIC_LEVEL | SET sets the default microphone's level; STATE reports the level and a muted flag. |
| 3 | MEDIA_POSITION | SET seeks the current track to that percent, where the player allows it; STATE reports the percent and a playing flag. |
| 4 | REFRESH_RATE | SET 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. |
| 5 | PEN_COLOR | SET 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. |
| 6 | CAPTURE_TARGET | Where 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. |
| 7 | CLIPBOARD | In the fixture, not yet described on this page. |
| 8 | PEN_WIDTH | SET 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. |
| 9 | PEN_OPACITY | SET 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. |
Gamepad buttons
| Mask | Name | What it means |
|---|---|---|
| 0 | NONE | Nothing held. What PAD_STATE carries the moment the last button comes up. |
| 1 | DPAD_UP | D-pad up. |
| 2 | DPAD_DOWN | D-pad down. |
| 4 | DPAD_LEFT | D-pad left. |
| 8 | DPAD_RIGHT | D-pad right. |
| 16 | START | Start, the menu button. |
| 32 | BACK | Back, the view button. |
| 64 | LEFT_THUMB | Left stick pressed in. |
| 128 | RIGHT_THUMB | Right stick pressed in. |
| 256 | LEFT_SHOULDER | Left bumper. |
| 512 | RIGHT_SHOULDER | Right bumper. |
| 1024 | GUIDE | The Xbox button. |
| 4096 | A | A. |
| 8192 | B | B. |
| 16384 | X | X. |
| 32768 | Y | Y. |
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
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%\Edgepadon Windows, under~/Library/Application Support/Edgepadon 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.exeis 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
| Path | What |
|---|---|
| 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.
| Package | What | Testable |
|---|---|---|
| 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.
| Folder | What | Testable |
|---|---|---|
| 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
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
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 codeIt 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
| Half | Step | Local / CI |
|---|---|---|
| android | Kotlin formatting | ktlintFormat / ktlintCheck |
| android | Android lint, then the unit tests | same |
| core | C# formatting, build, then test | same commands as windows, on shared/ |
| windows | C# formatting | dotnet format / --verify-no-changes |
| windows | Build, then test | dotnet build -warnaserror; dotnet test |
| linux | C# formatting, build, then test | same commands as windows, on linux/ |
| macos | Swift formatting | swift format lint --strict |
| macos | Build, then test | swift 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
Laptop
dotnet run --project windows/src/EdgepadIt must already be running before the phone tries to connect: there is no discovery or retry on the laptop side, only the phone reconnects.
dotnet publish windows/src/Edgepad -c Release -r win-x64 --self-contained \
-p:PublishSingleFile=true \
-p:IncludeNativeLibrariesForSelfExtract=true \
-p:EnableCompressionInSingleFile=trueA self-contained single file, the same shape a release ships. Compression takes it from roughly 143 MB to 58.5 MB.
cd windows && dotnet build Edgepad.slnx -c ReleaseLinux
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.gzThe 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
cd macos && swift run
bash macos/bundle.sh 0.0.0-dev outswift 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
cd android && ./gradlew installDebugUninstall 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.
cd android && ./gradlew assembleDebugTogether
- Pair the phone with the laptop in its Bluetooth settings.
- Start the tray app with
dotnet run, orswift runon a Mac. - Install and open the phone app, then tap the laptop.
- 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
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-mutatingBiome 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
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 testThe 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
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- Bring your fork's
mainup to date withupstream/main, then branch from it on your fork. - Keep the apps in step. A protocol change edits
protocol/frames.txtorprotocol/actions.txt, the codec and enums inshared/, on the phone and on the Mac, and bumps the protocol version on every side — all in one commit. - 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.
- Run
pwsh scripts/check.ps1until it is clean. - Commit with a Conventional Commits (opens in a new tab) subject and a body saying what changed and why, including what you rejected.
- Add a line under Unreleased in
CHANGELOG.md. - Push the branch to your fork and open a pull request against
mainhere. CI runs the same gate on every half, and the site's gate whensite/orprotocol/changed. The maintainer reviews and merges.
Style
- No UI libraries on the phone. No third-party packages in the Windows app beyond NAudio,
System.ManagementandNefarius.ViGEm.Client, none in the Linux app beyond Avalonia andTmds.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
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.