Gateways

Gateways come in two flavors - hardware and cloud based. The initial provisioning of a gateway involves some back and forth between your networking team and the Mapped support team, whether it's configuring a hardware gateway prior to shipping or getting the proper keys from our side to provision a software gateway. As such, via the API, you can't do any provisioning work but you can still interact with gateways four ways:

• List the gateways you have provisioned to your account (whether they've been assigned to a building yet or not)
• Look at the details for a specific gateway
• Assign a provisioned gateway to a building and relevant spaces
• Suspend a gateway (which prevents it from collecting or sending data)

Viewing gateways

There are quite a lot of possible fields you can return for a gateway, including getting all the way into the certificates of the SIM of a hardware gateway. We'll only grab a few of the most relevant in our example, but if you drill down through all the available fields, you'll see how extensive they go.

Request Response
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  gateways {
    gatewayId
    active {
      lastSeenTime
    }
    assignment {
      assignmentTime
      physicalPlaceId
      servesPlaceIds
    }
    firstBoot {
      bootTime
    }
    provisioning {
      provisionTime
    }
    state
  }
}

In the above response, we can see the gateway is not yet active, but it is assigned to a physical location and the places within that physical location that it serves (for example, which spaces on a specific floor are sending input to this gateway). We can see it hasn't booted yet, we're provided the ID for the gateway, and then some provisioning details including the orgId and when it was added. The last field we have is the state, which at this point says ASSIGNED because it has not yet been activated. Other states include PROVISIONED, SHIPPED and SUSPENDED.

Viewing a specific gateway's details

If you want to look up just a single gateway, you just need to add a filter for the gatewayId like so:

Request Response
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  gateways(filter: {gatewayId: {eq: "GWE6BvSemH5UBbEZmyPf1H7R"}}) {
    gatewayId
    active {
      lastSeenTime
    }
    assignment {
      assignmentTime
      physicalPlaceId
      servesPlaceIds
    }
    state
  }
}

Assigning a gateway

When a gateway is initially provisioned, it is associated with an organization but not assigned to a building or any spaces. This is typically handled on the customer side through the console, though we can help as needed. This assignment window looks like the following:

If you wanted to assign the gateway via the API instead, the same request would look like this (note you'll likely need to make calls to various place fields to get the IDs you need, such as buildings or floors):

Request Response
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
mutation{
  assignGateway(
    input: {
      gatewayId: "GWE6BvSemH5UBbEZmyPf1H7R"
      assignment: {
        physicalPlaceId: "1a12bfd3c-1abb-49fc-bc05-27715321230"
        servesPlaceIds: [
          "abe21352-1fc2-4506-93f1-9223153720"
          "2ef14ef3-9f12-4d00-bbb7-28265361129"
        ]
      }
    }
  ) {
    _
  }
}

The Physical Location of the gateway is where it's actually set up - typically this is building level, though in some cases you may have different gateways per floor or space (such as a scenario where one building has multiple independent tenants that use Mapped). Places Served represents the places containing equipment that the gateway will be able to “see” from its given location / network, which is typically a subset of the Physical Location like floors 1 and 2 of a building.

Suspending a gateway

Lastly, you can also suspend a gateway; this takes the gateway offline and prevents it from receiving or sending any further data. You will need to include a reason in the details field; currently there are five options:

• SUSPENSION_REASON_ACCOUNT_STATE
• SUSPENSION_REASON_CUSTOMER_REQUEST
• SUSPENSION_REASON_LOST_TEMPORARY
• SUSPENSION_REASON_UNSPECIFIED
• SUSPENSION_REASON_UNSUSPEND

The first four are informative, however if you pass "SUSPENSION_REASON_UNSUSPEND" then this will reverse the process and bring the gateway back online.

Request Response
Copy
1
2
3
4
5
6
7
8
9
mutation {
  suspendGateway (
    input: {
      gatewayId: "GWE6BvSemH5UBbEZmyPf1H7R"
      details: {reason:SUSPENSION_REASON_CUSTOMER_REQUEST}
    }) {
    _
  }
}