Skip to content

V2

Jump to bottom
christian-photo edited this page Dec 27, 2024 · 40 revisions 
http://<ip>:<port>/v2/

This documentation is outdated for plugin version >= 2.1.0.0 The new documentation is available here (api) and here (websockets)

Version

http://<ip>:<port>/v2/api/version

Returns the version of the V2 API, V1 and V2 version numbers are independent of one another

Equipment

Note: Due to limitations in the api provided by NINA, it is not (yet?) possible to specify which device to connect to / switch devices

Camera

http://<ip>:<port>/v2/api/equipment/camera/{action}

This endpoint provides the following required route parameter:

  • action:
    • connect: performs a rescan before connecting to the previously connected camera, if not already connected
    • disconnect: disconnects the camera
    • abort-exposure: aborts a currently running exposure if there is one
    • capture: Captures (and solves if requested) and image
    • info: returns information about the camera

Optional URL parameters (only needed for capture):

  • solve (bool): determines if the image should be solved or not
  • duration (double): specifies the exposure time
  • getResult (bool): This returns the image (and if solved, the platesolve result) when the capture (and solving) task is finished
  • resize (bool), used together with size to resize an image
  • size, specifies the new image dimensions (requires resize to be true) in the following format: <width>x<height>
  • quality, specifies the jpg quality of the returned image (-1 returns a png)

These can have the following responses (provided they are successful)

action Response
connect Camera connected
disconnect Camera disconnected
abort-exposure Exposure aborted or Camera not exposing or Camera not connected as Error with StatusCode 409
capture The capture result (see below) or Capture started or Capture already in progress or Camera not connected as Error with StatusCode 409 or Camera currently exposing as Error with StatusCode 409 or No capture processed as Error with StatusCode 409
unknown Unknown action in Error, with StatusCode 400
Capture

Note: If the image wasn't solved, the "Platesolve" field is missing.

{
  "Response": {
    "Platesolve": {
      "SolveTime": "2024-08-15T18:27:19.5702457+02:00",
      "Orientation": 89.92822656826866,
      "PositionAngle": 270.07177343173134,
      "Pixscale": 6.891310190786149,
      "Radius": 3.903996512523301,
      "Coordinates": {
        "RA": 0.7201166013695368,
        "RAString": "00:43:12",
        "RADegrees": 10.801749020543053,
        "Dec": 41.2062853500786,
        "DecString": "41° 12' 23\"",
        "Epoch": 2,
        "DateTime": {
          "Now": "2024-08-15T18:27:51.2030373+02:00",
          "UtcNow": "2024-08-15T16:27:51.2030394Z",
          "MinValue": "0001-01-01T00:00:00",
          "MaxValue": "9999-12-31T23:59:59.9999999"
        }
      },
      "Flipped": false,
      "Success": true,
      "RaErrorString": "--",
      "RaPixError": "NaN",
      "DecPixError": "NaN",
      "DecErrorString": "--",
      "Separation": null
    },
    "Image": "<Your image>"
  },
  "Error": "",
  "StatusCode": 200,
  "Success": true,
  "Type": "API"
}
Camera info 
{
  "Response": {
    "DewHeaterOn": false,
    "SubSampleX": 0,
    "DefaultOffset": 0,
    "GainMax": 10000,
    "CameraState": -1,
    "XSize": 640,
    "LiveViewEnabled": false,
    "CanSubSample": false,
    "SubSampleY": 0,
    "DisplayName": "N.I.N.A. Simulator Camera",
    "ElectronsPerADU": "NaN",
    "GainMin": 0,
    "CoolerOn": false,
    "Gain": 0,
    "Gains": [],
    "OffsetMin": 0,
    "BinX": 1,
    "HasShutter": false,
    "CanSetTemperature": false,
    "ReadoutModes": [
      "Default"
    ],
    "Battery": -1,
    "OffsetMax": 1000,
    "ReadoutModeForNormalImages": 0,
    "DriverVersion": null,
    "CoolerPower": "NaN",
    "PixelSize": 3.8,
    "USBLimit": 0,
    "YSize": 480,
    "DeviceId": "4C0BBF74-0D95-41F6-AAD8-D6D58668CF2C",
    "USBLimitMin": 0,
    "BayerOffsetX": 0,
    "ExposureEndTime": "2024-08-06T12:13:03.2513401+02:00",
    "CanGetGain": true,
    "CanSetUSBLimit": true,
    "SensorType": 0,
    "USBLimitMax": 100,
    "SubSampleWidth": 0,
    "TemperatureSetPoint": "NaN",
    "BinningModes": [
      {
        "X": 1,
        "Y": 1
      }
    ],
    "SupportedActions": [],
    "ReadoutMode": 0,
    "ExposureMax": 1.7976931348623157e+308,
    "Offset": 0,
    "BayerOffsetY": 0,
    "Connected": true,
    "ExposureMin": 0,
    "SubSampleHeight": 0,
    "CanSetGain": true,
    "DefaultGain": 0,
    "IsSubSampleEnabled": false,
    "Temperature": "NaN",
    "LastDownloadTime": 0.0059787,
    "ReadoutModeForSnapImages": 0,
    "Description": null,
    "HasDewHeater": true,
    "CanSetOffset": true,
    "BitDepth": 16,
    "DriverInfo": null,
    "Name": "N.I.N.A. Simulator Camera",
    "IsExposing": false,
    "CanShowLiveView": true,
    "BinY": 1
  },
  "Error": "",
  "StatusCode": 200,
  "Success": true,
  "Type": "API"
}

