Getting Started with Nature Remo: Control Your Room's Lighting via Shell Script and API

Introduction

I recently purchased the Nature Remo 3 to build a DIY smart home and control my appliances. In this article, I'll guide you through the steps to control your room's lighting from a local shell script by interacting with the Nature Remo Cloud API.
（Click here to read the article in Japanese.）

Nature Remo 3

Sequence Diagram

Who Is This For?

1. Anyone looking to experiment with the Nature Remo 3 API.
2. My future self who might forget these steps after three months.

Steps

Logging In

Access the Nature Remo API login page:
https://api.nature.global/login

Follow the prompts to log in with your Nature Remo account.

Generating an Access Token

Navigate to the access token section and generate a new token.

Save the generated token securely, for example, in a password manager like 1Password.

Checking API Limits

Before making API requests, it's essential to understand the rate limits.

From the Nature Remo Developer Documentation:

RATE LIMITS #
If we observe more than 30 requests in 5 minutes, we throttle your requests and you’ll see 429 status codes. See following headers to check your throttling status.

• X-Rate-Limit-Limit
• X-Rate-Limit-Reset
• X-Rate-Limit-Remaining

For personal use, this limit should suffice. Even if you exceed it during testing, you can resume after 5 minutes.

Determining Which Appliance to Control

How can we turn on or off our room's lighting?

Let's look at the API specifications in the menu.

This opens the Swagger documentation. Let's try a simple GET request.

ACCESS_TOKEN="your_access_token_here"
curl -H "Authorization: Bearer ${ACCESS_TOKEN}" \
     -H "Accept: application/json" \
     -X GET "https://api.nature.global/1/users/me"

# Result
{"id":"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX","nickname":"tqer39"}

Next, let's get a list of registered remote configurations.

curl -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Accept: application/json" \
  -X GET "https://api.nature.global/1/appliances" \
  | jq | pbcopy

This command fetches the appliances and copies the formatted JSON to your clipboard.

[
  {
    "id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "device": {
      "name": "Remo3 Room",
      "id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
      "created_at": "2024-09-17T17:13:49Z",
      "updated_at": "2024-09-22T05:58:38Z",
      "mac_address": "xx:xx:xx:xx:xx:xx",
      "bt_mac_address": "xx:xx:xx:xx:xx",
      "serial_number": "XXXXXXXXXXXXXX",
      "firmware_version": "Remo/1.14.6",
      "temperature_offset": 0,
      "humidity_offset": 0
    },
    "model": null,
    "type": "IR",
    "nickname": "Lighting",
    "image": "ico_light",
    "settings": null,
    "aircon": null,
    "signals": [
      {
        "id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
        "name": "Off",
        "image": "ico_off"
      },
      {
        "id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
        "name": "Night Light",
        "image": "ico_night_light"
      },
      {
        "id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
        "name": "Dim",
        "image": "ico_lightdown"
      },
      {
        "id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
        "name": "On",
        "image": "ico_lightup"
      }
    ]
  }
]

Let's try the "Off" signal for the "Lighting" appliance.

1. Since we're updating, we'll use a POST method.
2. We have a signalId from the signals array.
3. The appropriate API endpoint seems to be POST /1/signals/{signalId}/send.

Looking at the send method's Example Value | Schema, it's empty {}, so we likely only need the signalId.

Command:

signalId="your_signal_id_for_off"
curl -H "Authorization: Bearer ${ACCESS_TOKEN}" \
     -H "Accept: application/json" \
     -X POST "https://api.nature.global/1/signals/${signalId}/send"

# Result
{}

It worked! :smiiley:

Warning: Since this operation affects your actual room lighting, ensure you're testing with a device you can safely control.

Conclusion

The operation worked as I had envisioned. I plan to utilize this to integrate with other services and IoT devices moving forward.