{"id":13437290,"url":"https://github.com/bbc/nmos-joint-ri","last_synced_at":"2025-10-18T02:32:11.102Z","repository":{"id":136960472,"uuid":"106807695","full_name":"bbc/nmos-joint-ri","owner":"bbc","description":"BBC reference implementation demonstrating AMWA IS-04, IS-05 and IS-10","archived":false,"fork":false,"pushed_at":"2019-11-22T13:34:53.000Z","size":139,"stargazers_count":13,"open_issues_count":1,"forks_count":1,"subscribers_count":22,"default_branch":"master","last_synced_at":"2025-03-22T06:51:15.666Z","etag":null,"topics":["rd-project","rd-section-apmm","rd-stability-green"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bbc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2017-10-13T09:55:10.000Z","updated_at":"2024-09-16T03:22:50.000Z","dependencies_parsed_at":"2024-01-07T12:56:11.620Z","dependency_job_id":null,"html_url":"https://github.com/bbc/nmos-joint-ri","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbc%2Fnmos-joint-ri","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbc%2Fnmos-joint-ri/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbc%2Fnmos-joint-ri/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bbc%2Fnmos-joint-ri/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bbc","download_url":"https://codeload.github.com/bbc/nmos-joint-ri/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247547582,"owners_count":20956577,"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":["rd-project","rd-section-apmm","rd-stability-green"],"created_at":"2024-07-31T03:00:55.747Z","updated_at":"2025-10-18T02:32:06.056Z","avatar_url":"https://github.com/bbc.png","language":"Python","funding_links":[],"categories":["NMOS"],"sub_categories":[],"readme":"# NMOS IS-04, IS-05 and BCP-003-02 Joint Reference Implementation\n\n## Introduction\n\nThis repository contains a Vagrant provisioning to build 4 virtual machines:\n* IS-04/05 node\n* IS-04 registry\n* BCP-003-02 Authorisation Server\n* NMOS Testing Tool\n\nThe node VM will also present a user interface for interacting with the APIs, and another which allows senders and receivers to be added to a \"mock driver\". This mock driver takes the place of the interface that would normally exist between the APIs and a sender or receiver, and allows the user to add mock up senders or receivers to the Connection Management and Node APIs. Note that the VM does not contain any actual RTP senders or receivers - you cannot produce media streams using this software.\n\nThe mock user interfaces allows calls to be made to the IS-05 API, the effects of which can be observed by inspecting the Node and Connection management APIs on port 8884, and the Query API on port 8882. If there are any port collisions on the host, Vagrant will attempt to re-map the ports to compensate. Run `vagrant port \u003cmachine name\u003e` to check.\n\n## Setup\n\n### Prerequisites\n\nFor the best experience:\n- Use a host machine running Ubuntu Linux (tested on 16.04 and 14.04) - it may work on other platforms but this has not been tested.\n- Install vagrant using a Virtualbox as a provider (https://www.vagrantup.com/docs/installation/) (https://www.vagrantup.com/docs/virtualbox/).\n- Install Ansible 2.8 or newer\n```\npip install ansible\n```\n\nThe Node VM will bind to three host machine ports: 8884 to present the APIs themselves, 8858 to present the mock driver user interfaces and 8860 to present the IS-05 API user interface.\n\nThe Registration and Query machine will present its APIs on port 8882.\n\nThe Authorisation Server will present its APIs on port 8886.\n\nThe testing tool will present itself on port 8888.\n\nIf these ports are already in use on the host machine the bindings may be changed in the Vagrant file.\n\n\n### Installing behind a proxy\n\n[Optionally] Install vagrant proxyconf plugin if you want to easily pass host machine proxy configuration to the guest machines. If you are running the machines behind a proxy they will not configure correctly without proxy information, as they use git to pull down repositories to install.\n```\nvagrant plugin install vagrant-proxyconf\n```\n\nSet environment HTTP proxy variables (these will be passed to Vagrant VMs for use by git, apt and pip if Vagrant proxyconf plugin is installed):\n```\nexport http_proxy=http://\u003cpath-to-your-proxy:proxy-port\u003e\nexport https_proxy=https://\u003cpath-to-your-proxy:proxy-port\u003e\n```\n\nFor Windows users the proxy settings will have to be added to the vagrant file. Please see the [vagrant-proxyconf github](https://github.com/tmatilai/vagrant-proxyconf) for details.\n\n### Start\n\nTo bring up the vagrant machine:\n\n```\ncd vagrant\nvagrant up\n```\n\nTest if servers and their services are running by changing back into the root of this repo and then doing\n```\npython -m unittest discover\n```\nYou should expect to see a number of tests passing successfully.\n\n## Mock Driver User Interface\n\nThe mock driver is presented on (http://localhost:8858/). Two forms allow the creation of mock-up senders and receivers, which have the following options:\n\n* Number of legs - Typically one unless SMPTE 2022-7 is use to allow use of a redundant path.\n* Enable FEC - If checked the sender/receiver will expose parameters related to operation with forward error correction.\n* Enable RTCP - If checked sender/receiver will expose parameters related to operation with RTCP.\n\nOnce added the sender or receiver's UUID will be listed in the table below the form, along with the settings used to create it. Clicking on the dustbin symbol on the right of each entry will remove the corresponding sender/receiver.\n\nOnce senders and receivers have been added they will show up in both the Node and Connection APIs on the node machine, and be propagated to the registry. This can be seen by inspecting the APIs presented on ports 8884 (Node machine) and 8882 (registry machine).\n\n## IS-05 API User Interface\n\nThe IS-05 API user interface is presented on (http://localhost:8859/).\n\nThe interface defaults to expecting the API to be presented on http://localhost:8859. If this is not the case enter the root URL for the API (e.g http://localhost:12345) into the text box in the top left corner of the page, then click \"Change API Root\". If your browser supports HTML5, this value is saved to your browser, and will be remembered even if the page is refreshed.\n\nIf the API currently has senders and receivers registered their UUIDs will be listed below the \"Senders\" and \"Receivers\" headings. If no UUIDs are visible this may indicate that the root address for the API is set incorrectly. If using the example API presented by the VM ensure you have used the Mock Driver Interface (see above) to add some senders and receivers. Note that the page must be refreshed before new to update this list.\n\nClicking on the UUIDs causes a set of headings to appear beneath it. These are subtly different for senders and receivers. Click on a heading to expand its corresponding form. Each of the sections (for both senders and receivers) are detailed below:\n\n### Staged Transport Parameters\n\nLists the staged transport parameters currently presented by the API. Only fields that are permitted by the sender/receiver's schema will be present. The \"leg\" drop down allows the user to toggle between parameters for the primary and redundant leg of SMPTE 2022-7 devices. Parameters for both legs must be populated before staging on such devices.\n\nClicking \"Stage Parameters\" makes an HTTP PUT request to the API. At present only PUT is supported by the UI, and as such all parameters will be updated to reflect their values in the form.\n\n\n### Staged Transport File (Receivers Only)\n\nThis allows the transport file for a given receivers to be staged. \"Transport File Type\" should be set to application/sdp. The sdp file contents should be placed in the \"Data\" box. Optionally the user may provide a Sender ID.\n\nClicking \"Stage File\" will staged these setting to the API. Once again only PUT is supported by the UI, however leaving \"Sender ID\" empty is acceptable, and will result in the Sender Id being set to \"null\".\n\n### Activation\n\nThe activation form has a button for each of the activation types supported by the API - immediate, absolute and relative. Clicking \"Activate Now\" will transfer all staged parameters to active immediately. Clicking \"Activate Relative\" will move staged parameters to active after the offset defined by the \"seconds\" and \"nanoseconds\" fields has elapsed. Finally \"Activate Absolute\" will move the parameters at the TAI time provided in its own \"seconds\" and \"nanoseconds\" boxes. Note that TAI time differs from UTC, as it does not account for leap seconds.\n\nDuring the period between a activation being requested and it occurring staged parameters are deemed to be \"locked\". Attempting to change the parameters during this time will result in an error.\n\n### Active Transport File (Senders Only)\n\nProvides a link to the transport file that should be used to configure receivers to receiver from this sender.\n\n### Active Transport Parameters\n\nDisplays the transport parameters currently active on the device. The refresh button may be used to update these as required.\n\n## Debugging\n\n### SSH into guests\n\nVagrant allows ssh into guest machines. To ssh into the node and registry machines respoectivly use the following commands from the Vagrant directory:\n\n```\nvagrant ssh node\n```\n\n```\nvagrant ssh regquery\n```\n\n```\nvagrant ssh auth\n```\n\n```\nvagrant ssh testing\n```\n\nThe directories cloned down during setup are found in the home directory, but have root permissions. As such any operations on them require root privilidges. Software in the repositories may be built using:\n\n```\nsudo make deb\n```\n\nand installed using dpkg in the usual way from the home directory:\n\n```\nsudo dpkg -i ../\u003cdeb name\u003e\n```\n\n### Logging\n\nThe NMOS software installed on both guests will log into the /var/log/nmos.log. SSH into the guests as detailed above to view these logs.\n\n### Using alternative NMOS branches\n\nThe joint RI allows the user to set which branches of each of the NMOS repositories will be used when provisioning. The branches are set in environment variables on the host before the VM is provisioned. This is primarily intended for use in automated testing.\n\nThe environment variables to be set are as follows:\n\n```\nNMOS_RI_COMMON_BRANCH\nNMOS_RI_MDNS_BRIDGE_BRANCH\nNMOS_RI_REVERSE_PROXY_BRANCH\nNMOS_RI_NODE_BRANCH\nNMOS_RI_QUERY_BRANCH\nNMOS_RI_REGISTRATION_BRANCH\nNMOS_RI_CONNECTION_BRANCH\nNMOS_RI_AUTH_BRANCH\nNMOS_RI_TESTING_BRANCH\n```\n\nFor example, the RI may be configured to use the \"dev\" branch of the reverse proxy as follows:\n\n```\nexport NMOS_RI_REVERSE_PROXY_BRANCH=dev\nvagrant up\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbbc%2Fnmos-joint-ri","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbbc%2Fnmos-joint-ri","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbbc%2Fnmos-joint-ri/lists"}