Using Indego Robot Mowers from Homey

Most requests in the API require a contextId value, and to get one of those we first need to make a POST request to the /authenticate endpoint providing some details about the client as well as a Basic authentication token.

The authentication token is built by base64 encoding a string comprised of your username and password separated by a colon. This can be done conveniently in most programming languages, such as javascript:

return btoa("username@email.com:secret-password");

As is, this will output the following (but don't forget to use your actual username and password if you want to connect to the API for real):

dXNlcm5hbWVAZW1haWwuY29tOnNlY3JldC1wYXNzd29yZA==

(Note that the above code sample won't actually work in HomeyScript, so you'll need to use a different approach if you want to generate the token as part of that)

With the token generated we can get a contextId from the /authenticate endpoint:

POST https://api.indego.iot.bosch-si.com/api/v1/authenticate
Authorization: Basic dXNlcm5hbWVAZW1haWwuY29tOnNlY3JldC1wYXNzd29yZA==
Content-Type: application/json

{
    "accept_tc_id":"202012",
    "device": "",
    "os_type": "Android",
    "os_version": "4.0",
    "dvc_manuf": "unknown",
    "dvc_type": "unknown"
}

The token generated previously is provided in the Authorization header, while we can use sample data to populate most of the fields in the request. It is worth noting that the accept_tc_id field value will likely need to be updated in the future if a new revision of the terms and conditions for the API are released.

HTTP/1.1 200 
Content-Type: application/json

{
  "contextId" : "'3f2a9e8c-93cb-402e-a200-e325859f3ffe",
  "userId" : "0a86dc31-7136-4009-9ef6-61ac4cab696e",
  "alm_sn" : "000000000"
}

This provides us with the contextId that is needed to make other requests.

Before making other requests we can make this in a HomeyScript function:

// pull values from the flow editor
const user = args[0];
const pwd = args[1];

// btoa isn't available :(
const buffer = Buffer.from(user + ':' + pwd);
const headerData = buffer.toString('base64');
const authHeader = 'Basic ' + headerData;

const authRequestBody = {
    accept_tc_id: "202012",
    device: "",
    os_type: "Android",
    os_version: "4.0",
    dvc_manuf: "unknown",
    dvc_type: "unknown"
};

const result = await fetch('https://api.indego.iot.bosch-si.com/api/v1/authenticate', {
    method: 'POST',
    body: JSON.stringify(authRequestBody),
    headers: {
        'Authorization': authHeader,
        'Content-Type': 'application/json'
    }
});

// fail for any error and return any error message we were given
if (!result.ok) {
    throw new Error(result.statusText);
}

const body = await result.json();

// return just the context id because we don't care about the other values
return body.contextId;

The two const values for user and pwd should be provided from the flow editor, and this will output the contextId as a text value, that can then be passed to another function to do something.

If you already know the serial number for your mower, you can skip this step and just use that to work with it directly. If you don't know the serial number or you have multiple mowers that you want to work with, there is an API endpoint that will list all the available devices:

GET https://api.indego.iot.bosch-si.com/api/v1/alms/
x-im-context-id: 3f2a9e8c-93cb-402e-a200-e325859f3ffe

Which will give a list containing the serial number and status code for the mowers connected to the account:

HTTP/1.1 200
Content-Type: application/json

[ {
  "alm_sn" : "000000000",
  "alm_status" : 258
} ]

The serial number is then used to get more detailed information or to control the mower.

Now we have the contextId and the serial number of the mower we want to work with, we can make two different calls to get information about the mower.

With code in place to authenticate with the API and retrieve information about the mower it is quite straightforward to control the mower. We just need to make a PUT request to the /state endpoint with the desired state command:

PUT https://api.indego.iot.bosch-si.com/api/v1/alms/{serial number}/state
x-im-context-id: 3f2a9e8c-93cb-402e-a200-e325859f3ffe
content-type: application/json

{
  "state": "mow"
}

We can issue a mow command to start the mower, and a returnToDock command to stop it and have it go back to the dock.

In HomeyScript this can be done like so:

// pull values from the flow editor
const contextId = args[0];
const serialNumber = args[1];

// send the request to the api
const body = {
    state: "mow"
};

const result = await fetch('https://api.indego.iot.bosch-si.com/api/v1/alms/' + serialNumber + '/state', {
    method: 'PUT',
    body: JSON.stringify(body),
    headers: {
        'x-im-context-id': contextId,
        'Content-Type': 'application/json'
    }
});

if (!result.ok) {
    throw new Error(result.statusText);
}

// this doesn't return a body, so as long as it didn't fail it should be good

The code snippets in this post can be added to HomeyScript cards in the flow editor, and you can link up your robot mower to anything else controlled by Homey.

The screenshot below shows examples of controlling the mower with a virtual device, and monitoring the battery percentage with a virtual sensor.

Happy Automating!