### Connect to GrandMA 2 WebSocket Server

Source: https://github.com/deltaeight/ma2-websocket-api/blob/master/docs/index.html

This example shows how to establish a WebSocket connection to the GrandMA 2 console. Replace '{deskIp}' with the actual IP address of the desk.

```shell
ws://{deskIp}/?ma=1
```

--------------------------------

### Complete GrandMA2 Client Connection Flow (JavaScript)

Source: https://context7.com/deltaeight/ma2-websocket-api/llms.txt

A comprehensive example demonstrating a full connection, authentication, data request, and disconnection workflow using Node.js. It includes a `GrandMA2Client` class to manage the WebSocket connection and interactions.

```javascript
const WebSocket = require('ws');
const crypto = require('crypto');

class GrandMA2Client {
  constructor(deskIp = "192.168.0.1") {
    this.url = `ws://${deskIp}/?ma=1`;
    this.sessionId = null;
    this.ws = null;
  }

  hashPassword(password) {
    return crypto.createHash('md5').update(password).digest('hex');
  }

  connect() {
    return new Promise((resolve, reject) => {
      this.ws = new WebSocket(this.url);

      this.ws.onopen = () => resolve();
      this.ws.onerror = (err) => reject(err);

      this.ws.onmessage = (event) => {
        const msg = JSON.parse(event.data);
        this.handleMessage(msg);
      };
    });
  }

  handleMessage(msg) {
    if (msg.status === "server ready") {
      console.log("Server ready, appType:", msg.appType);
    } else if (msg.session !== undefined && msg.forceLogin !== undefined) {
      this.sessionId = msg.session;
      console.log("Session established:", this.sessionId);
    } else if (msg.responseType === "login") {
      console.log("Login result:", msg.result);
    } else if (msg.responseType === "getdata") {
      console.log("Data received:", msg.data);
    }
  }

  login(username, password) {
    this.ws.send(JSON.stringify({
      requestType: "login",
      username: username,
      password: this.hashPassword(password),
      session: this.sessionId,
      maxRequests: 10
    }));
  }

  getData(fields) {
    this.ws.send(JSON.stringify({
      requestType: "getdata",
      data: fields,
      maxRequests: 10,
      session: this.sessionId
    }));
  }

  close() {
    this.ws.send(JSON.stringify({
      requestType: "close",
      session: this.sessionId,
      maxRequests: 1
    }));
    this.ws.close();
  }
}

// Usage
// async function main() {
//   const client = new GrandMA2Client("192.168.0.100");
//
//   await client.connect();
//   console.log("Connected to GrandMA 2");
//
//   // Wait for session, then login
//   setTimeout(() => client.login("admin", "password"), 1000);
//
//   // Request data after login
//   setTimeout(() => client.getData("set,clear,solo,high"), 2000);
//
//   // Close connection
//   setTimeout(() => client.close(), 5000);
// }
//
// main().catch(console.error);
```

--------------------------------

### GrandMA 2 WebSocket API: Publish Operations

Source: https://github.com/deltaeight/ma2-websocket-api/blob/master/docs/index.html

Examples of messages that can be published to the GrandMA 2 WebSocket API. These include requests for session information, data retrieval, login, and closing the connection.

```json
{
  "session": 0
}
```

```json
{
  "requestType": "getdata",
  "data": "string",
  "maxRequests": 1,
  "session": 0
}
```

```json
{
  "requestType": "login",
  "username": "string",
  "password": "string",
  "session": 0,
  "maxRequests": 1
}
```

```json
{
  "requestType": "close",
  "session": 0,
  "maxRequests": 1
}
```

--------------------------------

### GrandMA 2 WebSocket API: Subscribe Operations

Source: https://github.com/deltaeight/ma2-websocket-api/blob/master/docs/index.html

Examples of messages that can be subscribed to from the GrandMA 2 WebSocket API. These include server status, session information, data responses, and login responses.

```json
{
  "status": "server ready",
  "appType": "gma2"
}
```

```json
{
  "realtime": true,
  "session": 0,
  "forceLogin": true,
  "worldIndex": 0
}
```

```json
{
  "realtime": true,
  "responseType": "getdata",
  "data": [
    {}
  ],
  "worldIndex": 0,
  "prompt": "[Channel]>",
  "promptcolor": "#808080"
}
```

```json
{
  "realtime": true,
  "responseType": "login",
  "result": true,
  "worldIndex": 0
}
```

--------------------------------

### Establish WebSocket Connection to GrandMA 2 Console

Source: https://context7.com/deltaeight/ma2-websocket-api/llms.txt

Connects to the GrandMA 2 console's WebSocket server using its IP address and the '?ma=1' query parameter. Handles connection opening, message reception, and errors.

```javascript
const deskIp = "192.168.0.1";
const ws = new WebSocket(`ws://${deskIp}/?ma=1`);

