OpenBlocks_iot_Developer_Guide Open Blocks Developer Guide V3.1.0 Eng 20180604

User Manual:

Open the PDF directly: View PDF .
Page Count: 39

Chapter 1 General
- 1-1. Items included in package for VX2
- 1-2. Names of parts (VX2 main body)
Chapter 2 Before starting to use the OpenBlocks IoT Family
Chapter 3 Using the OpenBlocks IoT Family
Chapter 4 Product specifications
Chapter 5 Cautions and supplementary information
- 5-1. Countermeasures against delays due to script processing
- 5-2. List of ports used

OpenBlocks IoT Family

Developer Guide

Version 3.1.0

Plat'Home Co., Ltd.

■ About trademarks

・ Linux is a trademark or registered trademark of Linus Torvalds in the United States

and/or other countries.

・ Company and product names mentioned in this Developer Guide may be trademarks or

registered trademarks of their respective companies.

・ Product names and other proper nouns in this Developer Guide are trademarks or

registered trademarks of their respective companies.

・ Docker and Docker logo are trademarks or registered trademarks of Docker, Inc. in the

United States and/or other countries. Docker, Inc. and other parties may also have

trademark rights in other terms used herein.

■ Before using this product

・ No reproduction of this material is allowed without written permission of Plat'Home Co.,

Ltd.

・ Content and information contained within this material may be changed or updated

without prior notice.

・ We consistently aim to keep the content in this material as precise as possible. However,

should any errors in descriptions, etc. be noticed, please contact Plat'Home Co., Ltd.

The latest version of this material can be downloaded from our website.

・ While using this product, please be aware that it is not designed or assumed for use in

fields where there is a risk to life.

・ Regardless of the aforementioned, in no event will Plat'Home be liable for any special,

incidental, indirect or consequential damage arising out of use of this product, including

but not limited to damage to profits or loss.

3/39

Table of contents

Chapter 1 General .................................................................................................................. 5

1-1. Items included in package for VX2 .............................................................................. 5

1-2. Names of parts (VX2 main body) ................................................................................ 6

Chapter 2 Before starting to use the OpenBlocks IoT Family ................................................ 8

2-1. Product overview ......................................................................................................... 8

2-2 Cautions about SSD-based system development ....................................................... 8

2-3 About SIM cards .......................................................................................................... 11

2-4 eMMC storage partition information ............................................................................ 11

2-5 Storage mode ............................................................................................................. 12

2-6. Connecting PC to OpenBlocks IoT Family ................................................................ 13

2-7. WEB UI ...................................................................................................................... 14

Chapter 3 Using the OpenBlocks IoT Family ....................................................................... 15

3-1. Indication colors of status indicators ......................................................................... 15

3-2. Modem control for mobile networks .......................................................................... 18

3-3-1. On-demand connections ........................................................................................ 20

3-3-2. User control of mobile network modem ................................................................. 21

3-4. Backup ....................................................................................................................... 24

3-5. Restoration ................................................................................................................ 25

3-6. Applications ................................................................................................................ 26

3-7. WEB UI extensions .................................................................................................... 27

3-7-1. Script editing ........................................................................................................... 27

3-7-2. Command execution .............................................................................................. 28

3-7-3. SMS command execution ...................................................................................... 28

3-8 Switching boot modes ................................................................................................ 29

3-9. WEB UI extensions .................................................................................................... 29

3-10. Special setting of WEB UI filter table ...................................................................... 29

3-11. Sending SMS messages ......................................................................................... 30

3-12. Switching operations of LTE module (KDDI) ........................................................... 30

3-13. Factory Reset (Reset to condition at time of factory shipment) .............................. 32

3-14. Recovery startup ..................................................................................................... 33

3-15. Building a cross-development environment ............................................................ 33

3-16. Automatic external storage mounting in WEB UI .................................................... 34

3-17. Recommended device files to use .......................................................................... 35

3-18. Docker ..................................................................................................................... 35

Chapter 4 Product specifications ......................................................................................... 36

4/39

4-1. Open Blocks IoT VX2 main body specifications ....................................................... 36