Mount

http://<ip>:<port>/v2/api/equipment/mount/{action}

This endpoint provides the following required route parameter:

  • action:
    • connect: performs a rescan before connecting to the previously connected mount, if not already connected
    • disconnect: disconnects the mount
    • park: orders the mount to park, returns when the park is successfully issued
    • unpark: orders the mount to unpark, returns when the unpark is successfully issued
    • info: returns information about the mount

These can have the following responses (provided they are successful)

action Response
connect Mount connected
disconnect Mount disconnected
park Mount already parked or Parking or Mount not connected as Error with StatusCode 409
unpark Mount not parked or Unparking or Mount not connected as Error with StatusCode 409
unknown Unknown action in Error, with StatusCode 400
Mount info 
{
  "Response": {
    "TrackingRate": {
      "TrackingMode": 5,
      "CustomRightAscensionRate": null,
      "CustomDeclinationRate": null
    },
    "IsPulseGuiding": false,
    "SiteLatitude": 4.482748294,
    "Declination": 1.9445019937538122,
    "GuideRateRightAscensionArcsecPerSec": 15.041068619585433,
    "Description": null,
    "DisplayName": "Simulator",
    "TrackingModes": [
      0,
      1,
      2,
      3,
      4,
      5
    ],
    "AzimuthString": "256° 57' 31\"",
    "HoursToMeridianString": "24:00:00",
    "PrimaryAxisRates": [
      {
        "Item1": 0,
        "Item2": 8
      }
    ],
    "SideOfPier": -1,
    "DriverInfo": null,
    "CanSetPark": true,
    "TargetSideOfPier": null,
    "UTCDate": "2024-08-06T10:18:48.717",
    "Connected": true,
    "CanMovePrimaryAxis": true,
    "AltitudeString": "13° 26' 08\"",
    "GuideRateDeclinationArcsecPerSec": 15.041068619585433,
    "TargetCoordinates": null,
    "CanFindHome": true,
    "Azimuth": 256.958651496096,
    "CanMoveSecondaryAxis": true,
    "SiteLongitude": 8.48283837461,
    "RightAscensionString": "03:07:27",
    "Slewing": false,
    "SupportedActions": [],
    "CanPulseGuide": true,
    "Coordinates": {
      "RA": 3.1240425363796707,
      "RAString": "03:07:27",
      "RADegrees": 46.86063804569506,
      "Dec": 1.9445019937538122,
      "DecString": "01° 56' 40\"",
      "Epoch": 0,
      "DateTime": {
        "Now": "2024-08-06T12:18:48.5531348+02:00",
        "UtcNow": "2024-08-06T10:18:48.553233Z",
        "MinValue": "0001-01-01T00:00:00",
        "MaxValue": "9999-12-31T23:59:59.9999999"
      }
    },
    "SiteElevation": 110,
    "SecondaryAxisRates": [
      {
        "Item1": 0,
        "Item2": 8
      }
    ],
    "TimeToMeridianFlip": 24,
    "CanPark": true,
    "SiderealTimeString": "07:53:17",
    "CanSetPierSide": false,
    "EquatorialSystem": 0,
    "CanSetRightAscensionRate": true,
    "HasUnknownEpoch": false,
    "AtPark": false,
    "AlignmentMode": 1,
    "SiderealTime": 7.887960053767035,
    "RightAscension": 3.1240425363796707,
    "TimeToMeridianFlipString": "24:00:00",
    "DriverVersion": null,
    "CanSetDeclinationRate": true,
    "CanSlew": true,
    "Altitude": 13.4356807384605,
    "CanSetTrackingEnabled": true,
    "AtHome": false,
    "TrackingEnabled": false,
    "DeclinationString": "01° 56' 40\"",
    "DeviceId": "ScopeSim.Telescope",
    "Name": "Simulator"
  },
  "Error": "",
  "StatusCode": 200,
  "Success": true,
  "Type": "API"
}

Focuser

http://<ip>:<port>/v2/api/equipment/focuser/{action}

This endpoint provides the following required route parameter:

  • action:
    • connect: performs a rescan before connecting to the previously connected focuser, if not already connected
    • disconnect: disconnects the focuser
    • move (releases with 2.0.1.0): moves the focuser to the specified (absolute) position
    • auto-focus: issues an autofocus run with the current filter
    • info: returns information about the focuser

These can have the following responses (provided they are successful)

