What is OpenSync?

OpenSync™ is an open source software defined networking framework to reliably and dynamically deliver and modify programmable services at scale in CPEs and consumer networking devices. Learn more at https://opensync.io

Who is the author of OpenSync?

Plume Design, Inc. was the initial author. Before Plume contributed it to open source in 2018, it was called PML. Learn more at https://www.opensync.io/about

Who is the maintainer of OpenSync?

OpenSync maintenance is currently done by Plume Design Inc., in cooperation with main contributors and adopters.

Why does OpenSync use the ® sign?

OpenSync name is a registered trademark of Plume Design, Inc.

Is OpenSync software free?

OpenSync is licensed under the 3-clause BSD license and is therefore free software. The 3-clause BSD license is approved by the Open Source Initiative.

Which is the latest OpenSync version?

Latest releases are published on https://opensync.atlassian.net/wiki/spaces/OCC/pages/39920140289. Join our mailing list and confluence to be always up-to-date.

When is the next OpenSync release?

OpenSync releases one release every 12 months. Each release has three long-term versions (LTS) that can be integrated into CPEs or consumer networking devices. Each OpenSync release is stable for 2.5 years after which it is marked as end-of-life.

What is the difference between “mainline”, “stable”, and “longterm” releases?

1. Mainline - The latest stable release is marked as “mainline”. Although it has successfully exited its stabilization cycle, it is likely to be amended with “bugfix” releases.

2. Stable - Releases marked as “stable” typically already have a number of adopters, who use it in production. Additional “bugfix” or “maintenance” releases are less likely at this stage.

3. Long term - If a release is widely adopted, it may receive bug fixes for a longer period. Such releases are marked as “longterm” also known as long-term support branch (LTS).

Old releases are eventually ‘retired’ and are marked as “end-of-life”. Maintainers will not release any additional bug fixes for such releases. Adopters of existing integrations should consider moving to a newer stable release. No support will be provided for adopters wishing to create new integrations based on “end-of-life” releases.

What is a spike?

Before starting development efforts on a new feature with many unknowns, spike serves as an information gathering project. A spike does not include actual development work on the feature, but helps you estimate how much work the feature would require.

After a finished spike, you should know about the project requirements, limitations, testing scenarios, and potential introduction of new technologies or standards.

When can I send my contributions to OpenSync?

You can contribute to OpenSync anytime by following rules and workflows in https://opensync.atlassian.net/wiki/spaces/OCC/pages/39920566277 and they will be added into the current development release. In case you want to backporting changes into older release, best to reach out over info@opensync.io.

How can developers access the Git repositories?

OpenSync repositories are hosted on GitHub. Repositories and releases are also laid out in https://opensync.atlassian.net/wiki/spaces/OCC/pages/39920140289 .

What does OpenSync consist of?

OpenSync consists of multiple components. The following components are publicly available:

• core includes managers that transfer the southbound API calls (target layer) through northbound (OVSDB) API calls to the Cloud, where they are used by the services. Such approach enables adding new services without firmware upgrades. This component is common for all devices.

• platform includes a hardware abstraction layer, known as “target layer”. This layer is positioned between the OpenSync and the SoC. A platform component typically includes implementation for multiple chipsets of an SoC vendor (e.g., platform/qca).

• vendor provides templates and guidelines that guide the ODM/OEMs while implementing the device-specific functionalities by using the OpenSync overlay build system. This component is specific and unique per vendor and its devices.

• service-provider is intended to store cloud/service provider configuration such as redirector address, insecure back-haul settings and firmware profiles like development and production. Currently we provide service-provider-local and once you sign-up with one provider, they will provide you the new repository under service-provider directory.

NOTE: Some older SDK versions might require the sdk/overlay component to enable OpenSync for specific devices. Overlays are available per request on integration@opensync.io.

Which SoC platforms does OpenSync support?

OpenSync supports the following SoC platforms:

• Qualcomm

• Broadcom

