# Special objects for scripts

## Overview

Special objects are available within processing scripts to provide enhanced management capabilities for **Devices** and their **Settings**. These objects can be referenced directly in your scripts to perform various operations and modify device attributes.

---

## The `device` Object

The script execution context includes a special `device` object that allows you to modify attributes of the managed **Device** and perform related actions and operations.

### Attributes

The `device` object provides the following attributes:

| Name | Type/Access | Description |
|------|-------------|-------------|
| `obj_id` | integer<br><small>(read-only)</small> | Numeric unique identifier of the current device |
| `name` | string<br><small>(read-write)</small> | Device name field |
| `customer_id` | string<br><small>(read-write)</small> | Customer ID field of the current device |
| `type_id` | integer<br><small>(read-only)</small> | Numeric identifier of the device's profile |
| `organization_id` | integer<br><small>(read-only)</small> | Numeric identifier of the device's organization |
| `serial_number` | string<br><small>(read-write)</small> | Serial number field of the current device |
| `serial_number_alt` | string<br><small>(read-write)</small> | Alternate serial number field of the current device |
| `status` | boolean<br><small>(read-only)</small> | Operational status of the device |
| `status_change` | datetime<br><small>(read-only)</small> | Date/time of the last status change |
| `last_connection` | datetime<br><small>(read-only)</small> | Date/time of the last connection from the device to the platform |
| `update_frequency` | integer<br><small>(read-write)</small> | Device's update frequency or periodic report interval (in seconds). Changes to this attribute will trigger a connection request |
| `software_version` | string<br><small>(read-only)</small> | Software version information as reported by the device |
| `hardware_version` | string<br><small>(read-only)</small> | Hardware version information as reported by the device |
| `address` | string<br><small>(read-only)</small> | Management address used by the device to connect to the platform |
| `description` | string<br><small>(read-write)</small> | Description field of the current device |
| `description2` | string<br><small>(read-write)</small> | Second description field of the current device |
| `description3` | string<br><small>(read-write)</small> | Third description field of the current device |
| `description4` | string<br><small>(read-write)</small> | Fourth description field of the current device |
| `reboot` | boolean<br><small>(read-write)</small> | Activate the 'Reboot' action on the device or detect if a 'Reboot' action is pending |
| `factory` | boolean<br><small>(read-write)</small> | Activate the 'Factory reset' action on the device or detect if a 'Factory reset' action is pending |
| `device_factory` | boolean<br><small>(read-write)</small> | Activate the 'Remote (device only) factory reset' action or detect if the action is pending |
| `factory_remote` | boolean<br><small>(read-write)</small> | Alias for `device_factory`. Activate the 'Remote (device only) factory reset' action or detect if the action is pending |
| `sync` | boolean<br><small>(read-write)</small> | Activate the configuration 'Synchronization' action with the device or detect if the action is pending |
| `reconf` | boolean<br><small>(read-write)</small> | Activate the device 'Reconfiguration' action or detect if the action is pending |
| `location_id` | integer<br><small>(read-write)</small> | Normalized location ID assigned to the device |
| `location_name` | string<br><small>(read-write)</small> | Non-normalized location name assigned to the device |
| `latitude` | float<br><small>(read-write)</small> | Latitude geographical coordinate of the device |
| `longitude` | float<br><small>(read-write)</small> | Longitude geographical coordinate of the device |
| `firmware_image_id` | integer<br><small>(read-write)</small> | Numeric identifier of the firmware image that can be applied to the device |
| `firmware_image_is_pending` | boolean<br><small>(read-write)</small> | Indicates whether the configured firmware image will be applied to the managed device |

### Methods

The `device` object provides the following methods:

#### `save()`

Save changes made to the device's read-write attributes.

**Returns:**
- `status` (boolean)
- `message` (string)

**Example:**
```python
status, message = device.save()
```

---

#### `set()`

Change the value of a specified **Parameter** by its `parameter_name`, `variable_name`, or `parameter_id`.

**Parameters:**
- `parameter_name` (string) – Parameter name identifier
- `variable_name` (string) – Variable name identifier
- `parameter_id` (integer) – Numeric parameter identifier
- `value` (string) – New value to set