action Response
connect Focuser connected
disconnect Focuser disconnected
move Move started
auto-focus Autofocus started or Focuser not connected as Error with StatusCode 409
unknown Unknown action in Error, with StatusCode 400
Focuser info 
{
  "Response": {
    "TempComp": false,
    "Name": "Simulator",
    "DeviceId": "FocusSim.Focuser",
    "SupportedActions": [],
    "DriverInfo": "",
    "DriverVersion": "",
    "IsSettling": false,
    "IsMoving": false,
    "Position": 20000,
    "Temperature": 0.440000000000004,
    "StepSize": 40,
    "Description": "",
    "TempCompAvailable": true,
    "Connected": true,
    "DisplayName": "Simulator"
  },
  "Error": "",
  "StatusCode": 200,
  "Success": true,
  "Type": "API"
}

Rotator

http://<ip>:<port>/v2/api/equipment/rotator/{action}

This endpoint provides the following required route parameter:

  • action:
    • connect: performs a rescan before connecting to the previously connected rotator, if not already connected
    • disconnect: disconnects the rotator
    • move: rotates to the specified position
    • move-mechanical: rotatest to the specified mechanical position
    • info: returns information about the rotator

Optional URL parameter:

  • position (float), used for rotating

These can have the following responses (provided they are successful)

action Response
connect Rotator connected
disconnect Rotator disconnected
move Rotator move started or Rotator not connected as Error with StatusCode 409
move-mechanical Rotator move started or Rotator not connected as Error with StatusCode 409
unknown Unknown action in Error, with StatusCode 400
Rotator info 
{
  "Response": {
    "DriverInfo": "ASCOM.Simulator.Rotator",
    "MechanicalPosition": 5,
    "Reverse": false,
    "DeviceId": "ASCOM.Simulator.Rotator",
    "SupportedActions": [],
    "Name": "Rotator Simulator .NET",
    "DriverVersion": "6.6",
    "Synced": false,
    "IsMoving": false,
    "Position": 5,
    "StepSize": 0.75,
    "Description": "ASCOM Rotator Driver for RotatorSimulator",
    "CanReverse": true,
    "Connected": true,
    "DisplayName": "Rotator Simulator .NET"
  },
  "Error": "",
  "StatusCode": 200,
  "Success": true,
  "Type": "API"
}

Filterwheel

http://<ip>:<port>/v2/api/equipment/filterwheel/{action}

This endpoint provides the following required route parameter:

  • action:
    • connect: performs a rescan before connecting to the previously connected filterwheel, if not already connected
    • disconnect: disconnects the filterwheel
    • info: returns information about the filterwheel

These can have the following responses (provided they are successful)

action Response
connect Filterwheel connected
disconnect Filterwheel disconnected
unknown Unknown action in Error, with StatusCode 400
Filterwheel info 
{
  "Response": {
    "SelectedFilter": {
      "_name": "Filter 1",
      "_focusOffset": 0,
      "_position": 1,
      "_autoFocusExposureTime": -1,
      "_autoFocusFilter": false,
      "FlatWizardFilterSettings": {
        "FlatWizardMode": 0,
        "HistogramMeanTarget": 0.5,
        "HistogramTolerance": 0.1,
        "MaxFlatExposureTime": 30,
        "MinFlatExposureTime": 0.01,
        "MaxAbsoluteFlatDeviceBrightness": 1,
        "MinAbsoluteFlatDeviceBrightness": 0,
        "Gain": -1,
        "Offset": -1,
        "Binning": {
          "X": 1,
          "Y": 1
        }
      },
      "_autoFocusBinning": {
        "X": 1,
        "Y": 1
      },
      "_autoFocusGain": -1,
      "_autoFocusOffset": -1
    },
    "Name": "Simulator",
    "DriverInfo": "",
    "DisplayName": "Simulator",
    "IsMoving": false,
    "Description": "",
    "SupportedActions": [],
    "Connected": true,
    "DriverVersion": "",
    "DeviceId": "FilterWheelSim.FilterWheel"
  },
  "Error": "",
  "StatusCode": 200,
  "Success": true,
  "Type": "API"
}

Dome

http://<ip>:<port>/v2/api/equipment/dome/{action}

This endpoint provides the following required route parameter:

  • action:
    • connect: performs a rescan before connecting to the previously connected dome, if not already connected
    • disconnect: disconnects the dome
    • open: issues the dome shutter to open
    • close: issues the dome shutter to close
    • stop: issues the dome shutter to stop movement, only works if the movement was started using the api
    • info: returns information about the dome

These can have the following responses (provided they are successful)

