Soracom IoT Starter Kit with Arduino MKR

Welcome!

Cellular connectivity opens up a world of possibilities for IoT development, letting you build devices that can connect to the cloud from almost anywhere — and we're excited to help you get started!

This Starter Kit includes an Arduino MKR board, which provides a familiar Arduino programming environment to capture data from sensors, and a Soracom Air IoT SIM card, which will let you send the data to the Soracom cloud and beyond over a cellular connection.


Starter Kit Contents

Box Contents


Setup your Soracom Account

Before we dive in, let's make sure your Soracom account is all set up.

Register your Payment Information

As Soracom services are post-paid, a credit card is required in order to begin using services. While any fees from Soracom services will be billed to your credit card, the Soracom SIM card included in your Starter Kit also includes a $10 or $20 coupon credit (depending on which kit you purchased), enough to cover basic service and data fees for a few months. First, let’s get our payment information set up.

  1. Access the Soracom User Console by visiting: console.soracom.io

  2. Login using your email address and password.

    Login

  3. Click your email address at the top right corner, and select Payment settings:

    https://console.soracom.io

    Payment settings

  4. Click New payment method, and enter your credit card information.

    https://console.soracom.io

    Payment method

    If you have trouble adding your credit card, please try another card, or refer to the Additional Resources and Support section at the end of this guide in order to contact Soracom Support.


Register your Soracom IoT SIM Card

Now that your Soracom account is set up, let’s register the Soracom IoT SIM card that was included in your Starter Kit.

Normally, registering a Soracom SIM card requires entering the ICCID and PUK numbers printed on the SIM card itself. However, when you purchased your starter kit from Soracom, the SIM card included in the kit was pre-registered to your account, which allows you to easily complete SIM registration without typing any numbers.

While manually registering a SIM using its ICCID and PUK is simple, pre-registration will allow you to automatically register a large number of SIMs with a single click, if you plan on purchasing additional SIMs in the future.

  1. Click the Menu button at the top left corner, and select SIM Management.

  2. Click Register SIM.

    https://console.soracom.io

    Register SIM

  3. A dialog will appear asking how you would like to register your SIM. Within the From Order tab, the order that includes your Arduino MKR starter kit should be listed. Simply click the Register button next to your order:

    Register SIMs from an order

Your SIM card will now appear in the list, and you can confirm it is Ready for cellular connections and currently Offline:

https://console.soracom.io

SIM Registered

Once your SIM is regsitered, the $10 or $20 coupon will be added to your account, and at the end of each monthly billing cycle, this credit will automatically be applied to your balance. You can check the balance of your coupon at any time by click your email address at the top right corner, and selecting Manage coupons.

Your SIM card is now ready for use! In addition to registering and managing Soracom SIM cards, the Soracom User Console gives you access to additional Soracom services, such as Soracom Beam and Soracom Lagoon. From the User Console, you can suspend or terminate your Soracom SIM card, and disable other Soracom services at any time to stop fees.

For more information on using the User Console, refer to the Additional Resources and Support section.


Setup your Arduino MKR

Insert the Soracom IoT SIM Card

  1. Carefully remove the Soracom SIM card from its packaging.

    Remove SIM card

    The plan01s SIM included in the starter kit is a 3-in-1 design that allows you to conveniently break out the SIM card into standard/mini (2FF), micro (3FF), and nano (4FF) form factors. As the Arduino MKR uses the micro (3FF) size, take care to remove the micro SIM card size when removing it from its packaging.

  2. Insert Soracom Air SIM card into the Arduino MKR, ensuring the SIM card is oriented correctly:

    Insert SIM card

    Insert SIM card

  3. Attach the included antenna to the Arduino MKR.

    Attach antenna

Now with the SIM card inserted and antenna attached, lets set up your computer to program the Arduino MKR.


Setup Arduino IDE

Arduino provides several methods for programming the Arduino MKR boards. For simplicity, we'll use the Arduino Desktop IDE app (also known as Arduino IDE) in this guide.