ws.onopen = () => {
  console.log("Connected to GrandMA 2 console");
};

ws.onmessage = (event) => {
  const message = JSON.parse(event.data);
  console.log("Received:", message);
};

ws.onerror = (error) => {
  console.error("WebSocket error:", error);
};
```

--------------------------------

### Request Data from Desk (JavaScript)

Source: https://context7.com/deltaeight/ma2-websocket-api/llms.txt

Sends a request to the desk to retrieve specified data fields. The data fields are provided as a comma-separated string. Requires an active WebSocket connection and a session ID.

```javascript
function requestData(ws, dataFields, sessionId) {
  const dataRequest = {
    requestType: "getdata",
    data: dataFields,       // comma-separated field names
    maxRequests: 10,        // integer >= 1
    session: sessionId      // integer >= 0
  };

  ws.send(JSON.stringify(dataRequest));
  console.log("Data request sent:", dataFields);
}

// Usage - request multiple data fields
// requestData(ws, "set,clear,solo,high", 12345);
// Sends: {
//   "requestType": "getdata",
//   "data": "set,clear,solo,high",
//   "maxRequests": 10,
//   "session": 12345
// }
```

--------------------------------

### Authenticate with GrandMA 2 Console (Login)

Source: https://context7.com/deltaeight/ma2-websocket-api/llms.txt

Sends a login request to the GrandMA 2 console, requiring a username, password (MD5-hashed), session ID, and maximum requests. It utilizes Node.js crypto for password hashing.

```javascript
const crypto = require('crypto');

// Generate MD5 hash of password
function hashPassword(password) {
  return crypto.createHash('md5').update(password).digest('hex');
}

// Send login request
function login(ws, username, password, sessionId) {
  const loginRequest = {
    requestType: "login",
    username: username,
    password: hashPassword(password),  // 32-character MD5 hash
    session: sessionId,                 // integer >= 0
    maxRequests: 10                     // integer >= 1
  };

  ws.send(JSON.stringify(loginRequest));
  console.log("Login request sent for user:", username);
}

// Usage
login(ws, "admin", "mypassword", 12345);
// Sends: {
//   "requestType": "login",
//   "username": "admin",
//   "password": "34819d7beeabb9260a5c854bc85b3e44",
//   "session": 12345,
//   "maxRequests": 10
// }
```

--------------------------------

### Handle GrandMA 2 Server Ready Status

Source: https://context7.com/deltaeight/ma2-websocket-api/llms.txt

Processes incoming WebSocket messages to detect when the GrandMA 2 server is ready. It specifically checks for a 'server ready' status and 'gma2' app type.

```javascript
ws.onmessage = (event) => {
  const message = JSON.parse(event.data);

  if (message.status === "server ready" && message.appType === "gma2") {
    console.log("GrandMA 2 server is ready");
    // Server status response structure:
    // {
    //   "status": "server ready",
    //   "appType": "gma2"
    // }
  }
};
```

--------------------------------

### Handle Data Response from Desk (JavaScript)

Source: https://context7.com/deltaeight/ma2-websocket-api/llms.txt

Listens for incoming messages on a WebSocket connection and processes data responses from the desk. It specifically handles messages with 'responseType' set to 'getdata', logging various fields and iterating through the received data array.

```javascript
// Handling data response
// ws.onmessage = (event) => {
//   const message = JSON.parse(event.data);
//
//   if (message.responseType === "getdata") {
//     console.log("Data received:");
//     console.log("Realtime:", message.realtime);
//     console.log("World index:", message.worldIndex);
//     console.log("Prompt:", message.prompt || "[Channel]>");
//     console.log("Prompt color:", message.promptcolor || "#808080");
//
//     // Data array contains objects with requested field values
//     message.data.forEach((item, index) => {
//       console.log(`Data item ${index}:`, item);
//     });
//
//     // Data response structure:
//     // {
//     //   "realtime": true,
//     //   "responseType": "getdata",
//     //   "data": [{"set": "value", "clear": "value"}],
//     //   "worldIndex": 0,
//     //   "prompt": "[Channel]>",
//     //   "promptcolor": "#808080"
//     // }
//   }
// };
```

--------------------------------

### Send Session Message to GrandMA 2 Console

Source: https://context7.com/deltaeight/ma2-websocket-api/llms.txt

Constructs and sends a session message to the GrandMA 2 console via WebSocket to maintain session state. Requires the WebSocket instance and a session ID.

```javascript
function sendSession(ws, sessionId) {
  const sessionMessage = {
    session: sessionId  // integer >= 0
  };

  ws.send(JSON.stringify(sessionMessage));
  console.log("Sent session:", sessionMessage);
}