**Returns:**
- `status` (boolean) – Operation status
- `message` (string) – Operation message
- `created` (boolean) – Whether a new parameter was created
- `changed` (boolean) – Whether the value was changed
- `old_value` (string) – Previous value

**Examples:**
```python
status, message, created, changed, old_value = device.set(parameter_id=100, value='test')

device.set(parameter_name='Device Name', value='test')

device.set(variable_name='Device.SystemID', value='test')
```

---

#### `get()`

Retrieve the value of a specified **Parameter** by its `parameter_name`, `variable_name`, or `parameter_id`.

**Parameters:**
- `parameter_name` (string) – Parameter name identifier
- `variable_name` (string) – Variable name identifier
- `parameter_id` (integer) – Numeric parameter identifier

**Returns:**
- `value` (string) – Parameter value
- `found` (boolean) – Whether the parameter was found

**Examples:**
```python
value, found = device.get(parameter_id=100)

value, _ = device.get(parameter_name="Uptime")

value, _ = device.get(variable_name='Device.SystemID')
```

---

#### `delete()`

Delete a setting from the device database specified by its parameter's `parameter_name`, `variable_name`, or `parameter_id`.

**Parameters:**
- `parameter_name` (string) – Parameter name identifier
- `variable_name` (string) – Variable name identifier
- `parameter_id` (integer) – Numeric parameter identifier

**Returns:**
- `deleted` (boolean) – Whether the parameter was deleted
- `message` (string) – Operation message

**Examples:**
```python
deleted, message = device.delete(parameter_id=100)

device.delete(parameter_name='Uptime')

device.delete(variable_name='Device.SystemID')
```

---

#### `cwmp_set()`

Perform a CWMP SetParameterValues operation on devices managed by CWMP/TR-069.

**Parameters:**
- `variable_name` (string, required) – Variable name to set
- `value` (string, required) – Value to assign
- `variable_type` (string, optional) – Type of parameter (default: `'string'`). Options: `'string'`, `'boolean'`, `'integer'`, `'positive'`
- `log` (boolean, optional) – Enable operation logging (default: `False`)
- `disable_connreq` (boolean, optional) – Disable CWMP connection request after the operation (default: `False`)

**Examples:**
```python
device.cwmp_set(variable_name='Device.SystemID', value='test')

device.cwmp_set(variable_name='Device.SystemID', value='test', variable_type='string', log=True, disable_connreq=True)
```

---

#### `connection_request()`

Perform a connection request to the managed device.

**Parameters:**
- `wait` (boolean, optional) – Wait for connection request response or timeout (default: `False`)
- `sleep_time` (float, optional) – Wait time between operations in seconds (default: `0.05`)
- `type` (string, optional) – Connection request type: `'regular'` or `'light'` (default: `'regular'`)

**Example:**
```python
device.connection_request(wait=False, type='light')
```

---

#### `alert_clear()`

Clear any active alert on the managed device.

**Example:**
```python
device.alert_clear()
```

---

#### `ping()`

Perform an ICMP ping from the platform to the device's management address.

**Parameters:**
- `count` (integer, optional) – Number of packets to send (default: `2`, maximum: `10`)
- `timeout` (integer, optional) – Timeout in seconds (default: `1`, maximum: `10`)

**Returns:**
- `status` (boolean) – Ping operation status
- `message` (string) – Operation message
- `packet_loss` (integer) – Packet loss percentage

**Example:**
```python
status, message, packet_loss = device.ping()
```

---

#### `get_or_create()`

Get or create a device with the specified parameters. Commonly used with the `csv_row` variable.

**Parameters:**
- `name` (string, optional) – Device name
- `serial_number` (string, optional) – Serial number
- `serial_number_alt` (string, optional) – Alternate serial number
- `username` (string, optional) – Username
- `location_id` (integer, optional) – Location ID

**Returns:**
- `device_obj` (device object) – Device object on which you can perform operations

**Examples:**
```python
device_obj = device.get_or_create(name=csv_row[0])

device_obj = device.get_or_create(name="device_name", username="username")
```

---

#### `get_obj()`

Retrieve a device with the specified parameters. Commonly used with the `csv_row` variable.

