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)