Sandbox
Sandbox makes testing energy apps simple and effective by providing access to virtual assets of any kind. This guide will help you understand Sandbox’s core features, its functionality, and how to use it to simulate real-world scenarios during application development.
Copy linkWhat is Sandbox?
Think of Sandbox as a virtual playground for your energy apps, where real-world physical assets are replaced with virtual assets you can control instantly.
Copy linkKey features
- Support for all asset types: Create and control vehicles, batteries, and other asset types
- Full state control: Modify asset states instantly to simulate real-world conditions. For example, you can simulate a vehicle’s battery reaching a specific level without waiting for a physical vehicle being charged to the required battery level
- Webhook integration: Monitor live updates and changes directly in the Sandbox UI
- Intervention simulations: Test interventions and their effects on assets in a controlled environment. For example, you can test scenarios where a vehicle loses location capabilities, affecting its ability to use smart charging
Copy linkWhy Sandbox?
Developing for energy devices is inherently challenging due to:
- Dependence on third-party hardware outside your control
- High costs and difficulties in accessing diverse device models for testing
- Delays caused by waiting for real-world devices to reach specific states
Sandbox helps with these challenges, enabling faster, cost-effective, and more reliable development.
Copy linkGetting started
Simply head to your Sandbox client in the customer dashboard and select Assets from the left-hand menu.
Copy linkCreating a new asset
In the Assets tab, click Create New
Select the asset type and vendor
Choose a model from the supported list
Add a display name to identify your asset
Lastly, decide whether to link the asset to a user:
- Linked: Links the asset to a specific or new user
- Not Linked: Allows you to test the linking flow manually via Link UI
Please note: You will find vendor credentials to use in Link UI by selecting the virtual asset in the virtual asset list.
Copy linkManaging assets
Copy linkAsset list
The Asset List displays all the assets on your Sandbox client. You can:
- Filter by asset type
- Search for assets by name or ID
Selecting an asset opens the Asset view, where you can:
Copy linkVirtual asset tab
This tab shows all virtual assets in your Sandbox client. Here, you can:
- Find virtual vendor credentials for linking
- See which assets are linked to a virtual asset
Copy linkAssets vs. virtual assets
In Sandbox, you interact with two key concepts – assets and virtual assets.
Copy linkAssets
Assets represent the linked entities accessible via the Enode API. For example, a vehicle object returned by the GET /vehicles request is an asset.
The concept and format of this entity are the same for the Sandbox and Production environment.
Copy linkVirtual assets
Virtual assets are virtual representations of real-world devices. Think of it as the actual car parked in the driveway of your end-user, only within the virtual Sandbox environment.
They allow you to:
- Simulate linking workflows
- Test edge cases like linking the same car to multiple users
Virtual assets exist only in the Sandbox environment, whereas assets in production are tied to real devices owned by end users.
Copy linkAsset view
The Asset view is your central hub for working with an asset.
Copy link1. Asset state
The main section of the asset view is the asset’s state. It follows the structure of the API response, e.g., GET /vehicles, and shows all fields of the asset’s state.
It updates in real-time based on webhook events or when editing fields.
Copy link2. Editing fields
Copy linkHow to edit a field
Click the Edit button next to a field, update the value in the dialog, and preview the resulting changes.
Copy linkOutput preview and side effects
Once you change the field's value via the input, the dialog displays a preview of the resulting asset state, including potential side effects.
When changed, most fields trigger secondary changes to other fields. For example, changing the powerDeliveryState of a vehicle from PLUGGED_IN:CHARGING to PLUGGED_IN:COMPLETE automatically sets isCharging to false.
Copy linkField descriptions
Each action is accompanied by a description giving you more context about the field and, where applicable, common scenarios about what can trigger a change of the field in the real world.
This information can be very valuable to gain a better understanding of how assets behave in reality.
Copy link3. Events feed
The asset view in Sandbox UI subscribes to webhook updates. So, any changes to the asset state made either by you, a colleague using the Sandbox UI on the same asset on another machine, or changes made using the API will automatically be received by your Sandbox UI instance and will be reflected in the asset’s state.
The Events Feed provides detailed information about the updates received for the asset:
- Webhook updates reflecting state changes.
- A record of actions performed on the asset.
This ensures you can associate every modification with its associated webhook.
By clicking on one of the webhooks in the feed you will have access to:
- A summary of all the fields that have updated
- The raw JSON body of the webhook
Copy linkTesting Actions
When you create an action in the API, Enode will attempt to execute that action on the device until it succeeds, fails (times out), or is cancelled.
In the real world, an action succeeds when the physical asset transitions to the desired state.
In Sandbox, you must manually change the virtual asset’s state to the desired outcome to simulate a successful action. This also allows you to test failure scenarios by letting the action time out or setting the asset to an unintended state.
For more details on different test cases, refer to our Sandbox testing guide.