**Parameters:**
- `name` (string, optional) – Device name
- `serial_number` (string, optional) – Serial number
- `serial_number_alt` (string, optional) – Alternate serial number
- `username` (string, optional) – Username
- `location_id` (integer, optional) – Location ID
- `organization_id` (integer, optional) – Organization ID

**Returns:**
- `found` (boolean) – Whether the device was found

**Note:** When a device is found, the `device` variable is converted to the corresponding device object.

**Examples:**
```python
found = device.get_obj(name=csv_row[0])

found = device.get_obj(name="device_name", username="username")
```

---

#### `delete_obj()`

Delete the current device object.

**Returns:**
- `deleted` (boolean) – Whether the device was deleted

**Example:**
```python
deleted = device.delete_obj()
```

---

#### `update_location()`

Update or clear the device location.

**Parameters:**
- `id` (integer, optional) – Location ID
- `name` (string, optional) – Location name
- `short_name` (string, optional) – Location short name

**Returns:**
- `updated` (boolean) – Whether the location was updated
- `message` (string) – Operation message

**Examples:**
```python
updated, message = device.update_location(name="Location name")

updated, message = device.update_location(short_name="loc-short-name")

# Clear the current location
updated, message = device.update_location()
```

---

#### `group_list()`

List the groups the device belongs to.

**Parameters:**
- `short_name` (boolean, optional) – Return short names instead of IDs (default: `False`)

**Returns:**
- `group_list` (list) – List of group IDs or short names

**Examples:**
```python
group_list = device.group_list()

group_list = device.group_list(short_name=True)
```

---

#### `group_add()`

Add the device to a specified group.

**Parameters:**
- `id` (integer, optional) – Group ID
- `short_name` (string, optional) – Group short name

**Returns:**
- `updated` (boolean) – Whether the device was added to the group
- `message` (string) – Operation message

**Examples:**
```python
updated, message = device.group_add(id=45)

updated, message = device.group_add(short_name="group-short-name")
```

---

#### `group_remove()`

Remove the device from a specified group.

**Parameters:**
- `id` (integer, optional) – Group ID
- `short_name` (string, optional) – Group short name

**Returns:**
- `updated` (boolean) – Whether the device was removed from the group
- `message` (string) – Operation message

**Examples:**
```python
updated, message = device.group_remove(id=45)

updated, message = device.group_remove(short_name="group-short-name")
```

---

### Script Examples

**Example 1: Update device description and set parameter**
```python
result = value
device.description = value
device.save()
status, message, created, changed, old_value = device.set(variable_name='Device.SystemID', value=value)
if changed:
    device.connection_request()
```

**Example 2: Update alternate serial number based on variable name**
```python
result = value
if variable_name == 'Device.X_LTE_INFO.imei':
    device.serial_alt = value
    device.save()
```

**Example 3: Build description from multiple parameters**
```python
result = value
if variable_name == 'Device.SystemInfo.Manufacturer':
    imsi = device.get(variable_name='Device.X_LTE_INFO.imsi')
    if imsi:
        device.description2 = '%s - imsi: %s' % (value, imsi)
    else:
        device.description2 = value
    device.save()
```

**Example 4: Conditional connection request based on ping results**
```python
if device.status is False:
    ping_status, ping_message, ping_packet_loss = device.ping()
    if ping_status is True and ping_packet_loss < 50:
        # Send connection request if the device is reachable and packet loss is less than 50%
        device.connection_request()
```

---

## The `csv_row` Object

When a script is executed over a CSV file, the code defined in the **script** field is applied to every row of the CSV file. The `csv_row` object (array) is available within the script context, containing the values from the current row.

### CSV Processing Example

The following example demonstrates updating device coordinates from a CSV file with the format: `[device_name, latitude, longitude]`

```python
# Updating device coordinates with info from CSV file
# CSV format: [device_name, latitude, longitude]

# Look up the device using the serial number (or "name")
found = device.get_obj(serial_number=csv_row[0])
latitude = csv_row[1]
longitude = csv_row[2]

if found:
    # Set latitude and longitude
    device.latitude = latitude
    device.longitude = longitude
    # Save changes
    device.save()
    # Show success message
    out = "Updated the coordinates on Device: %s" % csv_row[0]
else:
    # Device not found
    out = "Not found serial_number: %s" % csv_row[0]
```