To Fill In

This Tutorial assumes that you have followed the basic CorteXlab operation tutorials (at least GNU Radio benchmark example, and Eyes and ears inside CorteXlab, but GNU Radio benchmark, interactive command execution and GNU Radio benchmark example with docker are recommended)

Here, we will go through an experiment using and operating the reflective intelligent surface (RIS) installed in the CorteXlab room, that should showcase all that is necessary to drive it for your own experiments.

We assume prior knowlegde of the concept of RIS and its uses. We focus on the technical operation of the one we have installed in the room. .

The RIS currently installed in SLICES/CorteXlab is a prototype of a FR1 RIS by Greenerwave.

It is in the form of a flat square 40cm on a side and designed to operate on a wide 800MHz band centered around 3.7 GHz with a 120° field of view on both azimuth and elevation.

It contains 128 reflective elements (pixels), with one bit control (on/off), arranged in pairs in a 8×8 square. One element of the pair handling vertical polarisation, the other horizontal.

You can find more technical information about it and request their specsheet on their website.

Please check with the CorteXlab Team for changes to that setup (and to check if it has changed)

ris_and_target_map_demo.pdf

The RIS is currently hanging off the ceiling railings, inbetween nodes 31 and 33, and pointing to the “east” of the room's map (see the crude pdf map).

It is connected to node 31 via USB for power and control, so we will have to use that node to drive it.

The RIS installation is designed to be easy to relocate so feel free to contact the CorteXlab team if you want to run experiments with the RIS in a different location (we may need to plug it in a different node).

To show a more interesting, non line-of-sight scenario, some wall panels with RF absorbing foam have been setup between nodes 35 and 39 (again, see the map). As for the RIS itself, they are designed to be relocated, so don't hesitate to tell us if you need them elsewhere.

The RIS itself can not be directly booked, and a low level driver is not made available interact with it. It is connected to a node via USB, so booking that node is necessary to have it power on and controlled.

We provide a ready to use docker image that need to run on the node to serve as driver:

registry.gitlab.inria.fr/cortexlab/measurements/ris-api/ris:1.1

When instantiated, it automatically starts a small web server on port 5000 serving a REST API for remote control and feedback from any of the other nodes, or even (through a proxy), your own computer.

The available controls are:

• Turn on/off with /turn_on and /turn_off (The off state corresponds to setting all ones on the pixels)
• Manually setting the pixel states with /set_pixels, with a list 128 of 0 and/or 1
• Configuration algorithms:
  • /ref_optimization that tries many configurations and iterates on them based on feedback from a receiver
  • /narrow_beamforming that generates a configuration for a narrow_beam based on geometric parameters

• Managing configuration files with /load_file_conf, /read_file_conf, and /write_file_conf to replay, read, and write previously optimized pixel configurations stored on the control node

For more details on this API, the code and a detailed readme is hosted in this repository.

In this example scenario to demonstrate basic operation, we will do the following based on the room setup:

• Setup node 38 to continuously transmit a known sequence over a 5MHz bandwidth
• Setup the RIS node with the provided docker image to allow for RIs control
• Setup node 18, on the other side of the wall, to receive the signal and display received power and channel frequency response information, as well as buttons to send command to the RIS node.

The files we are going to use live inside the same repository as the REST API. Let's go to the tutorial folder to get those:

you@srvairlock:~$ mkdir -r Tutorials/Tuto_RIS
you@srvairlock:~$ cd Tutorials/Tuto_RIS
you@srvairlock:~/Tutorials/Tuto_RIS git clone https://gitlab.inria.fr/cortexlab/measurements/ris-api.git
you@srvairlock:~/Tutorials/Tuto_RIS cd ris-api

We will be using the contents of the examples/power_feedback folder

you@srvairlock:~/Tutorials/Tuto_RIS/ris-api cd examples/power_feedback
you@srvairlock:~/Tutorials/Tuto_RIS/ris-api/examples/power_feedback ls
power_reader_epy_block_0.py  power_reader.grc  power_reader.py  power_tx.grc  power_tx.py  scenario

Let's go over each one of the files in this folder:

• power_tx.grc: the GNU Radio Companion flowgraph description for the transmitter
• power_reader.grc: the GNU Radio Companion flowgraph description for the receiver
• power_tx.py: the GNU Radio python script for the transmitter
• power_reader.py: the GNU Radio python script for the receiver
• power_reader_epy_block_0.py: Helper code for the receiver (code for communication with the RIS)
• scenario: The folder containing the scenario description file that we will edit

Edit the scenario file to point the commands to the user's folder

Let's open the existing scenario file using nano (or some installed text editor that you may prefer):

you@srvairlock:~/Tutorials/Tuto_RIS/ris-api/examples/power_feedback nano scenario/scenario.yaml

# Scenario textual description
description: Power monitoring tutorial for use with RIS

# Experiment maximum duration
duration: 1800


nodes:
  node18:
    container:
    - image: ghcr.io/cortexlab/cxlb-gnuradio-3.10:1.5
      exec: 
      - bash -lc "pip install flask && apt install curl"
      command: bash -lc "python3 /cortexlab/homes/{YOUR USERNAME}/Tutorials/Tuto_RIS/ris-api/examples/power_feedback/power_reader.py -r 5e6"
  node38:
    container:
    - image: ghcr.io/cortexlab/cxlb-gnuradio-3.10:1.5
      command: bash -lc "python3 /cortexlab/homes/{YOUR USERNAME}/Tutorials/Tuto_RIS/ris-api/examples/power_feedback/power_tx.py -r 5e6"

  node31:
    container:
    - image: registry.gitlab.inria.fr/cortexlab/measurements/ris-api/ris:1.1
    passive: true

Make sure you edit the command paths for TX and RX to point to your own folder (replace with your username)

As you can see here, the scenario file is very similar to what was used in previous tutorials. For node 31, driving the RIS itself, the only thing required is to specify the ris-api docker image. No need for a command, server startup is automatic.

The only exotic element here would be for node 18:

      exec: 
      - bash -lc "pip install flask && apt install curl"

This option allows for execution of extra commands in parallel of the main one. We use it to install flask and curl, two packages we want to use to communicate with the RIS, on the fly, without having to generate a dedicated docker image.

Show what's inside the TX and RX files. Quick for TX For RX, point to the feedback snippet and the http_helper block, showing how they work. Useful because these are the elements users would need to reuse for their own experiments

TODO: set the scenario so that it installs flask and does the proper setup. Directly run the commands, no connecting over ssh

Take the opportunity to show the socks proxy connection system, it's so useful

Get to displaying the bokeh interface, and show the operation when we click on the buttons.