{"id":27940727,"url":"https://github.com/telecominfraproject/wlan-cloud-ucentralgw","last_synced_at":"2025-12-25T08:37:14.603Z","repository":{"id":37508726,"uuid":"355272747","full_name":"Telecominfraproject/wlan-cloud-ucentralgw","owner":"Telecominfraproject","description":null,"archived":false,"fork":false,"pushed_at":"2025-05-02T15:40:32.000Z","size":19957,"stargazers_count":26,"open_issues_count":3,"forks_count":42,"subscribers_count":69,"default_branch":"master","last_synced_at":"2025-05-07T10:19:56.825Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Telecominfraproject.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-04-06T17:19:37.000Z","updated_at":"2025-04-24T20:56:13.000Z","dependencies_parsed_at":"2022-07-14T04:20:33.174Z","dependency_job_id":"41ec2c42-7ce2-45ce-8912-78873120b8e5","html_url":"https://github.com/Telecominfraproject/wlan-cloud-ucentralgw","commit_stats":null,"previous_names":[],"tags_count":86,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Telecominfraproject%2Fwlan-cloud-ucentralgw","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Telecominfraproject%2Fwlan-cloud-ucentralgw/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Telecominfraproject%2Fwlan-cloud-ucentralgw/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Telecominfraproject%2Fwlan-cloud-ucentralgw/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Telecominfraproject","download_url":"https://codeload.github.com/Telecominfraproject/wlan-cloud-ucentralgw/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252856711,"owners_count":21814881,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-05-07T10:20:04.511Z","updated_at":"2025-12-25T08:37:14.546Z","avatar_url":"https://github.com/Telecominfraproject.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n    \u003cimg src=\"images/project/logo.svg\" width=\"200\" alt=\"OpenWiFi Project\"/\u003e\n\u003c/p\u003e\n\n# OpenWiFI Gateway (OWGW)\n\n## What is it?\nThe OpenWiFi Gateway is a service for the TIP OpenWiFi CloudSDK (OWSDK). \nOWGW manages Access Points that implement the OpenWiFi uCentral protocol. OWGW, like all other OWSDK microservices, is\ndefined using an OpenAPI definition and uses the ucentral communication protocol to interact with Access Points. To use \nthe OWGW, you either need to [build it](#building) or use the [Docker version](#docker).\n\n## Building\nTo build the microservice from source, please follow the instructions in [here](./BUILDING.md)\n\n## Docker\nTo use the CLoudSDK deployment please follow [here](https://github.com/Telecominfraproject/wlan-cloud-ucentral-deploy)\n\n#### Expected directory layout\nFrom the directory where your cloned source is, you will need to create the `certs`, `logs`, and `uploads` directories.\n```bash\nmkdir certs\nmkdir certs/cas\nmkdir logs\nmkdir uploads\n```\nYou should now have the following:\n```text\n--+-- certs\n  |   +--- cas\n  +-- cmake\n  +-- cmake-build\n  +-- logs\n  +-- src\n  +-- test_scripts\n  +-- openapi\n  +-- uploads\n  +-- owgw.properties\n```\n\n### Certificates\nThe OWGW uses a number of certificates to provide security. There are 2 types of certificates required for \na normal deployment:\n- A Server Certificate to secure the OWGW\u003c-\u003eAP channel\n- A REST API Certificate to secure the Northbound API\n- Device Certificates\n\n#### The `certs` directory\nFor all deployments, you will need the following certs directory, populated with the proper files.\n\n```text\ncerts ---+--- root.pem\n         +--- issuer.pem\n         +--- websocket-cert.pem\n         +--- websocket-key.pem\n         +--- clientcas.pem\n         +--- +cas\n         |    +--- issuer.pem\n         |    +--- root.pem\n         +--- restapi-ca.pem\n         +--- restapi-cert.pem\n         +--- restapi-key.pem\n```\n\n#### DigiCert files\nThese are the files you should install on your OWGW and devices. For your OWGW, you will need to provide tge following files in the directory above\n- `root.pem` is [here](https://github.com/Telecominfraproject/wlan-cloud-ucentralgw/blob/main/certificates/root.pem).\n- `issuer.pem` is [here](https://github.com/Telecominfraproject/wlan-cloud-ucentralgw/blob/main/certificates/issuer.pem).\n- `clientcas.pem` is [here](https://github.com/Telecominfraproject/wlan-cloud-ucentralgw/blob/main/certificates/clientcas.pem).\n\n#### OWGW Server certificate (must be obtained from TIP)\nThe gateway requires its own DigiCert certificate. Once obtained, you need to identify the `key` and the `certificate` rename\nthem `websocket-key.pem` and `websocket-cert.pem`, and copy them in your `certs` directory. These files mus be obtained from TIP.\n\n#### OWGW for certificate: for REST API (from your favourite Certificate Provider)\nThe gateway requires a key/certificate/ca for the REST interface. These files you need to obtain on your own or generate them. This is beyond the scope of this \ndocument. You, may choose to select LestEncrypt or any other Certificate Authority. Once you have these files, you need to renamed them `restapi-key.pem`, `restapi-cert.pem`, and `restapi-ca.pem`. \nThis will guarantee proper HTTPS in your browser and RESTAPI. \n\n### OpenWiFi Device certificates\nThis may have already done at the factory. If not, you will need to get the following in order to point your devices to use the OWGW:\n- A DigiCert certificate that you will call `cert.pem`\n- A DigiCert key that goes with that certificate. Please call this `key.pem`\n- The Digicert root certificate that you will find [here](https://github.com/Telecominfraproject/wlan-cloud-ucentralgw/blob/main/certificates/root.pem). You must copy `root.pem`\n  and rename it `cas.pem` on the device.\n- A Device ID file called `dev-id` or something similar\n- Copy all the 4 files to the `/certificates` directory of the AP (you must have firmware created Jun 15th or later).\n\nYou will need to upgrade your device to the latest firmware. Once updated, you will need to copy the 4 files mentioned above in\nthe `/certificates` directory. Please remove all old keys or certificates from the `/etc/ucentral` directory\n(anything ending in `.pem`).\n\n### Environment variables\nThe following environment variables should be set from the root directory of the service. They tell the OWGW process where to find \nthe configuration and the root directory.\n```bash\nexport OWGW_ROOT=`pwd`\nexport OWGW_CONFIG=`pwd`\n```\nYou can run the shell script `set_env.sh` from the microservice root.\n\n### OWGW Service Configuration\nThe configuration is kept in a file called `owgw.properties`. To understand the content of this file, \nplease look [here](https://github.com/Telecominfraproject/wlan-cloud-ucentralgw/blob/master/CONFIGURATION.md)\n\n### Running the OWGW\nTu run the OWGW, you must run the executable `owgw`. You can use several command line options to run as a daemon or \nspecify the configuration file location.\n\n### systemd: owgw.service\n`owgw.service` is a skeleton to allow to run the OWGW in a systemd based operating system (i.e. Debian). You will need \nto modify slightly to reflect your environment.\n\n### Default device configuration\nBy default, the devices will receive a built-in default configuration. This built-in default configuration is probably not what you need. \nSo there are 2 options in order to specify your own default configuration:\n- In the OWGW data directory, you can create a `default_config.json` file that contains your own personal configuration\n- Using the OWGW UI, on the left hand pane, there is a `configurations` choice. There you can do the same but apply it with more granularity ot each device type \nyou may be deploying.\n\n### Command line options\nThe current implementation supports the following. If you use the built-in configuration file, you do not need to use any command-line\noptions. However, you may decide to use the `--daemon` or `umask` options. \n\n```bash\n./owgw --help\nusage: owgw OPTIONS\nA owgw gateway implementation for TIP.\n\n--daemon        Run application as a daemon.\n--umask=mask    Set the daemon's umask (octal, e.g. 027).\n--pidfile=path  Write the process ID of the application to given file.\n--help          display help information on command line arguments\n--file=file     specify the configuration file\n--debug         to run in debug, set to true\n--logs=dir      specify the log directory and file (i.e. dir/file.log)\n```\n\n#### file\nThis allows you to point to another file without specifying the OWGW_CONFIG variable. The file name must end in `.properties`.\n#### daemon\nRun this as a UNIX service\n#### pidfile\nWhen running as a daemon, the pid of the running service will be set in the speficied file\n#### debug\nRun the service in debug mode.\n#### logs\nSpeficy where logs should be kept. You must include an existing directory and a file name. For example `/var/ucentral/logs/log.0`.\n#### umask\nSeet the umask for the running service.\n\n## Docker\nIf you would rather launch the docker-compose or helm for the controller, please click [here](https://github.com/Telecominfraproject/wlan-cloud-ucentral-deploy).\n\n## uCentral communication protocol\nThe communication protocol between the device and the OGWG is detailed in this [document](https://github.com/Telecominfraproject/wlan-cloud-ucentralgw/blob/main/PROTOCOL.md).\n\n## OpenAPI\nThe OWGW supports an OpenAPI REST based interface for management. You can find the [definition here](https://github.com/Telecominfraproject/wlan-cloud-ucentralgw/blob/main/openapi/ucentral/owgw.yaml).\nAnd here is [how to use it](https://github.com/Telecominfraproject/wlan-cloud-ucentralgw/blob/main/OPENAPI.md)\n\n## Using the API\nIn the `test_scripts` directory, you will find a series of scripts that will show you how to use the API \nwith [curl](https://github.com/Telecominfraproject/wlan-cloud-ucentralgw/blob/main/CLI.md) \nor [python](https://github.com/Telecominfraproject/wlan-cloud-ucentralgw/blob/main/TEST_PYTHON.md). \nMore scripts will be added in the future.\n\n## Firewall Considerations\n| Port | Description | Configurable |\n| :--- | :--- |:------------:|\n| 15002 | Default port from the devices to the OWGW |     yes      |\n| 16002 | Default port for REST API Access to the OWGW |     yes      |\n| 5912 | Default port for RTTY connection |     yes      |\n| 5913 | Defailt port for RTTY connection |     yes      |\n\n## Kafka topics\nToe read more about Kafka, follow the [document](https://github.com/Telecominfraproject/wlan-cloud-ucentralgw/blob/main/KAFKA.md)\n\n## Contributions\nWe need more contributors. Should you wish to contribute, \nplease follow the [contributions](https://github.com/Telecominfraproject/wlan-cloud-ucentralgw/blob/master/CONTRIBUTING.md) document.\n\n## Pull Requests\nPlease create a branch with the Jira addressing the issue you are fixing or the feature you are implementing. \nCreate a pull-request from the branch into master. \n\n## Additional OWSDK Microservices\nHere is a list of additional OWSDK microservices\n| Name | Description | Link | OpenAPI |\n| :--- | :--- | :---: | :---: |\n| OWSEC | Security Service | [here](https://github.com/Telecominfraproject/wlan-cloud-ucentralsec) | [here](https://github.com/Telecominfraproject/wlan-cloud-ucentralsec/blob/main/openpapi/owsec.yaml) |\n| OWGW | Controller Service | [here](https://github.com/Telecominfraproject/wlan-cloud-ucentralgw) | [here](https://github.com/Telecominfraproject/wlan-cloud-ucentralgw/blob/master/openapi/owgw.yaml) |\n| OWFMS | Firmware Management Service | [here](https://github.com/Telecominfraproject/wlan-cloud-ucentralfms) | [here](https://github.com/Telecominfraproject/wlan-cloud-ucentralfms/blob/main/openapi/owfms.yaml) |\n| OWPROV | Provisioning Service | [here](https://github.com/Telecominfraproject/wlan-cloud-owprov) | [here](https://github.com/Telecominfraproject/wlan-cloud-owprov/blob/main/openapi/owprov.yaml) |\n| OWANALYTICS | Analytics Service | [here](https://github.com/Telecominfraproject/wlan-cloud-analytics) | [here](https://github.com/Telecominfraproject/wlan-cloud-analytics/blob/main/openapi/owanalytics.yaml) |\n| OWSUB | Subscriber Service | [here](https://github.com/Telecominfraproject/wlan-cloud-userportal) | [here](https://github.com/Telecominfraproject/wlan-cloud-userportal/blob/main/openapi/userportal.yaml) |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftelecominfraproject%2Fwlan-cloud-ucentralgw","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftelecominfraproject%2Fwlan-cloud-ucentralgw","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftelecominfraproject%2Fwlan-cloud-ucentralgw/lists"}