Introduction

Hologram’s Command Line Interface is an easy-to-use command set for managing cellular modems and sending data to and from devices.

It’s designed to be run on small Linux devices such as Raspberry Pi, which are connected to the internet using a USB cellular modem like the Hologram Nova.

Python SDK

The Hologram CLI is built with the Hologram Python SDK.

The Python SDK is open-source and customizable for your own hardware or cloud applications.

Installation

Requirements:
  • PPP
  • Python 2.7

We wrote scripts to ease the installation process.

Please run this command to download the script that installs the Python SDK:

curl -L hologram.io/python-install | bash

Please run this command to download the script that updates the Python SDK:

curl -L hologram.io/python-update | bash

If everything goes well, you’re done and ready to use the SDK.

Command Line Interface (CLI)

The package includes some command line tools that you can use to perform operations with the Hologram cloud or as examples for writing your own application using this SDK.

We do this by exporting a few scripts and adding them to your PATH. After installing the SDK, you should be able to run hologram on your terminal. Type hologram --help for more information.

Here are some basic subcommands that you may find useful:

activate

hologram activate [-h] [-v] [--apikey [APIKEY]]

Options:

  • --apikey (string) – Hologram organization API key. This is optional as users can choose to log in with their username and password.
  • -v --verbose – SDK verbose option.
  • -h, --help – show a help message and exit.

Example:

# Activate a SIM via the organization apikey.
hologram activate --apikey 'thisisaverylongapikey'
# Activate a SIM via username and password prompt.
hologram activate
Please enter your Hologram username:<username>
Please enter your Hologram password:<password>

send cloud

This script sends messages to your specified host.

There are two modes to do this:

  1. Send messages via CSRPRK Authentication while in network agnostic mode.
  2. Send messages via TOTP Authentication while using the cellular modem. This can be configured with the --authtype command line option.
hologram send --cloud [-h] [--authtype [AUTHTYPE]]
                    [--duration [DURATION]] [--devicekey [DEVICEKEY]]
                    [--repeat [REPEAT]] [--timeout [TIMEOUT]]
                    [-t [TOPIC [TOPIC ...]]] [-v]
                    [message]

Options:

  • message (string) – A message that will be sent to the cloud. If there are whitespaces in your message, you probably want to encapsulate it with double quotes to denote a single string in Python.
  • --devicekey (string) – The 8 character device key obtained from your dashboard.
  • --timeout (int) – The period in seconds before the socket closes if it doesn’t receive a response. Default to 5 seconds.
  • --authtype (string) – The authentication type used. Pick between ‘csrpsk’ and ‘totp’. Default to ‘totp’.
  • --host (string) – The host used for the TCP outbound connection. Default to ‘cloudsocket.hologram.io’
  • -p --port (string) – The port used for the TCP outbound connection. Default to 9999.
  • -t --topic (string, optional) – Topics for the message
  • -v --verbose – SDK verbose option.
  • -h, --help – show a help message and exit

Note

You must set the `devicekey` if you choose to use the `HologramCloud` class to send messages to our cloud. You must also set the `host` and `port` arg values if you choose to use the `CustomCloud` interface.

Example:

# Send messages while in network agnostic mode.
hologram send --cloud 'message'  --topic 'topic-example'
# Send messages via TOTP mode using the connected cellular modem.
hologram send --cloud --authtype 'totp' 'my test message'

send sms

This script sends a SMS to a given destination number by utilizing the HologramCloud interface.

hologram send --sms [-h] --devicekey [DEVICEKEY] --destination
                  [DESTINATION]
                  [message]

Options:

  • message (string) – SMS that will be sent to the destination number.
  • --devicekey (string) – The 8 character device key obtained from your dashboard.
  • --destination (string) – The destination number in which the SMS will be sent. This must be a E.164 formatted string with a ‘+’ sign.
  • -v --verbose – SDK verbose option.
  • -h, --help – Show a help message and exit.

Example:

# sends a "hey there!" message to +11234567890
hologram send --sms --destination +11234567890 'hey there!'

Note

You must set `devicekey` if you choose to use the `HologramCloud` class to send messages to our cloud.

receive data

This subcommand listens for data from the Hologram Cloud.

hologram receive --data [-h] [-m [MODEM]] [-v] [-t [TIMEOUT]]

Options:

  • -t --timeout (int) – The number of seconds before the socket is closed. Default to -1 (blocking forever until explicitly closed by the user).
  • -v --verbose – SDK verbose option.
  • -h, --help – Show a help message and exit.

Example:

# Listens on inbound connections.
hologram receive --data

# You can also do this since the default is --data.
hologram receive

receive sms

This subcommand listens for SMS from the Hologram Cloud.

hologram receive --sms [-h] [-m [MODEM]] [-v] [-t [TIMEOUT]]

