Soracom LTE-M Button Setup Guide

The Soracom LTE-M Button is an easy-to-use, battery-powered IoT button device with built-in cellular connectivity provided by Soracom that allows button click events to be sent wirelessly to the cloud from anywhere LTE-M coverage is available. With a cellular modem, antenna, and all other components integrated inside a sturdy IP54 case, you can begin exploring various IoT concepts and even build simple but powerful applications without the need to design, test, or build complicated hardware.

While the button itself provides a straightforward physical interface, the real power comes from its direct integration to the Soracom platform. By combining the LTE-M Button with Soracom Beam, Soracom Funk, Soracom Funnel, or Soracom Harvest Data, you can easily send button click events to your own server or to various web applications using webhooks, integrate directly with popular cloud functions or cloud services, or even store and view click events directly inside Soracom.

This guide will help you set up your Soracom LTE-M Button, test its cellular connection, and build some example applications that utilize Soraocm Harvest, Beam, and Funk to perform basic actions when the button is clicked.

LTE-M Button Overview

Your Soracom LTE-M Button comes with all the hardware set up and ready to go: no need to connect it to a computer, program its internal software, or write any code — just register the built-in embeded SIM (eSIM), insert batteries, and start clicking.

On the exterior, the size of the device is designed both to accommodate user-replaceable batteries as well as a large positive-action button that can be easily operated with gloves or other instruments, and also allows for IP54-rated protection from dust and moisture, allowing the button to be deployed as-is across a wide variety of use cases.

For cellular connectivity, the LTE-M Button leverages Soracom's global cellular coverage with a built-in eSIM that contains the plan01s - LDV subscription. This subscription allows the button to connect to many LTE-M networks around the world without having to change SIMs or manage eSIM profiles, all with a low monthly basic fee and flat data fee.

The LTE-M Button is programmed to go a step further by sending button click events to the cloud using highly efficient binary data in a UDP packet, which consumes significantly less data compared to other common data formats or protocols. Meanwhile, Soracom platform features such as Binary Parser and Unified Endpoint allow you to decode binary data into web application friendly JSON, convert UDP into HTTP, and forward button clicks to multiple cloud endpoints without retransmitting data, giving you full control over building sophisticated IoT applications while keeping data costs to a minimum.

In the box, you will find the following contents:

• One (1) Soracom LTE-M Button
• One (1) 3.5mm to 2-wire accessory cable

In addition, your Soracom LTE-M Button includes a digital coupon of $15 which will be automatically credited to your Soracom account upon registering the built-in eSIM. This coupon, along with various free tiers provided by Soracom, will allow you to use your Soracom LTE-M Button without any data usage or service fees for at least 1 year at no additional cost.

Setup Guide Requirements

In addition to your Soracom LTE-M Button, you will need the following items to follow along with this setup guide:

• A Soracom account, with a valid Payment Method registered
• A PH0 size Phillips screwdriver
• Two (2) 1.5V alkaline AA batteries
• A computer, to follow this guide as well as to configure Soracom services

You should also be located in an area with LTE-M coverage. To check if LTE-M coverage is available in your country, please refer to the Supported Carriers page.

---

Hardware Setup & SIM Registration

To begin using the Soracom LTE-M Button, we'll need to prepare it for operation. We'll do this using the following steps:

• Unpack the button and remove its rear cover
• Register the eSIM to your Soracom account
• Insert batteries and let the button perform an initial network scan
• Reassemble the button

Open the Button

Let's remove the button's rear cover so we can access the inside of the device.

1. Using a PH0 Phillips screwdriver, carefully unscrew the two screws from the rear cover.

   

2. Separate the rear cover from the main unit.

   

---

Register the built-in eSIM

Your Soracom LTE-M Button includes a built-in embedded SIM (eSIM) which the button uses when connecting to cellular networks. In order for the button to use this SIM, it needs to first be registered to your Soracom account. The steps for registering the built-in eSIM depend on where you purchased your LTE-M Button.

Once you have registered the SIM for your LTE-M Button, you should see it in your list of registered SIMs:

---

Insert batteries

Now let's insert our 2x AA alkaline batteries into the button, making sure to pay attention to the correct orientation for each battery:

As soon as you insert the batteries, the LTE-M Button will power up and begin scanning for available LTE-M networks.

This initial scan may take up to 5 minutes, depending on how many networks are available in your area and the signal strength of each network. During this process, you will see the LED on the front of the LTE-M Button blinking orange.

Once the LTE-M Button has found a suitable LTE-M Network, the LED will turn green to indicate that the button was able to find and connect to a cellular network. The button will also cache the network information so that it can quickly reconnect to the same network without scanning for networks again.