• Mediatek

• Maxlinear

• Quantenna

• NXP

• Celeno

Additionally, SoC vendors compliant to the open-source RDK and OpenWRT SDK and target layer APIs are supported. SDK and driver versions can be seen in https://opensync.atlassian.net/wiki/spaces/OCC/pages/39920173106 or https://opensync.atlassian.net/wiki/spaces/OCC/pages/39920140289. If your platform is not listed here, please contact integration@opensync.io and let’s talk about how OpenSync can be supported on other SoC platforms.

Which SDK distributions support OpenSync?

OpenSync is available for:

• Qualcomm SDK

• Broadcom SDK

• RDK-B

• OpenWRT

Details can be also seen in https://opensync.atlassian.net/wiki/spaces/OCC/pages/39920173106 and in case your SDK is not labeled, it doesn’t that is not compatible but maybe you will need to adapt OpenSync or SDK overlay to your flavor of SDK and best that you also upstream those changes, so next OpenSync will include those changes.

We are working with chipset vendors to have OpenSync pre-integrated in some future SDKs. If you’d like to add to the list, write to info@opensync.io.

Which services or features are available in OpenSync?

All features per release can be found here: https://opensync.atlassian.net/wiki/spaces/OCC/pages/39920435205

What is the role of OVS in OpenSync?

OpenSync was created around the SDN concept, in which OVS represents the heart of the system. OpenSync expands the default set of OVSDB management tables with dedicated wireless and L3 networking tables. In addition to managing the networking features of devices, these tables enable the cloud to also manage the wireless features of devices.

How to connect the OpenSync enabled devices to the Cloud?

OpenSync uses the OVS database management protocol (OVSDB) for device provisioning and management. The OpenSync enabled devices can therefore be managed by any SDN controller using the OVSDB protocol. To connect your device to the cloud, we will provide a cloud environment for you if you are a certified partner. Please get in touch with us at info@opensync.io to know more.

How can an OpenSync integration be tested?

There are two level of testing and those are:

• OpenSync standalone/cloudless by using unit tests and FUT (everything is opensource)

• Service provider or end to end testing with cloud which requires test framework and test plan from your cloud provider.

Is there a community support group for the OpenSync on RDK-B?

RDK-B Central Wiki features section ‘How to integrate OpenSync onto a RDK-B platform’ where you can get tips to help you with your integration efforts.

Integration

Which OpenSync managers are mandatory?

OpenSync uses Kconfig framework and default settings already selects mandatory managers per platform.

How do the OpenSync managers load?

Diagnostics Manager (DM) goes over Kconfig configuration and start all managers which are enabled. Some 3rdparty services can be started or stopped in runtime by changing Node_Config table.

Wifi_Radio_Config  table updates, but Wifi_Radio_State does not. Why?

Generally speaking, config tables store the configuration we want to have on our devices, and state tables represent the current state of our devices. If config and state tables are out of sync, something went wrong during the configuration. This usually happens when calling various target API calls.  

If you change a value in the Wifi_Radio_Config table, and the change does not appear in the Wifi_Radio_State table, this means that the Wireless Manager (WM) did not apply the change successfully. As mentioned, this is an issue with target layer API integration.  

If FUT tests are failing because of this, this means that FUT is doing its job and that there's a bug in the implementation of the target API. The best way to continue is to try and debug why the WM is failing in applying the configuration set to the Wifi_Radio_Config table and review logs plus code.

Should the images folder be empty after a successful native target build?

The target = native does not build a complete x86 image. The image is only used for building certain debugging tools.   

The rest of the targets are cross-compiled inside the SDK. This is where a target is an abstraction that needs to be added inside the vendor makefile. The target takes proper BCM or QCA profiles and platform libraries, and produces the images.

How to work with files in the OpenSync ovsdb directory?

The OpenSync development team has added a suite of json files to the /ovsdb directory to propose how to pre-populate the OVSDB tables.

These json files are meant for adding the physical components that never change, such as radio, ethernet, etc. All other parameters are defined at runtime using the OpenSync managers or the cloud.

Which files are necessary to build OpenSync?

Each platform include reference board which you should use to compare with your device. Reference board uses all the necessary files needed for that platform.

How to complete the OpenSync build with core code only?

Best is to create the new target in your vendor directory and compare it with native target build. Select or deselect Kconfig options that you use stub or null implementation based on your requriments.

What are the OpenSync prerequisites for Broadcom-based devices?

All prerequisites are defined in SDK overlay package.

What is the required BCM SDK version for OpenSync builds?

https://opensync.atlassian.net/wiki/spaces/OCC/pages/39920173106 shows where OpenSync was stabilized and deployed. Any deviations requires an adaptation. It is your responsibility to adapt OpenSync or SDK overlay and upstream the changes to OpenSync.

How to synchronize OVSDB and TR-069/TR-181 data models?

OpenSync uses the OVSDB as provisioning and management protocol, the platform also provides an extension component. This component enables efficient management data synchronization using the existing interfaces (SNMP, TR-069, TR181, WEBUI, etc.) and resources.

The extension component consists of the OpenSync Exchange Manager (XM), and the connector library. These two together enable bi-directional data access and database synchronisation. For example, between OpenSync and TR-069.

Note: Take into account that many operators are moving away from TR-069 and similar management protocols, and directly use the OVSDB.

Clone the source code from:

• XM

• Connector library

Details are here https://opensync.atlassian.net/wiki/spaces/OCC/pages/39920140311/Requirements#External-DB-Integration

How do OpenSync managers trigger the get status?

OpenSync is using different methods for getting status which can be event driven or polling or one time. Best to review southbound implementation per platform or generic in core.

Is WAN interface required in the OVS br-wan bridge?

Not anymore. Dual bridge design is deprecated as part of OpenSync 2.2 release and we introduce WAN Operator (WANO) which configures WAN interfaces and routes with support of Network Manager (NM).

Are VLANs and PPPoE interfaces required in OVS br-wan bridge?

VLAN and PPPoE interfaces are now handled by WANO (OpenSync 2.2 and later). Because of this, br-wan bridge is not required. Furthermore, PPPoE interfaces cannot be bridged, so br-wan cannot be used in combination with PPPoE.

Which OVS tables are required?

All tables in the OVS schema are required. Some are used by OpenvSwitch internally, while the others are necessary for OpenSync features.

Which APIs in the Southbound API documentation are mandatory?

Similar to the Northound OVSDB API usage, some of the APIs can depend on the features (Kconfig) and platform. Mostly all southbound API’s are already implement based on reference board (core, platform, vendor). In case you have different API as reference board, then those has to be changed. Example is reading out your serial number.

How does an OpenSync device handle VLAN tags on WAN interface?

As a part of OpenSync, WANO can create VLANs based on the persistent configuration. In special cases, this can be changed using a dedicated WAN plug-in.

How does an OpenSync device handle PPPoE credentials on WAN interface?

Similar to VLANs, the PPPoE credentials are saved in persistent storage and can be configured to the device using Bluetooth (part of OpenSync 2.2 WANO). In newer releases, we provide also ability over OVSDB tables.

How does OpenSync use a single SSID for guest & home networks using a single password? Is Hostapd capable of this?

OpenSync can use multiple access zones to manage access privileges of the connecting devices. Each access zone is accessible using a unique set of keys (Wi-Fi passwords), any of which can be used to access the SSID. Please see https://opensync.atlassian.net/wiki/spaces/OCC/pages/39920140311/Requirements#Multi-psk for more details.

The feature is internally called MPSK (multi_PSK), where we can assign more than one key for one SSID. It is a function of hostapd. We created patches which have already been upstreamed to hostapd.

• https://w1.fi/cgit/hostap/commit/?id=b08c9ad0c78d2c767d62e1d169560debe8db0ce6

