This article will provide an overview of how to install and leverage Hologram's Command Line interface to manage cellular modems and send 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
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 3.9
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></username>
Please enter your Hologram password:<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 --authtypecommand 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 --authtypecommand 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></qual></rssi>
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>"</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=""></modem>
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"}</hh:mm:ss></latitude></longitude></altitude",>
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
Multi-factor Authentication (MFA)
Overview
Hologram's multi-factor authentication (MFA) helps developers and businesses verify IoT device identity, maintain privacy, and re-issue security keys to restore trust with devices following a security incident or breach. Currently available via Hologram secure SIMs with the Hologram Python SDK or CLI, Hologram multi-factor authentication enables key rotation, signing, and message authentication codes, such as Time-based One-Time Password for Machines (TOTP-M), all through a few lines code.
Available now in private beta. Contact sales to learn more.
Hologram MFA
- Nonce and Challenge-Response Scheme
Hologram SDK generates a nonce which is input to a challenge-response scheme embedded within secure memory in all Hologram secure IoT SIMs. - Serial and time-based One-time Password for Machines (OTP-M) Generation
Hologram secure IoT SIM returns Serial and Time-based One-time Password for Machines (OTP-M) for authentication for message payload. - Serial and OTP-M Key Submission
Message payload and serial+OTP-M key submitted to Hologram authentication server. - Hologram MFA Validation
Hologram authentication server symmetrically reproduces nonce and challenge scheme for validation of device identity and payload then returns confirmation/success in real-time.
Setup
The send cloud CLI script allows developers to specify authentication type used for message validation. By default, a single factor One-time Password (OTP) based on time is used. Enabling multi-factor authentication through a combination of the default OTP and Hologram MFA element in Hologram's secure IoT SIMs requires only initializing the authentication type parameter with --authtype 'sim-otp'.
Example:
# Send messages via Hologram MFA using the connected cellular modem.
hologram send --cloud --authtype 'sim-otp' 'my MFA test message'