API Control

API calls…

You can control microM8 using an HTTP-based API. You make API calls to port 38911 and you need to start up microM8 with the -control-port command-line flag. If you would like to start microM8 without an application frame you can add the -disable-border flag.

POST /api/control/window/position

  • Handler: HandlePositionRequest
  • Purpose: Set Window position and size.
  • Payload: JSON: 
    { 
    "x": number, 
    "y": number, 
    "w": number, 
    "h": number 
}

POST /api/control/input/keyevent

  • Handler: HandleKeyRequest
  • Purpose: Notify a keypress/release event.
  • Payload: JSON: 
    {
    "key": number,                // microM8 keycode
    "scancode": number,           // scancode (reserved)
    "action": number,             // 1 = Press, 0 = Release
    "modifier": number            // 1 = Shift, 2 = Ctrl, 4 = Alt
}

GET /api/control/window/hide

  • Handler: HandleHideRequest
  • Purpose: Hide microM8 window and suspend execution.
  • Payload: (none)

GET /api/control/window/show

  • Handler: HandleShowRequest
  • Purpose: Show microM8 window and resume execution.
  • Payload: (none)

GET /api/control/system/reboot

  • Handler: HandleRebootRequest
  • Purpose: Reboot the current VM.
  • Payload: (none)

POST /api/control/window/screen

  • Handler: HandleScreenRequest
  • Purpose: Write current screen in PNG to supplied filename.
  • Payload: JSON: 
    {
    "path": string,              // png file path
}

GET /api/control/window/focused

  • Handler: HandleFocusedRequest
  • Purpose: Return main window focus state.
  • Payload: (none)
  • Returns: 1 if focussed, 0 if not focussed.

POST /api/control/hardware/disk/insert

  • Handler: HandleDiskInsertRequest
  • Purpose: Insert a disk image.
  • Payload: JSON: 
    {
    "path": string,              // disk image file path
    "drive": number              // drive number (0/1 = Disk II, 2 = SmartPort)
}

GET /api/control/hardware/disk/eject/{drive}

  • Handler: HandleDiskEjectRequest
  • Purpose: Eject disk in drive {drive}
  • Payload: (none)

GET /api/control/hardware/disk/blank/{drive}

  • Handler: HandleDiskBlankRequest
  • Purpose: Insert blank unformatted disk in drive {drive} (0/1 only)
  • Payload: (none)

GET /api/control/system/catalog

  • Handler: HandleCatalogRequest
  • Purpose: Launch microM8 catalog function.
  • Payload: (none)

GET /api/control/interpreter/{name} (fp, int or logo)

  • Handler: HandleInterpRequest
  • Purpose: Start microM8 interpreter {name} in this VM.
  • Payload: (none)

GET /api/control/input/meta/key/{key}/value/{value}

  • Handler: HandleMetaKeyRequest
  • Purpose: Simulate a meta key combination (Eg. Ctrl+Shift+{key}, then {value})
  • Payload: (none)

POST /api/control/settings/update

  • Handler: HandleSettingsUpdateRequest
  • Purpose: Update (and optionally persist) a runtime setting.
  • Payload: JSON: 
    {
    "path": string,              // settings path: Eg. "current.fullscreen"
    "scope": string,             // settings scope: Eg. "video"
    "value": string,             // value
    "persist": number            // 0 = false, 1 = true (save to defaults)
}

POST /api/control/settings/get

  • Handler: HandleSettingsFetchRequest
  • Purpose: Get value of runtime setting.
  • Returns: value.
  • Payload: JSON: 
    {
    "path": string,              // settings path: Eg. "current.fullscreen"
    "scope": string,             // settings scope: Eg. "video"
}

POST /api/control/input/mouseevent

  • Handler: HandleMouseRequest
  • Purpose: Update mouse position within window.
  • Payload: JSON: 
    {
    "x": number,                  // x mouse position (relative to window)
    "y": number,                  // y mouse position (relative to window)
}

GET /api/control/hardware/disk/swap

  • Handler: HandleDiskSwapRequest
  • Purpose: Swap disks in drive 0 and drive 1.
  • Payload: (none)

GET /api/control/system/profile/set/{profile} (apple2-plus, apple2e, apple2e-en, apple2e-en-cpm)

  • Handler: HandleProfileSetRequest
  • Purpose: Reboot VM into the specified system profile.
  • Payload: (none)

GET /api/control/system/profile/get

  • Handler: HandleProfileGetRequest
  • Purpose: Return current system profile.
  • Returns: profilename
  • Payload: (none)

POST /api/control/system/freeze/restore

  • Handler: HandleFreezeRestoreRequest
  • Purpose: Restore VM state from a freeze state.
  • Payload: JSON: 
    {
    "path": string,                  // freeze path
}

