RIS

class tlkcore.tmydev.DevRIS.RISController(*parent)

Reconfigurable Intelligent Surface.

Note

The “RIS pattern” refers to the radiation pattern of an RIS module.

getNetInfo()

Retrieve basic network information in dictionary format.

Returns:

RetData

dict: A dictionary with the following keys:
- mac: The MAC address of the device.
- ip_mode: The IP mode (e.g., DHCP or STATIC) as an IPMode enum.
- ip: The current IP address of the device.
- static_ip: The static IP address (if configured).
- subnet_mask: The static subnet mask (if configured).
- gateway: The static gateway address (if configured).

Return type:

RetType

Examples

>>> ret = service.getNetInfo(sn)
>>> print(ret.RetData)
{
    'mac': '8c:1f:aa:bb:12:10',
    'ip_mode': <IPMode.DHCP: 0>,
    'ip': '192.168.137.168',
    'static_ip': '192.168.100.114',
    'subnet_mask': '255.255.255.0',
    'gateway': '192.168.100.1'
}

setIPMode(ip_mode: IPMode | int)

Set the IP mode for the device.

Parameters:

ip_mode (Union[IPMode, int]) – The IP mode to set. It can be an instance of IPMode or an integer.

Returns:

An object containing the result of the operation.

OK: If the IP mode is successfully set.
ERROR: If there is an error during the operation.

Return type:

RetType

Examples

>>> service.setIPMode(sn, IPMode.STATIC)

setSubnetMsk(mask)

Set the subnet mask for the device.

Parameters:

mask (str) – The subnet mask to set, in the format “x.x.x.x”.

Returns:

An object containing the result of the operation.

OK: If the subnet mask is successfully set.
ERROR: If there is an error during the operation.

Return type:

RetType

setGateway(gateway)

Set the gateway address for the device.

Parameters:

gateway (str) – The gateway address to set, in the format “x.x.x.x”.

Returns:

An object containing the result of the operation.

OK: If the gateway address is successfully set.
ERROR: If there is an error during the operation.

Return type:

RetType

getRISModuleInfo() → RetType

Get all module’s freq info(MHz), hw version, fpga version…etc as json format.

Returns:

RetData

dict: A dictionary with the following keys:
- module_sn: Module’s SN
- hw_ver: Hardware version in hex
- fpga_ver: FPGA version (e.g., “v1.0.0”)
- element_spacing: Element spacing in mm (e.g., [5400, 5400])
- antenna_size: Antenna size in elements (e.g., [32, 32])
- edge_gap_size: Edge gap size in um (e.g., [L, R, U, D])
- freq_mhz: Supported frequency dictionary in range and step, unit: MHz.
  
  central: Central frequency in MHz
  
  min: Minimum frequency in MHz
  
  max: Maximum frequency in MHz
  
  step: Step frequency in MHz

Return type:

RetType

Examples

>>> module_info = service.getRISModuleInfo(sn).RetData
>>> print(module_info)
{
    "1": {
        "module_sn": "RIS-2521000-0100",
        "hw_ver": "v0",
        "fpga_ver": "v1.0.0",
        "element_spacing": [5400, 5400],
        "antenna_size": [32, 32],
        "edge_gap_size": [49100, 50500, 49760, 49840],
        "freq_mhz": {
            "central": 28000,
            "min": 26000,
            "max": 30000,
            "step": 100
        },
        "features": {
            "is_enable_findme": True,
        }
    },
    "2": {
        ...
    },
    "3": {
        ...
    },
    "4": {
        ...
    }
}

setRISAngle(incident: RIS_Dir, reflection: RIS_Dir, module_config: RIS_ModuleConfig, save=False)

Set RIS pattern via Incident angle and Reflection angle

Parameters:

incident (RIS_Dir) – RIS direction for incident with distance in meters.
reflection (RIS_Dir) – RIS direction for reflection with distance in meters.
module_config (RIS_ModuleConfig) – RIS module config for combination
save (bool, optional) – Save pattern to csv file for debugging. Defaults to False.

