Welcome to python-hologram-api’s documentation!¶

Contents:

python-hologram-api¶

Python client for https://dashboard.hologram.io/api.

https://img.shields.io/travis/vicyap/python-hologram-api.svg

https://coveralls.io/repos/github/vicyap/python-hologram-api/badge.svg?branch=master

Installation¶

pip install python-hologram-api

Documentation¶

Python API: https://python-hologram-api.readthedocs.io.
HTTP API: https://hologram.io/docs/reference/cloud/http/

Usage¶

HologramClient is the main class you should use. Most of its methods are sub-categorized based on the endpoint that the method interfaces with. For example, user account management is under client.user.

To use python-hologram-api in a project:

import os
from python_hologram_api.client import HologramClient

HOLOGRAM_API_KEY = os.environ.get('HOLOGRAM_API_KEY')
client = HologramClient(HOLOGRAM_API_KEY)

Example Usages:

# List Devices
resp = client.devices.list()
if resp.get('success'):
    devices = resp.get('data')

# Get a Device
device_id = 1234
resp = client.devices.get(device_id)
if resp.get('success'):
    device = resp.get('data')

# Activate SIMs
sims = ['99990000000012345678']
plan = 73
tier = 1
resp = client.cell.activate_sims(sims, plan, tier)
assert resp.get('success') is not None

The following submodules are available:

Device Management
- client.devices
- client.cell
- client.tags
- client.data_plans
Hologram Cloud
- client.csr
- client.sms
- client.cloud
- client.spacebridge
Account Management
- client.user
- client.org

License¶

Free software: MIT license

python_hologram_api package¶

Submodules¶

python_hologram_api.cellular module¶

Cellular Links module.

class python_hologram_api.cellular.CellularLinks(client)[source]¶

Bases: object

CellularLinks class.

A Cellular Link is the association between a Device and a cellular data plan and SIM. Typically, a device has exactly one Cellular Link.

activate_sims(sims, plan, tier)[source]¶

Activate SIMs.

Parameters:	sims (List[str]) – array of SIM numbers to activate. plan (int) – Device data plan. Look up plan IDs with List Data Plans. tier (int) – Geographic zone. Currently the valid tiers are 1 and 2. Higher tiers incur higher costs. See pricing for details.
Returns:	the json response as a dictionary.
Return type:	dict

change_overage_limit(link_id, limit)[source]¶

Change Overage Limit.

Parameters:	link_id (int) – Integer ID of the link to modify. limit (int) – Number of bytes over the plan limit to allow. Set -1 for no data limit.
Returns:	the json response as a dictionary.
Return type:	dict

change_plan(link_id, plan, tier)[source]¶

Change Plan.

Parameters:	link_id (int) – Integer ID of the link to change. plan (int) – Device data plan. Look up plan IDs with List Data Plans. tier (int) – Geographic zone. Currently the valid tiers are 1 and 2. Higher tiers incur higher costs. See pricing for details.
Returns:	the json response as a dictionary.
Return type:	dict

get_link(link_id)[source]¶

Get Cellular Link.

Parameters:	link_id (int) – Integer ID of the link to retrieve.
Returns:	the json response as a dictionary.
Return type:	dict

list_links(org_id=None)[source]¶

List Cellular Links.

Parameters:	org_id (int, optional) – Only return results for the given organization ID.
Returns:	the json response as a dictionary.
Return type:	dict

pause_link(link_id)[source]¶

Pause Data.

Parameters:	link_id (int) – Integer ID of the link to modify.
Returns:	the json response as a dictionary.
Return type:	dict

unpause_link(link_id)[source]¶

Unpause Data.

Parameters:	link_id (int) – Integer ID of the link to modify.
Returns:	the json response as a dictionary.
Return type:	dict

python_hologram_api.client module¶

Main module.

class python_hologram_api.client.HologramClient(api_key, base_url='https://dashboard.hologram.io/api/1/')[source]¶

Bases: object

Hologram API Client class.