action Response
connect Dome connected
disconnect Dome disconnected
open Shutter opening or Shutter already open or Dome not connected as Error with StatusCode 409
close Shutter closing or Shutter already closed or Dome not connected as Error with StatusCode 409
stop Movement stopped or Dome not connected as Error with StatusCode 409
unknown Unknown action in Error, with StatusCode 400
Dome info 
{
  "Response": {
    "ShutterStatus": 0,
    "AtHome": false,
    "CanSetAzimuth": true,
    "Azimuth": 180,
    "CanPark": true,
    "Name": "Simulator",
    "DeviceId": "DomeSim.Dome",
    "CanSyncAzimuth": true,
    "CanSetPark": true,
    "SupportedActions": [],
    "Slewing": false,
    "DriverVersion": "",
    "AtPark": true,
    "CanFindHome": true,
    "DriverInfo": "ASCOM Dome Simulator 5.0.8\r\nDeveloped by Jon Brewster\r\nhttp://ascom-standards.org/  ",
    "Description": "ASCOM Dome Simulator",
    "DriverFollowing": false,
    "DriverCanFollow": false,
    "CanSetShutter": true,
    "Connected": true,
    "DisplayName": "Simulator"
  },
  "Error": "",
  "StatusCode": 200,
  "Success": true,
  "Type": "API"
}

Switch

http://<ip>:<port>/v2/api/equipment/switch/{action}

This endpoint provides the following required route parameter:

  • action:
    • connect: performs a rescan before connecting to the previously connected switch, if not already connected
    • disconnect: disconnects the switch
    • set: sets the value of a writeable switch
    • info: returns information about the switch

URL parameters:

  • index (int): the index of the switch that should be written
  • value (double): the value to set the switch to

These can have the following responses (provided they are successful)

action Response
connect Switch connected
disconnect Switch disconnected
set Switch value updated
unknown Unknown action in Error, with StatusCode 400
Switch info 
{
  "Response": {
    "SupportedActions": [
      "OCHTag",
      "OCHTestPowerReport"
    ],
    "DriverInfo": "Switch V2 Simulator, version: 6.6.2.4195",
    "Description": "ASCOM SwitchV2 Simulator Driver.",
    "DriverVersion": "6.6",
    "DisplayName": "ASCOM SwitchV2 Simulator Driver",
    "Connected": true,
    "WritableSwitches": [
      {
        "Maximum": 1,
        "Minimum": 0,
        "StepSize": 1,
        "TargetValue": 0,
        "Id": 9,
        "Name": "Raining",
        "Description": "Rain monitor, true if raining",
        "Value": 0
      }
    ],
    "DeviceId": "ASCOM.Simulator.Switch",
    "Name": "ASCOM SwitchV2 Simulator Driver",
    "ReadonlySwitches": [
      {
        "Id": 0,
        "Name": "Power1",
        "Description": "Generic power switch",
        "Value": 0
      },
      {
        "Id": 1,
        "Name": "Power2",
        "Description": "Generic Power switch",
        "Value": 0
      },
      {
        "Id": 2,
        "Name": "Light Box",
        "Description": "Light box , 0 to 100%",
        "Value": 0
      },
      {
        "Id": 3,
        "Name": "Flat Panel",
        "Description": "Flat panel , 0 to 255",
        "Value": 0
      },
      {
        "Id": 4,
        "Name": "Scope Cover",
        "Description": "Scope cover control true is closed, false is open",
        "Value": 0
      },
      {
        "Id": 5,
        "Name": "Scope Parked",
        "Description": "Scope parked switch, true if parked",
        "Value": 0
      },
      {
        "Id": 6,
        "Name": "Cloudy",
        "Description": "Cloud monitor: 0=clear, 1=light cloud, 2= heavy cloud",
        "Value": 0
      },
      {
        "Id": 7,
        "Name": "Temperature",
        "Description": "Temperature in deg C",
        "Value": 12
      },
      {
        "Id": 8,
        "Name": "Humidity",
        "Description": "Relative humidity %",
        "Value": 50
      }
    ]
  },
  "Error": "",
  "StatusCode": 200,
  "Success": true,
  "Type": "API"
}

Guider

http://<ip>:<port>/v2/api/equipment/guider/{action}

This endpoint provides the following required route parameter:

  • action:
    • connect: performs a rescan before connecting to the previously connected guider, if not already connected
    • disconnect: disconnects the guider
    • start: issues the guider to start
    • stop: issues the guider to stop
    • info: returns information about the guider

These can have the following responses (provided they are successful)

action Response
connect Guider connected
disconnect Guider disconnected
start Guiding started or Guider not connected as Error with StatusCode 409
stop Guiding stopped or Guider not connected as Error with StatusCode 409
unknown Unknown action in Error, with StatusCode 400
Guider info 
{
  "Response": {
    "RMSError": {
      "RA": {
        "Pixel": 0,
        "Arcseconds": 0
      },
      "Dec": {
        "Pixel": 0,
        "Arcseconds": 0
      },
      "Total": {
        "Pixel": 0,
        "Arcseconds": 0
      },
      "PeakRA": {
        "Pixel": 0,
        "Arcseconds": 0
      },
      "PeakDec": {
        "Pixel": 0,
        "Arcseconds": 0
      }
    },
    "PixelScale": 0,
    "Name": "PHD2",
    "DeviceId": "PHD2_Single",
    "SupportedActions": [],
    "DriverInfo": "PHD2 Guider",
    "DriverVersion": "1.0",
    "CanSetShiftRate": true,
    "CanGetLockPosition": true,
    "Description": "PHD2 Guider",
    "CanClearCalibration": true,
    "Connected": true,
    "DisplayName": "PHD2"
  },
  "Error": "",
  "StatusCode": 200,
  "Success": true,
  "Type": "API"
}