Note

RIS direction only accept positive numbers.

Returns:

An object containing the result of the operation.

OK: If the operation is successful.
ERROR: If there is a general error during the operation.

Return type:

RetType

Examples

Set RIS pattern with incident angle (0, 0) and reflection angle (45, 0), and distance is 1m, central freq set to 28G, only module 1 (port 1), not rotate.

>>> incident = RIS_Dir(('distance'=1, (0, 0)))
>>> reflection = RIS_Dir(('distance'=1, (45, 0)))
>>> module_config = RIS_ModuleConfig(28000, 1)
>>> service.setRISAngle(sn, incident, reflection, module_config)

Set RIS pattern with incident angle 60 and reflection angle 60

>>> incident = RIS_Dir(0, 60)
>>> reflection = RIS_Dir(0, 60)

Changed in version v2.3.0: Modify parameters to RIS_Dir and RIS_ModuleConfig

setRISPattern(module_pattern: list | dict)

Set RIS pattern in list or dict for single/multiple modules.

Parameters:

module_pattern (Union[list, dict]) –

Pattern data for single or multiple modules.

If list: A 2D list representing a single pattern (applies to module 1 by default)
If dict: A dictionary mapping module numbers to their patterns: {module_number: pattern}

Where pattern is a 2D list of integers (0 or 1):

0: Antenna element OFF
1: Antenna element ON

Note

The size of pattern should match the antenna_size from getRISModuleInfo()

Returns:

An object containing the result of the operation.

OK: If the operation is successful.
ERROR: If there is a general error during the operation.

Return type:

RetType

Examples

Set single pattern only, here demo a simple case for 4 x 2 array (“antenna_size”: [4, 2])
>>> ptn = [[1,0,1,1], [0,0,1,1]] >>> service.setRISPattern(sn, ptn)

Set the group of module and pattern, here demo a simple case for module 1 & 2, with a 4 x 2 array (“antenna_size”: [4, 2])

>>> module_ptn = {1: [[1,0,1,1], [0,0,1,1]], 2: [[1,1,0,0], [1,1,0,0]]}
>>> service.setRISPattern(sn, module_ptn)

Changed in version v2.1.3: Add module

Changed in version v2.3.0: Remove module param and extend to module_pattern for multiple modules

getRISPattern(module: int | list = 1) → RetType

Get the current RIS pattern from single or multiple modules.

Parameters:

module (Union[int, list], optional) –

Module selection. Defaults to 1.

If int: Single module number (1~4), e.g., module = 1 for module 1.
If list: List of module numbers or nested list for specific modules, e.g., module = [1, 2] for modules 1 and 2.

Returns:

RetData

list: pattern

structure

[
    [r1c1, r1c2, ...],
    [r2c1, r2c2, ...],
    ...
]

dict: assigned pattern of modules

structure

{
    "1": [
        [r1c1, r1c2, ...],
        [r2c1, r2c2, ...],
        ...
    ],
    "2": [
        [r1c1, r1c2, ...],
        [r2c1, r2c2, ...],
        ...
    ]
}

Return type:

RetType

Changed in version v2.3.0: Add support for multiple modules

hexPatternToIntMatrix(module_number: int, hex_pattern: str) → list[list[int]]

Convert hex pattern string to 2D int matrix according to antenna configuration.

Parameters:

module_number – The RIS module number based on connection port (1~4).
hex_pattern – The hex pattern string.

Returns:

2D matrix representing the pattern with 0s and 1s.

Return type:

list[list[int]]

Examples

>>> # For a RIS module with antenna size [8, 4]
>>> hex_pattern = "2D333C0F"
>>> pattern_matrix = service.hexPatternToIntMatrix(sn, 1, hex_pattern)
>>> print(pattern_matrix)
[
    [0, 0, 1, 0, 1, 1, 0, 1],
    [0, 0, 1, 1, 0, 0, 1, 1],
    [0, 0, 1, 1, 1, 1, 0, 0],
    [0, 0, 0, 0, 1, 1, 1, 1]
]

