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/
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
OpenSync maintenance is currently done by Plume Design Inc., in cooperation with main contributors and adopters.
OpenSync name is a registered trademark of Plume Design, Inc.
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.
Latest releases are published on Download OpenSync . Join our mailing list and confluence to be always up-to-date.
Next OpenSync releases are described in the Roadmap .
End of support occurs 2.5 years after the general availability (GA) release of OpenSync. After this period, no further support, patches, or code fixes will be provided, except for fixes related to critical security vulnerabilities.
End of life (EOL) is reached 3 years after the GA release of OpenSync. At this stage, no support, additional patches, or fixes will be provided, including those for critical security vulnerabilities.
You can contribute to OpenSync anytime by following rules and workflows in Contribute 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.
OpenSync repositories are hosted on GitHub. Repositories and releases are also laid out in Download OpenSync .
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 info@opensync.io.
Publicly available are the following SoC platforms:
Qualcomm
Broadcom
Mediatek
Maxlinear
Quantenna
NXP
Celeno
Additionally, SoC vendors compliant to the open-source RDK-B and OpenWRT SDK and target layer APIs are supported. SDK and driver versions can be seen in Check Compatibility or Download OpenSync. If your platform is not listed here, please contact info@opensync.io and let’s talk about how OpenSync can be supported on other SoC platforms.
OpenSync is available for:
Qualcomm SDK
Broadcom SDK
RDK-B
OpenWRT
Android
Details can be also seen in Check Compatibility 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.
All features per release can be found here: Feature Support Matrix
Some services or features might require special libraries, tools and licensing, and therefore cannot be part of the public OpenSync components. These services require various |
Open vSwitch offers a variety of features that OpenSync has utilized, particularly before the integration of Linux SDN. Currently, the primary focus of OVS in OpenSync is its role in supporting northbound APIs, which are managed through OVSDB for OpenSync management.
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.
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.
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.
OpenSync uses Kconfig framework and default settings already selects mandatory managers per platform.
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.
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.
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.
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.
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.
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 requirements.
All prerequisites are defined in SDK overlay package.
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:
Details are here https://opensync.atlassian.net/wiki/spaces/OCC/pages/39920140311/Requirements#External-DB-Integration
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.
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).
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.
All tables in the OVS schema are required. Some are used by OpenvSwitch internally, while the others are necessary for OpenSync features.
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.
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.
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.
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
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.
_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
_postfixvalues
#define SCHEMA_SET_STR(FIELD, VALUE) \
do { \
STRSCPY(FIELD, (VALUE)); \
FIELD##_exists = true; \
FIELD##_present = true; \
} while (0) |
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); |
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).
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.
osp_dl_download API?The purpose of the API is to download new firmware images. The API is available here.
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.
Redirector is define by service-provider repository and it will select automatically based on firmware profile.
Perform these checks (using GRE):
Confirm that the values for backhaul interfaces in Wifi_VIF_Config and Wifi_VIF_State tables match.
Check Wifi_Inet_Config and Wifi_Inet_State tables to confirm that DHCP server is configured for backhaul interfaces.
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.
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).
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.
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 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 not require any connection to the cloud, as the tests verify OpenSync implementation.
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.
OpenSync Reference Testbed (OSRT) or Comprehensive Reference Apparatus for Testing OpenSync (CRATOS) is mandatory to run FUT.
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 provided OSRT/CRATOS reference devices.
Some of the device-specific config parameters should be adapted and maintained by the integrator. See the FUT User Manual for more details.
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.
Repository is located here and documentation is in the same repository.
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.
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).
Compete the below steps to check your SSL connection in case of a non-responsive Cloud redirector.
Test the ssh connection from your computer. For example, run this command:
curl -iv https://<redirector URL> |
Observe what kind of error is reported. Does the redirector connection become active? If everything is ok, you should see the following status:
Connected to <redirector URL> (12.345.333.333) port 443 (#0) |
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:
SSL certificate problem |
In this case, try handing over the certificate files to curl:
curl -iv --cacert </path/to/ca.pem> --cert </path/to/client.pem> --key </path/to/client.key> https://<redirector URL> |
When done, you should be able to establish the SSL connection. If the above steps are effective, repeat the steps for your specific device.
OpenFlow Manager (OM) manages all the OpenFlow operations and OVSDB tables are labeled in the code. OpenFlow is deprecated with introduction of Linux SDN.
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.
There are two connections to the cloud: OVSDB (for management) and MQTT (for statistics or events). We leverage their built-in technologies, and you can learn more through the following resources: