The Hologram Cloud provides an API and an interface in your dashboard to send TCP or UDP messages to any port on a cellular device through a SIM. By running a server on your device that listens on a given port, you can receive and process these messages.
Start a test server
One simple way to start a test TCP server on a Linux device (e.g. Raspberry Pi) is with the netcat command. To listen on port 9876 and print any incoming message, run the command:nc -l -p 9876
By default netcat will quit after the sender closes the connection. Some versions support a -k option to keep listening indefinitely.
A more realistic application might use a socket library in a language like Python, where you could then parse and act on the incoming messages. But for illustrating the communication channel itself, netcat is nice and simple.
Send a message
From your dashboard
You can send messages to a device from the SIM's details page in your dashboard.
- Open the Manage SIM menu and select Send message to SIM.
- In the modal that opens, choose the Cloud data option.
- Enter the same port number as you configured your server to listen on, and select TCP as the protocol. When you submit the form, the Hologram Cloud will forward the message to your device.
Via REST API
Messages can be sent via HTTP API using the /devices/message endpoint.
Via inbound webhook
The HTTP API above requires an API key to authenticate. This can make it difficult to integrate with an external service that simply sends webhook requests to a configurable URL. To accommodate this use case, you may generate a special URL endpoint which does not require additional authentication.
To generate a URL for inbound webhooks, find the SIM you want to communicate with and open its details page.
- Open Webhooks tab on a device’s dashboard page.
- Click Generate webhook and specify which port and protocol (TCP or UDP) to forward data to:
- Enter the protocol and port you plan to communicate with, and copy the URL to use in your own code.
When you send an inbound message to the webhook, the request body must contain a data field with a string value. This value gets emitted to the device on the configured port.
Replies
If the device sends data back through the socket connection after receiving a message, it gets sent as a message to the Data Router.
Advanced messaging with device tunneling
Spacebridge is a lower-level alternative to cloud messaging. It acts as a secure proxy from a device’s port to a port on your local machine. This allows you to implement other two-way TCP and UDP based protocols to communicate with your device via secure, authenticated tunnels.
See our device tunneling guide for details.