checkFWVersion(min_version: VER, msg: str = '') → RetType

Check if the current firmware version is greater than or equal to the minimum required version.

Parameters:

min_version (VER) – The minimum required firmware version.

Returns:

RetData

bool: True if the current firmware version is sufficient, False otherwise.

Return type:

RetType

checkHWVersion(versions: List[VER], msg: str = '', check_version: VER = None) → RetType

Check if the current hardware version is greater than or equal to the minimum required version.

Parameters:

version (VER) – The minimum required hardware version.

Returns:

RetData

bool: True if the current hardware version is sufficient, False otherwise.

Return type:

RetType

getDFUSupport()

Check if the device supports Device Firmware Upgrade (DFU).

Returns:

RetData

bool: True if DFU is supported, False otherwise.

Return type:

RetType

getDevTypeName()

Retrieve current name of device.

Returns:: Name of device

Examples

>>> service.getDevTypeName(sn)
'RIS'

processDFU(file_path: str, dfu_dev_info: dict)

Process the Device Firmware Upgrade (DFU) at the local side.

Parameters:

file_path (str) – The file path to the firmware file to be uploaded.
dfu_dev_info (dict) –
Information about the DFU device.
- sn (str): Serial number of the device.
- address (str): Address of the device.
- devtype (int): Device type as defined in TMYDevType.
- in_dfu (bool): Indicates if the device is already in DFU mode.
- fw_ver (str): Firmware version of the device.
- hw_ver (str): Hardware version of the device.

Returns:

An object containing the result of the DFU process.

OK: If the DFU process completes successfully.
ERROR_METHOD_NOT_SUPPORT: If DFU is not supported on the device.
ERROR_DFU: If the DFU process encounters an error.

Return type:

RetType

queryFWVer()

Query FW version of the device.

Returns:

RetData

str: FW version.

Return type:

RetType

Examples

>>> fw_version = service.queryFWVer(sn).RetData
>>> print(f"FW Version: {fw_version}")
v1.0.0

queryHWVer()

Query the hardware version of the device.

Returns:

RetData

str: The hardware version as a string.

Return type:

RetType

Examples

Query the hardware version of the device

>>> hw_version = service.queryHWVer(sn).RetData
>>> print(f"Hardware Version: {hw_version}")

queryLoaderVer()

Query the bootloader version of the device.

Returns:

RetData

str: The bootloader version as a string.

Return type:

RetType

queryMAC()

Query the MAC address of the device.

Returns:

An object containing the MAC address of the device.

str: The MAC address as a string.

Return type:

RetType

Examples

Query the MAC address of the device

>>> mac_address = service.queryMAC(sn).RetData
>>> print(f"MAC Address: {mac_address}")
MAC Address: 00:0C:FE:AA:BB:01

querySN()

Query the serial number of the device.

Returns:

RetData

str: The serial number of the device.

Return type:

RetType

queryStaticIP()

Query the static IP address of the device.

Parameters:

sn (str) – The serial number of the device.

Returns:

RetData

str: Static IP of the device.

Return type:

RetType

Note

Some FW versions of device not support this feature

Examples

Query the static IP address of a device:

>>> static_ip = service.queryStaticIP(sn).RetData
>>> print(f"Static IP Address: {static_ip}")
Static IP Address: 192.168.100.111

reboot()

Reboot of the device.

Returns:

An object containing the result of the reboot process.

OK: If the reboot process completes successfully.

Return type:

RetType

setStaticIP(ip, reboot=False)

Set the static IP address of the device, and reboot or not.

Note

Support LAN device only,

Parameters:

ip (str) – IP with x.x.x.x format
reboot (bool, optional) – reboot device after setting static IP. Defaults to False.

Note

Some FW versions of device not support this reboot feature.

Return type:: RetType

Examples

Set the static IP address of a device:

>>> service.setStaticIP(sn, "192.168.100.150", True)