menu arrow_back close search On Github

Interactive terminal

  1. Home
  2. Tutorials
  3. Interactive terminal

The EE-NBIOT-01 board is just a breakout board to the u-blox SARA-N210 radio module with a Telenor Norway SIM-card, antenna and a voltage regulator.

This guide is a simple walk-through of how to get started with communication with the module directly from your computer without the use of a microcontroller. The same commands can of course be called from a microcontroller instead, so with this knowledge you can implement a library for the EE-NBIOT-01 for any microcontroller in any language you prefer.

Contents

Parts needed

Connecting to the EE-NBIOT-01

Here is a brief guide on what you need and how to set up the serial communication with the EE-NBIOT-01. If you need more details, SparkFun has an excellent in depth guide on Serial Terminal Basics.

USB to serial adapter

The communication to the u-blox SARA-N210 is just a simple serial connection with text commands. Modern computers don’t have a serial port any more, so you need a special USB cable to connect the serial pins (RX/TX) of the EE-NBIOT-01 board to your computer. These cables are often called FTDI, UART, or TTL cables.

The SARA-N210 RX/TX pins require 3.3V. The absolute max in the SARA-N210 datasheet is 4.25V; more may lead to damaging the SARA-N210 module. So make sure you get a cable that has 3.3V logic for RX/TX.

Regarding power, the EE-NBIOT-01 has a buck voltage regulator that can handle 1.8V-5.5V input, so it’s fine if the USB to serial adapter has 5V VCC.

Here are a few suggestions for adapters:

In Norway you should be able to find them in any of these stores:

Install serial adapter driver

Most cables require you to install a driver for the USB serial adapter. Check the product description and it should guide you to the correct driver for your operating system.

Serial terminal application

You can use any serial terminal application you like. We’ll only explain how to use CoolTerm in this guide - since it’s free, easy to use and works on Windows, macOS and Linux.

  1. Download and install CoolTerm for your OS
  2. Open app and click the «Options» button
  3. Choose which serial port to use
    • This depends on which driver and operating system you use.
      • In Linux the serial ports are treated as files, typical examples would be /dev/ttyS0, /dev/ttyUSB0 if you use a USB to serial adapter or /dev/ttyAMA0 on the Raspberry Pi.
      • In Mac OSX serial ports can have various names, for example usbserial-FTACX955.
      • At last there is Windows. In Windows, the serial port is an abstraction called a “COM port”. You can find these by looking the device manager. In the screenshot below, we have connected a TTL-232 USB cable to the machine: Device manager screenshot
  4. Set the baud rate to 9600

    CoolTerm Serial Port options screenshot

  5. Go to «Terminal» options (on the left)
  6. Change to «Line Mode»
  7. Check «Local Echo» to see the commands you’ve sent
  8. Leave the rest of the options as default and click «OK»

    CoolTerm Terminal options screenshot

  9. Click the «Connect»-button
  10. Enter commands in the input field near the bottom of the window

Connecting the cables

Normally on a serial connection, the TX is the output from one device and RX is the input. So when you connect two devices, you would connect TX->RX both ways. However, u-blox thought otherwise, so they’ve labled the input as TX and output as RX. To avoid an extra layer of confusion we used the same labeling as u-blox on the EE-NBIOT-01. So when connecting the wires - connect RX to RX and TX to TX.

NB! Make sure the cable has 5V to 3.3V logic level conversion on RX&TX

Table 1:

Serial adapter EE-NBIOT-01
VCC +5V/3.3V - red VCC
GND - black GND
RX - yellow RXD
TX (3.3V) - orange TXD

FTDI to EE-NBIOT-01
See image in full resolution

Terminal commands

You control the u-blox SARA-N210 by sending it AT-commands over the serial connection. The response will be prefixed with > to indicate it’s a response and not something you should write in the terminal.

APN config

We need to set the APN so that our devices’ upstream messages are forwarded correctly and so that our devices are assigned IP addresses to which can send downstream messages.

Before changing the config we must disable auto-connect because we don’t want the device to start connecting while we’re modifying the config. Then we need to reboot before the changes will take effect.