4-2. OpenBlocks IoT VX series options ............................................................................ 37

4-2-1. 3G module .............................................................................................................. 37

Chapter 5 Cautions and supplementary information............................................................ 38

5-1. Countermeasures against delays due to script processing ...................................... 38

5-2. List of ports used ....................................................................................................... 38

5/39

Chapter 1 General

This manual is a developer guide for the OpenBlocks IoT Family.

If a general user, please refer to the OpenBlocks IoT Family WEB UI Set-up Guide.

1-1. Items included in package for VX2

Standard configuration of OpenBlocks IoT VX2 is as follows:

1 x VX2 main body 1 x USB Type-A Micro USB cable

1 x Start-up Guide 1 x AC adapter

1 x Heat radiation and installation bracket

6/39

1-2. Names of parts (VX2 main body)

No. Name Remarks

① USB serial console port Micro USB Micro-B

② Ethernet port 0 10BASE-T / 100BASE-TX / 1000BASE-T

③ Ethernet port 1 10BASE-T / 100BASE-TX / 1000BASE-T

④ Power switch Shuts down OS if in operation.

Starts up OS if not in operation.

⑤ FUNC switch Enables allocated functions.

⑥ Status indicator LEDs illuminate or flash in seven colors.

⑦ RS-485 (half duplex) connector

⑧ Wide range power supply input

⑨ USB host mode port A-Type/USB3.0

⑩ USB host mode port A-Type/USB3.0

⑪ FUNC switch Enables allocated functions.

7/39

No. Name Remarks

⑫ Power switch Shuts down OS if in operation.

Starts up OS if not in operation.

⑬ Status indicator LEDs illuminate or flash in seven colors.

⑭ SIM slot Slot for inserting SIM card.

*Supports mini-

SIM card format (2FF) (standard

SIM)

⑮ MMC slot

As MMC cards cannot secure sufficient reliability

for system operations, use them for file exchanges

and log storage only.

⑯ Expansion slot 2 Expansion slot for EnOcean, Wi-

SUN and other

modules.

⑰ Expansion slot 1

Expansion slot for mobile adapter card of mobile

networks.

Mobile adapter card supporting carrier To be use is

mounted. Essentially, this is a factory option.

⑱ DIP switch As this switch is set prior to factory shipment, do

not alter the settings.

SW1-3: For modem identification

SW4-5: Not used

SW6: OFF=RS485 terminator ON (default)

⑲ Holes to install external antenna Holes are unopened in image.

⑳

Holes to mount heat radiation

and installation bracket

*To insert a SIM card, turn the VX2 main body upside down and insert into the back of the

slot. Similarly, to remove a SIM card, turn the VX2 main body upside down and extract the

card.

●Modem type identification

Modem type SW1 SW2 SW3

3G module ON OFF OFF

Modem uninstalled ON ON ON

8/39

Chapter 2 Before starting to use the

OpenBlocks IoT Family

2-1. Product overview

The OpenBlocks IoT Family is a general-purpose server product employing Debian

GNU/Linux as an OS. Though customized to take advantage of hardware properties, it is

possible to use the OpenBlocks IoT Family in a general operational method for Debian and

other Linux products, apart from such customization.

2-2 Cautions about SSD-based system development

In recent times, cost reductions in flash memories have led to the employment of Solid State

Drives ("SSD"), replacing conventional hard disk drives used in smartphones, laptop PCs

and many other devices. This product uses embedded MMC (eMMC), which is a type of

SSD.

With advantages such as high-speed random access performance and solid-state design,

SSD has extremely high resistance against mechanical failures and environmental

performance. However, compared to hard disk drives, the data writing limit is a lot less.

SSD can generally be divided into SLC and MLC. The SLC type with tens of thousands of

counts of write performance was the mainstream in the capacity range of a few gigabytes,

but the low-cost MLC with a write count of thousands has drastically increased capacity and

is applied to smartphones and PCs. Currently, SLC SSDs are gradually being faded out.

In actual fact, SLC products as options for our micro-servers only remain in the range of