Flatdevice

http://<ip>:<port>/v2/api/equipment/flatdevice/{action}

This endpoint provides the following required route parameter:

  • action:
    • connect: performs a rescan before connecting to the previously connected flatdevice, if not already connected
    • disconnect: disconnects the flatdevice
    • info: returns information about the flatdevice

These can have the following responses (provided they are successful)

action Response
connect Flatdevice connected
disconnect Flatdevice disconnected
unknown Unknown action in Error, with StatusCode 400
Flatdevice info 
{
  "Response": {
    "DriverInfo": "CoverCalibrator driver version: 6.6.2.4195.",
    "Name": "ASCOM CoverCalibrator Simulator",
    "CoverState": 2,
    "DeviceId": "ASCOM.Simulator.CoverCalibrator",
    "MaxBrightness": 100,
    "SupportedActions": [],
    "SupportsOnOff": true,
    "DriverVersion": "6.6",
    "LocalizedLightOnState": "On",
    "LightOn": true,
    "Brightness": 100,
    "Description": "ASCOM CoverCalibrator Simulator",
    "SupportsOpenClose": true,
    "LocalizedCoverState": "Closed",
    "Connected": true,
    "MinBrightness": 0,
    "DisplayName": "ASCOM CoverCalibrator Simulator"
  },
  "Error": "",
  "StatusCode": 200,
  "Success": true,
  "Type": "API"
}

Safetymonitor

http://<ip>:<port>/v2/api/equipment/safetymonitor/{action}

This endpoint provides the following required route parameter:

  • action:
    • connect: performs a rescan before connecting to the previously connected safetymonitor, if not already connected
    • disconnect: disconnects the safetymonitor
    • info: returns information about the safetymonitor

These can have the following responses (provided they are successful)

action Response
connect Safetymonitor connected
disconnect Safetymonitor disconnected
unknown Unknown action in Error, with StatusCode 400
Safetymonitor info 
{
  "Response": {
    "Name": "N.I.N.A. Simulator Safety Device",
    "DriverVersion": "",
    "SupportedActions": [],
    "DeviceId": "613EC0FF-87D7-4475-9352-F6F6EB1CDE75",
    "DriverInfo": "",
    "Connected": true,
    "DisplayName": "N.I.N.A. Simulator Safety Device",
    "Description": "",
    "IsSafe": false
  },
  "Error": "",
  "StatusCode": 200,
  "Success": true,
  "Type": "API"
}

Weather

http://<ip>:<port>/v2/api/equipment/weather/{action}

This endpoint provides the following required route parameter:

  • action:
    • unfortunately there isn't much we can do about the weather :(
    • connect: performs a rescan before connecting to the previously connected weather source, if not already connected
    • disconnect: disconnects the weather source
    • info: returns information about the weather

These can have the following responses (provided they are successful)

action Response
connect Weather connected
disconnect Weather disconnected
unknown Unknown action in Error, with StatusCode 400
Weather info 
{
  "Response": {
    "Humidity": 52,
    "DriverVersion": "1.0",
    "DriverInfo": "NINA internal OpenWeatherMap API client",
    "SupportedActions": [],
    "StarFWHM": "NaN",
    "SkyQuality": "NaN",
    "WindGust": "NaN",
    "SkyBrightness": "NaN",
    "SkyTemperature": "NaN",
    "WindSpeed": 1.5,
    "AveragePeriod": 0,
    "CloudCover": 30,
    "RainRate": "NaN",
    "Temperature": 25.560000000000002,
    "Name": "OpenWeatherMap",
    "Description": "Uses OpenWeatherMap's Current Weather API. Weather data is refreshed every 10 minutes.",
    "DeviceId": "NINA.OpenWeatherMap.Client",
    "DewPoint": 15.158650029965683,
    "WindDirection": 136,
    "Connected": true,
    "DisplayName": "OpenWeatherMap",
    "Pressure": 1012
  },
  "Error": "",
  "Success": true,
  "Type": "API"
}

Sequence

http://<ip>:<port>/v2/api/sequence/{action}

The api only works with the advanced sequencer!

This endpoint provides the following required route parameter:

  • action:
    • start: Starts the sequence
    • stop: Stops the sequence
    • json: Returns the current state of the sequence

and this optional URL parameter:

  • skipValidation (bool), used when starting a sequence to determine whether validation should be skipped or not

These can have the following responses (provided they are successful)

action Response
start Sequence started or Sequence is not initialized as Error with StatusCode 409
stop Sequence stopped
json [The sequence json] or Sequence is not initilalized as Error with StatusCode 409 or No DSO Container found as Error with StatusCode 409
unknown Unknown action in Error, with StatusCode 400