If you're interested in exploring other ways to program your Arduino MKR, take a look at Arduino's getting started guides:

If you haven't installed the Arduino Desktop IDE app to your computer yet, take a moment to download and install it from the official Arduino Downloads site.

Together with Arduino IDE, we also need to install:

Finally, once everything is installed we will configure Arduino IDE for our Arduino MKR device.

Install Arduino MKR Board Definitions

In order for Arduino IDE to compile your code, you need to install the Arduino MKR board definitions.

  1. Start Arduino IDE.

  2. From Arduino IDE, click Tools Board Boards Manager....

    Boards Manager

  3. In the Boards Manager, search for Arduino SAMD. Find the Arduino SAMD Boards (32-bits ARM Cortex-M0+) board definition and click Install.

    Install Board Definition

Install Arduino MKR Libraries

Next, let's install an Arduino MKR library. These libraries contain useful example sketches specific for the Arduino MKR boards, which will help you quickly add functionality to your board.

  1. From Arduino IDE, click Tools Manage Libraries....

    Manage Libraries

  2. If you are using the MKR NB 1500 board, search for MKRNB. If you are using the MKR GSM 1400 board, search for MKRGSM. Then install the library for your corresponding board.

    Install Library

Select Arduino MKR Board and Port

Last, let's tell Arduino IDE that our program should be compiled for our Arduino MKR board, and select the port where our MKR board is attached.

  1. First, connect the Arduino MKR to your computer using an appropriate micro-USB cable (not included in the kit).

    Please note that some USB cables may only provide charging capabilities. You will need to use a USB cable that also supports data transfer in order for your computer to detect the Arduino MKR. If you have any trouble with the next steps, try using a different USB cable.

  2. From Arduino IDE, click Tools Boards Arduino SAMD Boards (32-bits ARM Cortex-M0+). If you are developing for the MKR NB 1500, select Arduino MKR NB 1500. If you are developing for the MKR GSM 1400, select Arduino MKR GSM 1400.

    Select Board

  3. Next, with your Arduino MKR connected to your computer, click Tools Port, then select the port that corresponds to your Arduino MKR.

    Select Port

Great! Everything is now set up, and we're ready to flash our first Arduino MKR program.


Test the Modem

The Arduino MKR library we installed earlier includes a simple program that tests that the u-blox modem on our MKR board is functioning correctly. We can use this as a quick test to check that we can successfully write a program to our MKR board.

  1. Start Arduino IDE.

  2. From Arduino IDE, click File Examples MKRNB or MKRGSM Tools TestModem. A new Arduino IDE window will open with the example code.

  3. Check that your MKR is connected to your computer. Then click the Upload button.

    Test Modem

    Arduino IDE will compile the sketch for your MKR, and once complete it will automatically upload it to your MKR.

  4. Once the upload is complete, we can open the Serial Monitor to check the output of the program. Click Tools Serial Monitor.

    Open Serial Monitor

    If everything went well, you should be able to see the output of the program:

    Serial Monitor

    If part of the output is cut off, or you want to run the program again, you can close the Serial Monitor, press the RST button on your Arduino MKR, and then open the Serial Monitor again.

Congratulations! You've flashed your first Arduino MKR program! Although it's just a simple program to test the modem, you are now well prepared to connect your MKR to a cellular network and begin sending/receiving data!

Next, you can also take a look at the other example sketches included in the MKRNB or MKRGSM library:

Please note that the TestModem example does not actually connect to a cellular network, but rather simply checks that the MKR board can access the u-blox modem correctly.

Additionally, if you are using the MKRNB, the u-blox SARA-R410M modem built into the board may come with a feature called Power Saving Mode (PSM) enabled by default. Depending on which cellular network you connect to, PSM may not be available, which may cause your modem to become unresponsive. If you have trouble connecting to a cellular network and sending data with your MKRNB, you can use the program from the Grove Sensor Data example below to reset your modem.


Send Grove Sensor Data to Harvest

