###################################################################################################
#                                                                                                 #
# SEQUENCING                                                                                      #
#                                                                                                 #
# This Python script demonstrates how to interact with the Voodoo Robotics Sequencing feature      #
# using Python functions to communicate with the Voodoo Robotics REST API.                         #
# The script covers creating, reading, updating, launching, and deleting sequences.                #
#                                                                                                 #
###################################################################################################

import requests  # Import the requests library for making HTTP requests to the REST API
import json      # Import the json library for formatting and displaying JSON data

# Define the base URL for the API endpoint. This should be modified to point to your specific server.
url = 'https://www.voodoodevices.com/api/'

# Define the API key for authentication. Replace 'your_api_key' with your actual API key.
api_key = 'your_api_key'

# Define the HTTP headers to include the API key for authorization.
headers = {'API-KEY': api_key}


def allSequences():
    """
    Retrieve All Sequences

    This function retrieves a list of all sequences from the Voodoo Robotics API,
    including unstarted, in-progress, and completed sequences.

    Returns:
        list: A list of dictionaries containing details of each sequence, such as:
              - sequence nonce
              - start_time
              - complete_time
    """
    response = requests.get(url + "sequence/", headers=headers)
    return response.json()

def createSequence(seqID):
    """
    Create and Launch a New Sequence

    This function creates a new sequence with specified steps.  It does not immediately launch it.
    Steps are executed based on their 'order' value, with steps having the same order
    executing simultaneously only after all previous steps are acknowledged.

    Detailed Explanation:
        - **Order of Execution:** 
            When launched, steps are executed in sequential order. 
            - Step 1 runs first. 
            - Steps with the same 'order' value run concurrently after the previous step(s) are acknowledged.
            - In this example, steps with order 2 will execute simultaneously after step 1 is acknowledged.
        
        - **Device vs Location:**
            - Each step can specify either a device directly or a location name.
            - If a location is specified instead of a device, the system uses super-string matching 
              to find the first device associated with that location. 
            - If multiple devices match, the first one found is used (which could be unpredictable).
        
        - **Command and Messaging:**
            - Each step can send multiple lines of text to the device (line1 to line5).
            - Commands like 'flash' trigger specific actions on the device.
            - Optional parameters such as 'arrow', 'seconds', 'color', and 'sound' customize the behavior.
        
        - **Acknowledgment and Nonce Handling:**
            - **stepnonce:** A unique tag sent to a feedback server when a step is acknowledged (ACK) or times out (NACK).
            - **sequencenonce:** A unique tag sent to the feedback server after the last step is acknowledged.
        
        - **Timeout Handling:**
            - Each step includes a 'seconds' parameter specifying how long to wait before timing out.
            - A timeout halts the entire sequence until the issue is resolved.

    Args:
        seqID (str): The unique identifier for the new sequence.

    Returns:
        None
    """
    sequence_data = {
        "sequenceid": seqID,
        "sequencenonce": seqID + 'Order 314 Completed',
        "steps": [
            {"order": 1, "device": "CAE96B:5DC841", "command": "flash", "line1": "Take 4", 
             "line2": "of SKU 984-534", "arrow": "left", "seconds": 300},
            {"order": 2, "location": "Warehouse Display", "command": "flash", "line1": "Betty", 
             "line2": "PICK", "barcode": "SKU 567-554", "quantity": 36, 
             "seconds": 300, "color": "g"},
            {"order": 2, "device": "D59094:AD433B", "command": "flash", "line1": "Betty", 
             "line2": "PICK", "barcode": "SKU 443-222", "quantity": 8, 
             "seconds": 300, "color": "b"},
            {"order": 4, "device": "D255D3:3A17E8", "command": "flash", "line1": "Pick", 
             "barcode": "SKU 563-559", "arrow": "left", "quantity": 4, "seconds": 30, 
             "stepnonce": "Item|4|completed", "sound": "15,c5,4"}
        ]
    }
    requests.post(url + "sequence/", headers=headers, json=sequence_data)



def readSequence(seqID):
    """
    Retrieve a Specific Sequence

    This function retrieves detailed information about a specific sequence,
    including all its steps, from the Voodoo Robotics API.

    Args:
        seqID (str): The unique identifier of the sequence.

    Returns:
        dict: A dictionary containing the sequence's details and steps.
    """
    response = requests.get(url + "sequence/" + str(seqID) + "/", headers=headers)
    return response.json()


def updateSequence(seqID):
    """
    Update an Existing Sequence

    This function updates an existing sequence by replacing its steps with new ones.
    It demonstrates how to use the HTTP PUT method to modify data via the API.

    Args:
        seqID (str): The unique identifier of the sequence to update.

    Returns:
        None
    """
    updated_data = {
        "sequenceid": seqID,
        "sequencenonce": "Order 314: Updated order completed",
        "steps": [
            {"order": 5, "location": "Warehouse Display", "command": "flash", "line1": "Betty", 
             "line2": "PICK", "barcode": "SKU 567-554", "quantity": 36, 
             "seconds": 300, "color": "g"},
            {"order": 6, "device": "D255D3:3A17E8", "command": "flash", "seconds": 10, 
             "stepnonce": "Item|4|completed", "sound": "15,c5,4"}
        ]
    }
    requests.put(url + "sequence/" + str(seqID) + "/", headers=headers, json=updated_data)


def deleteSequence(seqID):
    """
    Delete a Sequence

    This function deletes a specified sequence from the Voodoo Robotics API.

    Args:
        seqID (str): The unique identifier of the sequence to delete.

    Returns:
        None
    """
    requests.delete(url + "sequence/" + str(seqID) + "/", headers=headers)


def launchSequence(seqID):
    """
    Launch a Sequence

    This function launches a specific sequence or relaunches a stalled sequence.

    Args:
        seqID (str): The unique identifier of the sequence to launch.

    Returns:
        None
    """
    requests.get(url + "launchsequence/" + str(seqID) + "/", headers=headers)


# Example usage (uncomment to execute):
# print("Existing sequences:")
# print(json.dumps(allSequences(), indent=4))

# sequenceID = "Test_3"
# createSequence(sequenceID)
# print("Sequence created:")
# print(json.dumps(readSequence(sequenceID), indent=4))

# updateSequence(sequenceID)
# print("Sequence updated:")
# print(json.dumps(readSequence(sequenceID), indent=4))

# deleteSequence(sequenceID)
# print("Sequence deleted.")