Building OpenSync with OpenWrt DATE: December 23, 2019 Document number: 019-1223-31 Table of Contents Introduction 3 OpenSync on OpenWrt Platforms 4 Requirements 4 Integration Steps 5 Preparing the vendor repository 5 vendor-arch.mk 5 CERTIFICATES_PLACEHOLDER 5 target_ARMVIRT.h 5 “src” directory with C source code 5 Choosing the OpenWrt SDK 6 Customizing the build procedure for the OpenSync package 6 Deploying the Example ARMVIRT Target to QEMU 7 Vendor Layer 8 Creating Custom OpenWrt Targets 8 References [1] https://www.opensync.io/documentation/ ​ 2/8 Introduction OpenSync™ is a platform for building software defined networks (SDN). SDNs allow service ​ providers to virtualize network management along with wireless functions. This simplifies their service roll-out. Figure 1: OpenSync block diagram ​ Target layer is an adaptation layer that binds OpenSync managers with low-level SoC/Linux ​ drivers. We refer to the OpenSync compatible devices as targets. ​ ​ There are many different target layer flavors, which can be specific to a particular platform ​ ​ such as RDK or OpenWrt. The scope of this document is vanilla OpenWrt integration. For more information on OpenSync visit https://opensync.io. ​ ​ For more information on OpenWrt, visit https://openwrt.org. ​ ​ 3/8 OpenSync on OpenWrt Platforms The OpenSync OpenWrt meta-project includes components that allow you to create OpenSync ​ ​ ​ packages on OpenWrt based platforms. The OpenWrt meta-project includes: ● opensync/core OpenSync core repository, see OpenSync repository. ​ ​ ​ ​ ​ ● opensync/platform This component implements a common part of the target layer for OpenWrt-based platforms. The opensync/platform component also includes the OpenSync feed for ​ ​ OpenWrt. The repository is available online under the name opensync-platform-openwrt. ​ ​ ● opensync/vendor This repository provides all vendor-specific code, certificates, configuration files, etc. Vendor (Platform integrator) creates and maintains this component. OpenSync comes ​ ​ with a vendor repository template based on QEMU ‘armvirt’ target, available at GitHub under the name opensync-vendor-armvirt. More on customizing that repository template ​ ​ can be found in the following sections. ● Feeds ○ feeds/network/services/opensync/Makefile OpenWrt makefile for the OpenSync ​ ​ build ○ feeds/lang/python/python3-kconfiglib/Makefile OpenWrt makefile for the host-side kconfiglib dependency build Requirements To build OpenSync with OpenWrt, you need the OpenWrt SDK. Download the OpenWrt SDK ​ ​ and complete the below listed integration steps. Requirement: Download OpenWrt SDK and follow the Integration Steps ​ ​ ​ ​ 4/8 Integration Steps Preparing the vendor repository The content of opensync-vendor-armvirt repository is listed below. Vendor (platform integrator) ​ is obliged to modify files in this repository. The necessary modifications for each file are briefly explained below the listing. ├── LICENSE ├── NOTICE ├── README.md ├── build │ └── vendor-arch.mk ├── ovsdb​ │ └── static_configuration.json ├── rootf​s │ └── common │ └── usr │ └── plume │ └── certs │ └── CERTIFICATES_PLACEHOLDER └── src ​ └── lib └── target ├── inc │ └── target_ARMVIRT.h ├── over​ride.mk └── src └── entity.c ​ vendor-arch.mk This file is an element of OpenSync build system. The file enables/disables and configures ​ ​ builds for specific targets. When creating or modifying a new target, change all “armvirt/ARMVIRT” occurrences to the actual target name. ​ CERTIFICATES_PLACEHOLDER Replace files in rootfs/common/usr/plume/certs with appropriate certificates that allow the device to connect to the OpenSync cloud. For more information on how to obtain the certificates ​ ​ contact Plume. target_ARMVIRT.h Rename “target_ARMVIRT.h” to “target_<TARGET>.h”. “src” directory with C source code As mentioned above, you must implement a small Target API subset in the vendor component. ​ The opensync-vendor-armvirt comes with bare minimum that must be implemented to bring-up ​ 5/8 OpenSync connectivity. Use the entity.c file to implement the functions related to the model ​ identifications. Read more about the target layer APIs for the required OpenSync and OpenWrt structures in ​ the target (southbound) API document [1]. ​ ​ Choosing the OpenWrt SDK Let's suppose the package must be built for 18.06.4 OpenWrt on 32 bit armvirt target. The first step is to find an OpenWrt SDK file for that version and architecture. 1. Open https://downloads.openwrt.org/releases/ and navigate to 18.06.4 -> targets -> ​ ​ armvirt -> 32. ​ 2. Under "Supplementary Files", locate the openwrt-sdk-*.tar.xz file and copy the link to ​ that file: NOTE: You can also use search to locate the relevant file for your target. Customizing the build procedure for the OpenSync package ​ ​ OpenSync uses the standard OpenWrt package build procedure. Complete these steps: ​ 1. Add python3-kconfiglib to feeds.conf (build-time dependency): ​ ​ ​ ​ echo "src-link kconfiglib <path-to-this-repo>/feeds/lang" >> feeds.conf 2. Add the opensync feed to feeds.conf: ​ ​ 6/8 echo "src-link opensync <path-to-this-repo>/feeds/network" >> feeds.conf 3. Update and install the feeds: ./scripts/feeds update -a ./scripts/feeds install -a 4. To build the package, specify the following parameters: ​ package/opensync/compile OPENSYNC_SRC=<path-to-this-repo> TARGET=<target> See also the example/ directory for an ARMVIRT example. ​ ​ Deploying the Example ARMVIRT Target to QEMU Complete these steps to deploy the example package to QEMU: 1. Install qemu-system-arm. If you are using Ubuntu, run: ​ ​ sudo apt-get install qemu-system-arm 2. Assuming that you are using the 18.06.4 OpenWrt package, and 32-bit armvirt target, navigate to https://downloads.openwrt.org/releases/18.06.4/targets/armvirt/32/. ​ 3. See the Image Files section. Locate the zImage-initramfs image and copy the link ​ ​ to that file. 7/8 4. Next, run the following command (using the above link): make start_qemu IMAGE_URL=<URL_TO_ZIMAGE> Subsequent uses will not require the IMAGE_URL parameter. ​ ​ 5. Start the QEMU console with the internet connectivity setup. 6. From another terminal push the OpenSync ipk package to the /tmp directory, for ​ example: scp -o StrictHostKeyChecking=no \ out/opensync_1.0-1_arm_cortex-a15_neon-vfpv4.ipk \ [email protected]:/tmp 7. Get back to the QEMU console, and run the following commands: opkg update cd /tmp opkg install opensync_1.0-1_arm_cortex-a15_neon-vfpv4.ipk This installs and starts OpenSync. The logs can be dumped using logread, and OVSDB tables ​ ​ ​ ​ can be inspected using ovsh. ​ ​ Vendor Layer The vendor layer is a place for vendor specific utilities and configuration. Typically it contains utility scripts and certificates. Certificates allow the device to connect to the OpenSync cloud. ​ Contact Plume for more information on how to obtain the certificates. Creating Custom OpenWrt Targets To create a new target, it is best to use the vendor/armvirt tree as a template. ​ ​ Follow these steps for the basic bring-up of a new target: 1. Copy vendor/armvirt to vendor/<new_target> ​ ​ ​ 2. Modify build/vendor-arch.mk, replacing “ARMVIRT” and “armvirt” with the new name ​ ​ 3. Rename and adjust vendor/<new_target>/src/lib/target/inc/target_<new_target>.h ​ 4. Modify vendor/<new_target>/src/lib/target/entity.c so that the functions return ​ ​ the correct model name, id, etc. 5. Modify vendor/<new_target>/ovsdb/static_configuration.json according to ​ ​ actual Wi-Fi radios configuration 6. Copy certificates to vendor/<new_target>/rootfs/common/usr/plume/certs/ ​ 8/8 .