Node Sharing

ESP RainMaker allows a user to control a node remotely over the Internet. However, there is often a need to allow others to use the same node. It could be something like giving control of lightbulbs to members of your family, or temporarily giving access to a door lock to your tenant or a maid, or something like a shared hardware resource being accessed remotely by multiple employees. To serve such use cases, ESP RainMaker offers an ability of sharing a node with others.

User Roles

Node sharing has introduced a concept of "User Role". There can be two types of User roles for any given node.

1. Primary User: A user who has added a node by provisioning it from the phone app will be the primary user for a node. A primary user can add/remove other users. If the primary user's association with the node is removed, all secondary users will also be automatically removed.
2. Secondary User: Any user added by a primary user will be a secondary user for the given node. A secondary user cannot add/remove other users, however, it can access the node configuration and node parameters in the same way as the primary user.

Please check out here for more information on user roles.

Workflow

Sharing Node(s)

1. Primary user registers a request with the ESP Rainmaker cloud to share node(s) with a user.

2. Secondary user can list the request(s) it has received and accept/decline, as required.

3. Primary user can also list the request(s) it has initiated by passing the "primary user" flag and cancel them if required.

4. Once a request is accepted, declined or cancelled, it will not show up in the list of requests.

   Note:

• The pending request(s) are valid for 7 days and are automatically deleted if the request is not accepted/declined/cancelled.
• Secondary users cannot further share the node(s). Only primary users can do so.

Once a node is shared, it can be used directly from the secondary user's phone app.

Removing Shared Node(s)

Primary user can remove the secondary user from the shared node(s) anytime and the node(s) will no longer be shared with the user.

Note:

• If primary user removes its own association with a node, then all secondary users are removed automatically.
• If secondary user removes its own association with a shared node, it won't affect the association of the node with the other users.
• If a new user gets associated with a node (via provisioning), then the previous primary user and all secondary user(s) it had shared the node with, will be removed. The new user becomes the primary user for the node.

Viewing Node Sharing Details

• User can list sharing details of the node(s) it is associated with.
• For each node, the sharing details include the node id, primary user and secondary user(s) of that node.

Usage

Easiest way to use node sharing is via the ESP RainMaker Phone apps. Alternatively, this can be tried from the CLI.

ESP Rainmaker CLI

If you haven't already set up the CLI, please follow the steps here. Once installed, log into your account using the login command. Thereafter, use the sharing command to perform the operations. The CLI help should be self-explanatory.

      ~# python esp-rainmaker-cli sharing  -h
      usage: esp-rainmaker-cli sharing [-h]
                                  {add_user,remove_user,accept,decline,cancel,list_nodes,list_requests}
                                  ...

      positional arguments:
        {add_user,remove_user,accept,decline,cancel,list_nodes,list_requests}
          add_user            Request to add user for sharing the node(s)
          remove_user         Remove user from shared node(s)
          accept              Accept sharing request(s)
          decline             Decline sharing request(s)
          cancel              Cancel sharing request(s)
          list_nodes          List node(s) sharing details
          list_requests       List pending request(s)

      optional arguments:
        -h, --help            show this help message and exit

      User Login:
        Current (logged-in) user must be a primary or secondary user to the node(s)
        while performing the sharing operations

• Primary user can list the pending request(s) it has initiated, by using the
  --primary_user parameter. This parameter enables the API flag, setting the user role to Primary user.

  esp-rainmaker-cli sharing list_requests --primary_user

Users using Sign-Up with Apple

If you have Signed Up using Apple and have chosen the "Hide My Email" option, please check the auto-generated email address under your profile in the iOS app, or by using the esp-rainmaker-cli getuserinfo CLI command. This email address will be of the form <unique-alphanumeric-string>@privaterelay.appleid.com. Use this email address in the node sharing add_user/remove_user commands.

API

To know more about the API's, you can refer to the documentation here.