---

Put the button back together

With your LTE-M Button's eSIM registered and batteries inserted, it's time to put the rear cover back on the button.

1. Align the rear cover with the main unit, then press the main unit and rear cover together firmly until you hear a click.

   The click ensures a secure seal around all edges and helps the button achieve its IP54 rating.

2. Finish the assembly by tightening both screws.

With your LTE-M Button set up, you are now ready to move on to configuring the button for use with Soracom services.

---

Configuring Soracom Services

The Soracom LTE-M Button is pre-programmed to send button click events to Soracom's Unified Endpoint, a conslidated data ingress endpoint that automatically redirects device data to the Soracom Beam, Soracom Funk, Soracom Funnel, or Soracom Harvest Data services, depending on which of these services you have enabled. These services provide the following capabilities:

• Soracom Beam - Forwards data to your web server or to a web application with a custom webhook, such as IFTTT, Zapier, Make, or Automate.io
• Soracom Funk - Forwards data to cloud function providers, such as AWS Lambda, Google Cloud Functions, or Microsoft Azure Functions
• Soracom Funnel - Forwards data to cloud service providers, such as AWS IoT, AWS Kinesis Streams, Google Cloud Pub/Sub, or Microsoft Azure Event Hubs
• Soracom Harvest Data - Stores data directly in Soracom

By sending its data to Unified Endpoint, you can easily control how the data sent from the LTE-M Button is handled by simply enabling or modifying a Soracom Beam, Funk, Funnel, or Harvest Data configuration, without having to reprogram the button itself.

Soracom Beam, Funk, Funnel, and Harvest Data services are configured using Groups. Using groups lets you create a specific service configuration and apply it to multiple devices. For example, by enabling the Soracom Harvest Data service for a group, any SIMs added to the group will automatically be able to use Harvest Data. That way, you can easily add more devices to the group without needing to enable Harvest Data for each SIM individually.

The Soracom LTE-M Button is also pre-programmed to send button click data in binary format. By sending data in binary, the button can keep cellular data usage to a minimum. However, binary data can be difficult to decode, and web applications and cloud services often do not support binary data at all.

Groups also provides a Binary Parser function which automatically converts device data from binary to JSON, making it easier to work with. With this function enabled, the binary data sent from the LTE-M Button will first be converted to JSON format, and then redirected to Soracom Beam, Funk, Funnel, or Harvest Data.

Before we begin using Soracom Beam, Funk, Funnel, or Harvest Data services, lets first create a Group and enable the Binary Parser function.

---

Create a Group

1. Back in the User Console, open the SIM Management screen again.

2. From the list of SIM cards in your account, click the checkbox next to the SIM we registered earlier.

3. Click the Actions menu, and select Change group.

   https://console.soracom.io

   

4. Click the dropdown menu, and select Create group….

   

5. In the popup, give the group a name, such as My Button Group, then click Create.

   

6. Our group has been created. Now let's click Change Group to set the new group for our SIM.

   

You should see that the SIM has been added to the group you just created:

---

Enable Binary Parser

Next, let's enable Binary Parser for our new group.

1. From the SIM Management screen, find the SIM for the button. In the Group column, click the name of the group to modify the group configuration.

   https://console.soracom.io

   

2. From the group configuration screen, click the SORACOM Air for Cellular panel to show its settings.

   https://console.soracom.io

   

3. Scroll down to the Binary Parser option, then click the toggle switch to enable the function.

4. Enter @soracom.button into the Format field and click Save.

   

   The @soracom.button setting is a predefined format that tells the Binary Parser function that incoming binary data is being sent by a Soracom LTE-M Button device, and that the binary data should be converted to JSON based on the binary data format that the Soracom LTE-M Button uses.

With a group set up and Binary Parser enabled, we are now ready to set up Soracom Beam, Funk, Funnel, or Harvest Data.

---

Example 1: Soracom Harvest Data

In this example, we will enable the Soracom Harvest Data service to capture and store button click data coming from our LTE-M Button directly in Soracom. Although the Harvest Data service will only store the data, it will allow us to easily view the data sent by our button and confirm that it is working correctly, without having to set up other services.

To begin using Harvest Data, we will perform the following steps:

• Enable Soracom Harvest Data for our group
• Click the button to send data to Harvest Data
• View the data captured by Harvest Data
• Disable Soracom Harvest Data after we're done

Enable Soracom Harvest Data

1. Back in the group configuration screen, click the SORACOM Harvest Data panel to show its settings.

   https://console.soracom.io

   

