Soracom LTE-M Button Setup Guide

Soracom LTE-M Button

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 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

Soracom LTE-M Button box contents

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 button 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.

For more information on plan01s - LDV coverage and pricing, refer to the Soracom Air for Cellular: SIM Types, Supported Carriers, and Pricing & Fee Schedule documentation.

In the box, you will find the following contents:

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.

LTE-M Button Functionality

Modes, Features, and Message Types

To change your button configuration or update its firmware, please contact Soracom Support for assistance.

The LTE-M Button can operate in multiple modes beyond its default Event Mode that only sends messages when the button is clicked. There are also additional features that are availble on different firmware versions.

Additional Features and Message Types Minimum Version Required Functionality
Status Messages v2220 Sends battery, firmware, hardware, and operation mode information.
Heartbeat Messages v2220 Sends messages containing the battery status at a configurable interval.
Network Standby v3134 The LTE-M Button can optionally be configured to stay connected to network for a configurable period after sending messages.
Battery Voltage in All Messages v3134 Starting in v3134 every message sent includes battery voltage information.
Automatic Status Message v3134 Status messages can be optionally sent every 24 hours.
Enhanced LED Behavior v3134 Enhanced LED patterns for improved usability and troubleshooting capability.


Configurable Modes Minimum Version Required Functionality
Event Mode v2220 Sends message upon click or external I/O trigger.
Event + Heartbeat Mode v2220 Sends message upon click or external I/O trigger along with Heartbeat messages.
Timer Mode v2220 Logs the number and type of clicks and I/O events over a configurable period then sends a message containing that data.
Event + Timer Mode v2220 Sends message upon click or I/O trigger. Also logs the number and type of clicks and I/O events over a configurable period.
Alert Mode v3134 Sends immediate message on click or I/O trigger, prioritizing delivery for emergencies.
Alert + Heartbeat Mode v3134 Sends immediate message on click or I/O trigger, prioritizing delivery for emergencies. Also sends Heartbeat messages.

Additional Features and Message Types - Detailed

Refer to the table above in order to determine whether features are supported by your currently installed firmware version.

Configurable Modes - Detailed

LED Features

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

LED Behavior

Light Behavior Table

LED Reference Table

When configured for Alert Mode, the LED will blink orange after each click, making it easy to differentiate from other modes. v3134 and above.

Color Pattern Pattern timing / details Meaning
Green • One short blink (70ms on) Button detected a single short click: falling edge, or rising edge. *1, *3
• • Two short blinks (70ms on/330ms off, twice) Button detected a double short click. *1
• • • Three short blinks (70ms on/330ms off, three times) Button detected an extra long click. *3
• • • • • (repeating) Continuous short blinks (70ms on/630ms off, repeating) Button has connected and is sending a message.
━ One long blink (1000ms on) Button detected a single long click. *1, *3
━ ━ (repeating) Continuous medium blinks (350ms on/650ms off, repeating) Button is connecting to an LTE-M network.
━━ One extra long blink (2000ms on) The button successfully connected to a network and sent a button click event.
Orange • One short blink (70ms on) Button detected a single click: falling edge, or rising edge. *2, *3
• • • Three short blinks (70ms on/930ms off) Button was powered on.
• • • (repeating) Continuous short blinks (70ms on/930ms off, repeating) Button is performing LTE-M band scan.
Red • • • (repeating) Continuous short blinks (70ms on/930ms off, repeating) Button battery is low.
━━ One extra long blink (2000ms on) There was an error connecting to a cellular network, or an error sending a button click event.

*1 - Applies only to Event, Timer, Event + Timer, and Event + Heartbeat modes.
*2 - Applies only to Alert and Alert + Heartbeat modes.
*3 - Only available in firmware v3134 or above.

Setup Guide Requirements

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

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.

Please note that in some countries, LTE-M networks may not have been deployed in all areas. If you are following this guide but your LTE-M Button is unable to connect to a network, please refer to the Troubleshooting section at the end of this guide for details.

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:

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.

    Unscrew rear cover

  2. Separate the rear cover from the main unit.

    Button with rear cover removed

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.

If you purchased your button directly from Soracom:

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

  2. Click Register SIM.

    https://console.soracom.io

    Register SIM

  3. Click the From Order tab, then find your order and click the Register button.

    Register SIM

When registering SIMs from an order, they will be added to your list of SIMs without any name. If you would like to give your SIM a name, simply find the SIM in the list of SIMs, hover over the Name column, and click the icon in order to give your SIM a name such as my-button.

If you purchased multiple LTE-M Buttons and want to check which SIM is associated with which button, look for the 19-digit ICCID number printed on the label inside the button. This number will match the SIM ID listed in the SIM Management screen.

If you purchased your button elsewhere:

With the button's rear cover removed, you will find a label containing a 19-digit ICCID number and an 8-digit PUK code. This is the information you need to register the SIM.

ICCID and PUK printed inside the device

