Flip&Click: Getting Started

Setting up your environment

You will need:

• Flip&Click available from MikroE

• Click modem compatible with Flip & Click available from MikroE

  • A list of supported modems is available in the Thingstream Arduino SDK

• Arduino IDE

• Thingstream Arduino SDK

Arduino Environment

• Download the Arduino IDE for your platform of choice from here

• Install the downloaded Arduino build on your target platform

• For first time users of the Flip & Click or SAM based boards you will need to install the Arduino SAM boards library.

• To install this, start the Arduino IDE and navigate to the Tools Menu

• Select the Boards option and then the Boards Manager 

• In the search filter type Arduino&Due – this will return the Arduino SAM Boards (32-bits ARM Cortex-M3) package, install this 

• After installing this board package if you plug the Flip N Click into the USB port you should be able to Navigate to Tools / Board you should have Arduino SAM Boards listed.

• If you move your pointer over this menu item a sub menu offers two Arduino Due options, select the Native USB Port option

• Now that the Board has been selected, we need to select the Port. Navigate to Tools/Port, the IDE will list the detected com/serial ports

• Select the (Arduino Due (Programming port))

Thingstream Arduino SDK

• Obtain the Thingstream Arduino build.

  • Log into your Thingstream domain here

  • If you haven’t registered a Thingstream domain please do so here and then log into your domain

  • Once logged in, Select the ‘Downloads’ link in the sidebar and click on IoT Communication-as-a-Service.

  • Several Download groups are displayed, select the Arduino group

  • Download the latest version of the ‘C SDK Arduino Library’

• The Thingstream Library will need to be imported.

• The Downloaded Arduino SDK will be downloaded in .zip format, unzip this.

• The library that we want to import is located in thingstream-client-Arduino-library-BLD…../library

• In the Arduino IDE Navigate to the Sketch Menu and move the pointer over the ‘Include Library’ option.

• There is an option to ‘Add .zip Library…’, select this

• A file picker is opened which will permit you to navigate to the Thingstream/library folder mention above and select the thingstream.zip

• Once this has been imported the Thingstream examples will be available to flash and run.

• Navigate to the File menu and move the navigation pointer over the ‘Examples’ listing.

• Sub menus are displayed in groups, we are looking for the ‘Examples from Custom Libraries’ group which will contain a ‘thingstream’ entry

• Move the navigational pointer over the Thingstream listing and several options are available, move the navigational pointer over the FlipAndClick listing and the following examples are listed

• Thingstream_basic_publish

• Thingstream_early_setup

• Thingstream_echo_test

• Thingstream_long_message

• Thingstream_publish_getMessages

• Thingstream_sensor_predefined_topic

Examples and what they do…..

(these are explained in greater detail in the SDK documentation – these can be found in ~ thingstream-client-Arduino-library-BLDXXXX-vx.xxx/example/doc/index.html)

Thingstream_basic_publish

Sends a message to the Thingstream server at QoS level '-1' which does not require a connection.

Thingstream_early_setup

This example demonstrates how to access the modem before fully initialising the Thingstream stack. For instance, it can be useful when the network configuration needs to be changed before network registration, or the application needs early access to SIM information.

Thingstream_echo_test

On reset or power-up, the application connects to the Thingstream server and registers, subscribes to and publishes a test message at QoS level '1'. The test message should be received by the client and printed to debug output.

Thingstream_example_tracker

If you are using a u-blox SARA Click modem or the Quectel BG96 Click, the Thingstream_example_tracker example gives you a fully functioning asset tracker which can be combined with Tracker 2 flow available in the Thingstream Flow library

Thingstream_long_message

This example demonstrates how to publish a message that's longer than the underlying transport's maximum transmission unit (MTU).

MTU for USSD: ~90 bytes

MTU for UDP (with base64): ~730 bytes

MTU for UDP (without base64): ~980 bytes

Sending a 'long message' is achieved by providing a buffer to Thingstream_createProtocolTransport() which holds the entire message. The SDK can then fragment the message for transmission.

Thingstream_lowpower_sendAndReceive

This example attempts to demonstrate sending and receiving messages from the Thingstream server in as few messages, and as little modem up-time as possible

Thingstream_sensor_predefined_topic

This example attempts to demonstrate sending messages to the Thingstream server using multiple predefined topics.

The following topics will need to be created in your domain before using this example

Alias   Suggested topic

300 sensor/temperature

301 sensor/pressure

302 sensor/battery/voltage

303 sensor/battery/charge

When it comes to building an example, there may be warnings about support for precompiled libraries

• The Flip & Click may require a minor change to the build recipes in order to link against the pre-built Thingstream SDK client.

• The file to edit is platform.txt 

  • This can be found on Mac @  /Users/<username>/Library/Arduino15/packages/packages/arduino/hardware/sam/1.6.12  

  • On Windows systems, this may be in the users folder C:\Users\<username>\AppData\Local\Arduino15\packages\arduino\hardware\sam\1.6.12

  • On Ubuntu this may be found at /home/<username>/.arduino15/packages/arduino/hardware/sam/1.6.12

• Update the list of compiler flags (compiler.xxx.xxx_flags=) found at approx. line 44-49 in this file by adding the following:

  • compiler.libraries.ldflags=

• Update 'recipe.c.combine.pattern' at approx. line no 81/82 to include:

  • {compiler.libraries.ldflags} 

 this should be added after the {object_files} entry,  as indicated below:

• recipe.c.combine.pattern="{compiler.path}{compiler.c.elf.cmd}" -mcpu={build.mcu} -mthumb {compiler.c.elf.flags} "-T{build.variant.path}/{build.ldscript}" "-Wl,-Map,{build.path}/{build.project_name}.map" {compiler.c.elf.extra_flags} -o "{build.path}/{build.project_name}.elf" "-L{build.path}" -Wl,--cref -Wl,--check-sections -Wl,--gc-sections -Wl,--entry=Reset_Handler -Wl,--unresolved-symbols=report-all -Wl,--warn-common -Wl,--warn-section-align -Wl,--start-group {compiler.combine.flags} {object_files} {compiler.libraries.ldflags} "{build.variant.path}/{build.variant_system_lib}" "{build.path}/{archive_file}" -Wl,--end-group -lm -lgcc

• Editing the platform.txt file will require a reboot of the Arduino IDE for the changes to take effect, after which the flip and Click examples should compile without issue.

• The Thingstream_basic_publish example is a good place to start.  Before uploading the example, open the Serial Monitor

• When the upload has completed you will be presented with a menu in the Serial Monitor.  It is a good idea to reset the Flip & Click at this stage using the reset button,  The menu will load again enabling you to select the Click Modem and the Slot into which it has been plugged after which the example will begin execution.