AT+NCONFIG="AUTOCONNECT","FALSE";+NRB
> OK
...
> REBOOT_CAUSE_APPLICATION_AT
> u-blox 
> OK

Now we’re ready to update the config. It’s not persisted on the SARA-N210, so remember to run this after every reboot:

AT+CFUN=1;+COPS=1,2,"24201";+CGDCONT=1,"IP","mda.ee";+CGACT=1,1
> OK
> OK
> OK
> OK

If you haven’t registered the devie in the Telenor NB-IoT Developer Platform yet, now is a good time. You’ll need the IMSI and IMEI:

AT+CIMI;+CGSN=1;
> <IMSI number>
> OK
> +CGSN: <IMEI number>
> OK

Save these numbers and follow the getting started guide to add the device, so you’ll be able to watch the incoming data that you’re about to send in the next section.

Hello world!

Check if we are registered on the network yet?:

AT+CEREG?
> +CEREG: 0,2

The seccond response value (2) is the registration status. Status 2 is not registered, but it’s currently trying to attach or searching for an operator to register to.

Wait a few seconds and try again:

AT+CEREG?
> +CEREG: 0,1

Now the registration status is 1, which means it’s registered to the home network.

Then open a new UDP socket. If successful, the first line of the response will be the socket number. You need the socket number later when sending data.

AT+NSOCR="DGRAM",17,30000,1
> 0
> OK

Now socket 0 is ready to send UDP data to a server. The APN we configured earlier will forward data from devices in the Telenor network to your application server.

AT+NSOST=0,"172.16.15.14",1234,12,"48656C6C6F20576F726C6421"
> 0,12
> OK

The first response line is <socket>,<sent_length>, followed by OK if it was successful.

To close socket 0:

AT+NSOCL=0

Hello world terminal screenshot

Important AT commands cheat sheet

This is just a summary of the commands we find the most useful. For the complete list, download the u-blox «SARA-N2 AT Commands» PDF from the u-blox website instead.

Most commands have 3 syntaxes. Read (COMMAND?), set (COMMAND=...) and test (COMMAND=?). Test will list possible values for all arguments.

Table 2:

Command name Syntax Response Description
Enable/disable radio AT+CFUN=<fun> OK <fun> values:
0**: Disable the radio
1**: Enable the radio
Read IMEI AT+CGSN=1 ¹ <imei>
OK
Request the IMEI (International Mobile Equipment Identity).
Read IMSI AT+CIMI <imsi>
OK
Request the IMSI (International Mobile Subscriber Identity).
Operator selection AT+COPS=<mode> ¹ OK Force an attempt to select and register with the network operator. Through <mode> parameter the network selection can automatically be performed or forced by this command.
Supported <mode> values:
0**: (default) automatic
1: manual
2**: deregister from network
GPRS attach/detach AT+CGATT=[<state>] OK Attach or detach to/from the mobile network. Allowed <state> values:
0**: Detach from network
1**: Attach to network
Check if GPRS attached AT+CGATT? +CGATT: <state>
OK
Check if SARA-N210 is attached to the mobile network or not. <state> values:
0**: Detached from network
1**: Attached to network
Network registration status AT+CEREG? +CEREG: <n>,<stat> ¹
OK
This command has 6 different modes, each of which gives different return values. Response is +CEREG: <n>,<stat>[...], where <n> is the mode number and <stat> is the registration status. See chapter 9.6.3 in «SARA-N2 AT Commands» for all modes and descriptions. Here are the <stat> number values:
0**: not registered, the MT is not currently searching an operator to register to
1: registered, home network
2: not registered,but the MT is currently trying to attach or searching an operator to register to
3: registration denied
4: unknown (e.g. out of E-UTRAN coverage)
5: registered, roaming
8**: attached for emergency bearer services only
Check signal strength AT+CSQ +CSQ: <signal_power>,<qual>
OK
Request signalpower_ and qual. On the SARA-N210, qual will always be 99. The mapping between signalpower_ and RSSI dBm is -113 + (signal_power * 2).
Example response: +CSQ: 25,99
RSSI = (-113 + (25 * 2)) = -63 dBm
Create socket AT+NSOCR=<type>,<protocol>,<listen_port>,<receive_control> <socket>
OK
Create a socket. If a port is set, receiving is enabled and +NSONMI URC will appear for any message that is received on that port. Max number of ports: 7.
Supported <type>: "DGRAM"
Supported <protocol>: 17 (UDP)
Port range: 0-65535 except for 5683.
<receive_control> allowed values:
0**: incoming messages will be ignored
1: (default) incoming messages will trigger a +NSONMI URC

