Atmosphere IoT Agent

The Atmosphere IoT Agent is a local application that runs in your computer’s system tray, and acts as an intermediary between the computer’s connectivity protocol drivers and the browser running Atmosphere.

Agent Icon

The agent is used for programming hardware and enables you to program a device from within Atmosphere Iot Studio. The agent is also used to assist in registering it to Atmosphere by searching your computer for any compatible device connected to it from an available communication port. While the agent is running, a device connected to your computer with Atmosphere firmware installed on it can be registered to Atmosphere directly without the assistance from an additional connection.


Operating System Support Version Link
Windows Windows 7 and up 1.4.4 Download
Linux All Linux platforms 1.4.4 Download
macOS macOS 10.4 and up 1.4.4 Download



Run the downloaded installation .exe, then specify the local directory where to install the agent.


Navigate to the directory that contains the downloaded .AppImage file. Run chmod u+x on the downloaded file, and add the current user to the dialout group on your system: sudo adduser $USER dialout. Alternatively, you can run the .AppImage as root (not recommended) .

NOTE: These instructions have been verified to work on Ubuntu/Debian based distributions. Tailor the suggested commands to your particular distribution.

Automatic Updates via AppImage

In order to enable the Atmosphere IoT Agent to update to a new version automatically while operating on Linux, either of the following configurations are required on your system:

  • Run the AppImage as a standalone application without enabling desktop integration. (recommended)
  • Set the APPIMAGELAUNCHER_DISABLE environment variable to true then launch the AppImage. Example: APPIMAGELAUNCHER_DISABLE=true AtmosphereIoTAgent.AppImage. There is also an appimagelauncher.cfg configuration file where this can be set. Its location will be dependent on your Linux distribution.
  • Uninstall AppImageLauncher from your system prior to initiating an automatic update, and then reinstall the package once the update is complete.


Run the downloaded installation .dmg, then drag and drop the Atmosphere IoT icon inside the DMG view into the Applications folder on your system.

For USB-C only Macbooks

Install the Silicon Labs VCP UART drivers here in order to get the IoT Agent to communicate via USB-C adapters for your ESP32.

Agent Firefox Exception

In order to use the Atmosphere IoT Agent within Firefox, a security exception for the agent needs to be added to communicate in the browser. Without the exception, Firefox won’t allow Atmosphere to communicate to your computer. This behavior is unique to Firefox and other browsers aren’t affected.

To create a security exception certificate for Firefox:

  1. Close all open Firefox windows, and close the Atmosphere IoT Agent.
  2. Relaunch both Firefox and the agent.
  3. In Firefox, open the browser menu and click Options.
  4. From the Options menu, click Privacy & Security.
  5. From the Privacy & Security menu, scroll down to the Security section, then under Certificates click View Certificates.
  6. From the Certificate Manager window, click the Servers tab.
  7. In the Servers tab, click Add Exception.
  8. In the Location field, enter https://localhost:48701, then click Get Certificate.
  9. Select the Permanently store this exception checkbox, then click Confirm Security Exception to complete the process.

This enables Firefox to communicate to the agent’s server running on your computer. The next time you login to Atmosphere and attempt to program on Firefox, your browser should be able to communicate with your computer without issue.

Running the Agent

Using the Atmosphere IoT Agent simply involves running it in the background of your computer during programming or device registration, with no additional instructions or usage involved.

Operating the Agent as a Gateway

The Atmosphere IoT Agent can be configured to operate as a gateway for Zigbee applications. When configured, the agent acts as the gateway for the Zigbee network’s coordinator device as long as the device is connected to the computer running the agent. This enables end node devices on the network to communicate with the Zigbee coordinator, which then has data sent to Atmosphere via the agent through the computer’s Internet connection.

To configure the agent as a gateway:

Close the Atmosphere IoT Agent prior to modifying any configurations.

  1. Locate the agent’s user account folder on your system. The folder is located in a path such as C:\Users\Username\.atmosphereiotagent, though the location may vary based on your operating system.
  2. In the folder, open the settings.json file in a text editor. This file is used to set custom gateway configurations for the agent. The file should resemble the following default configuration:
         "gateway": {}

    Having never been modified, the file includes empty gateway settings. To run the agent as a gateway, it needs the following information:

    • URL: The URL the data is sent to.
    • Network ID: The unique Zigbee network the data is sent to, defined in an Atmosphere project.
    • COM port: The COM port the Zigbee coordinator device is connected to on your computer.
    • Baud rate: The rate data is sent from the Zigbee coordinator device to Atmosphere.
  3. In the file, copy and paste the following into your settings:
         "gateway": {
             "url": "",
             "zigbee": {
                 "networkId": "YourNetworkID",
                 "comPort": "YourDeviceCOMPort",
                 "baudRate": 9600

    Replace the network ID and COM port entries with the information from your Zigbee application and device, respectively. The baud rate is recommended to remain at 9600 as this is a tested rate verified to work properly, though advanced users may modify this to a rate that meets their application’s needs.

  4. When finished, save the updated file. The gateway configurations will take effect once the agent is run.

With the Atmosphere IoT Agent configured, any subsequent use with the agent will work alongside a Zigbee application built using that network ID.

If you're interested in building an application with the Atmosphere IoT Agent as a gateway, the Using the Atmosphere IoT Agent as a Zigbee Gateway guide provides a simple walkthrough for incorporating this into a Zigbee network project.

Gateway Configuration Considerations

Additional information pertaining to operating the Atmosphere IoT Agent as a gateway are detailed below.

  • The agent may only operate as a gateway for one Zigbee network at a time.
  • Data will be forwarded via the agent to the configured URL as long as the computer’s Internet connection is maintained. If the computer loses its Internet connection, data received from network end node devices during that time will be lost.
  • The agent must remain running in the system tray in order to send data to Atmosphere. However, a browser window isn’t required to be open.
    • If the computer goes to sleep or into hibernation, data might not be sent. This is determined by your system’s connection settings.
  • Gateway configurations will remain intact whenever the agent is updated. However, if the agent is entirely uninstalled and a new version is installed, it returns to its default configuration.

Uninstalling the Agent


Navigate to Add or remove Programs, select the Atmosphere IoT Agent uninstall button, and follow the uninstaller instructions.


Remove the AppImage file from your system.


Navigate to Finder -> Applications and remove the Atmosphere IoT Application Bundle.

Alternatively, in Terminal, run rm -rf /Applications/Atmosphere\ IoT\