// Usage
sendSession(ws, 0);
// Sends: {"session": 0}
```

--------------------------------

### GrandMA 2 Websockets API - Publish

Source: https://github.com/deltaeight/ma2-websocket-api/blob/master/docs/index.html

This section details the messages that can be published to the GrandMA 2 Websockets API. It includes operations for session management, data requests, login, and closing the connection.

```APIDOC
## POST /

### Description
This endpoint allows publishing various messages to the GrandMA 2 console, including session management, data requests, login credentials, and connection closure.

### Method
POST

### Endpoint
`/{deskIp}/?ma=1`

### Parameters
#### Request Body
**One of the following message types is required:**

**1. session**
- **session** (integer) - Required - Session identifier, must be >= 0.

**2. dataRequest**
- **requestType** (string) - Required - Must be "getdata".
- **data** (string) - Required - Comma-separated string of data fields to query (e.g., "set,clear,solo,high").
- **maxRequests** (integer) - Required - Maximum number of requests, must be >= 1.
- **session** (integer) - Required - Session identifier, must be >= 0.

**3. loginRequest**
- **requestType** (string) - Required - Must be "login".
- **username** (string) - Required - Username for login.
- **password** (string) - Required - MD5 hash of the user's password, must match ^[0-9a-zA-Z]{32}$.
- **session** (integer) - Required - Session identifier, must be >= 0.
- **maxRequests** (integer) - Required - Maximum number of requests, must be >= 1.

**4. closeConnection**
- **requestType** (string) - Required - Must be "close".
- **session** (integer) - Required - Session identifier, must be >= 0.
- **maxRequests** (integer) - Required - Maximum number of requests, must be >= 1.

### Request Example
```json
{
  "session": 0
}
```

```json
{
  "requestType": "getdata",
  "data": "set,clear,solo,high",
  "maxRequests": 1,
  "session": 0
}
```

```json
{
  "requestType": "login",
  "username": "your_username",
  "password": "your_md5_password_hash",
  "session": 0,
  "maxRequests": 1
}
```

```json
{
  "requestType": "close",
  "session": 0,
  "maxRequests": 1
}
```

### Response
#### Success Response (200)
Responses vary based on the request type. Common fields include:
- **realtime** (boolean) - Indicates if the response is real-time.
- **responseType** (string) - The type of response (e.g., "login", "getdata").
- **result** (boolean) - For login responses, indicates success or failure.
- **data** (array<object>) - For data responses, contains the requested data.
- **worldIndex** (integer) - The world index associated with the response.

#### Response Example
```json
{
  "realtime": true,
  "responseType": "login",
  "result": true,
  "worldIndex": 0
}
```

```json
{
  "realtime": true,
  "responseType": "getdata",
  "data": [
    {}
  ],
  "worldIndex": 0,
  "prompt": "[Channel]>",
  "promptcolor": "#808080"
}
```
```

--------------------------------

### Handle GrandMA 2 Login Response

Source: https://context7.com/deltaeight/ma2-websocket-api/llms.txt

Processes the response from the GrandMA 2 console after a login attempt. It checks the 'result' field to determine if the login was successful and logs the outcome.

```javascript
ws.onmessage = (event) => {
  const message = JSON.parse(event.data);

  if (message.responseType === "login") {
    if (message.result === true) {
      console.log("Login successful!");
      console.log("World index:", message.worldIndex);
    } else {
      console.log("Login failed - check credentials");
    }
    // Login response structure:
    // {
    //   "realtime": true,
    //   "responseType": "login",
    //   "result": true,
    //   "worldIndex": 0
    // }
  }
};
```

--------------------------------

### GrandMA 2 Websockets API - Subscribe

Source: https://github.com/deltaeight/ma2-websocket-api/blob/master/docs/index.html

This section details the messages that can be subscribed to from the GrandMA 2 Websockets API. It includes operations for server status, session information, data responses, and login responses.

```APIDOC
## GET /