The action json will return a light representation of the sequence. This will only work if there is a DSO Container present!

The returned sequence json will contain the fields Name, Status, Description for each sequence item. If the item is a container, the name will habe the suffix _Container and a field named Items containing all items inside the container. Note that sequence start, target area and end are all containers.

Status can have the following values:

  • CREATED
  • RUNNING
  • FINISHED
  • FAILED
  • SKIPPED
  • DISABLED
Sample Sequence 
{
  "Response": [
    {
      "Name": "Start_Container",
      "Description": "",
      "Status": "CREATED",
      "Items": []
    },
    {
      "Name": "Targets_Container",
      "Description": "",
      "Status": "CREATED",
      "Items": [
        {
          "Name": "Some-Nebula_Container",
          "Description": "Works like a sequential instruction set, but a deep sky object can be specified inside, which will auto populate all instructions inside it with the coordinates and rotation when necessary.",
          "Status": "CREATED",
          "Items": [
            {
              "Name": "Prepare_Container",
              "Description": "Runs all items in a sequential order. Trigger and conditions are evaluated after each item",
              "Status": "CREATED",
              "Items": [
                {
                  "Name": "Slew and center",
                  "Description": "Slews to the target and centers the telescope via plate solving for the given coordinates",
                  "Status": "CREATED"
                },
                {
                  "Name": "Start Guiding",
                  "Description": "Starts autoguiding",
                  "Status": "CREATED"
                }
              ]
            },
            {
              "Name": "Imaging_Container",
              "Description": "Runs all items in a sequential order. Trigger and conditions are evaluated after each item",
              "Status": "CREATED",
              "Items": [
                {
                  "Name": "Take Exposure",
                  "Description": "Takes an exposure for the given duration, gain and offset",
                  "Status": "CREATED"
                }
              ]
            }
          ]
        }
      ]
    },
    {
      "Name": "End_Container",
      "Description": "",
      "Status": "CREATED",
      "Items": []
    }
  ],
  "Error": "",
  "StatusCode": 200,
  "Success": true,
  "Type": "API"
}

Event History

http://<ip>:<port>/v2/api/event-history

This will return all the events that were recorded by the websocket so far.

Event History 
{
  "Response": [
    {
      "Event": "CAMERA-CONNECTION",
      "Time": "2024-08-09T14:51:35.0183716+02:00"
    },
    {
      "Event": "CAMERA-CONNECTION",
      "Time": "2024-08-09T14:51:35.0637393+02:00"
    },
    {
      "Event": "TELESCOPE-CONNECTION",
      "Time": "2024-08-09T14:51:37.7290466+02:00"
    },
    {
      "Event": "TELESCOPE-CONNECTION",
      "Time": "2024-08-09T14:51:38.0681832+02:00"
    },
    {
      "Event": "IMAGE-SAVE",
      "Time": "2024-08-09T14:51:40.9181797+02:00"
    },
    {
      "Event": "NINA-ADV-SEQ-START",
      "Time": "2024-08-09T14:51:40.9875917+02:00"
    },
    {
      "Event": "NINA-ADV-SEQ-STOP",
      "Time": "2024-08-09T14:51:40.9878283+02:00"
    }
  ],
  "Error": "",
  "StatusCode": 200,
  "Success": true,
  "Type": "API"
}

Image History

http://<ip>:<port>/v2/api/image-history

This endpoint can be used to get information like image statistics about previously taken images

It provides the following URL parameters:

  • all (bool), if true information about all images that were taken is returned
  • count (bool), if true the amount of images taken is returned
  • index (int), specifies which image should should be returned

If all parameters are omitted, information about the image at index 0 is returned

Count request 
{
  "Response": 1,
  "Error": "",
  "StatusCode": 200,
  "Success": true,
  "Type": "API"
}
Sample image information 
{
  "Response": [
    {
      "ExposureTime": 0,
      "Index": 0,
      "Filter": "",
      "RmsText": "Tot: 0.00 (0.00\")",
      "Temperature": "NaN",
      "CameraName": "N.I.N.A. Simulator Camera",
      "Gain": 0,
      "Offset": 0,
      "Date": "2024-08-09T12:26:01.5424785+02:00",
      "TelescopeName": "",
      "FocalLength": "NaN",
      "StDev": 99.983193747121,
      "Mean": 4999.483922526042,
      "Median": 4999,
      "Stars": 0,
      "HFR": 0
    }
  ],
  "Error": "",
  "StatusCode": 200,
  "Success": true,
  "Type": "API"
}

Image

http://<ip>:<port>/v2/api/image/{index}

Returns a Base64 encoded image

This endpoint provides the following required route parameter:

  • index: specifies the index of the image

Optional URL parameters:

  • resize (bool), used together with size to resize an image
  • size, specifies the new image dimensions (requires resize to be true) in the following format: <width>x<height>
  • quality, specifies the jpg quality of the returned image (-1 returns a png)

Framing Assistant (to be released with 2.0.1.0)

http://<ip>:<port>/v2/api/framing/{action}

This endpoint provides the following required route parameter:

  • action:
    • info: returns information about the current state of the framing assitant
    • set-coordinates: sets the coordinates of the framing assistant
    • set-rotation: sets the rotation of the frame / camera
    • slew: slews (optionally centers or rotates) to the coordinates

Optional URL parameters:

  • RAangle, the RA angle, used for set-coordinates
  • DECangle, the Dec angle, used for set-coordinates
  • rotation, the rotation that should be set
  • slew_option, either Center, Rotate or omitted, controls if the mount should center, rotate or just slew to the object

These can have the following responses (provided they are successful)

action Response
set-coordinates Coordinates updated
set-rotation Rotation updated
slew Slew started
unknown Unknown action in Error, with StatusCode 400 
{
  "Response": {
    "BoundHeight": 832,
    "BoundWidth": 1125,
    "CameraHeight": 480,
    "CameraWidth": 640,
    "CameraPixelSize": 4.29,
    "DecDegrees": 1,
    "DecMinutes": 13,
    "DecSeconds": 32.56392,
    "RAHours": 23,
    "RAMinutes": 52,
    "RASeconds": 51.60835,
    "FieldOfView": 5,
    "FocalLength": 135,
    "HorizontalPanels": 1,
    "VerticalPanels": 1,
    "Rectangle": {
      "OriginalX": 465.5496332323772,
      "OriginalY": 343.2872249242829,
      "OriginalCoordinates": {
        "RA": 23.881002319884626,
        "RAString": "23:52:52",
        "RADegrees": 358.2150347982694,
        "Dec": 1.2257122006440255,
        "DecString": "01° 13' 33\"",
        "Epoch": 2,
        "DateTime": {
          "Now": "2024-11-25T14:28:02.7171109+01:00",
          "UtcNow": "2024-11-25T13:28:02.7179407Z",
          "MinValue": "0001-01-01T00:00:00",
          "MaxValue": "9999-12-31T23:59:59.9999999"
        }
      },
      "Id": 0,
      "Coordinates": {
        "RA": 23.881002319884626,
        "RAString": "23:52:52",
        "RADegrees": 358.2150347982694,
        "Dec": 1.2257122006440255,
        "DecString": "01° 13' 33\"",
        "Epoch": 2,
        "DateTime": {
          "Now": "2024-11-25T14:28:02.7186583+01:00",
          "UtcNow": "2024-11-25T13:28:02.7186627Z",
          "MinValue": "0001-01-01T00:00:00",
          "MaxValue": "9999-12-31T23:59:59.9999999"
        }
      },
      "DSOPositionAngle": 0,
      "OriginalOffset": 0,
      "RotationOffset": 0,
      "Rotation": 0.01,
      "TotalRotation": 0.01,
      "X": 465.5496332323772,
      "Y": 343.2872249242829,
      "Width": 193.90073353524568,
      "Height": 145.42555015143427
    }
  },
  "Error": "",
  "StatusCode": 200,
  "Success": true,
  "Type": "API"
}

Profile

http://<ip>:<port>/v2/api/profile/{action}

This endpoint provides the following required route parameter:

  • action:
    • switch: switch to a different profile using a profile ID
    • change-value: changes a setting in the profile using a setting path
    • show: returns a list with all profiles, recognized by NINA or the active profile

Optional URL parameters:

  • profileid, used for switching to a different profile, can be obtained using show
  • settingpath, used for changing a setting in the profile (use show with active = true for help)
  • newValue, used for chaning a setting in the profile, this is the new value to be set
  • active, used when showing profiles, determines whether the active profile should be returned or a list of all recognized profiles

settingpath has the following format: <SettingName>-<SettingName>-<SettingName>-..., e.g. CameraSettings-PixelSize

These can have the following responses (provided they are successful)

action Response
switch Successfully switched profile or No profile with specified id found! as Error with StatusCode 400
change-value Updated setting or Invalid path as Error with StatusCode 400 or New value can't be null as Error with StatusCode 400
show [A list of profiles or the currently active profile]
unknown Unknown action in Error, with StatusCode 400

See here for a sample active profile response