Response**: Socket identifier to be referenced by the other socket AT commands
Send UDP to IP AT+NSOST=<socket>,<remote_ip_address>,<remote_port>,<length>,<data> <socket>,<sent_length>
OK
Send a UDP datagram to the specified host and port. See Table 3 for parameter descriptions.
Send UDP to IP with flags AT+NSOSTF=<socket>,<remote_ip_address>,<remote_port>,<flags>,<length>,<data> <socket>,<sent_length>
OK
Send a UDP datagram to the specified host and port with flags. Needed for power saving mode. See Table 3 for parameter descriptions.
Error report formatting AT+CMEE=[<n>] OK Configure formatting of errors. List of supported values:
0**: ERROR
1**: +CME ERROR:

See Appendix A in the «SARA-N2 AT Commands» documentation for error result code descriptions.
Config AT+NCONFIG=<function>,<value> OK Configure customizable aspects of the SARA-N210 (e.g Auto Attach). The changes are effective after the module reboot by means of the AT+NRB command. Use AT+NCONFIG? to show current config.
PDP context definition AT+CGDCONT=[<cid>[,<PDP_ type>[,<APN>[,<PDP_addr>]]]] ¹ OK Define the connection parameters for a PDP context. Usually to configure APN settings manually. See example further up.
Device statistics AT+NUESTATS[=<type>] NUESTATS: <type>,<param_ name>,<value>
[NUESTATS: …]
OK
Request the most recent operational statistics of the module. Should be called right after sending. Some interesting values: TX power, ECL (equipment coverage class), throughput, bytes received, bytes sent, cell info. See chapter 4.8 in «SARA-N2 AT Commands» for full description of all fields and available <type>s.
Reboot AT+NRB REBOOT_CAUSE_APPLICATION_AT
u-blox
OK
Reboot the SARA-N210. There is a short delay after the command issuing before the SARA-N210 reboots.
Power saving mode settings AT+CPSMS=[<mode>[,,,<Requested_Periodic_TAU>[,<Requested_Active_Time>]]] ¹ OK Enable and configure the power saving mode. See own low power tutorial for full details and examples.
Enable/disable eDRX AT+CEDRXS=<mode>[,<AcT_type>[,<Requested_eDRX_value>]] OK Configure extended discontinuous reception (eDRX) parameters. See own low power tutorial for full details and examples.
Get network time/clock AT+CCLK? +CCLK: "YY/MM/DD,HH:MM:SS+ZZ"
OK
Fetches the network time/clock.

¹ - Simplified syntax. See «SARA-N2 AT Commands» for full syntax.

Table 3: AT+NSOST parameters (from SARA-N2 AT Commands documentation)

Parameter Type Description
socket Number Socket identifier returned by AT+NSOCR
remote IP address String Remote host IP address of the remote host in IPv4 format. IP addresses can be specified in decimal, octal or hexadecimal notation.
remote port Number A number in the range 0-65535. Remote port the messages will be received on.
length Number Size of the data to send. The maximum length 512 bytes.
data String Data to be sent (as a hexadecimal string)
flags (for NSOSTF) Number Specifies the type of message transmission in hexadecimal format. Values of this argument are formed by logically OR’ing zero or more of the following flags:
• 0x000: no flags are set
• 0x100: exception message. Send message with high priority
• 0x200: release indicator. Indicate release after next message
• 0x400: release indicator. Indicate release after next message has been replied to
Edit this page