In case the ICCID and PUK numbers are too small to read, QR codes for both are also printed on the label, and can be scanned using a smartphone camera or dedicated 2D barcode reader.

With these numbers ready, let's register the button's built-in eSIM to your Soracom account:

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

  2. Click Register SIM.

    https://console.soracom.io

    Register SIM

  3. Enter the ICCID and PUK for your button.

    Register SIM from direct input

    • You can optionally set a Name for this SIM, such as my-button. This may be helpful if you are registering more than one button and want to tell them apart.
    • If this is your first time setting up a Soracom LTE-M Button, you can leave the Group option empty. We will set up a group for our button later in this guide.

      If you have already set up another Soracom LTE-M Button before and want to set up this button with the same settings, you can specify the Group setting here and begin using your additional button right away.

  4. Click Register.

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

https://console.soracom.io

LTE-M Button SIM registered to account

For additional information on how to register SIMs, refer to the SIM Registration page.

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:

Insert batteries into the button

Although rechargeable AA batteries will also fit in the Soracom LTE-M Button, please pay close attention to the voltage of such batteries. Certain rechargeable batteries have a nominal voltage well in excess of 1.5V, and inserting such batteries in the Soracom LTE-M Button may cause permanent damage.

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.

If the LED turns red during this process, it indicates that the button was unable to find a suitable network, or that the network connection failed. Refer to the Troubleshooting section at the end of this guide for details.

Reassemble the Button

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 button 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:

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 buttons. 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 buttons 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 button 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

    Change group

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

    Change group

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

    Create group

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

    Update group

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

https://console.soracom.io

SIM added to group

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

    Click to edit group

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

    https://console.soracom.io

    Soracom Air for Cellular settings

  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.

    Binary Parser configuration

    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.

If you have set up a Soracom LTE-M Button before, or have no need for storing data on Soracom, feel free to skip to the next examples.

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

Enable Soracom Harvest Data

Soracom Harvest Data is a paid service. A free tier is available, which you can use to capture data sent by your LTE-M Button in order to verify that it is working correctly.

Please note that if Harvest Data is enabled for multiple buttons, you might exceed the free tier. If you have no need to store button data on Soracom after confirming that everything is working correctly, we recommend turning off the Harvest Data service to avoid unwanted charges.

Please also note that regardless of the free tier, sending and receiving data over the cellular network will still incur data usage fees.

Refer to the Pricing & Fee Schedule for more information.

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

    https://console.soracom.io

    Soracom Harvest Data settings

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

    Enable Harvest Data

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.

    Click the LTE-M Button

    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.

If the LED turns red during this process, it indicates that the button was unable to find a suitable network, or that the network connection failed. Refer to the Troubleshooting section at the end of this guide for details.

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 View Harvest Data.

    https://console.soracom.io

    Select the SIM and choose Harvest Data

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:

https://console.soracom.io

Harvest Data displaying the button data in JSON format

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:

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:

  1. 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

    Enable Harvest Data Auto Refresh

  2. 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.

For additional information on using Harvest Data, refer to the Harvest: Configuration and Harvest: Viewing Data documentation.

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.

Of course, some button applications may not have any need to perform further actions besides simply recording the button click events. If your application can utilize just the click event data that is stored, you can also enable Soracom Lagoon, a dashboard and data visualization service that sits on top of Harvest Data and lets you build interactive dashboards for viewing button click events.

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.

    Disable Harvest Data

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.

While IFTTT is a great place to start, it is by no means the only option. You can use Soracom Beam with almost any service that supports HTTP or HTTPS POST webhooks, such as Zapier, Make, and Automate.io. If you want to connect your LTE-M Button to a different service, simply use its HTTP/HTTPS endpoint instead of the IFTTT example below.

Note that some services may require a specific data format or authentication method which may not be supported by Soracom Beam. Refer to the Soracom Beam documentation for more details on how Beam forwards data to your endpoint.

If you have your own web server or API endpoint that accepts incoming HTTP or HTTPS POST requests, you can also just use it instead of a third party service. Skip to the Enable and configure Soracom Beam section below, and configure Soracom Beam to use your HTTP endpoint instead of the IFTTT example below.

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

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

    Create a new IFTTT applet

  3. In the If This block, click Add.

    https://ifttt.com

    Add an If trigger

  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

    Select Webhook trigger

  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

    Configure Webhook trigger

  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

    Select Email action

  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

    Configure Email action

  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

    Finish creating applet

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

    View Webhook details

  2. Then click the Documentation link:

    https://ifttt.com

    View Webhook documentation

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

    https://ifttt.com

    Get the Webhook URL

    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

Soracom Beam is a paid service billed according to the number of requests used. A free tier is available, which will provide enough requests for thousands of button clicks each month. However, if you are planning to deploy a large number of LTE-M Buttons, you might exceed the free tier.

Please note that regardless of the free tier, sending and receiving data over the cellular network will still incur data usage fees.