api_key¶: Return api_key.

base_url¶: Return base_url.

python_hologram_api.cloud_messaging module¶

Cloud Messaging module.

class python_hologram_api.cloud_messaging.CSRMessaging(client)[source]¶

Bases: object

Cloud Services Router (CSR) class.

list_messages(device_id=None, limit=None, org_id=None, topic_name=None, time_stamp_start=None, time_stamp_end=None)[source]¶

List CSR Messages.

Parameters:	device_id (int, optional) – Filter for messages originating from one device. limit (int, optional) – Return a maximum of this many messages. Default is 25. org_id (int, optional) – Filter for messages from devices belonging to this organization. topic_name (str, optional) – Filter for messages with a given topic. time_stamp_start (int, optional) – Only return messages received after this time (Unix timestamp). time_stamp_end (int, optional) – Only return messages received before this time (Unix timestamp).
Returns:	the json response as a dictionary.
Return type:	dict

send_message(device_id, data, tags=None)[source]¶

Send a CSR Message.

Parameters:	device_id (int) – Device ID to associate the message to. data (str) – Data payload of the message. tags (List[str], optional) – Additional topics to associate with the message.
Returns:	the json response as a dictionary.
Return type:	dict

class python_hologram_api.cloud_messaging.CloudToDeviceMessaging(client)[source]¶

Bases: object

Cloud To Device Messaging.

Send a TCP or UDP message to one or more devices on the Hologram network.

send_message(device_ids, protocol, port, data=None, base64_data=None)[source]¶

Send a Message to a List of Devices.

Must send either data or base64data.

Parameters:	device_ids (List[int]) – IDs of devices to send message. protocol (str) – The protocol to use: ‘TCP’ or ‘UDP’. port (int) – The port to use. data (str) – The data to send. Max length of 10k bytes. base64_data (str) – The data to send, encoded in base64. Max length of 10k bytes.
Returns:	the json response as a dictionary.
Return type:	dict

trigger_webhook(device_id, webhook_guid, data=None, base64_data=None)[source]¶

Send Message to a Device via Webhook.

This endpoint does not require authentication with your API key, as the webhook GUID serves as an authentication token. In order to generate a webhook URL, please visit the cloud configuration page for your device.

Must send either data or base64data.

Parameters:	device_id (int) – ID of the device to send to. webhook_guid (str) – generated UUID for the webhook URL. data (str, optional) – The data to send. Max length of 10k bytes. base64_data (str, optional) – The data to send, encoded in base64. Max length of 10k bytes.
Returns:	Integer Code of responded HTTP Status, e.g. 404 or 200.
Return type:	int

class python_hologram_api.cloud_messaging.SMSMessaging(client)[source]¶

Bases: object

SMS Messaging class.

send_message(device_id, body, from_number=None)[source]¶

Send SMS Message.

There is no cost to send SMS messages to Hologram devices via API.

Parameters:	device_id (int) – ID of the device to send to. body (str) – ASCII Text representation of the SMS body. from_number (str, optional) – Phone number to display as the sender.
Returns:	the json response as a dictionary.
Return type:	dict

python_hologram_api.constants module¶

Constants module.

python_hologram_api.data_plans module¶

Data Plans module.

class python_hologram_api.data_plans.DataPlans(client)[source]¶

Bases: object

DataPlans class.

The Data Plans endpoints return pricing and descriptions for the different data plans that Hologram offers. When changing the data plan for a cellular link via API, you must refer to the plan by its ID, which you can determine from these endpoints.

get(plan_id)[source]¶

Get a Data Plan.

Parameters:	plan_id (int) – The ID of the plan to get.
Returns:	the json response as a dictionary.
Return type:	dict

list()[source]¶

List Data Plans.

Returns:	the json response as a dictionary.
Return type:	dict

python_hologram_api.device_tags module¶

Device Tags module.

class python_hologram_api.device_tags.DeviceTags(client)[source]¶

Bases: object

DeviceTags class.