### Description
This endpoint allows subscribing to various messages from the GrandMA 2 console, including server status updates, session information, data responses to previous requests, and login confirmation.

### Method
GET

### Endpoint
`/{deskIp}/?ma=1`

### Parameters
#### Query Parameters
No specific query parameters are documented for subscription, but the connection is established via WebSocket on the base endpoint.

### Request Example
(No specific request body for subscription, connection is established via WebSocket)

### Response
#### Success Response (200)
Responses vary based on the subscription type. Common fields include:

**1. serverStatus**
- **status** (string) - Required - Server status, must be "server ready".
- **appType** (string) - Required - Application type, must be "gma2".

**2. sessionInformation**
- **realtime** (boolean) - Indicates if the information is real-time.
- **session** (integer) - Required - Session identifier, must be >= 0.
- **forceLogin** (boolean) - Required - Indicates if a forced login is required.
- **worldIndex** (integer) - Required - The world index, must be >= 0.

**3. dataResponse**
- **realtime** (boolean) - Indicates if the response is real-time.
- **responseType** (string) - Required - Must be "getdata".
- **data** (array<object>) - Required - An array of objects containing the requested data. Each object's property keys correspond to the requested data fields.
- **worldIndex** (integer) - Required - The world index, must be >= 0.
- **prompt** (string) - Optional - The prompt used by the desk shell. Default: "[Channel]>".
- **promptcolor** (string) - Optional - The color of the prompt. Default: "#808080".

**4. loginResponse**
- **realtime** (boolean) - Indicates if the response is real-time.
- **responseType** (string) - Required - Must be "login".
- **result** (boolean) - Required - Indicates if the login was successful.
- **worldIndex** (integer) - Required - The world index, must be >= 0.

#### Response Example
```json
{
  "status": "server ready",
  "appType": "gma2"
}
```

```json
{
  "realtime": true,
  "session": 0,
  "forceLogin": true,
  "worldIndex": 0
}
```

```json
{
  "realtime": true,
  "responseType": "getdata",
  "data": [
    {}
  ],
  "worldIndex": 0,
  "prompt": "[Channel]>",
  "promptcolor": "#808080"
}
```

```json
{
  "realtime": true,
  "responseType": "login",
  "result": true,
  "worldIndex": 0
}
```
```

--------------------------------

### Retrieve GrandMA 2 Session Information

Source: https://context7.com/deltaeight/ma2-websocket-api/llms.txt

Parses WebSocket messages to extract session details, including the session ID and whether a forced login is required. This information is crucial for subsequent API interactions.

```javascript
ws.onmessage = (event) => {
  const message = JSON.parse(event.data);

  if (message.session !== undefined && message.forceLogin !== undefined) {
    console.log("Session ID:", message.session);
    console.log("Force login required:", message.forceLogin);
    console.log("World index:", message.worldIndex);
    // Session information response structure:
    // {
    //   "realtime": true,
    //   "session": 12345,
    //   "forceLogin": true,
    //   "worldIndex": 0
    // }
  }
};
```

--------------------------------

### Close WebSocket Connection (JavaScript)

Source: https://context7.com/deltaeight/ma2-websocket-api/llms.txt

Sends a request to gracefully close the WebSocket connection with the desk. This function requires the WebSocket instance and a session ID. It constructs a 'close' request object and sends it over the WebSocket.

```javascript
function closeConnection(ws, sessionId) {
  const closeRequest = {
    requestType: "close",
    session: sessionId,   // integer >= 0
    maxRequests: 1        // integer >= 1
  };

  ws.send(JSON.stringify(closeRequest));
  console.log("Close connection request sent");
}

// Usage
// closeConnection(ws, 12345);
// Sends: {
//   "requestType": "close",
//   "session": 12345,
//   "maxRequests": 1
// }
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.