2. Click the toggle switch to enable Harvest Data collection, then click Save.

   

Click the button

Now that we have set up the LTE-M Button and enabled Soracom Harvest Data, it's time to test a button click.

1. Click the button once.

   

   After a second, the LED on the LTE-M Button will begin to blink green (1 blink per second). This indicates that the button is in the process of connecting to a cellular network.

   Once the button has connected to the cellular network, it will automatically send the data for the button click event to Unified Endpoint.

If the transmission was successful, the LED will turn solid green for 2 seconds, and the button will automatically turn off. We can now go back to the User Console and verify the data that was sent by the button.

Verify the data

Finally, let's head back to the User Console to check out the test data online.

1. From the Menu, open the SIM Management screen.

2. Click the checkbox next to your SIM card. Then click the Actions menu and select Harvest Data.

   https://console.soracom.io

   

We can now see the data sent from the button to Unified Endpoint, which was then converted from binary to JSON, and then forwarded to Soracom Harvest Data and stored:

If you see data similar to the above, congratulations! You have just sent your first button click event from the Soracom LTE-M Button to the cloud!

Taking a closer look at the Content, we can see the following values that were decoded by Binary Parser:

• prod_type - A fixed value of 1 that corresponds to the Soracom LTE-M Button device.
• f_ack - A boolean true or false that indicates if the button requested a response. When true, Soracom sends a response back to the button to let it know that the data was successfully received. In turn, this lets the button know to display the solid green LED.
• msg_type - A string event which indicates that the data sent was due to a button click event.
• seq_number - An integer that increases sequentially, indicating how many times the button has been clicked. This number automatically resets to 0 after 4095.
• detect_type - The type of click detected by the button. Possible values:
  • Single short click - When the button is pressed and released once.
  • Double short click - When the button is pressed and released twice within 2 seconds.
  • Single long click - When the button is pressed, held for more than 2 seconds and up to 6 seconds, and then released.
• crc8 - A boolean true or false that indicates if there was an error during transmission that resulted in corrupted data. When true, all values above are accurate, and when false, data corruption has occurred and the values above may not be what the button originally sent.
• binaryParserEnabled - An additional boolean value true indicating that the data was converted to JSON using Binary Parser.

While we're here, we can also test out the double click and long click events, and even see the data appear in almost real time:

3. From the SORACOM Harvest Data screen, click the Auto refresh toggle to automatically check for new data as it arrives in Harvest Data.

   https://console.soracom.io

   

4. Click the LTE-M Button again, this time testing another click type:

   • Double short click - Press and release the button twice within 2 seconds.
   • Single long click - Press and hold the button for more than 2 seconds and up to 6 seconds, and then release it.

   Once again, the LED will begin blinking green as the button reconnects to the cellular network, and will turn solid green when the data has been successfully sent.

   You should also be able to see the additional clicks show up in Harvest Data as they are received, with the detect_type value confirming the type of click.

If you are able to see different button click events show up in Harvest Data, then your button and its cloud connectivity are fully operational!

However, Soracom Harvest Data only stores the data sent by the button and does not perform any other actions — For that, we need to set up Soracom Beam, Soracom Funk, or Soracom Funnel next.

Disable Soracom Harvest Data

Once you are done testing and verifying the data coming from the LTE-M Button, you can disable the Soracom Harvest Data service if you have no need for storing the data on Soracom.

1. Open the group configuration screen again, and click the SORACOM Harvest Data panel to show its settings.

2. Click the toggle switch to disable Harvest Data collection, then click Save.

   

---

Example 2: Soracom Beam & HTTP Webhook

In this example, we will enable the Soracom Beam service to trigger an HTTP webhook in order to send an email to ourselves whenever our button is clicked. For this example, we will use IFTTT (If This Then That), which is a popular automation service that provides an intuitive way to quickly build different event-driven actions. IFTTT has a vast library of official and community-made actions that can be combined with a webhook (as well as other types of events), making it easy to prototype different behaviors for your LTE-M Button.

To set up Beam with IFTTT, we will perform the following steps:

• Create a new IFTTT email webhook
• Enable and configure Soracom Beam
• Check that we received an email

Create an IFTTT email webhook

Before we can configure Soracom Beam, we need to set up a webhook. Let's create one now.

1. Login to IFTTT or create a free account.

2. From main menu, click Create to create a new IFTTT applet.

   https://ifttt.com

   

3. In the If This block, click Add.

   https://ifttt.com

   

4. In the list of available services, search for webhook and select Webhooks. Then select the Receive a web request with a JSON payload trigger.

   https://ifttt.com

   