Device tags are user-configurable categories that you can use to classify your devices. A device may be linked to more than one tag.

create(name)[source]¶

Create a Device Tag.

Parameters:	name (str) – Name for the new tag.
Returns:	the json response as a dictionary.
Return type:	dict

delete(tag_id)[source]¶

Delete a Device Tag.

Parameters:	tag_id (int) – The ID of the tag to delete.
Returns:	the json response as a dictionary.
Return type:	dict

link_devices(tag_id, device_ids)[source]¶

Link a List of Devices to a Tag.

Parameters:	tag_id (int) – The ID of the tag. device_ids (List[int]) – List of device IDs to link to this tag.
Returns:	the json response as a dictionary.
Return type:	dict

list()[source]¶

List Device Tags.

Returns:	the json response as a dictionary.
Return type:	dict

unlink_devices(tag_id, device_ids)[source]¶

Unlink a List of Devices to a Tag.

Parameters:	tag_id (int) – The ID of the tag. device_ids (List[int]) – List of device IDs to unlink to this tag.
Returns:	the json response as a dictionary.
Return type:	dict

python_hologram_api.devices module¶

Devices module.

class python_hologram_api.devices.Devices(client)[source]¶

Bases: object

Devices class.

get(device_id)[source]¶

Get a Device.

Parameters:	device_id (int) – The device id to get.
Returns:	the json response as a dictionary.
Return type:	dict

list(org_id=None)[source]¶

List Devices.

Parameters:	org_id (int, optional) – Only return results for the given organization ID.
Returns:	the json response as a dictionary.
Return type:	dict

python_hologram_api.organization module¶

Organization Account Management module.

class python_hologram_api.organization.Organization(client)[source]¶

Bases: object

Organization class.

Organizations allow multiple users to share access to the same devices and billing account. See the guide for more information.

add_balance(org_id, amount)[source]¶

Add Balance.

Charge the organization’s configured billing source and add that amount to the account balance

Parameters:	org_id (int) – The organization’s unique identifier. amount (float) – Amount to add to current user balance.
Returns:	the json response as a dictionary.
Return type:	dict

balance_history(org_id)[source]¶

Get Balance History.

Retreive a history of transactions (credits and charges).

Parameters:	org_id (int) – The organization’s unique identifier.
Returns:	the json response as a dictionary.
Return type:	dict

get(org_id)[source]¶

Get an Organization.

Parameters:	org_id (int) – The organization’s unique identifier.
Returns:	the json response as a dictionary.
Return type:	dict

get_balance(org_id)[source]¶

Get Current Balance.

Parameters:	org_id (int) – The organization’s unique identifier.
Returns:	the json response as a dictionary.
Return type:	dict

list()[source]¶

List Organizations.

List all organizations that you are a member of. This includes the special “personal” organization tied to your user.

Returns:	the json response as a dictionary.
Return type:	dict

python_hologram_api.spacebridge module¶

Spacebridge module.

class python_hologram_api.spacebridge.Spacebridge(client)[source]¶

Bases: object

Spacebridge class.

See the Spacebridge guide for details. https://hologram.io/docs/guide/cloud/spacebridge-tunnel/

add_public_key(public_key)[source]¶

Add Public Key.

Associate an SSH key with your user. This key can then be used to tunnel to devices that you control.

Parameters:	public_key (str) – SSH public key.
Returns:	the json response as a dictionary.
Return type:	dict

disable_key(tunnel_key_id)[source]¶

Disable a Key.

Parameters:	tunnel_key_id (int) – ID of the tunnel key to disable.
Returns:	the json response as a dictionary.
Return type:	dict

enable_key(tunnel_key_id)[source]¶

Enable a Key.

Parameters:	tunnel_key_id (int) – ID of the tunnel key to enable.
Returns:	the json response as a dictionary.
Return type:	dict

list_public_keys(with_disabled=False)[source]¶

List Public Keys.

Parameters:	withdisabled (bool, optional) – Set to True to include disabled keys.
Returns:	the json response as a dictionary.
Return type:	dict

