agent

README

indihub-agent

The indihub-agent is a command line interface tool to connect your astro-photography equipment to INDIHUB network. The network can be used to share you equipment with others, use others' equipment remotely or just use your equipment without sharing but still contribute your images to INDIHUB-network.

NOTE: all astro-photos taken via INDIHUB-network (with auto-guiding or main imaging cameras) will be processed by INDIHUB cloud pipeline and used for scientific purposes.

Prerequisites

1. You have a desire to contribute to Space exploration and sustainability projects.
2. You have motorized astro-photography equipment connected to your home network.
3. Your equipment is controlled by INDI-server, manuals and docs can be found on INDI-lib Web-site.
4. INDI-server is controlled by INDI Web Manager.
5. You have ready to use INDI-profile created with INDI Web Manager.
6. Raspberry PI (or computer) where you run indihub-agent is connected to Internet so it can register your equipment on INDIHUB-network.

Registration on INDIHUB-network as a host

Registration is very easy - you don't have to do anything.

The indihub-agent doesn't require any signup or token to join INDIHUB.

When you first run indihub-agent and it is connected to INDIHUB-network successfully - it receives token from network and saves in the same folder in the file indihub.json. Please keep this file there and don't loose it as it identifies you as a host on INDIHUB-network. Also, this file will be read and used automatically for all next runs of indihub-agent.

indihub-agent modes

There are three modes available at the moment:

1. share - open remote access to your equipment via INDIHUB-network of telescopes, so you can provide remote imaging sessions to your guests.
2. solo - use you equipment without opening remote access but equipment is still connected to INDIHUB-network and all images taken are contributed for scientific purposes.
3. robotic - open remote access to your equipment to be controlled by scheduler running in INDIHUB-cloud (experimental).

The mode is specified via -mode parameter, i.e. to run indihub-agent in a share-mode you will need run command:

./indihub-agent -indi-profile=my-profile -mode=share

The only mandatory parameter is -indi-profile where you specify profile name created with INDI Web Manager. All other parameters have default valyes. I.e. -mode default value is solo.

To get usage of all parameters just run:

./indihub-agent -help

The latest indihub-agent release can be downloaded from releases or indihub.space Web-site.

API

There is an API-server running as part of indihub-agent and listening on port :2020 (or on port specified via -api-port=N parameter) which provides two different APIs to control or use indihub-agent:

• RESTful API to get status or switch modes of the agent
• Websocket API to control equipment via websocket-connections

By default API-server works over HTTP-protocol. You can switch it to work over TLS by providing -api-tls parameter. This will make indihub-agent to generate self-signed CA and certificate.

RESTful API

You can use this simple RESTful API to control indihub-agent.

NOTE: CORS protection can be specified with comma-separated list of allowed origins via agent parameter:

-api-origins=host1,host2,hostN.

Also, all examples assume indihub-agent is running on host raspberrypi.local.

1. Get indihub-agent status (public)

curl -X GET http://raspberrypi.local:2020/status

Response example:

{
    "indiProfile": "NEO-remote",
    "indiServer": "raspberrypi.local:7624",
    "mode": "solo",
    "phd2Server": "",
    "status": "running",
    "supportedModes": [
        "solo",
        "share",
        "robotic"
    ],
    "version": "1.0.3"
}

2. Restart indihub-agent current mode (public)

curl -X GET "http://raspberrypi.local:2020/restart"

3. Switch indihub-agent mode (protected via token)

You need to do HTTP-request POST "http://indihub-agent-host:2020/mode/{mode}" specifying required mode in a mode URI-parameter and supplying your token in Authorization header, i.e.:

curl -X POST "http://raspberrypi.local:2020/mode/share" -H "Authorization: Bearer cca13ac2951efd6d912ead20a7ab4882"

Response will have status of agent running in new mode:

{
    "indiProfile": "NEO-remote",
    "indiServer": "raspberrypi.local:7624",
    "mode": "share",
    "phd2Server": "",
    "publicEndpoints": [
        {
            "name": "INDI-Server",
            "addr": "node-1.indihub.io:55642"
        }
    ],
    "status": "running",
    "supportedModes": [
        "share",
        "robotic",
        "solo"
    ],
    "version": "1.0.3"
}

Websocket API

You can use indihub-agent to control your equipment via Websocket API, i.e. from your Web-app open int the Web-browser.

NOTE: Websocket upgrade-requests are allowed only from origins specified with comma-separated list via agent parameter:

-api-origins=host1,host2,hostN