small capacity products.

Thus, the number of operations with micro-servers using MLC SSD is enormous.

Generally, MLC has a write capability of 3,000 times. Just beyond 3,000 times, it starts to

cause bit errors, which can be recovered with ECC.

As soon as MLC exceeds the limit for an ECC recovery, read errors will be caused.

Therefore, consider system design to avoid MLC being in this condition.

9/39

●Write count per cell and block size of flash memory

Despite a write capacity of 3,000 times per cell, just one byte of writing onto an SSD means

one count.

To support large capacity with a small number of address lines, recent flash memory is read

and written in a block as large as 512 KB.

In other words, writing one byte or 512 KB is counted once.

For this reason, in relation to writing on SSD, it is possible to minimize the number of write

counts on SSD by writing in large data sizes through accumulating as much data as possible

in a buffer, as opposed to writing in small data sizes with more counts.

●Wear leveling function

As SSD can endure only a relatively small number of write cycles in a specific block, it will

average the number of writes so that the writes do not concentrate on the same actual block

address against actions to write onto the same block over and over.

This is achieved by virtualizing block addresses.

OS will notify used and unused blocks to SSD. In order to be ready for a next write to be

performed, SSD will prepare a block with the smallest number of writes for a write.

By doing so, the number of writes to individual blocks are consequently averaged out.

●Static wear leveling

In the case of conventional wear leveling, it is assumed that 50% of data is in a used domain

and rarely rewritten. This means that since installation of OS, 50% of available blocks are

written only once. While these blocks are virtually new, the remaining 50% are rewritten over

and over. Compared to the case where rewriting is averaged, the end life for SSD comes

twice as fast.

As a countermeasure to this, static wear leveling was devised. Data in rarely rewritten

blocks are moved to frequently rewritten blocks, while applying blocks that are virtually new

to a domain for reuse.

By doing so, even if 50% of blocks are rarely written, the life of SSD is almost fully exploited.

●Assuming total write cycles of SSD

For example, supposing there is a 4-gigabyte SSD using 512 KB blocks and 3,000 write

cycles per cell available. If writing data of 512 KB or less, we can assume that the total

number of write cycles of SSD is as follows:

