MEC Sandbox Help: Difference between revisions
No edit summary |
|||
Line 5: | Line 5: | ||
== MEC Sandbox Concepts & Usage == | == MEC Sandbox Concepts & Usage == | ||
An introduction to MEC Sandbox concepts and usage were presented in a webinar (February 2021). | An introduction to MEC Sandbox concepts and usage were presented in a webinar (February 2021). The recording and related Q&A are available here: | ||
The recording and related Q&A are available here: | |||
* [https://www.etsi.org/events/1869-2021-01-webinar-getting-started-with-the-etsi-mec-sandbox MEC Sandbox Webinar] | * [https://www.etsi.org/events/1869-2021-01-webinar-getting-started-with-the-etsi-mec-sandbox MEC Sandbox Webinar] | ||
* [https://mecsandbox.slack.com/archives/C01NBU36DU4 Q&A] | * [https://mecsandbox.slack.com/archives/C01NBU36DU4 Q&A] |
Revision as of 22:07, 16 February 2021
Platform Concepts
MEC Sandbox is an interactive environment that enables users to learn & experiment with ETSI MEC Service APIs. These standardized RESTful APIs are targeted towards MEC application developers to expose the value added services offered by MEC, including real time access to network and context information, as well as location awareness. The design principles for developing the APIs have also been specified in ETSI GS MEC 009, along with http methods, templates, conventions and patterns. The MEC service APIs are available in YAML and JSON format at https://forge.etsi.org, presented via OpenAPI compliant descriptions.
MEC Sandbox provides the user with a choice of scenarios combining different network technologies (4G, 5G, Wi-Fi) and terminal types. Combining these assets in a geolocated environment, a user can gain hands-on experience on the behavior and capabilities of the Location (MEC013), Radio Network Information (MEC012) and WLAN Information (MEC028) service APIs. Such contextual information can offer significant differential performance for edge based MEC applications.
MEC Sandbox Concepts & Usage
An introduction to MEC Sandbox concepts and usage were presented in a webinar (February 2021). The recording and related Q&A are available here:
To access the Q&A users must first join the MEC Sandbox Discussion Board.
Web UI
MEC Sandbox Portal is a single page web application that provides an interactive interface; once signed in, it allows a user to experiment with an individual sandbox.
Home Page The home page provides:
|
|
Sandbox Dashboard When a user signs in, the MEC Sandbox creates the necessary backend resources and opens a user-specific sandbox dashboard that allows to:
In both cases, MEC Sandbox APIs respond according to the current state of the network scenario. More details about the MEC Sandbox UI are provided in the platform usage section of this wiki. |
Terminology
Point of Access (POA)
A point of attachment to access a network; MEC Sandbox networks supports 4G, 5G and WiFi POAs.
- Each POA has coverage range within which a terminal may attach to the network.
- The PoA range is represented by a circle and its the range varies depending on the network technology
- Both the PoAs and their associated range can be shown or hidden by selecting the appropriate layers on the map.
User Equipment (UE) / Terminal Device
A end user devices equipped with a wireless radio that allows to connect to a PoA.
- MEC Sandbox supports three types of UEs; stationary, low-velocity and high-velocity
- UE types are described in more detail in this wiki section.
- Number of UEs present in a scenario can be configured
- Each UE has an associated velocity and path that defines how they move on the map; these are fixed in a scenario.
- UEs have their preferred access network types with their preferred order of connection
- Preferred connectivity order is (1) WiFi, (2) 5G and (3) 4G
- The default UE behavior is to remain connected to a POA as long as it is in range unless a higher priority network access becomes available.
Zone
A zone is a logical grouping of one or more PoAs, irrespective of their wireless technologies.
- On the map, zones are represented by using color coding.
- The definition of zones help structure the network.
- MEC Location Service (MEC013) can be used to discover zones or UEs present in a zone.
Network Scenario
A simulated network of geo-located UEs and POAs that are grouped in Zones.
- One network scenario can be deployed at a time in a MEC Sandbox instance.
- At any time a user can terminate a scenario or select a new one without requiring to re-create a new sandbox.
- While a network scenario is deployed, requests can be sent to the MEC Service APIs which will return a response
- MEC Services may also generate notifications depending on the subscriptions created by the user
- Both responses and notifications reflect the state of the network at the moment they were generated
Network Scenarios
Networks
MEC Sandbox provides the following simulated networks
4G Macro Network
|
4G-WiFi Macro Network
|
4G-5G-WiFi Macro Network
|
UE Types
UEs are divided into the following categories:
Stationary UE
|
Low Velocity UE
|
High Velocity UE
|
NOTE: The number of UEs in a network scenario is dynamically configurable, however the positions and paths are the same for all scenarios.
MEC Services
MEC012 - Radio Network Information Service (RNIS)
MEC Sandbox supports version v02.01.01 of the MEC012 specification, available on ETSI website
RNIS provides cellular radio network information to edge applications, such as:
- Radio network conditions
- Measurements related to user plane
- Information about UEs connected to the radio network (context, Radio Access Bearers (RAB))
- Notification events such as cell change, RAB establishment and RAB release
MEC Sandbox supports a subset of RNI API endpoints and subscription types; for more details on the supported endpoints access the SwaggerUI client in a MEC Sandbox.
MEC013 - Location Service
MEC Sandbox supports version v02.01.01 of the MEC013 specification, available on ETSI website
Location Service provides geospatial and network location information to edge applications, such as:
- Location information related to user and zones
- Notification events such as user tracking, zonal status or traffic
MEC Sandbox supports a subset of the Location API endpoints and subscription types; for more details on the supported endpoints access the SwaggerUI client in a MEC Sandbox.
MEC028 - WLAN Access Information Service (WAIS)
MEC Sandbox supports version v02.01.01 of the MEC028 specifications, available on ETSI website
WAIS provides WLAN radio network information to edge applications, such as:
- Access point conditions
- Information about terminals connected to the network
- Notification events such as terminal connectivity
MEC Sandbox supports a subset of the WAI API endpoints and subscription types. for more details on the supported endpoints access the SwaggerUI client in a MEC Sandbox.
Usage
The following section provides MEC Sandbox usage guidelines.
Sign In
The MEC Sandbox home page provides a Sign In button to initiate a user session. When clicked, the user is prompted to authenticate with one of the following external OAuth 2.0 providers:
To successfully sign in to the MEC Sandbox, the user must have a valid account with one of the above providers, must successfully sign in, and must accept an authorization request for access to public profile information. Once signed in and after successful backend resource allocation, the user is redirected to the MEC Sandbox dashboard. NOTE: External OAuth provider login and authorization may be seamless if they have already been performed |
MEC Sandbox Dashboard
The dashboard is the main screen of the MEC Sandbox; it is divided in 4 main areas that are explained below:
- Map area: Observe physical assets on the map
- Configuration area: Select networks and UEs
- API Console: Investigate MEC API communication
- Try-it area: Details about accessing MEC Service APIs
Map AreaMap area allows to observe the location of different assets; it provides the following information and capabilities:
|
|
Configuration areaConfiguration area allows dynamic configuration of the MEC Sandbox; it provides the following capabilities:
|
|
API ConsoleAPI console displays a table of real-time requests and notifications that the MEC Service APIs receive and generate. The table provides a summary of the communication messages, including type (request/notification), service involved, endpoint, HTTP method, time and response code. Requests are HTTP messages received by the MEC Service
Notifications are HTTP message sent by the MEC Service
|
|
Try-it areaTry-it area provides information on how to access a specific MEC Service API in the MEC Sandbox; a drop down allows to select the desired MEC API. Note: MEC Services are always running (from MEC Sandbox creation); selecting a MEC API only changes the displayed information in the dashboard Try-it in the browser allows to launch a SwaggerUI client for the selected MEC API; from the client a user can send requests to the MEC Services. Try-it from your MEC application provides the link to use to reach the selected MEC API from an external application. Note: the provided link needs to be provisioned in an application client to access the MEC Service running in the sandbox. |
Swagger UI
The Swagger UI client is a powerful tool to learn about MEC APIs as it provides curated & browsable information about the API endpoints - but it also serves as an API client allowing to send requests and observe responses.
The figure on right shows Swagger UI for the MEC Location Service.
|
|
The figure on right shows the documentation details available at the endpoint level:
|
|
The figure on right shows how a request can be sent to the MEC service running in the MEC Sandbox. After clicking
|
MEC Application
MEC Application developers can access MEC Services running in the MEC Sandbox using the base path URL provided in the Try-it
area of the Sandbox dashboard. This link routes requests for the selected MEC API to a specific user sandbox.
NOTE: Any external application or process with HTTP client capabilities and access to the MEC Sandbox can be used to send requests to the MEC Services (for example curl)
MEC applications must use the provided link as a base path for API requests and must append the desired endpoint path. MEC applications must also provide path, query and body parameters when necessary. For more details on the supported endpoint paths and parameters, access the Swagger UI client in a MEC Sandbox.
For notification subscriptions, MEC applications must provide notification URLs where MEC Service notifications should be sent. If a notification URL points to a publicly accessible endpoint, the API Console will show the request and response data and codes; otherwise, the request will fail and the API console will display a 500 Internal error.
Examples
This section provides some common usage examples.
SubscriptionsThe subscription endpoints available in each service are used to register for specific event notifications. To subscribe for event notifications, a user may use the provided Swagger UI Try it out feature or may directly post a subscription request from a MEC application. In both cases, the subscription request body must contain the following:
A successful subscription response includes the following:
The resource URL contains a unique subscription identifier that must be provided when updating or deleting a subscription. |
Location Subscriptions
To register for user location change events, set the following subscription request body:
{ "userTrackingSubscription": { "clientCorrelator": "0123", "callbackReference": { "notifyURL": "http://my.callback.com/location-user-tracking/some-id" }, "address": "10.100.0.1", "userEventCriteria": [ "Entering", "Leaving", "Transferring" ] } }
A successful response for the above subscription request creates a new subscription with and ID of '2', as shows in the following response body:
{ "userTrackingSubscription": { "address": "10.100.0.1", "callbackReference": { "notifyURL": "http://my.callback.com/location-user-tracking/some-id" }, "clientCorrelator": "0123", "resourceURL": "https://try-mec.testfqdn.dev/sbx123456/location/v2/subscriptions/userTracking/2", "userEventCriteria": [ "Entering", "Leaving", "Transferring" ] } }
RNI & WAI Subscriptions
The same subscription procedure applies for RNIS and WAIS, with the exception of the resource URL response format. The subscription identifier can be found at the following location:
{ "_links": { "self": { "href": "https://try-mec.testfqdn.dev/sbx123456/rni/v2/subscriptions/1" } }, ... }
MEC013 Location API Common Examples
User Tracking
Track UE 10.100.0.1 as it moves across PoAs & zones:
{ "userTrackingSubscription": { "callbackReference": { "notifyURL": "http://my.callback.com/location_notifications/userTracking" }, "address": "10.100.0.1", "userEventCriteria": [ "Entering", "Leaving", "Transferring" ] } }
A ZonalPresenceNotification notification will be sent when UE 10.100.0.1 does the following:
- Enters a new zone
- Leaves its current zone
- Attaches to a different PoA within the same zone
NOTE: If a UE switches from a PoA in one zone to a PoA in a different zone, then 2 separate notifications are sent, one for leaving the old zone and another for entering a new zone.
Zonal Traffic
Track all UE location changes within zone01:
{ "zonalTrafficSubscription": { "callbackReference": { "notifyURL": "http://my.callback.com/location_notifications/zonalTraffic" }, "zoneId": "zone01", "userEventCriteria": [ "Entering", "Leaving", "Transferring" ] } }
A ZonalPresenceNotification notification will be sent when any UE does the following:
- Enters zone01
- Leaves zone01
- Attaches to a different PoA within zone01
Zonal Status
Track UE number thresholds within zone01:
{ "zoneStatusSubscription": { "callbackReference": { "notifyURL": "http://my.callback.com/location_notifications/zonalStatus" }, "zoneId": "zone01", "numberOfUsersAPThreshold": 2, "numberOfUsersZoneThreshold": 3 } }
A ZoneStatusNotification notification will be sent on every change in UE connection count in zone01 where:
- Number of UEs attached to a single PoA is greater than or equal to 2
- Number of UEs in zone is greater than or equal to 3
MEC012 RNI API Common Examples
Cell Change
Track UE 10.100.0.1 cell changes:
{ "subscriptionType": "CellChangeSubscription", "callbackReference": "http://my.callback.com/rni/cellChange", "filterCriteriaAssocHo": { "associateId": [ { "type": 1, "value": "10.100.0.1" } ], "ecgi": [ { "plmn": { "mnc": "001", "mcc": "001" }, "cellId": "1010101" } ] } }
A CellChangeNotification notification will be sent when UE 10.100.0.1 does the following:
- Moves from a 4G PoA to another 4G POA with cell ID 1010101, MNC 001 & MCC 001
- Moves from a 4G PoA with cell ID 1010101, MNC 001 & MCC 001 to another 4G POA
NOTE: Moving between a 4G and a non 4G POA will not trigger a cell change notification.
RAB Establishment
Track UE connections to cell ID 1010101:
{ "subscriptionType": "RabEstSubscription", "callbackReference": "http://my.callback.com/rni/rabEst", "filterCriteriaQci": { "ecgi": [ { "plmn": { "mnc": "001", "mcc": "001" }, "cellId": "1010101" } ], "qci": 80 } }
A RabEstNotification notification will be sent when any UE does the following:
- Moves from a non 4G PoA to a 4G PoA with cell ID 1010101, MNC 001, MCC 001 & QCI 80
NOTE: MEC Sandbox currently uses a constant QCI value of 80.
RAB Release
Track UE disconnections from cell ID 1010101:
{ "subscriptionType": "RabRelSubscription", "callbackReference": "http://my.callback.com/rni/rabRel", "filterCriteriaQci": { "ecgi": [ { "plmn": { "mnc": "001", "mcc": "001" }, "cellId": "1010101" } ], "erabId": 6, "qci": 80 } }
A RabRelNotification notification will be sent when a UE with an Erabid of 6 does the following:
- Moves from a 4G PoA with cell ID 1010101, MNC 001, MCC 001 & QCI 80 to a non 4G PoA
NOTE: A new ErabId is allocated every time a UE connects to a 4G POA and stays unchanged until the UE disconnects from any 4G POA. The RAB Release notification can therefore only be seen once. The ECGI is an optional parameter, omitting it will allow less constraints on the conditions to see the notification.
MEC028 WAI API Common Examples
Associated Stations
Track stations associated to Wifi PoA with MAC ID 005C02020202:
{ "subscriptionType": "AssocStaSubscription", "callbackReference": "http://my.callback.com/wai/assocSta", "apId": { "macId": "005C02020202" } }
A AssocStaNotification notification will be sent when any UE does the following:
- Connects to a Wifi PoA with MAC ID 005C02020202;
- Disconnected from a Wifi PoA with MAC ID 005C02020202;
Discussion Board (Slack channels)
MEC Sandbox questions, feedback and discussions are tracked using slack channels in the MEC Sandbox Slack Workspace. The workspace is available here: New users first need to join the MEC Sandbox slack workspace by creating a new account using the invitation link provided here: |
Reporting Issues
MEC Sandbox issues are tracked using ETSI's bug-tracking system Bugzilla. The issue database is available here: Users with an EOL account may report issues directly in the issue database. All other users should report issues using the MEC Sandbox Discussion Board. |