Soracom Air for Cellular

Test Mode

Test Mode is a feature that allows an IoT SIM to connect to a network and send and receive a limited amount of data and SMS without incurring usage fees. Test Mode allows you to perform network communication tests and initial device provisioning tasks when manufacturing devices that use IoT SIMs, independent of when those devices will be deployed and activated.

Overview

Test Mode has the following behavior:

• When an IoT SIM in the Ready status makes its first connection to a network, its status automatically changes to Testing.
• While the SIM is in Testing status, data and SMS usage fees are waived up to a certain limit of data, SMS, or time spent in the Testing status.
• Once the SIM exceeds any of the data, SMS, or time limits, its status automatically changes to Active (or another IoT SIM status you designate) and billing begins.

Compatibility

While an IoT SIM is in Testing status, it can use most Soracom services and features normally, provided that those services or features do not rely on or affect the SIM's status. However, the following services and features have expanded or limited functionality when used by a SIM that is in Testing status:

Subscription Containers

When adding a Subscription Container to an IoT SIM that is in Testing status, the SIM will remain in Testing, and data and SMS usage fees will also be waived for the additional subscription, up to the defined Test Mode data, SMS, and time limits.

For example, after installing a plan01s SIM in a device and connecting to a network, the SIM status will change to Testing. You can then add a planX3 subscription container, and after the device reconnects to a network using the additional subscription, you can continue sending and receiving data and SMS in the Testing status, within the Test Mode data, SMS, and time limits.

Event Handler

When Test Mode is enabled, you can use the Testing status with Event Handler Subscriber status attribute and SIM status attribute rules to automatically perform actions when a SIM's status changes from Ready to Testing, or from Testing to another status.

For example, you can combine Event Handler with your own script to automatically add a Subscription Container to a SIM when it connects to a network for the first time and its status changes to Testing, or trigger other testing or device provisioning procedures. You can similarly use Event Handler to move a SIM from one group to another, or perform other deployment tasks when its status changes from Testing to Active.

Virtual Private Gateway

Virtual Private Gateways (VPG) allow you to create and manage a dedicated network environment on the Soracom platform for handling cellular connections (sessions) from IoT SIMs. Each type of VPG provides capacity for a certain amount of simultaneous sessions.

When Test Mode is enabled and an IoT SIM is configured to connect using a VPG, its session will count towards the session capacity of the VPG, even when the SIM's status is Testing.

As a result, when utilizing Test Mode with a VPG for a large number of SIMs, we recommend verifying that the VPG has sufficient session capacity for the expected number of cellular connections, including both Testing and Active statuses. If the session capacity is exceeded, IoT SIMs may have trouble establishing a connection.

Limitations

• Test Mode is currently available for the following IoT SIMs:
  • plan01s
  • plan01s - LDV
  • planX1
  • planX3
  • planP1
  • plan-US
• Once an IoT SIM's status has changed to Active, Standby, Suspended, or Terminated, it cannot be changed back to Testing.
• IoT SIMs in Testing status cannot be changed to Inactive.
• IoT SIMs in Testing status cannot be transferred from one operator to another. Refer to Transferring Soracom IoT SIMs for details on transferring SIMs in other statuses.

Enabling Test Mode

In order to enable Test Mode, contact us and submit an application with the following information:

• The Operator ID of your Soracom account
• The subscription(s) to enable Test Mode (such as plan01s or plan-US)^*1
• Preferred Test Mode limits:
  • Data usage limit (such as 1 MiB per SIM)^*2
  • SMS usage limit (such as 3 SMS per SIM)^*3
  • Time limit (such as 90 days)
• Status to apply when a SIM exceeds any of the above limits (choose one of the following):
  • Active (default)
  • Standby^*4
  • Suspended^*4

^{*1 - If you require Test Mode for a Subscription Container, specify the primary subscription of the SIM, either plan01s or plan-US.
*2 - Separate upload and download limits cannot be specified.
*3 - Separate SMS-MT and SMS-MO limits cannot be specified.
*4 - No additional fees are charged when a SIM changes from Testing to Standby/Suspended, however reactivation fees may apply when changing a SIM from Standby/Suspended to Active/Inactive. Refer to the Pricing & Fee Schedule.}

Soracom will review your application and contact you once Test Mode has been enabled, or to request additional information regarding your expected usage.

Searching for SIMs in Testing Status

Once Test Mode has been enabled, you can use the search function of the SIM Management screen to filter for SIMs that are in the Testing status.

Checking a SIM's Testing Status

When an IoT SIM is operating in Test Mode, its status will appear as Testing on the SIM Management screen.

Changing a SIM's Testing Status

From Ready to Testing

Once Test Mode has been enabled, when an IoT SIM in the Ready status makes its first connection to a network, its status automatically changes to Testing.

Manually changing a SIM's status to Testing is not supported.

From Testing to Another Status

As soon as an IoT SIM in the Testing status exceeds any of its Test Mode data, SMS, or time limits, its status will automatically change to the status you specified.

You can also manually change a SIM's status from Testing to another status from the User Console or by using the Soracom API/CLI. See Changing a Subscription Status for instructions.

However, note that the timing of the status change will affect how data and SMS usage fees are calculated, as follows:

• If an IoT SIM in Testing status sends or receives data or SMS on a given day and its status is changed after the end of the day (at 00:00 UTC), that usage will be waived, within Test Mode limits.
• If an IoT SIM in Testing status sends or receives data or SMS on a given day and its status is changed before the end of the day (at 00:00 UTC), that usage will be billed according to the data and SMS usage fees of the updated SIM status.

Therefore, when manually changing a SIM's status from Testing to another status, ensure that the device using the SIM has stopped sending or receiving data and SMS, and wait until after 00:00 UTC to manually change the SIM status.

Checking Remaining Usage Limits

While an IoT SIM is in the Testing status, you can check the current and remaining Test Mode data, SMS, and time limits.

1. Login to the User Console. From the Menu, open the SIM Management screen.

2. From the list of subscribers, click the for the SIM you want to view, then click the Details button.

   https://console.soracom.io

   

3. From the SIM Details panel, click the Usage tab. The current and remaining data, SMS, and time limits will be displayed.

   https://console.soracom.io

   

   The current and remaining Test Mode limits are only available while the IoT SIM is in Testing status. Once the SIM has changed to another status, these limits will no longer be available.

You can also click the Update history tab to check when your SIM's status changed to or from the Testing status.

Programmatic Usage

You can also use the Soracom API and Soracom CLI to get the current and remaining Test Mode data, SMS, and time limits of a particular SIM.

curl -X GET \
|  -H 'X-Soracom-API-Key: <MY-API-KEY>' \
|  -H 'X-Soracom-Token: <MY-TOKEN>' \
|  https://g.api.soracom.io/v1/sims/<SIM-ID>/testing/usage

{
  "startedTime": 1748547283716,
  "usageLimit": {
    "days": 180,
    "dataBytes": 102400,
    "numberOfSms": 5,
    "statusTransitionDelayDays": 0,
    "nextStatus": "active"
  },
  "usage": {
    "dataBytes": 3484,
    "numberOfSms": 0
  }
}

soracom sims get-testing-usage --sim-id <SIM-ID> --coverage-type g