4,294,967,296 Bytes ÷ 524,288 Bytes = 8,192 (4 GB ÷ 512 KB）

10/39

Number of physical blocks is 8,192.

If each of them are rewritten 3,000 times:

8,192 × 3,000 = 24,576,000 times

In other words, if writing one-byte data per time, the life will end when writing 18.4MB.

(Actually, SSD promotes efficiency of such writes). Furthermore, if assuming that for writes

of 512 KB in size, a block segment does not overlap the border of 512 KB, it will be one write,

whereas in fact, file access by OS may start writing in the middle of the block, so even if a

write of 512 KB or less is written twice with a 50% probability.

i.e.

24,576,000 times x 75% = 18,432,000 times (Only 512 KB writes are assumed here).

Furthermore, with access from OS, one more write cycle is added.

This is due to the fact that updating a file control block in the file closing process will result in

at least one rewrite.

Of course, SSD further reduces the number of write cycles by, for example, using cache, but

basically, this is the mechanism for processing.

●Use an SSD that is as large as possible

For example, the above-mentioned 4-gigabyte SSD has 8,192 blocks, but if there is a

8-gigabyte SSD, it has 16,384 blocks, which is twice that of a 4-gigabyte SSD. Simply put,

the number of write cycles is twice.

If SSDs have the same block size, the number of write cycles will simply increase in

proportion to the size.

For this reason, by using an SSD as large in size as possible, it will resist against problems

caused by an increasing number of writes.

●Reducing the number of writes to SSD by using tmpfs

In a Linux system, system development without due consideration will assume that storage

can be used as a device that can be used infinitely.

Even if no data storage is required, storage domain will be carelessly used as a buffer for

operation.

To avoid reducing the life of SSD for such a reason, give due consideration to system design

11/39

so that the storage necessary for operation processes are stored in tmpfs as much as

possible.

In addition, open source software frequently uses a storage domain secured for its use as a

temporary storage area. In this case, and as a countermeasure, that file is linked to a

domain in tmpfs.

●Log

It is general practice with a Linux system to keep a log in storage for everything. However, if

there is a process that records logs on a very frequent basis, contrivances such as writing in

tmpfs first and then moving logs to SSD periodically are recommended.

Though such countermeasures cannot respond to a sudden blackout, due consideration

should be given to whether one regards this as a trade-off or to send logs to a system log

server equipped with UPS.

2-3 About SIM cards

SIM cards that can be mounted onto OpenBlocks IoT Family are in a mini-SIM (2FF) format.

If there is a need to use micro-SIM or nano-SIM cards, use an adapter that can fix a SIM

card with a fall-preventing film and adhesive tape. Please note that any damage to the SIM

slot while a SIM adapter is used will be subject to repair on an at-cost basis.

2-4 eMMC storage partition information

Partition information of eMMC used for this product is as follows:

●In the case of OpenBlocks IoT VX2

Number Format Size OBS application Device name

1 fat16 1.5 gigabytes Boot mmcblk0p1

2 ext4 30.5 gigabytes Primary mmcblk0p2

12/39

2-5 Storage mode

Operation is conducted by referring to basic user land data from eMMC. Should an

unexpected power interruption occur, there is a risk of damage to files in physical storage,

but for Docker and other applications, data in storage are referenced by unionfs, thereby

securing normal operation.

Damage to files by a sudden power interruption mainly happen to files into which data is

being written. For this reason, it is recommended that to reduce any influence on OS, files

that are normally written should be limited to log files or such like.

*Execution results of mount command

root@obsiot:/var/webui/docroot# mount

/dev/mmcblk0p2 on / type ext4 (rw,relatime,data=ordered)

devtmpfs on /dev type devtmpfs (rw,relatime,size=956312k,nr_inodes=239078,mode=755)

sysfs on /sys type sysfs (rw,nosuid,nodev,noexec,relatime)

proc on /proc type proc (rw,nosuid,nodev,noexec,relatime)

securityfs on /sys/kernel/security type securityfs (rw,nosuid,nodev,noexec,relatime)

tmpfs on /dev/shm type tmpfs (rw,nosuid,nodev)

devpts on /dev/pts type devpts (rw,nosuid,noexec,relatime,gid=5,mode=620,ptmxmode=000)

tmpfs on /run type tmpfs (rw,nosuid,nodev,mode=755)

tmpfs on /run/lock type tmpfs (rw,nosuid,nodev,noexec,relatime,size=5120k)

tmpfs on /sys/fs/cgroup type tmpfs (ro,nosuid,nodev,noexec,mode=755)

cgroup on /sys/fs/cgroup/systemd type cgroup

(rw,nosuid,nodev,noexec,relatime,xattr,release_agent=/lib/systemd/systemd-cgroups-agent,name=systemd)

cgroup on /sys/fs/cgroup/freezer type cgroup (rw,nosuid,nodev,noexec,relatime,freezer)

cgroup on /sys/fs/cgroup/memory type cgroup (rw,nosuid,nodev,noexec,relatime,memory)

cgroup on /sys/fs/cgroup/cpuset type cgroup (rw,nosuid,nodev,noexec,relatime,cpuset)

cgroup on /sys/fs/cgroup/perf_event type cgroup (rw,nosuid,nodev,noexec,relatime,perf_event)

cgroup on /sys/fs/cgroup/pids type cgroup (rw,nosuid,nodev,noexec,relatime,pids)

cgroup on /sys/fs/cgroup/devices type cgroup (rw,nosuid,nodev,noexec,relatime,devices)

cgroup on /sys/fs/cgroup/blkio type cgroup (rw,nosuid,nodev,noexec,relatime,blkio)

cgroup on /sys/fs/cgroup/net_cls,net_prio type cgroup (rw,nosuid,nodev,noexec,relatime,net_cls,net_prio)

cgroup on /sys/fs/cgroup/cpu,cpuacct type cgroup (rw,nosuid,nodev,noexec,relatime,cpu,cpuacct)

cgroup on /sys/fs/cgroup/debug type cgroup (rw,nosuid,nodev,noexec,relatime,debug)

systemd-1 on /proc/sys/fs/binfmt_misc type autofs

(rw,relatime,fd=37,pgrp=1,timeout=0,minproto=5,maxproto=5,direct)

mqueue on /dev/mqueue type mqueue (rw,relatime)

debugfs on /sys/kernel/debug type debugfs (rw,relatime)

tmpfs on /tmp type tmpfs (rw,relatime)

13/39

2-6. Connecting PC to OpenBlocks IoT Family

The OpenBlocks IoT Family and a PC are connected via an accessory USB cable.

The OpenBlocks IoT VX series must be supplied with power via an AC adapter or a

wide-range power supply input.

In the case of a Windows PC, connection to a USB port will automatically install a USB

serial driver (if Windows PC is connected to an Internet environment).

After completing installation of driver, it is possible to make serial port connections via

terminal software such as TeraTerm and PuTTY.

Default communication parameters of serial port on OpenBlocks IoT Family are as

follows:

Communication speed: 115,200 bps

Data length: 8-bit

Parity: None

Stop bit: 1-bit

When the startup process is completed after establishing communication, a login prompt

will be displayed. With default root privileges, start the login process.

Password: 0BSI0T

*The above password is a default password. If the password has been changed

via WEB UI, please use password already set.

14/39

2-7. WEB UI

To enable basic system setup, this system is installed with WEB UI.

Use WEB UI to set up networks and control mobile networks.

In addition, WEB UI enables various functions to be added. Please refer to the WEB UI

Set-up Guide for basic use, etc. For functions added, refer to corresponding manuals.

15/39

Chapter 3 Using the OpenBlocks IoT

Family

The OpenBlocks IoT Family is a general-purpose server product employing Debian

GNU/Linux.

The OpenBlocks IoT Family can be used in the same way as with a regular Debian product.

This Chapter describes information that is particular to the OpenBlock IoT Family.

3-1. Indication colors of status indicators

The LEDs at the front of the OpenBlocks IoT Family product illuminate in seven colors with a

combination of RGB colors. For each color, flashing, etc. is controlled by script.

When WEB UI is employed, the specifications for default LED illuminations are as follows:

Status Color Illumination

status

Remarks

Main body and OS in

operation Yellow Illuminating

After completing startup of the main body

and OS, the unit will begin to check for a

signal reception in mobile network.

*Flashes green if no SIM card is inserted.

When the SIM slot is

unused Green Flashing

Normal operation without a SIM card or in a

waiting status before changing over to

waiting for signal reception

Mobile network signal:

Strong White Flashing Refer to "Details of signal status"

Mobile network signal:

Medium

Light

blue Flashing Refer to "Details of signal status"

Mobile network signal:

Weak Blue Flashing

Refer to "Details of signal status"

*Communication at this field intensity may

cause frequent retrials. If a mobile network

is being employed, use the unit with a

medium field strength or better.

Mobile network signal:

No signal Purple Flashing Refer to "Details of signal status"

When function is

Yellow Flashing

Alternately flashes with status indicator

16/39

Status Color Illumination

status

Remarks

enabled by FUNC button displaying that mobile network or SIM slot is

not used.

Terminating OS Yellow Illuminating

Initial trial to access

AirManage failed Red Illuminating

This indication is shown when an initial

access to AirManage remote control server

has failed. If WEB UI is not being used, the

OS will start to terminate in five minutes.

OS terminating after

initial access to

AirManage remote

control server has failed.

Red Flashing

*Details of signal status

Modem type Signal: Strong Signal: Medium Signal: Weak Signal: No

signal

3G module -

87 dBm or

higher

-88 to -108 dBm -109 to -112 dBm -113 dBm or lower

BWA module -

95 dBm or

higher

-95.1 to -105 dBm -105.1 to -120 dBm -

120.1 dBm or

lower

LED illumination control script when WEB UI is used

/var/webui/bin/set_signal_value.sh

/var/webui/scripts/led_updater.sh

●LED control

To change indication colors and illumination statuses of LEDs, edit /tmp/.runled file.

Please note that when a SIM card is inserted while using WEB UI, it will work with the field

strength, regularly updating this file. For this reason, to intentionally change this file, stop

using WEB UI or terminate the script to control LED illumination.

17/39

Line Setting description Remarks

1st line

Illumination #1 hours

(msec)

1 or more

2nd line

Illumination #2 hours

(msec)

1 or more

3rd line Illumination #1 color Refer to table below.

4th line Illumination #2 color Refer to table below. (If omitted: 0)

Color # Color

0 Not

illuminated

1 Red

2 Green

Color

number

Color

3 Yellow

4 Blue

5 Purple

6 Light blue

7 White

Out of

range

Not

illuminated

*Yellow flash every second

# echo -e "1000¥n1000¥n3" > /tmp/.runled

*Yellow and green flash alternately every second

# echo -e "1000¥n1000¥n3¥n2" > /tmp/.runled

18/39

3-2. Modem control for mobile networks

A tool to check the power ON/OFF state of module installed in this unit and radio wave state

is provided.

Command name: atcmd

Startup method 1: atcmd [Command]

Startup method 2: atcmd [Command 1] [Command 2] [Command 3]

Startup method 3: atcmd -d [Device file] [Command]

As shown in Startup method 2, it is possible to list commands and execute them in

sequence.

As shown in Startup method 3, it is also possible to designate a device file to use and

execute it.

Command Function Remarks

PON Turn the modem ON

POFF Turn the modem OFF

PRST Modem reboot Software reset

(Partial hardware reset)

HRST Modem reboot Hardware reset

CSQ Obtain radio wave strength

CCID Obtain SIM number

CTZU 1

Automatically obtain time

zone

*With a space

ATI Obtain modem type number

CGSN

Obtain modem serial

number

Commands to be assigned as per the above content.

*Turn the modem ON, obtain SIM number, turn the modem OFF

# atcmd PON CCID POFF

Xxxxxxxxxxxxxx

*Turn the modem ON, obtain radio wave strength, turn the modem OFF

# atcmd PON CSQ POFF

-86

19/39

When constantly obtaining radio wave status, WEB UI will occupy the device file. For this

command, designate a device file not used by WEB UI and execute it. In an environment or

user control not using WEB UI, this restriction will not apply.

Please note that depending on module in use, the device files that can be used by atcmd will

differ.

●3G module

Device file If atcmd can be used

/dev/ttyACM0 Yes

/dev/ttyACM1 Yes

/dev/ttyACM2 Yes

/dev/ttyACM3 No

/dev/ttyACM4 No

/dev/ttyACM5 No

/dev/ttyACM6 No

20/39

3-3. Mobile network connection

It can control the mobile line's modem using the Service network (Mobile line) menu in the

[Network]-[Basic] tab in WEB UI.

The OpenBlocks IoT Family supports a method to make a connection to mobile networks

whenever necessary through control by WEB UI (On-demand connections), and a method

to make a connection by the user fully excluding control by the modem.

3-3-1. On-demand connections

Press the [Network]-[Basic] tab and enter necessary information for mobile network

connections.

Following information is required:

・APN (This item does not exist for LTE

module (KDDI)).

・Username

・Password

・Authentication method

・Automatic connection:

Choose "Not

automatic connection."

・Host for communication confirmation

・Periodic re-connection settings

・Mobile network reconnection times

・SMS control

*Enable this item only when it is used.

Press the Save button and reboot the unit to reflect changes to mobile network modem.

To connect/disconnect to a mobile network, use the following commands:

●Connection to a mobile network

# /var/webui/scripts/mobile_control.sh con 1

●Disconnection from a mobile network

# /var/webui/scripts/mobile_control.sh coff 1

21/39

Below is a sample of a combination of the above commands, meaning:

1. Connect to mobile network.

2. Execute ping command to DNS server.

3. Disconnect from mobile network.

#!/bin/bash