Refer to the Pricing & Fee Schedule for more information.

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

    Soracom Beam configuration

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

    Add a UDP to HTTP/HTTPS configuration

    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:

    Configure the UDP to HTTP/HTTPS configuration

    • 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:

Soracom Beam with UDP to HTTP/HTTPS configured

Finally, we can press our button again...

Click the button

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

Email notification about button click

Behind the scenes, Binary Parser and Soracom Beam are doing most of the heavy lifting for us:

  • When we click the button, a UDP packet containing binary data is sent to Unified Endpoint.
  • Binary Parser takes care of converting the binary data to JSON.
  • Unified Endpoint then forwards the data to Soracom Beam.
  • Soracom Beam converts the UDP packet into a full HTTPS POST request, and sends the request to our IFTTT webhook.
  • Finally, IFTTT receives our webhook and runs the email action.

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:

AWS has recently released a new feature for AWS Lambda called Function URLs which allows you to create a public HTTPS endpoint that can be used to trigger your Lambda function. By enabling a Function URL for your function, you can call the function directly using Soracom Beam, similar to the previous IFTTT example, without having to create a dedicated AWS IAM user and register its credentials to Soracom. However, you will have to provide your own authentication logic, such as using the Soracom Beam: Header Manipualtion option to add a custom authentication header to the HTTPS request and validating it in your Lambda code.

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();
  });
};
  1. 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

Soracom Funk is a paid service billed according to the number of requests used. A free tier is available, which will provide enough requests for thousands of button clicks each month. However, if you are planning to deploy a large number of LTE-M Buttons, you might exceed the free tier.

Please note that regardless of the free tier, sending and receiving data over the cellular network will still incur data usage fees.

Refer to the Pricing & Fee Schedule for more information.

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.

This type of behavior is known as a dry contact circuit, meaning that the LTE-M Button provides its own current in order to detect whether the circuit is open or closed. The 2-wire accessory must not be connected directly to an external power source. Doing so may permanently damage the LTE-M Button.

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.

There is a small recess underneath the rear cover for storing the accessory port cover so that you don't lose it.

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:

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

How Long Do the Batteries Last?

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:

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.

When changing a button's SIM status to Inactive, please note the following:

  • Deactivating the SIM only disables the network connection and does not disable the LTE-M Button itself. The button will still respond to clicks by turning on and attempting to connect to a network. As the button will not be allowed to connect, it may consume additional battery trying to search for other networks.
  • In some cases, when a button with an Inactive SIM attempts to connect to a network and is blocked, it may temporarily stop trying to connect to the same network again. This may result in a short period where the button cannot connect to a network even after the SIM has been reactivated. If this occurs, follow the reset button instructions below to tell your button to perform a full network scan.

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 button 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.

Note that because the Soracom LTE-M Button is pre-programmed to send button click events to Unified Endpoint, it is not possible to use 3rd-party SIMs.

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.

Are firmware updates automatic?

Firmware updates are optional and won’t automatically download and install on your Soracom LTE-M Button by default.

Updating a button's firmware from an earlier version to v3134 must be managed manually and requires the button to be pressed as part of the operation. Buttons on firmware v3134 and later can automatically check for firmware updates and apply them without the need for the buttons to be pressed using the Automatic Status Message feature. This feature is disabled by default, as it requires the button to send a daily automatic status message that will incur data fees and affect battery life.

In order to receive firmware update instructions and additional assistance configuring the automatic status message mode for your button(s), please contact our Soracom Support team and include the ICCID(s) of your button(s) in your request.

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.

Device Activation

To troubleshoot:

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:

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:

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 Soracom support for assistance.

Firmware Changelog

It is recommended that you keep your LTE-M button firmware up to date so that you can leverage the most recent functionality on offer.

Firmware Versions

Release Date Firmware Version Release Notes
Initial Release v2220 Stock firmware for buttons manufactured before February 2024
June 2024 v3134 New usability features and bug fixes released
Updating your Soracom LTE-M Button's Firmware

Before updating your firmware, first send a status message via your button in order to verify whether you're up to date.

Press your button's main button for 10 seconds to receive a status message and refer to Firmware Versions.

To update your button firmware, please contact our Soracom Support team with the ICCID(s) of your button(s) in order to receive firmware update instructions and for additional assistance. Please don't hesitate to reach out if you are unsure of whether your button has the latest firmware, or if you have any other questions or concerns.

Updating your button’s firmware requires the use of the button's built-in eSIM; other SIMs are not supported for firmware updates.

v3134 New Features and Changes

New Features:

Refer to LTE-M Button Functionality for more detailed information.

Bug Fixes:

Details:

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.

If you run into trouble, feel free to contact our Support Team.

  1. Login to your User Console account.
  2. Click the Support menu and select Contact us. Doing so will redirect you to the Soracom Support portal.
  3. At the top of the page, click Submit a request.
  4. Complete the ticket form and click Submit.