5. Configure the webhook trigger by choosing a trigger Event Name. Since this webhook will be triggered when we press our LTE-M Button, let's call this button_pressed

   https://ifttt.com

   

6. Next, in the Then That block, click Add.

7. In the list of available services, search for email and select Email. Then select the Send me an email action.

   https://ifttt.com

   

8. Here you can configure the email action to customize the email that will be sent. For now, we can keep the default values.

   https://ifttt.com

   

9. Once you have finished selecting and configuring both the If trigger and Then action, click Continue, and finish the set up by giving your IFTTT applet a name such as Send me an email when my Soracom LTE-M Button is pressed.

   https://ifttt.com

   

Copy the IFTTT webhook address

To hook up this IFTTT applet to Soracom Beam, we need to get the Webhook trigger address.

1. From applet details page, click the icon that corresponds to the Webhooks trigger:

   https://ifttt.com

   

2. Then click the Documentation link:

   https://ifttt.com

   

3. A new page will open containing information for how to trigger the webhook:

   https://ifttt.com

   

   In the first URL, modify the {event} field to match the webhook Event Name you specified earlier. In this case, let's change this to button_pressed.

   Then copy the full URL. This is the IFTTT webhook URL that we will configure in Soracom Beam.

   Important! The key at the end of the IFTTT URL is your personal key for accessing the webhook. Take care to keep this key secret, otherwise an unauthorized person could run your IFTTT applet without your permission.

Enable and configure Soracom Beam

We're almost there! Now with IFTTT set up and the webhook URL handy, let's enable and configure Soracom Beam:

1. Head back to the User Console and open the Group settings page for your button group. Then click the SORACOM Beam panel to show its settings.

   https://console.soracom.io

   

2. Click Add Configuration, then select UDP → HTTP/HTTPS entry point.

   

   We're using the UDP → HTTP/HTTPS entry point option because the Soracom LTE-M Button will send its click data in a UDP packet. Since our IFTTT webhook will be expecting an HTTPS request instead, we can take advantage of Soracom Beam's Protocol Conversion function so that we don't have to convert UDP to HTTPS by ourselves.

3. Configure Soracom Beam with the following settings:

   

   • Configuration Name - Any name you like, such as Send Click to IFTTT
   • Protocol - HTTPS
   • Host Name - maker.ifttt.com
   • Port Number - 443 (the default port for HTTPS connections)
   • Path - The IFTTT webhook URL from earlier, with the https://maker.ifttt.com part removed, as we have specified these in the Protocol and Host Name settings above.

   If you are using a different webhook service, or if you have your own web server or API endpoint, enter the HTTP or HTTPS endpoint details here.

   As we don't need any other settings, we can leave the rest of the Beam options with their default values.

   Then click Save.

With the IFTTT webhook URL added to Beam, the Soracom Beam configuration should now look something like this:

Finally, we can press our button again...

...and in just a few moments, receive an email notification from IFTTT in our inbox!

Disable Soracom Beam

If you are switching to another service such as Soracom Funk or Soracom Funnel, or if you want to temporarily stop forwarding data to the server or webhook, don't forget to disable the Soracom Beam configuration.

1. From the Group settings page for your button group, click the SORACOM Beam panel, then click the toggle switch to disable your Soracom Beam configuration.

Your Soracom Beam settings will still be saved in the group configuration so that you can easily re-enable the setting later if needed.

---

Example 3: Soracom Funk & Cloud Function

In this example, we will enable the Soracom Funk service to invoke a cloud function when our button is clicked, which will in turn process the data and send a Slack notification.

By using a cloud function, we have full control over the logic for processing the button click event. While sending a notification to Slack is relatively trivial, this example will cover the basic concepts so that you can easily add any further logic that your application requires, such as connecting to databases or integrating with different web applications based on the type of button click.

For this example, we will set up Soracom Funk for use with an AWS Lambda cloud function. Since the Soracom Funk documentation already provides a dedicated guide for setting up Funk with AWS Lambda in order to send a Slack notification, this section will summarize the steps from that guide with a few changes specific for the Soracom LTE-M Button.

To set up Funk with AWS Lambda and Slack, we will perform the following steps:

• Create a Slack webhook
• Create an AWS Lambda function
• Create an AWS IAM user
• Register the AWS IAM credentials to Soracom
• Enable and configure Soracom Funk

Create a Slack webhook

Follow the instructions from the Using Funk to Send Data to Slack via AWS Lambda guide for creating a new Slack webhook. In general, you should:

1. Login to your Slack workspace, navigate to the Configure apps section, click the Custom Integrations section, and click Incoming WebHooks.

2. Click the Add Configuration button, and follow the instructions to select a channel where the webhook will post messages.

At the end of these steps, you should have a Slack Incoming WebHook URL which looks like this:

https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX

Create an AWS Lambda function

Next, follow the instructions from the Using Funk to Send Data to Slack via AWS Lambda guide for creating a new AWS Lambda function. In general, you should:

1. Login to your AWS account, select the AWS region where you want your Lambda function to be located, and access the AWS Lambda dashboard.

2. Then, Create a new function, follow the instructions to Author from scratch, give your Lambda function a name, and select a Node.js runtime.

3. Copy and paste the following Node.js application into the Function code, which incorporates some additional logic specific for the Soracom LTE-M Button:

import https from 'https';
import url from 'url';

const slackUrl = process.env.SLACK_URL;

export const handler = async function(event, context) {
  // Log the incoming event and context parameters
  console.log('event: %j', event);
  console.log('context: %j', context);

  // Get the 19-digit SIM ID (ICCID) where the click came from
  const simId = context.clientContext.simId;

  // Get the button click type
  const detectType = event.detect_type;

  // Set a custom message to send to Slack depending on click type
  let message;
  if (detectType === 'Single short click') {
    message = `Incoming single click! 💥`;
  } else if (detectType === 'Double short click') {
    message = `Incoming double click! 🔔🔔`;
  } else if (detectType === 'Single long click') {
    message = `Incoming long click! 🎉🎉🎉`;
  } else {
    message = `Unknown incoming event! 🤔`;
  }

  // The message to post to Slack, using Slack's Block payload format   
  // https://api.slack.com/block-kit
  var slackWebhookPayload = {
    "blocks": [
      {
        "type": "section",
        "text": {
          "type": "plain_text",
          "text": message,
          "emoji": true
        }
      },
      {
        "type": "context",
        "elements": [
          {
            "type": "mrkdwn",
            "text": `Sent from Soracom LTE-M Button (${simId})`
          }
        ]
      }
    ]
  };

  // Prepare the HTTP POST body
  const requestBody = JSON.stringify(slackWebhookPayload);

  // Prepare the HTTP POST options
  const slackWebhookOptions = url.parse(slackUrl);
  slackWebhookOptions.method = 'POST';
  slackWebhookOptions.headers = {
    "Content-Type": "application/json",
    "Content-Length": Buffer.byteLength(requestBody)
  };

  // Create the HTTP POST request
  return new Promise((resolve, reject) => {
    const req = https.request(slackWebhookOptions, (response) => {
      if (response.statusCode === 200) {
        // AWS Lambda log
        console.log('Message successfully sent to Slack!');

        // Response returned to device
        resolve({ "result": "ok" });
      } else {
        // AWS Lambda log
        console.log(`Slack Incoming WebHook returned error ${response.statusCode}`);

        // Response returned to device
        reject({ "result": "ng" });
      }
    });

    // Send the request body
    req.write(requestBody);
    req.end();
  });
};

4. Finally, add a SLACK_URL Environment variable and paste the Slack Incoming WebHook URL generated earlier, and Save your AWS Lambda function.

Create an AWS IAM user

Next, follow the instructions from the Using Funk to Send Data to Slack via AWS Lambda guide for creating a new AWS IAM user. In general, you should:

1. Open the AWS IAM dashboard.

2. Add a User with Programmatic access, and attach a policy that gives this user the lambda:InvokeFunction permission for the AWS Lambda function you created.

3. Generate an Access key ID and Secret access key for the user.

Register the AWS IAM credentials

Next, follow the instructions from the Using Funk to Send Data to Slack via AWS Lambda guide for registering the AWS IAM user credentials to Soracom. In general, you should:

1. Login to the User Console, access the Security screen, and click the Credentials.

2. Then, Register a credentials set, and enter the AWS credentials Access key ID and Secret access key generated earlier.

Enable and configure Soracom Funk

Finally, follow the instructions from the Using Funk to Send Data to Slack via AWS Lambda guide for enabling and configuring Soracom Funk. In general, you should:

1. Head back to the User Console and open the Group settings page for your button group, and click the SORACOM Funk panel to show its settings.

2. Then, click the toggle switch to enable Soracom Funk, select the AWS Lambda service, enter the Function ARN for your AWS Lambda function, select your AWS credentials, and specify JSON content type.

With these steps all completed, you can now click your button and see notifications appear in Slack.

Disable Soracom Funk

