Official Cuica Documentation

Token-Based HTTPS Request #1

The following example uses the requests library in Python to make an HTTPS request to a Cuica. This example assumes the API Token has already been generated in place of the placeholder <token> and a custom TLS certificate chain PEM file exists as my-cert.pem.

Client Python Code

import requests
api_key='<token>'
got = requests.get('https://cuica-host/v1/system/info',
    headers = {'Authorization': f'Bearer {api_key}'},
    verify='my-cert.pem')
print(f'{got.json()}')

Example Output

{"version":"1.2.3","buildVersion":"b1bd459", "lastCommitTime":"2025-02-11T01:07:43-05:00","serialNumber":"CUIPRF-XXX"}

Token-Based HTTPS Request #2

The following example also uses the requests library in Python to make an HTTPS request to a Cuica, but in this case a Binary Image ELF file is uploaded to the program endpoint to program a DUT.

This example assumes that the API token has already been generated and substituted for the placeholder <token>, a custom TLS certificate chain PEM file exists (my-cert.pem), and the Binary Image ELF file (my-binary.elf) has been built from source code.

# This will program the DUT with an binary using the 
# configurations provided.
import requests
api_key='<token>'
binary_image='my-binary.elf'
cert_file='my-cert.pem'
 
headers = {
    'Authorization': f'Bearer {api_key}',
    'Accept': 'application/json; charset=utf-8',
}
payload = {
    # Provide a requestUuid (optional)
    'requestUuid': str(uuid.uuid4()),
    # Override the default DUT config by label
    'dutConfigLabel': 'rp2040',
    # Override the default Deployer config by label
    'deployerConfigLabel': 'Cuica',
}
files = {
  'file': (binary_image, open(binary_image,'rb'), 'application/octet-stream')
}
 
# Set the root CA as well as a 30 second timeout for the 
# upload (not the DUT programming)
got = requests.request('POST',
   f'https://cuica-host/v1/dut/program',
   verify=cert_file,
   files=files, 
   headers=headers,
   timeout=30,
   data=payload)
 
# As this is a potentially time-consuming asynchronous command, it 
# will return 202 and a requestUUID that can then be used to determine 
# later when the operation is complete either by polling or by waiting 
# for the websocket event.
request_uuid = got.json()['requestUUID']

Websocket Event Reception

The following example uses the websocket library in Python to subscribe to the websocket events coming from a Cuica. This example assumes the API Token has already been generated and a custom TLS certificate chain PEM file exists.

Client Python Code

import json
import websocket
api_key = '<my-api-token>'
certificate_chain = 'my-chain.pem'
headers = {'Authorization': f'Bearer {api_key}'}
websocket_connection = websocket.create_connection(f'wss://cuica-host/ws',
    sslopt={'ca_certs': certificate_chain)}, header=headers)
 
websocket_connection.timeout = 30
 
try:
  websocket_result = websocket_connection.recv()
  websocket_json_result = json.loads(websocket_result)
  print(f'Received: {websocket_json_result}')
except websocket._exceptions.WebSocketTimeoutException as _:
  print(f'Websocket event never showed up')
 
websocket_connection.close()

Example Output

Received: {'eventType': 'wifiStatusChanged', 'connectionStatus': 'wifiConnected', 'activeWifiSsid': 'my-wifi-router', 'wifiSignalStrength': 'veryGood'}

Session-Based HTTPS Request

This example shows how to use a session-based connection instead of a token-based connection, with <username> and <password> serving as placeholders.

import requests
cuica_http_session = requests.Session()
login_payload = { 
    'username': '<username>',
    'password': '<password>'
}
cuica_http_session.post(f'https://cuica-host/login',
    verify='my-chain.pem',
    data=login_payload)
got = cuica_http_session.get('https://cuica-host/v1/system/info')
print(f'{got.json()}')

Example Output

{"version":"1.2.3","buildVersion":"b1bd459","lastCommitTime":"2025-02-11T01:07:43-05:00","serialNumber":"CUIPRF-XXX"}