Open a WebSocket Connection

You can open a websocket connection to a device's console to interact with it in real-time. This is useful for logging, automation, and debugging purposes.

Use the Browser's Developer Tools

To use the browser's developer tools to open a WebSocket connection, you will first need to find the WebSocket URL. You can either look at the browser's network traffic or use the REST API.

Find the WebSocket URL in the Browser

1. Start with a device that is running.

2. Open the browser's developer tools.

3. Go to the Network tab, delete the current entries, and reload the page.

4. Look for a socket type connection to your Corellium domain, which should look like either yourdomainname.enterprise.corellium.com or app.corellium.com.

   

5. Open the connection, find the request header section, and copy the entire URL including the final = character.

   

Find the WebSocket URL with the REST API

You can find the WebSocket URL with the GET /v1/instances/{instanceId}/console API endpoint. You can also see a curl command, which includes your API token in plaintext, to automate this step on the CURL tab.

note

The WebSocket URL from the REST API response will end with %3D, which is the URL-encoded version of the =. Either form of WebSocket URL will work.

(To use the REST API, open the user dropdown on the top-right, click on REST API, and enter your API Token on the Authentication page.)

Open a WebSocket in the Browser

After you have the WebSocket URL, you can open a new connection.

1. Go to the Console tab and declare a variable with the WebSocket URL.

   const ws_url = 'wss://yourdomainname.enterprise.corellium.com/console/ABCD0123abcd0123ABCD0_123abcd0123ABCD0123abcd0123ABCD0123abcd0123ABCD0123abcd0123ABCD0123abcd0123ABCD0123abcd0123ABCD0123abcd0123ABCD0123abcd0123ABCD0123A_BCD0123abcd0123A='

2. Copy and paste this entire block of code.

   let ws = new WebSocket(ws_url)
   
   ws.onopen = function() {
     console.log('WebSocket is open');
   }
   
   ws.onerror = function(error) {
     console.log('WebSocket error: ' + error);
   }
   
   ws.onmessage = function(event) {
     if (typeof event.data === 'string') {
       console.log('Received message:', event.data);
     } else if (event.data instanceof ArrayBuffer) {
       var utf8Decoder = new TextDecoder('utf-8');
       var message = utf8Decoder.decode(event.data);
       console.log('Received message:', message);
     } else if (event.data instanceof Blob) {
       var reader = new FileReader();
       reader.onload = function() {
         var utf8Decoder = new TextDecoder('utf-8');
         var message = utf8Decoder.decode(reader.result);
         console.log('Received message:', message);
       };
       reader.readAsArrayBuffer(event.data);
     } else {
       console.log('Received unknown data type');
     }
   } 

3. You should see a "WebSocket is open" line in the console. On the next line, you should see an "Received message:" line.

   

4. When you are ready, close the WebSocket connection.

   ws.close()

Use a Python Script

For the Python exmample, we will use the v1_get_instance_console API Endpoint.

The client is available with pip3 install corellium-api or in macOS by using venv. You can find the source code on GitHub.

Example Python Script

The following script is a simple example of how to open a websocket connection and stream the device's console output.

note

The ApiEndpoint argument should look like either https://yourdomainname.enterprise.corellium.com/api or https://app.corellium.com/api.

import asyncio
#from pprint import pprint # Optional for testing and development purposes.
import sys
import websockets
import corellium_api
from corellium_api.rest import ApiException

if len(sys.argv) < 3:
  print('Usage: %s <ApiEndpoint> <ApiToken>', sys.argv[0])
  exit(-1)

apiEndpoint = sys.argv[1]
apiToken = sys.argv[2]

instance_id = '0814f4c0-ea8d-4980-96a3-50d399b34efd' # str | Instance ID - uuid

async def main():
  configuration = corellium_api.Configuration(host = apiEndpoint)
  
  # Enter a context with an instance of the API client
  async with corellium_api.ApiClient(configuration=configuration) as api_client:
    # Create an instance of the API class
    api_instance = corellium_api.CorelliumApi(api_client)

    # Log in
    print('Logging in ...')
    try:
      token_response = await api_instance.v1_auth_login({
        "apiToken": apiToken
      })
      configuration.access_token = token_response.token
    except ApiException as e:
      print('Exception when calling v1_auth_login: %s\n' % e)
      exit(1)
    print('Logged in.')

    # Connect to the console WebSocket
    print('Requesting the instance console WebSocket URL ...')
    try:
      api_response = await api_instance.v1_get_instance_console(instance_id)
      console_websocket_url = api_response.url
    except ApiException as e:
      print('Exception when calling v1_get_instance_console: %s\n' % e)
      exit(1)
    print('Connecting to the WebSocket ...')
    async with websockets.connect(console_websocket_url) as ws:
      await handler(ws)
      await asyncio.Future()  # keep WebSocket connection open
  
async def handler(websocket):
  while True:
    message = await websocket.recv() # encoded in Unicode
    print(message.decode(encoding='UTF-8',errors='replace')) # decoded to UTF-8

if __name__ == '__main__':
  print('Starting the script ...')
  try:
    asyncio.run(asyncio.wait_for(main(), 600)) # The timeout in seconds.
  except Exception as e:
    print('Finished running main() due to AsyncIO timeout.')
  print('Finished the script.')
  exit(0)