Options:

  • -t --timeout (int) – The number of seconds before the SDK stops reading from the serial port. Default to -1 (blocking forever until explicitly closed by the user).
  • -m --modem (string) – The name of the modem. Either nova, ms2131 or e303.
  • -v --verbose – SDK verbose option.
  • -h, --help – Show a help message and exit.

Example:

# Listens for incoming SMS.
hologram receive --sms

heartbeat

This script sends messages to your specified host.

There are two modes to do this:

  1. Send messages via CSRPRK Authentication while in network agnostic mode.
  2. Send messages via TOTP Authentication while using the cellular modem. This can be configured with the --authtype command line option.
hologram heartbeat [-h] [--authtype [AUTHTYPE]]
                   [--duration [DURATION]] [--devicekey [DEVICEKEY]]
                   [--repeat [REPEAT]] [--timeout [TIMEOUT]]
                   [-t [TOPIC [TOPIC ...]]] [-v]
                   [message]

Options:

  • message (string) – A message that will be sent to the cloud. If there are whitespaces in your message, you probably want to encapsulate it with double quotes to denote a single string in Python.
  • --devicekey (string) – The 8 character device key obtained from your dashboard.
  • --timeout (int) – The period in seconds before the socket closes if it doesn’t receive a response. Default to 5 seconds.
    • --authtype (string) – The authentication type used. Pick between ‘csrpsk’ and ‘totp’. Default to ‘totp’.
    • --host (string) – The host used for the TCP outbound connection. Default to ‘cloudsocket.hologram.io’
    • -p --port (string) – The port used for the TCP outbound connection. Default to 9999.
    • -t --topic (string, optional) – Topics for the message.
    • -v --verbose – SDK verbose option.
    • -h, --help – show a help message and exit.

Note

You must set the `devicekey` if you choose to use the `HologramCloud` class to send messages to our cloud. You must also set the `host` and `port` arg values if you choose to use the `CustomCloud` interface.

Example:

  # Send messages while in network agnostic mode.
  hologram heartbeat 'message' --topic 'topic-example'
  # Send messages via TOTP mode using the connected cellular modem.
  hologram heartbeat --authtype 'totp' 'my test message'

spacebridge

This script utilizes either one of the 4 modems supported (Nova (U201), Nova (R404), MS2131, E303) and listens/receives data sent from the dashboard.

This is basically just an alias for hologram receive.

hologram spacebridge [-h] [-m [MODEM]] [-v] [-t [TIMEOUT]]

Options:

  • -t --timeout (int) – The number of seconds before the socket is closed. Default to -1 (blocking forever until explicitly closed by the user).
  • -m --modem (string) – The name of the modem. Either nova, ms2131 or e303.
  • -v --verbose – SDK verbose option.
  • -h, --help – show a help message and exit.

Example:

# Listens on inbound connections.
hologram spacebridge

modem signal

Prints a formatted signal strength string if a supported modem is available. The printed string will be formatted as follows:

Signal strength:<rssi>,<qual>

Properties:

  • rssi (int) – The rssi value here ranges between 0-31 and 99.
  • qual (int) – The qual value here ranges between 0-7 and 99.

Note

This CLI command will only work on the Hologram Nova (U201) modem.

Example:

hologram modem signal # Prints something similar to: "Signal strength: 11,5"

modem operator

Prints out the modem operator name if a supported modem is available. The printed string will be formatted as follows:

Operator: "<operator>"

Example:

hologram modem operator # Prints something like: Operator: "T-Mobile"

Note

It takes some time to establish a correct operator. Please wait for a while to call this property after the modem is physically connected.

modem type

Prints out the modem name if the SDK is able to detect it. The printed string will be formatted as follows:

Type: <modem name>

Example:

hologram modem type # Prints something like: Type: ms2131

modem location

Prints out a formatted string of the cellular modem’s approximate location.

The printed string will be a formatted JSON as follows:

{"altitude": "<altitude", "uncertainty": "<uncertainty>", "longitude": "<longitude>", "latitude": "<latitude>, "time": "<hh:mm:ss>", "date": "dd/mm/yyyy"}

Note

The current implementation will be blocking and could take a couple minutes to return.

Note

This CLI command will only work on the Hologram Nova (U201) modem.

Example:

hologram modem location
# Prints something like this in Chicago:
# Location: {"altitude": "201", "uncertainty": "235", "longitude": "-87.6243304",
# "latitude": "41.8893885", "time": "18:54:05.000", "date": "11/05/2017"}

network connect

Establishes a PPP session and set it as the default interface.

Example:

hologram network connect

network disconnect

Kills an existing PPP session that was established by a hologram network connect command.

Example:

hologram network disconnect
# Prints:
# Checking for existing PPP sessions
# Found existing PPP session on pid: 21448
# Killing pid 21448 now