1. Open WS-connection to INDI-server (protected via token)

To establish a new WS-connection to INDI-server you will need to use URL with format:

ws://raspberrypi.local:2020/websocket/indiserver?token=cca13ac2951efd6d912ead20a7ab4882

NOTE: we connect to raspberrypi.local:2020 which is indihub-agent API-server and we provide token via token query string parameter.

This will open WS-connection to you your equipment via indihub-agent API-server where all outgoing messages will be INDI-protocol commands and all incoming messages will be INDI-protocol replies from your equipment.

2. Message format for INDI-server Websocket connection

All commands are expected to be in JSON-format where INDI-command XML attributes translate to fields with attr_-prefix.

I.e. to send this INDI XML-command over WS-connection:

<getProperties version="1.7" />

You will need to send message over WS-connection in JSON-format:

{
  "getProperties": {
    "attr_version":"1.7"
  }
}

The INDI-protocol responses will be converted from XML to JSON-messages and sent over WS-connection as messages.

I.e. this INDI-response about telescopes installed on the mount in XML-format:

<defNumberVector device="iOptron CEM25" name="TELESCOPE_INFO" label="Scope Properties" group="Options" state="Ok" perm="rw" timeout="60" timestamp="2020-02-20T21:52:23">
    <defNumber name="TELESCOPE_APERTURE" label="Aperture (mm)" format="%g" min="10" max="5000" step="0">
120
    </defNumber>
    <defNumber name="TELESCOPE_FOCAL_LENGTH" label="Focal Length (mm)" format="%g" min="10" max="10000" step="0">
600
    </defNumber>
    <defNumber name="GUIDER_APERTURE" label="Guider Aperture (mm)" format="%g" min="10" max="5000" step="0">
50
    </defNumber>
    <defNumber name="GUIDER_FOCAL_LENGTH" label="Guider Focal Length (mm)" format="%g" min="10" max="10000" step="0">
162
    </defNumber>
</defNumberVector>

Will be converted in to JSON-format like this:

{
  "defNumberVector": {
      "attr_device":"iOptron CEM25",
      "attr_group":"Options",
      "attr_label":"Scope Properties",
      "attr_name":"TELESCOPE_INFO",
      "attr_perm":"rw",
      "attr_state":"Ok",
      "attr_timeout":60,
      "attr_timestamp":"2020-02-20T21:52:23",
      "defNumber": [
        {
          "#text":120,
          "attr_format":"%g",
          "attr_label":"Aperture (mm)",
          "attr_max":5000,
          "attr_min":10,
          "attr_name":"TELESCOPE_APERTURE",
          "attr_step":0
        },
        {
          "#text":600,
          "attr_format":"%g",
          "attr_label":"Focal Length (mm)",
          "attr_max":10000,
          "attr_min":10,
          "attr_name":"TELESCOPE_FOCAL_LENGTH",
          "attr_step":0
        },
        {
          "#text":50,
          "attr_format":"%g",
          "attr_label":"Guider Aperture (mm)",
          "attr_max":5000,
          "attr_min":10,
          "attr_name":"GUIDER_APERTURE",
          "attr_step":0
        },
        {
          "#text":162,
          "attr_format":"%g",
          "attr_label":"Guider Focal Length (mm)",
          "attr_max":10000,
          "attr_min":10,
          "attr_name":"GUIDER_FOCAL_LENGTH",
          "attr_step":0
        }
      ]
  }
}

Please NOTE:

• XML element attributes get converted into JSON-fields with attr_ prefix
• XML element value get converted into JSON-field with name #text
• vector like child-elements get converted into JSON-arrays

Building indihub-agent

You will need to install Golang.

There are make build-commands for different platforms available:

• make build-macos64 - build for macOS (64 bit)
• make build-linux64 - build for Linux (64 bit)
• make build-unix64 - build for Unix (64 bit)
• make build-win64 - build for Windows (64 bit)
• make build-win32 - build for Windows (32 bit)
• make build-raspberrypi - build for Raspberry Pi (ARM5)

Contributing

PRs and issues are highly appreciated. TODO: indihub-agent speaks to the INDIHUB-cloud so special dev-server will be added for development purposes soon.

What is next

The INDIHUB-network is in its beta release at the moment. We board new hosts on the network, collect data and most importantly - feedback from our first hosts.

Also we work on partnerships. If you are interested please send us email at info@indihub.space.

And last but not least - don't forget to signup to our mailing list on indihub.space so you will know all the news first!