• https://w1.fi/cgit/hostap/commit/?id=ec5c39a5574d4fbee983ae659ea0834bf48ea14d

• https://w1.fi/cgit/hostap/commit/?id=83c8608132f5e4b756aaac2df6ab06f6776f6642

Setting the wireless key using ovsh succeeds, but reading the table back still shows the old key

This could mean that the key was not successfully applied on the driver. If you use hostapd, this usually indicates issues with hostapd config file, or loading the config hostapd file. Please share the information about the command and OVS tables used, and also provide the list of managers running on your device during this action, and logs.

What is the difference between _exists and _present in schema structure variables?

In OVSDB, the optional fields are allowed to have unset or empty values, so the C structures have additional flags to differentiate between an empty value (empty set) or a field not being present in the record.

Different flags are also used in different OVSDB operations:

• Receiving a modification update from OVSDB: OVSDB will only send update for the fields one subscribes to. In this case:

  • .X represents the parameter that contains the value (if present and exist - see bellow)

  • .X_present defines if the update contains the field .X_exists defines if the field value is set

  • .X_changed is set to true if the field value changed compared to the old value

NOTE: some macros automatically set the _postfix values

• Updating an OVSDB record:

  • If _partial_update is set to true, only the fields which are .X_present will be updated.

  • If the field has to be unset then .X_exists has to be set to false, otherwise .X_exists is set to true and value stored in X.

  • If ._partial_update is set to false, then ALL the fields are updated.

  In other words, these combinations are possible for partial updates:

  • .X_present=false : don't update field X

  • .X_present=true, .X_exists=false : unset field .X (set to an empty value - delete)

  • .X_present=true, .X_exists=true, .X=value : set field X to value

  struct schema_Netfilter set; memset(&set, 0, sizeof(set)); set._partial_update = true; SCHEMA_SET_INT(set.enable, enable); where = ovsdb_where_simple(SCHEMA_COLUMN(Netfilter, name), rule);

Is LED behavior defined for each state in the osp_led_state table, or is it up to the vendor to define LED behavior?

LED implementation falls under the ODM piece of the product and it is defined by customer requirement. OpenSync provides the framework to control and read status of LED within Platform Manager (PM).

If the device does not have a fan, should we still implement some of the osp_tm APIs to at least retrieve the temperature?

No. Reading of SoC or temperature sensor should be already cover in target_stats_device_temp_get implementation. Thermal module (Kconfig in PM) should be disabled on device where is not needed.

What is the purpose of the osp_dl_download API?

The purpose of the API is to download new firmware images. The API is available here.

Unable to run any daemon using GDB. What should I do?

For online and offline debugging, we usually rely on logs. We do analyze crash dumps with GDB and addr2line. In the past we did debug some issues with gdb-server and that used to work. However GDB or gdb-server are part of the SDK, not OpenSync.

Which redirector address should I use for my specific device?

Redirector is define by service-provider repository and it will select automatically based on firmware profile.

How to troubleshoot extender connectivity issues?

Perform these checks (using GRE):

1. Confirm that the values for backhaul interfaces in Wifi_VIF_Config and Wifi_VIF_State tables match.

2. Check Wifi_Inet_Config and Wifi_Inet_State tables to confirm that DHCP server is configured for backhaul interfaces.

3. Check the Wifi_Associated_Clients table to see if any backhaul clients appear connected. Row UUIDs from this table are listed in the Wifi_VIF_Config.associated_clients table for the VIF they are connected to.

4. Check DHCP leases to make sure the leases are showing up in OVSDB, and that a lease exists for the connected extender (DHCP_leased_IP).

5. Check the Wifi_Inet-Config table to see if the cloud inserted a pgdX-YYY interface to create a GRE tunnel. If an extender was assigned a DHCP lease of 169.254.3.5, look for pgd3-5.

6. Check tcpdump on the pgdX-YYY interface to look for DHCP requests, and then check on LAN bridge where pgdX-YYY is inserted to make sure it's also receiving DHCP request and that it responds to the Pod.