POST /api/control/system/freeze/save

  • Handler: HandleFreezeSaveRequest
  • Purpose: Save VM state to a freeze state.
  • Payload: JSON: 
    {
    "path": string,                  // freeze path
}

GET /api/control/recorder/{action}

  • Handler: HandleRecordingRequest
  • Purpose: Perform recorder {action}:-
start-file-recording  Begin file based recording.
start-live-recording  Begin memory based recording.
stop-recording        Stop recording.
rewind                Rewind recording.
play                  Forward recording.
resume                Resume execution.
  • Payload: (none)

GET /api/control/recorder

  • Handler: HandleRecordingRequest
  • Purpose: Return recorder state.
  • Returns: 0 if not recording, 1 if live rewind enabled, 2 if file recording.
  • Payload: (none)

POST /api/control/system/launch

  • Handler: HandleLaunchRequest
  • Purpose: Launch a program or action.
  • Payload: JSON: 
    {
  workingDir: string,     // Eg. /local
  disks      []string,    // floppy disks
  pakfile    string,      // microPak file
  smartport  string,      // smartport volume
  runfile    string,      // basic, shell or logo file
  runcommand string,      // basic, shell or logo command
  dialect    string       // dialect for runfile/runcommand
}

GET /api/control/quit

  • Handler: HandleQuit
  • Purpose: Stop microM8.
  • Payload: (none)

GET /api/control/health

  • Handler: HandleAlive
  • Purpose: Returns “ok” if microM8 responsive.
  • Payload: (none)

GET /api/control/audio/{channel}/{action}

  • Handler: HandleAudioRequest
  • Purpose: Perform {action} on audio channel {channel}.
channel    One of "master" or "speaker". 
action     One of "up" or "down".
  • Payload: (none)

GET /api/control/cpu/warp/{action}

  • Handler: HandleCPURequest
  • Purpose: Perform {action} on CPU warp level.
action     One of "up" or "down".
  • Payload: (none)

GET /api/control/pause

  • Handler: HandlePauseRequest
  • Purpose: Toggle VM Paused state.
  • Payload: (none)

GET /api/control/mouse/buttonstate

  • Handler: HandleMBRequest
  • Purpose: Read mousebutton state.
  • Returns: 0 = none, 1 = left, 2 = right, 4 = middle
  • Payload: (none)

GET /api/control/mouse/buttonstate/{state}

  • Handler: HandleMBRequest
  • Purpose: Set mouse button state to {state}.
0 = none
1 = left
2 = right
4 = middle
  • Payload: (none)

GET /api/control/vm

  • Handler: HandleVMRequest
  • Purpose: Get the current vm number (1-8).
  • Returns: 1-8
  • Payload: (none)

GET /api/control/vm/{vm}

  • Handler: HandleVMRequest
  • Purpose: Set the current VM number (1-8)
  • Payload: (none)

GET /api/control/system/help

  • Handler: HandleHelpRequest
  • Purpose: Launch help system.
  • Payload: (none)

GET /api/control/window/screenshot

  • Handler: HandleShotRequest
  • Purpose: Take a screenshot.
  • Payload: (none)

GET /api/control/hardware/disk/wp/{drive}

  • Handler: HandleDiskWPRequest
  • Purpose: Read write protect state of {drive}.
  • Returns: 0 = not write protected, 1 = write protected
  • Payload: (none)

GET /api/control/hardware/disk/wp/{drive}/{verb}

  • Handler: HandleDiskWPRequest
  • Purpose: Perform {verb} on drives write protect state.
toggle    Toggles write protect.
  • Returns: 0 = not write protected, 1 = write protected
  • Payload: (none)

POST /api/control/paste

  • Handler: HandlePasteRequest
  • Purpose: Paste text into VM.
  • Payload: TEXT

GET /api/control/memory/read/{address}

  • Handler: HandleMemoryReadRequest
  • Purpose: Read value from VM memory {address}
  • Returns: value
  • Payload: (none)

GET /api/control/memory/write/{address}/{value}

  • Handler: HandleMemoryWriteRequest
  • Purpose: Write {value} to VM memory {address}
  • Payload: (none)

GET /api/control/memory/screen/text

  • Handler: HandleTextScreenRequest
  • Purpose: Returns content of active text screen.
  • Payload: (none)

POST /api/control/osd/send

  • Handler: HandleOSDRequest
  • Purpose: Send OSD message.
  • Payload: TEXT

GET /api/control/system/camera/{action}

  • Handler: HandleCameraRequest
  • Purpose: Perform action {action} on camera.
reset   Reset camera to defaults.
  • Payload: (none)

GET /api/control/mouse/buttonclick

  • Handler: HandleButtonClickRequest
  • Purpose: Simulate a left mouse button press and release.
  • Payload: (none)