If you are switching to another service such as Soracom Beam or Soracom Funnel, or if you want to temporarily stop sending data to your cloud function, don't forget to disable the Soracom Funk configuration.

1. From the Group settings page for your button group, click the SORACOM Funk panel, then click the toggle switch to disable Soracom Funk.

Your Soracom Funk settings will still be saved in the group configuration so that you can easily re-enable the setting later if needed.

---

Next Steps

With Soracom Beam, Soracom Funk, and Soracom Harvest Data providing core capabilities of sending click events to different servers, webhooks, cloud functions, or even simply storing click data, you can now integrate your Soracom LTE-M Button to just about any software automation service, smart device ecosystem, or other computerized system or process by just modifying your group settings.

For some advanced control, here are some additional services and button features which you can add into your application:

Using Different Groups

As we learned in this tutorial, Soracom Beam, Funk, Funnel, and Harvest Data settings are configured at a group level. Besides making it easy to add more buttons to the same group and inherit the same configuration, you can create multiple groups, with each group having its own application configuration, and then quickly switch a button from one group to another.

For example, you might create group A with a Soracom Beam configuration that sends an HTTPS webhook to an automation service, and group B with a Soracom Funk configuration that runs a cloud function to process some data. With these two groups set up, you can "wirelessly reprogram" your button to switch from the webhook to the cloud function by just moving the button from one group to the other.

Soracom Lagoon

For applications where you only need to store the button click history and do not need to perform additional actions when the button is clicked, you can add Soracom Lagoon on top of Soracom Harvest Data.

Lagoon provides powerful dashboard and data visualization tools which you can use to, for example, track the history of individual button clicks over time based on click type, or identify the time of day when the button is clicked most often.

While Lagoon's data visualization capabilities work best with devices that collect types of variable sensor data (such as temperature, humidity, accelerometer, and so on), you can still use it to build a functional dashboard for keeping track of button clicks. And because Lagoon integrates directly with Harvest Data, there are no servers or configurations to set up. Simply turn on Soracom Lagoon and start building your dashboards.

Soracom Funnel

While Soracom Beam and Soracom Funk allow you to integrate with the majority of automation services or cloud functions that you can think of, there are some cloud services that are especially suited for processing data coming from a large number of IoT devices.

Soracom Funnel is a cloud adapter service that allows you to integrate directly with services like AWS Kinesis Streams, Google Cloud Pub/Sub, and Microsoft Azure Event Hubs, without the need to build or set up the integration yourself.

If you begin to add more and more buttons to your application and need to integrate such a cloud service to process a large amount of button click data, Funnel allows you to easily set up the integration and begin streaming click data to your cloud.

2-Wire Accessory

True to its name, the main feature of the Soracom LTE-M Button is of course the actual physical button. However, some applications may require a physical action that is analogous to a button click, but without actually clicking the built-in button.

A 2-wire accessory is included in the Soracom LTE-M Button package, and provides a way to electronically trigger a button press.

When clicking the built-in button, a physical circuit inside the device is momentarily closed, allowing a small amount of electric current to flow through. By detecting this current, the LTE-M Button knows that the button was pressed. The 2-wire accessory functions similarly, with the LTE-M Button detecting when the two wires are connected or disconnected and triggering an event accordingly.

You can easily test this by removing the accessory port cover on the side of the LTE-M Button and inserting the 3.5mm plug into the accessory port, then touching the two exposed wires together. You should see the LED start blinking green, indicating that the LTE-M Button has detected the change in the circuit and is now connecting to a cellular network. Releasing the two exposed wires will also trigger another event.

The LTE-M Button is designed to be able to tell the difference between events coming from the built-in physical button and events coming from the 2-wire accessory. When using the accessory, the detect_type value in the click event data will become:

• Rising edge - When the 2-wire accessory is closed (the wires are connected)
• Falling edge - When the 2-wire accessory is opened (the wires are disconnected)

With this capability, you can connect the 2-wire accessory to a pressure sensor circuit, such as to detect when someone is stepping in a particular area or when a vehicle is driving over a specific location.

The 2-wire accessory can also be connected to other electronics, such as an Arduino or Raspberry Pi, allowing you to electronically trigger a button click based on other device logic. However, when doing so, you will need to make sure that the 2-wire accessory is opened or closed using a relay or transistor so that a voltage is not applied directly to the accessory.

---

Frequently Asked Questions

What do the LED lights mean?

The LED status light on the Soracom LTE-M Button has the following color and blink patterns:

• Blinking green - The button is connecting to a cellular network in order to send a button click event.
• Solid green - The button successfully connected to a network and sent a button click event.
• Blinking orange - The button is performing a network scan in order to find an available cellular network.
• Blinking red - The batteries are low and should be replaced soon.
• Solid red - There was an error connecting to a cellular network, or an error sending a button click event.

What is the battery life?

Since battery life depends on a wide variety of factors, it's impossible to get an estimate that is reasonably accurate across different scenarios. However, paying attention to these major factors may help you understand what sort of battery life to expect for your particular application:

• Advertised versus actual voltage - While all AA alkaline batteries are rated for 1.5V, there are usually some small differences between battery brands. Name brand batteries will usually provide a little extra charge in order to guarantee that 1.5V is actually available when the battery is used, while off brands may measure 1.5V when the battery is manufactured but with less charge by the time the battery is used.
• Type of battery - While Soracom recommends using alkaline batteries, it is technically possible to use other types of batteries that have a different chemistry, provided the battery voltage is still the required 1.5V. Compared to alkaline batteries where voltage drops at a relatively steady rate over time, other types of batteries may keep a more stable voltage for most of their charge, but then suddenly drop once the batteries are almost empty. While there may not be a significant difference in battery life between different types, keep in mind that using batteries other than alkaline may affect the timing of the low battery LED indicator due to the difference in voltage drop behavior.
• Frequency of clicks - Batteries will lose their charge slowly over time due to a tiny amount of idle current that the LTE-M Button needs to detect click events. If your application involves clicking the button dozens or even hundreds of times per day, the overall amount of battery life lost to passive drain is small compared to the battery life used to connect to a network and send click events, therefore you may be able to get a few thousand clicks before having to replace the batteries. On the other hand, if the button is clicked infrequently, a greater amount of charge is lost to passive drain, resulting in fewer clicks.
• Temperature - Regardless of battery type and frequency of clicks, cold temperature environments will artificially reduce the effective voltage of batteries. If your LTE-M Button is installed in a location that is frequently exposed to cold temperatures, adding some form of insulation or moving it to an area with less exposure may help improve battery life.

Even with so many factors, a fresh set of batteries should be able to last for up to 2,000 clicks in most common scenarios and applications.

Can I cancel a click?

Yes. Once you have initiated a single short click, a double short click, or a single long click, the LED on the LTE-M Button will begin to blink green. During this time, if you click the button again, the button will cancel the click.

Note that if you are using the seq_number value to keep track of how many times the button has been clicked, this value will still increase even if the click event is cancelled.

Can I temporarily disable my button?

Yes. You can change the status of your SIM from Active to Inactive. Doing so will disable the SIM in your button from being able to connect to a network. As a result, when the button is clicked, it will not be allowed to connect to any cellular network, and the click event will not be sent to the cloud. Deactivating your SIM ensures that your button will not incur any data usage fees.

For instructions on how to change the status of your SIM, refer to the Soracom Air: Subscriber Status documentation.

When you're ready to enable your button again, simply change the status of the SIM from Inactive back to Active. There are no fees for changing a SIM status between Active and Inactive, so you can deactivate the SIM as often as needed.

What does the reset button do?

Underneath the rear cover inside the main unit, there is a small reset button. Clicking this button will tell the LTE-M Button to perform a new network scan. This may be helpful if the device has moved from one location to another and is having trouble reconnecting to the previously used cellular network, such as when moving into an area where the previous network does not have coverage, or moving from one country to another.

To click the reset button, insert a thin, stury object such as a paperclip or a SIM ejector tool into the reset button and gently press until you feel a click, then release. The LED on the button will begin to blink orange, indicating that the button is now searching for available networks.

What is the extra SIM card slot for?

When setting up the LTE-M Button hardware, you might notice that there is a nano-SIM card slot located underneath the battery compartment.

Since the Soracom LTE-M Button includes a built-in embedded SIM (eSIM) that contains the plan01s - LDV subscription, there is no need to install any SIM card. Instead, this SIM card slot is reserved so that the cellular network coverage can be expanded in the future by inserting a different Soracom SIM, for situations where the plan01s - LDV subscription does not have coverage in a particular country.

When another Soracom SIM is installed in the SIM card slot, the button will use the SIM card to connect to a cellular network, rather than using the built-in eSIM.

What other Soracom services can I use?

Because the LTE-M Button provides just a basic function compared to other types of IoT devices, the Soracom services that are most relevant are the Groups, Binary Parser, Soracom Beam, Soracom Funk, Soracom Funnel, and Soracom Harvest Data functions and services covered in this guide.