Band and Client Steering

What is the difference between band steering and client steering?

Band steering:

• Controlled by device

• Scenario is pre-assocation client connection

• It’s following the rules applied within Band_Steering_Config and Band_Steering_Clients

Client steering:

• Controlled by cloud/service provider

• Uses AI to define best option for that client

• Triggers action within Band_Steering_Config and Band_Steering_Clients

FUT

Does running FUT scripts require cloud connection?

FUT does not require any connection to the cloud, as the tests verify OpenSync implementation.

Is SSH access to the DUT necessary?

SSH management access (VLAN) to the device under test (DUT) is essential for FUT as well as for the OpenSync integration process in general. This is the default way to execute commands on devices.

Is CRATOS/OSRT necessary to run FUT?

https://opensync.atlassian.net/wiki/spaces/OCC/pages/39920140747 / OSRT is mandatory to run FUT.

Are any HW changes on OSRT/CRATOS supported?

The OSRT/CRATOS comes equipped with reference devices which are ready for executing of the FUT directly. To validate OpenSync integration on your devices, these devices will have to be used instead of the reference devices provided in OSRT/CRATOS.

Which modifications of the FUT are required to test my specific device?

Some of the device-specific config parameters should be adapted and maintained by the integrator. See the FUT User Manual for more details.

What are the FUT troubleshooting steps?

If you detect that your tests are not passing, use these steps to diagnose the cause of failures:

• Ensure your FUT test cases are configured correctly.
  Incorrect input parameters for test scripts cause testcase failures. 

• Ensure your device parameter values are correct.
  The device-specific configuration parameters are important for the entire OpenSync integration, regardless of the testing framework. The OpenSync device must interface with the testing framework and the cloud. Unexpected behavior can be a consequence of any misconfigured parameters.

• Identify if your testcase failures are caused by FUT misconfiguration or incorrect OpenSync integration.
  See the FUT User Manual for further debugging steps.

Where is FUT repository and documentation?

Repository is located here and documentation is in the same repository.

Cloud

How do OpenSync node connect to the cloud?

The OpenSync Connection Manager (CM) reads the redirector address (redirector_addr). After resolving the redirector address , it will update the manager address (manager_addr) and create connection to the cloud. Details can be found in the code.

How MQTT traffic is sent to the cloud?

In AWLAN_node table there are three set of fields mqtt_settings, mqtt_topics, mqtt_headers, where you configure MQTT settings on the OpenSync node. That would be grab by Queue manager (QM) and will push MQTT data to the MQTT subscriber. If you want to extend the MQTT, you need enhancements on both sides (OpenSync and cloud).

Cloud redirector does not respond. How can I check my SSL connection?

Compete the below steps to check your SSL connection in case of a non-responsive Cloud redirector.

1. Test the ssh connection from your computer. For example, run this command:

   curl -iv https://<redirector URL>

2. Observe what kind of error is reported. Does the redirector connection become active? If everything is ok, you should see the following status:

   This message indicates that you are able to reach the redirector and to establish the TCP connection.

   The connection might close due to the following reason:

   In this case, try handing over the certificate files to curl:

   When done, you should be able to establish the SSL connection. If the above steps are effective, repeat the steps for your specific device.

Which OVSDB tables are updated for OpenFlow? Which manager handles this process?

OpenFlow Manager (OM) manages all the OpenFlow operations and OVSDB tables are labeled in the code.

How does OpenSync propagate the changed settings?

OpenSync uses build-in OpenvSwitch functionality with OVSDB in case of native OpenSync implementation. So every internal/external process which can hookup to OVSDB, it will get notification or ability to change setting the northbound API. All OpenSync managers are hookup to OVSDB, so they propage from northbound to southbound and vice versa.

In case of hybrid solution (OpenSync plus other management system) there is ability to use eXchange Manager (XM). More can be found here.