python_hologram_api.user module¶

User Account Management module.

class python_hologram_api.user.User(client)[source]¶

Bases: object

User class.

Requests to the user account balance endpoints are equivalent to calling the organization account balance endpoints with the personal organization.

add_balance(amount)[source]¶

Add Balance.

Charge the user’s configured billing source and add that amount to your account balance.

Parameters:	amount (float) – Amount to add to current user balance.
Returns:	the json response as a dictionary.
Return type:	dict

balance_history()[source]¶

Get Balance History.

Retreive a history of transactions (credits and charges).

Returns:	the json response as a dictionary.
Return type:	dict

get_balance()[source]¶

Get Current Balance.

Returns:	the json response as a dictionary.
Return type:	dict

get_info()[source]¶

Get Current User.

Returns:	the json response as a dictionary.
Return type:	dict

Module contents¶

Top-level package for python-hologram-api.

Contributing¶

Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given.

You can contribute in many ways:

Types of Contributions¶

Report Bugs¶

Report bugs at https://github.com/vicyap/python_hologram_api/issues.

If you are reporting a bug, please include:

Your operating system name and version.
Any details about your local setup that might be helpful in troubleshooting.
Detailed steps to reproduce the bug.

Fix Bugs¶

Look through the GitHub issues for bugs. Anything tagged with “bug” and “help wanted” is open to whoever wants to implement it.

Implement Features¶

Look through the GitHub issues for features. Anything tagged with “enhancement” and “help wanted” is open to whoever wants to implement it.

Write Documentation¶

python-hologram-api could always use more documentation, whether as part of the official python-hologram-api docs, in docstrings, or even on the web in blog posts, articles, and such.

Submit Feedback¶

The best way to send feedback is to file an issue at https://github.com/vicyap/python_hologram_api/issues.

If you are proposing a feature:

Explain in detail how it would work.
Keep the scope as narrow as possible, to make it easier to implement.
Remember that this is a volunteer-driven project, and that contributions are welcome :)

Getting Started¶

Clone the repo and run:

make setup

If that does not work for you, you can also install the requirements with pip:

pip install -r requirements_dev.txt

Running Tests¶

Tests are run with tox.

https://tox.readthedocs.io/en/latest/

History¶

0.1.6 (2017-10-27)¶

Add coverage to travis
Add coveralls to travis and README

0.1.5 (2017-10-27)¶

Update README formatting/highlighting

0.1.4 (2017-10-23)¶

Add python_hologram_api.rst to documentation

0.1.3 (2017-10-23)¶

Update documentation

0.1.2 (2017-10-23)¶

First release on PyPI.
Implemented a Python wrapper for https://hologram.io/docs/reference/cloud/http/

0.1.1 (2017-10-23)¶

Travis Errors

0.1.0 (2017-10-20)¶

Mistakes were made.

Welcome to python-hologram-api’s documentation!¶

python-hologram-api¶

Installation¶

Documentation¶

Usage¶

License¶

python_hologram_api package¶

Submodules¶

python_hologram_api.cellular module¶

python_hologram_api.client module¶

python_hologram_api.cloud_messaging module¶

python_hologram_api.constants module¶

python_hologram_api.data_plans module¶

python_hologram_api.device_tags module¶

python_hologram_api.devices module¶

python_hologram_api.organization module¶

python_hologram_api.spacebridge module¶

python_hologram_api.user module¶

Module contents¶

Contributing¶

Types of Contributions¶

Report Bugs¶

Fix Bugs¶

Implement Features¶

Write Documentation¶

Submit Feedback¶

Getting Started¶

Running Tests¶

History¶

0.1.6 (2017-10-27)¶

0.1.5 (2017-10-27)¶

0.1.4 (2017-10-23)¶

0.1.3 (2017-10-23)¶

0.1.2 (2017-10-23)¶

0.1.1 (2017-10-23)¶

0.1.0 (2017-10-20)¶

Indices and tables¶