The Soracom platform provides many additional network and application services, such as adding custom authentication for more security, creating a private cellular network connection, enabling remote device access, or provisioning devices with credentials. Since the LTE-M Button is designed to simply wake up, send a click event to the cloud, and go back to sleep, most of these additional services will not provide useful functionality for the LTE-M Button.

However, these additional services share the same sort of flexibility and ease of use as the Soracom Beam, Funk, Funnel, and Harvest Data services, such as the ability to create a single group configuration and apply it to multiple devices, or to change device behavior through the group configuration without having to modify the device, which you can leverage when building more complex IoT applications that utilize more powerful devices.

---

Troubleshooting

The following troubleshooting steps may help you identify and resolve some common issues.

The button cannot find or connect to a network

When setting up the LTE-M Button for the first time, or after pressing the reset button, the button will initiate a cellular network scan in order to find a suitable LTE-M network to use. During this time, the LED will blink orange, and once the button has found an available LTE-M network, the LED will turn green. This process may take up to 5 minutes to complete.

If the LED continues to blink orange and never turns green, the button may have trouble getting a strong enough signal with the cellular network, or an LTE-M network is not available.

To troubleshoot:

• First check the Supported Carriers page to see if LTE-M coverage is available in your country. Please note that in some countries, LTE-M networks may not have been deployed in all areas. If LTE-M coverage is not available where you are located, then unfortunately the LTE-M Button will not be able to connect to a network.
• If LTE-M coverage is available in your area, may have trouble getting a strong enough signal. Try the troubleshooting steps in the next section below.

If your LTE-M Button has already successfully completed a network scan but is unable to send button click events to the cloud (indicated by a blinking green LED followed by a solid red LED), this may also be caused by a poor network signal at your location. You can use the same steps in the next section below to troubleshoot.

The button takes a long time to connect to a network

Once the LTE-M Button has completed a network scan and found a suitable network, sending a button click event to the cloud should usually take no more than 15-20 seconds from clicking the button until seeing a solid green LED light.

If your button is able to successfully send click events, but takes significantly longer to connect to a network:

• Try testing the button in a different area. In some cases, environment obstructions such as concrete walls or reflective surfaces may affect the cellular network signal strength and slow down the network connection process.
• Make sure the built-in antenna is not obstructed. The LTE-M Button's built-in antenna is located opposite the button, underneath the Soracom LTE-M Button logo. Check that this side is not covered up, and is positioned away from surfaces or other devices that might interfere with wireless signals.
• In some cases, the cellular network previously used by the LTE-M Button may no longer be available, such as when moving from one area to another, or moving to another country. You can initiate a new network scan by pressing the reset button located inside the button.

The button successfully connected to a network but I don't see any data

The Soracom LTE-M Button is pre-programmed to send click event data to Unified Endpoint, which itself will forward data to Soracom Beam, Soracom Funk, Soracom Funnel, or Soracom Harvest Data, depending on which of these services you have enabled.

If you are not receiving any data:

• Check that you have created a Group, and that the SIM corresponding to your button has been added to the group
• Check that you have enabled a Soracom service, such as the Soracom Beam or Soracom Funk examples above.
• In some cases, Soracom Beam, Soracom Funk, or Soracom Funnel may have trouble forwarding data to your endpoint due to incorrect authentication. You can follow the Soracom Harvest Data example above to quickly verify whether the data arrives at Soracom but fails to be forwarded, or does not arrive at all.
• In some cases, your endpoint may be configured to receive a specific data format. For example, when using Soracom Funk, you can specify that the data being sent is in JSON format. However, if Binary Parser is not enabled, then the actual data will be in the LTE-M Button's original binary format, which will return an error. Check that the Binary Parser option and your Soracom service configuration have been configured with correct data format that your endpoint requires.

The click event data is not in JSON format

The Soracom LTE-M Button sends its data using a binary format. To convert the binary data into JSON so that it is easier to use, make sure that the Binary Parser option is enabled, and that the specified Format is @soracom.button. More details are in the Enable Binary Parser section above.

Nothing happens when pressing the button

When the remaining battery charge becomes too low, the LED will blink red indicating that the batteries should be changed soon. However, in some cases the batteries may become completely empty, which also results in the low battery LED stopping as well.

If nothing happens when pressing the button, it may be that the batteries have completely discharged. Replace the batteries with a new set, and try again.

If you still have trouble after replacing the batteries, please contact our support team for assistance.

---

Additional Resources & Support

For additional technical and product information on the Soracom LTE-M Button, please visit soracom.io/button

For complete information on using the Soracom User Console, SIM management tools and APIs, Soracom platform services, and additional capabilities, documentation is available on the Soracom Developers website.