Show profile (active = false) 
{
  "Response": [
    {
      "IsActive": true,
      "Description": "",
      "Location": "C:\\Users\\<username>\\AppData\\Local\\NINA\\Profiles\\7f4afdbc-ce37-43b5-98a2-d6063829dce1.profile",
      "Id": "7f4afdbc-ce37-43b5-98a2-d6063829dce1",
      "Name": "Default-2024-08-06T12:00:27",
      "LastUsed": "2024-08-09T14:51:29.1719728+02:00"
    },
    {
      "IsActive": false,
      "Description": "",
      "Location": "C:\\Users\\<username>\\AppData\\Local\\NINA\\Profiles\\3468d613-b966-4ad9-a443-23485bd64e2b.profile",
      "Id": "3468d613-b966-4ad9-a443-23485bd64e2b",
      "Name": "Canon 100-400mm",
      "LastUsed": "2024-08-08T15:42:15.1029068+02:00"
    },
    {
      "IsActive": false,
      "Description": "",
      "Location": "C:\\Users\\<username>\\AppData\\Local\\NINA\\Profiles\\4c12df08-d16a-4156-a545-4bb6cde1c237.profile",
      "Id": "4c12df08-d16a-4156-a545-4bb6cde1c237",
      "Name": "Samyang 135mm",
      "LastUsed": "2024-08-05T14:11:43.0232093+02:00"
    },
    {
      "IsActive": false,
      "Description": "",
      "Location": "C:\\Users\\<username>\\AppData\\Local\\NINA\\Profiles\\d91bdc56-b2cd-4b05-948f-e19de36f3674.profile",
      "Id": "d91bdc56-b2cd-4b05-948f-e19de36f3674",
      "Name": "Test",
      "LastUsed": "2024-08-05T13:56:32.2099052+02:00"
    }
  ],
  "Error": "",
  "StatusCode": 200,
  "Success": true,
  "Type": "API"
}

Application

http://<ip>:<port>/v2/api/application/{action}

This endpoint provides the following required route parameter:

  • action:
    • switch-tab: switch to a different tab in the application (useful for screenshots)
    • screenshot: changes a setting in the profile using a setting path

Optional URL parameters:

  • tab, the application tab to switch to
  • resize (bool), used together with size to resize an image
  • size, specifies the new image dimensions (requires resize to be true) in the following format: <width>x<height>
  • quality, specifies the jpg quality of the returned image (-1 returns a png)

The following tabs are availiable:

  • equipment
  • skyatlas
  • framing
  • flatwizard
  • sequencer
  • imaging
  • options

These can have the following responses (provided they are successful)

action Response
switch-tab Switched tab or Invalid application tab as Error with StatusCode 400
screenshot The image, the same was as for api/image (base64-encoded)
unknown Unknown action in Error, with StatusCode 400

Websocket

The websocket is available at:

ws://<ip>:<port>/v2/socket

Connection and log events:

CAMERA-CONNECTION
TELESCOPE-CONNECTION
FOCUSER-CONNECTION
ROTATOR-CONNECTION
DOME-CONNECTION
FILTERWHEEL-CONNECTION
SAFETY-CONNECTION
GUIDER-CONNECTION
FLAT-CONNECTION
WEATHER-CONNECTION

TELESCOPE-PARK
TELESCOPE-UNPARK
DOME-SHUTTER-OPENED
DOME-SHUTTER-CLOSED
DOME-STOPPED
ADV-SEQ-START
ADV-SEQ-STOP
TELESCOPE-CENTER
TELESCOPE-MF (Meridian Flip)
ERROR-AF (Error while running AF)
ERROR-PLATESOLVE

Connection events indicate a change in connection (e.g. connected -> disconnected or disconnected -> connected). All these events have the following response format

{
   "Response": {
      "Event": "<EventName>"
   },
   "Error": "",
   "StatusCode": 200,
   "Success": true,
   "Type": "Socket"
}

For new images (LIGHT only), there is the IMAGE-SAVE event:

{
   "Response": {
      "Event": "IMAGE-SAVE",
      "ImageStatistics": {
         "ExposureTime": 0,
         "Index": 0,
         "Filter": "",
         "RmsText": "Tot: 0.00 (0.00\")",
         "Temperature": "NaN",
         "CameraName": "N.I.N.A. Simulator Camera",
         "Gain": 0,
         "Offset": -1,
         "Date": "2024-08-12T11:12:57.0227298+02:00",
         "TelescopeName": "Canon 100-400mm",
         "FocalLength": 400,
         "StDev": 100.22584875024486,
         "Mean": 4999.821936848958,
         "Median": 5000,
         "Stars": 0,
         "HFR": 0
      }
   },
   "Error": "",
   "StatusCode": 200,
   "Success": true,
   "Type": "Socket"
}

TPPA Socket (to be released with 2.0.1.0)

The websocket for TPPA (Version >= 2.2.1.0) is available at:

ws://<ip>:<port>/v2/tppa

Once connected you can start and stop a TPPA procedure using the following messages. Send these via the websocket to the server:

  • start-alignment
  • stop-alignment

These will respond with a confirmation:

{
   "Response": "started procedure" <or> "stopped procedure",
   "Error": "",
   "StatusCode": 200,
   "Success": true,
   "Type": "Socket"
}

Note that these will not fail, even if the alignment process could not be started because not all necessary equipment is connected or the plugin is not installed, so make sure everything is set up properly

Once started and after the initial calibration is complete, you will receive ongoing updates about the alignment error in the following form:

{
   "Response": {
      "AzimuthError": <double>,
      "AltitudeError": <double>,
      "TotalError": <double>
   },
   "Error": "",
   "StatusCode": 200,
   "Success": true,
   "Type": "Socket"
}
Clone this wiki locally