Environment Variables
Environment variables are key-value pairs that are injected into every skill container running on a device. They allow skills to access device identity, configuration, and portal information at runtime without hardcoding those values into the skill image.
How environment variables work
There are two types of environment variables on Optra Edge devices:
- System variables — Automatically provided by the portal for every device. These are read-only and always present.
- Custom variables — Defined by you in the device Settings tab (or at the skill level). These override skill-level variables when the same key is used at both levels.
Override priority (highest to lowest):
Device-level custom variables → Skill-level variables → System defaults
System environment variables
The following variables are automatically injected into every skill on the device. You do not need to define these — they are always available.
| Variable | Description |
|---|---|
OPTRA_SERIAL_NUMBER | The device's 13-character serial number (uppercase) |
OPTRA_DEVICE_ID | The IoT module device ID used by the portal |
OPTRA_DEVICE_NAME | The device's display name as configured in the portal |
OPTRA_DEVICE_MODEL | The device model identifier (e.g., vz6100, cx2000) |
OPTRA_DEVICE_FIRMWARE_VERSION | The firmware version currently running on the device |
OPTRA_DEVICE_IP | The device's current IP address |
OPTRA_DEVICE_MAC | The device's MAC address |
OPTRA_DEVICE_SIGNATURE | A device-specific signature string |
OPTRA_DEVICE_TIMEZONE | The timezone of the device's assigned location (e.g., America/New_York). Defaults to UTC if no location is set. |
OPTRA_API_URL | The Optra portal API endpoint URL |
TZ | Same value as OPTRA_DEVICE_TIMEZONE. Sets the system timezone for the container. |
Custom environment variables
You can define custom key-value pairs to pass additional configuration to your skills. These are set in the Settings tab of the device detail view.
Adding custom variables
- Open the device detail view and click the Settings tab.
- Scroll to the Environment Variables section.
- Add a key and value for each variable.
- Click Save.
Key restrictions
Custom environment variable keys must follow these rules:
- Must not contain
.(period) - Must not contain
$(dollar sign) - Must not contain
#(hash) - Must not contain spaces
Invalid characters are rejected when you save.
Use cases
| Use case | Example |
|---|---|
| Point a skill to a local resource | API_ENDPOINT=http://192.168.1.50:8080 |
| Override a skill default | DETECTION_THRESHOLD=0.75 |
| Pass site-specific metadata | SITE_NAME=Warehouse-A |
| Configure a skill connection string | MQTT_BROKER=mqtt://broker.local:1883 |
If the same variable key is defined both at the device level and at the skill level, the device-level value takes precedence. This makes device-level variables useful for site-specific overrides of shared skill configurations.
Environment variables vs. skill inputs
Skill inputs are the preferred way to configure a skill when the configuration is workflow-specific. Use device-level environment variables when:
- You need a value to apply to all skills on a device, not just one.
- The value is device-specific (e.g., a local IP address or a site code).
- You want to override a skill's default without modifying the skill or workflow configuration.