If the Arduino MKR kit that you purchased included the Grove Sensor kit, you can follow these instructions to attach each sensor to your Arduino MKR and quickly begin sending sensor data to the cloud. In this example, we will enable the Soracom Harvest service for our SIM, which provides a simple way for us to collect sensor data and view it on the User Console.

Many services, including Harvest, are linked to groups. Groups let us manage multiple SIM cards together. When we enable Harvest for a particular group, all of the devices (SIM cards) that belong to that group will automatically be able to use Harvest. That way we can easily add more devices to the group without having to enable Harvest for each individual device.

To set everything up, we will need to perform the following steps:

Create a Group

Let’s first create a group for our SIM card.

  1. If you’re not already logged in, open https://console.soracom.io again and login using your email address and password.

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

  3. Then click the Actions menu, and select Change group.

    https://console.soracom.io

    Change group

  4. We don’t have any groups yet, so let’s create one. Click the dropdown menu, and select Create group….

    Change group

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

    Create group

  6. Our group has been created. Now let’s click Update to set our new group for our SIM card.

    Update group

Enable Soracom Harvest

Next, let’s enable Soracom Harvest for our new group.

  1. Click the name of the group underneath the Group column. This will open the group configuration page.

    https://console.soracom.io

    Open group

  2. Click the SORACOM Harvest panel to expand Harvest settings.

    https://console.soracom.io

    Group settings

  3. Click the toggle switch to turn Harvest ON, then click Save.

    Harvest settings

All done!

Send Data to Harvest

Now let's attach our sensors to the Arduino MKR.

  1. Carefully insert the Arduino MKR into the Arduino MKR Connector Carrier board, making sure that the pins from the Arduino MKR correspond to the same pins on the Connector Carrier board.

    Insert Connector Carrier

  2. Using the 4-pin Grove connector wires included with your Grove sensor kit, connect the sensors to the following ports on the Connector Carrier board:

    Sensor Port
    Temperature and humidity sensor D0
    Ultrasonic Range sensor D1
    Magnetic switch D2
    Buzzer D3
    3-axis accelerometer TWI
    GPS receiver Serial
  3. Connect the Arduino MKR to your computer using a micro-USB cable (not included).

  4. Download or copy the sample Arduino Sketch for your Arduino MKR and Grove sensor from the Soracom Labs repository:

  5. Start Arduino IDE, then open the Arduino sketch or paste the code into a new sketch.

  6. Click the Upload button.

Once the upload is complete, open the Serial Monitor to check the output of the program. Click Tools Serial Monitor. You should be able to see your Arduino MKR periodically reading the sensor values, and uploading the data to Soracom Harvest. If your output looks similar, then you have successfully configured your Arduino MKR to send sensor data to the cloud using a cellular connection!

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

  1. On the User Console, click the Menu button, and select SIM Management.

    https://console.soracom.io

    Harvest Data

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

You should be able to see the same sensor data, along with a simple time-series chart.

Keep in mind, depending on your location or conditions, not all sensors will have data immediately. For example, the GPS sensor typically will need to acquire a GPS signal outdoors before the Arduino MKR can read any location data.

If you are able to see the data appear in Harvest Data, then congratulations! You've finished building a fully-functional prototype device that you can deploy anywhere within reach of a cellular signal, with sensor data sent to the cloud!


Next Steps

Now you can begin to extend this example application to build your own prototype. For example:

There's also a vast number of resources for advanced functionality built into your Arduino MKR. To get started, you can check out the additional cellular functions provided directly in the MKRNB and MKRGSM Arduino libraries:

If you'd like to learn what else the SAMD processor on your Arduino MKR board is capable of, you can take a look at Seeed's getting started guide:

And don't forget to check out Arduino's forums if you want to see what other people are building, or if you run into any issues writing your programs:


Additional Resources and Support

For complete information on Soracom User Console tools and capabilities, full documentation is available on the Soracom Developer Site.

If you run into any trouble, feel free to submit a support ticket:

  1. Login to your Soracom account.
  2. Click the Support menu and select Contact us. You will be taken to the Soracom Support portal.
  3. At the top of the portal, click the Create a ticket link.