ack_alert

add

Add a and b together and return the result.

This is a dumb method for debugging. Requires a valid sessionkey, so use this to test logging in.

add_reg_ids

boom

Test for error handling, this method attempts to divide by zero

No parameters

change_password

change_tag_pin

get_alerts

Gets a list of alert objects for the companies devices. Make the same queries as the front page.

get_companies

Get a list of companies that may be managed by the user.

Companies are returned as a list of objects containing the name, company key and logo url.

e.g. [{"name":"Microsoft", "key":10}, {"name":"Sony", "key":20, "image_url": "example.com/images/logo.png"}]

get_customer_transactions_by_date

get_device

Gets a single device

get_device_with_uid

Gets a single device

get_devices_with_locations

get_product_types

get_site_groups

get_tag_types

Gets all tag types as enum labels and values in a dict

No parameters

get_tank_samples

hello

Sends a greeting to who.

This is a test method, meant as a debugging aid.

hydip_get_customer_transactions

hydip_get_tag_detail

hydip_get_tags

hydip_get_transactions

hydip_tag_add_mobile_reg

hydip_tag_login

hydip_user_add_mobile_reg

hydip_user_login

hydip_user_mute_all

keep_alive

Does nothing except extend the session for another hour.

login

logout

sites.get_networks

auth.authorize

Connect a device with a user, and return an auth key.

auth.change_password

Change password for the user specified by sessionkey. User must submit the current password for verification

Return the following output: { "password_changed": bool, whether the password was changed "errors": list of errors, when the password could not be changed }

auth.connect_device

Connect a device with a user, and return an auth key.

auth.login

Log in a user with credentials username and password.

Most of the json rpc methods require a login, so this should be the first call before anything else. If login is successful, this method will return a string containing the session key, this value should be passed to the other methods as a parameter called sessionkey.

If login is not successful this method will return an error state.

Sessions are automatically logged out, 60 minutes after the last request.

auth.logout

Log out a given session. Subsequent calls to methods requiring a login will fail.

Not really required, since sessions expire after 60 minutes, but this is good house-keeping, and can protect against potential exploits.

auth.reset_password

Looks up user by the specified email. Tries to send the password reset link; returns the following structure:

{ "reset_email_sent": True, if user was found False, otherwise }

devices.get_devices_by_asset_tag

endusers.assign_tag

This method binds Tag specified by tag_uid to the customer specified by enduser_uid

endusers.create_enduser

Creates Customer object.

The input data has the following allowed fields:

{
    'address1': <string>, // first line of address lines
    'address2': <string>, // second line of address lines
    'address3': <string>, // third line of address lines
    'cash_limit': <optional string>, // cash limit
    'cash_prepay_limit': <optional string>, // limit for cash prepay
    'credit_type': <int>, allowed values: 1 - Cash, 2 - Volume
    'email': <optional string>,
    'external_customer_id': <optional string>,
    'tel': <string>,
    'mobile': <string>,
    'multiproduct_limit': None,
    'mute_all_notifications': <boolean>,
    'name': <string>,
    'notes': <optional string>,
    'organization': <string>,
    'payment_type': <int>, possible values: 0 - pre-pay, 1 - daily limit,
    'pin': <optional string>,
    'send_email': <boolean>,
    'suspended': <boolean>,
    'zipcode': <string>,
}

endusers.get_endusers_by_network

Get list of Customers.

Returned in the following format:

[
    {
        'address1': '',
        'address2': '',
        'address3': '',
        'cash_limit': None,
        'cash_prepay_limit': None,
        'credit_type': 1,
        'email': None,
        'external_customer_id': None,
        'mobile': '',
        'multiproduct_limit': None,
        'mute_all_notifications': False,
        'name': 'treyes',
        'notes': None,
        'number': '0',
        'organization': '',
        'payment_type': 0,
        'pin': None,
        'send_email': False,
        'suspended': False,
        'tel': '',
        'uid': '498961e0-0bd2-4f46-a219-58f0cc2f6759',
        'zipcode': '',
    }
]

Returns: List[EndUserDict]: List of serialized EndUser objects

endusers.remove_enduser

This function moves all enduser tags to inventory and removes the user

hydip.change_tag_pin

Changes the tag pin

hydip.get_customer_info

Get customer info for logged in user.

hydip.get_customer_transactions

Gets customer transactions for the hydip app

hydip.get_customer_transactions_by_date

Get customer transactions. Transaction limit: 500.

Request example:

"filters":
    {
        "date":
        {
            "start": "2016-01-26 00:16:00" | "2016-01-01",
            "end": "2016-01-26 00:35:00" | "2018-01-01"
        }
    }
}

hydip.get_tag_detail

Get information regarding a logged in tag.

A successful response will return the following:

{
    "tag": <string>,
    "tag_id": <string: identifier for tag to be used in queries>,
    "tag_number": <string: formatted tag number for display>,
    "cust_name": <string: Customer name>,
    "address": <string: hex offset of tag in nems memory>,
    "hash": <string: hash of tag>,
    "source": <string: 'UI' or 'IMPORTED'>,
    "type": <integer: tag type>,
    "credit_type": <string: 'INVALID', 'CASH', or 'VOLUME'>,
    "credit type_id": <integer: 0, 1, 2>,
    "credit_type_label": <string: 'invalid', 'cash', or 'volume'>,
    "pay_class": <string: 'CASH_DAILY_LIMIT', 'CASH_PRE_PAY', 'VOLUME_DAILY_LIMIT', 'VOLUME_PRE_PAY'> or null,
    "pay_class_id": <integer: 0, 1, 2, 3> or null
    "pay_class_label": <integer: 'cash daily limit', 'cash_prepay', 'vol. daily limit', 'vol.prepay'> or null,
    "products": <list of string: names of products enabled on tag>,
    "credit": <number>,
    "muted": <boolean: notifications muted>,
    "reset_time": <number or null: epoch time of next reset or null for no rest time>
    "amount_used": <number: amount of tag used>,
    "limit": <number>,
    "phone_support_number": <optional str>,
}

hydip.get_tags

Returns tags for a hydip user

hydip.get_transactions

Returns list of transactions for the currently logged in tag Args: request (HttpRequest): Django HTTP Request object sessionkey (str): session ID for the currently logged in tag page (int, optional): page number. Defaults to 1. limit (int, optional): number of items per page. Defaults to 10. filters (StringMap, optional): Additional filters for the queryset. Defaults to {}. Returns: List[StringMap]: List of transactions

hydip.tag_add_mobile_reg

Adds the mobile reg id to the tag object

hydip.tag_login

Logs in with a tag number and a PIN.

On success, the response will be:

{
    "Session_key": <str>,
    "pin_change_enabled": <bool>,
    "customer_info" : <dict or None> {
        "name": <str>,
        "addr1": <str>,
        "addr2": <str>,
        "zip": <str>,
        "tel": <str>,
        "mobile": <str>
    },
    "database_id": <optional int>,
    "database_name": <optional str>,
    "company_id": <optional str>
}

hydip.user_add_mobile_reg

Adds the mobile reg id to the EndUser object

hydip.user_login

Logs a user in from a customer id and a PIN. Returns object containing session_key and other information.

{
    "session_key": <string>,
    "customer_info" : <object> {
        "name": <string>,
        "addr1": <string>,
        "addr2": <string>,
        "zip": <string>,
        "tel": <string>,
        "mobile": <string>
    },
    "mute_all": <boolean>,
    "database_id": <optional integer>,
    "database_name": <optional string>,
    "company_id"" <optional str>
}

hydip.user_mute_all

Mutes notifications for a user

network.create_tag

Create a tag specified by tag_data properties. The tag will either be created anew or moved from the inventory, if it exists there.

Tag details are specified as following:

{
    tag_number: str - tag number encoded as string
    tag_system: str - tag system. this field can be one of two values: mifare or ti
    customer: Optional[str] - the UID of customer that the new tag will be assigned to
    tag_type: int - tag type. Allowed values:
         1 (Tag)
         2 (Card)
         3 (Odometer required)
         4 (UID requied)
         5 (UID and Odometer required)
    credit_type: str. Allowed values:
         'CASH'
         'VOLUME'
    product_mask: list[int] - List of product types to support
    pin: Optional[str]
    suspended: bool
    daily_limits: list[tuple[int, Optional[int]]]
    metered_product_daily_limit: Optional[int]
    vehicle_reg: str
    vehicle_model: str
    vehicle_fleet_no: str
}

network.get_network_tags

Get tag objects that belong to a network specified by network_uid.

This method returns the following response:

[
    tag_detail,
    tag_detail,
    ...
]

where tag_detail is the same response as in hydip.get_tag_detail, i.e.:

{
    "tag": <string>
    "tag_id": <string, identifier for tag to be used in queries>,

    ...

    and so on
}

network.get_network_transactions

Get a list of transactions, with an option date range. If start and end are supplied, they should be given as seconds since the epoch.

A transaction contains the following information:

{
    "tag": <string tag id>,
    "device": <device key>,
    "customer": <string customer id>,
    "id": <string unique identifier for this transaction>,
    "start": <float start time>,  # as seconds since the epoch)
    "stop": <float stop time>,    # as seconds since the epoch
    "seq_num": <integer sequence number>,
    "product": <integer product enum (see fueltracking.import)>,
    "volume": <float volume dispensed>,
    "price": <float price of transaction>,
    "unit_price": <float price per unit of volume>,
    "status": <integer transaction status bits (see below)>
    "dispenser_index": <integer index of dispense>,
    "credit": <float credit applied>,
    "debit": <float debit applied>,
    "source": <integer source enum>,
    "odometer": <integer value of odometer>,
    "userid": <integer user ID>,
    "hosenumber": <integer index of hose>,
    "network_uid": <uuid uid of network>,
    "currency_display": <string currency>,
    "units_display": <string units of measurement (e.g litres)>,
    "device_name": <string device name>,
    "product_name": <string readable product label from enum>,
    "credit_type": <string readable credit type label from enum>,
    "dispenser_index": <string hose number>,
    "user_friendly_tagid": <string user friendly tag id>
}

Transaction status bits:

INVALID_ID = 1 << 0
ID_SEARCH_FAIL = 1 << 1
OUT_OF_CREDIT = 1 << 2
PIN_INCORRECT = 1 << 3
PIN_ENTRY_TIMEOUT = 1 << 4
DISPENSE_TIME_EXCEEDED = 1 << 5
COMM_ERR = 1 << 6
PWR_FAIL = 1 << 7
BCB_COMM_FAIL = 1 << 8
USER_ID_ENTRY_TIMEOUT = 1 << 9
ODOMETER_ENTRY_TIMEOUT = 1 << 10
RESTRICTED_FUEL_BIT = 1 << 11
CREDIT_CHECK = 1 << 12

Transaction source enum:

UNKNOWN = 0 (not used)
DEVICE = 1 (transaction was a device)
ADMIN = 100 (transaction was from admin)

network.get_new_transactions

Get new transactions since a previous call.

This method retrieves new transaction based on an update_index. On the first call to this method, update_index should be 0, which will return all transactions. A new value for update_index will be returned along with the transactions. Subsequent calls should use the update_index from the previous calls. This ensures that only new transactions will be returned.

This method returns the following response. The list of transactions is in the same format as the get_network_transactions method.

{
    "update_index": <integer update index>,
    "transactions": <list of transactions>
}

network.get_recent_transactions

Get a list of recent transactions, default limit of 50.

A transaction contains the following information:

{
    "tag": <string tag id>,
    "device": <device key>,
    "customer": <string customer id>,
    "id": <string unique identifier for this transaction>,
    "start": <float start time>,  # as seconds since the epoch)
    "stop": <float stop time>,    # as seconds since the epoch
    "seq_num": <integer sequence number>,
    "product": <integer product enum (see fueltracking.import)>,
    "volume": <float volume dispensed>,
    "price": <float price of transaction>,
    "unit_price": <float price per unit of volume>,
    "status": <integer transaction status bits (see below)>
    "dispenser_index": <integer index of dispense>,
    "credit": <float credit applied>,
    "debit": <float debit applied>,
    "source": <integer source enum>,
    "odometer": <integer value of odometer>,
    "userid": <integer user ID>,
    "hosenumber": <integer index of hose>,
    "network_uid": <uuid uid of network>,
    "currency_display": <string currency>,
    "units_display": <string units of measurement (e.g litres)>,
    "device_name": <string device name>,
    "product_name": <string readable product label from enum>,
    "credit_type": <string readable credit type label from enum>,
    "dispenser_index": <string hose number>,
    "user_friendly_tagid": <string user friendly tag id>
}

Transaction status bits:

INVALID_ID = 1 << 0
ID_SEARCH_FAIL = 1 << 1
OUT_OF_CREDIT = 1 << 2
PIN_INCORRECT = 1 << 3
PIN_ENTRY_TIMEOUT = 1 << 4
DISPENSE_TIME_EXCEEDED = 1 << 5
COMM_ERR = 1 << 6
PWR_FAIL = 1 << 7
BCB_COMM_FAIL = 1 << 8
USER_ID_ENTRY_TIMEOUT = 1 << 9
ODOMETER_ENTRY_TIMEOUT = 1 << 10
RESTRICTED_FUEL_BIT = 1 << 11
CREDIT_CHECK = 1 << 12

Transaction source enum:

UNKNOWN = 0 (not used)
DEVICE = 1 (transaction was a device)
ADMIN = 100 (transaction was from admin)

network.import

Import tag database. On success this method returns a dictionary containing statistics regarding the number of objects that were newly imported, modified or suspended. If the import fails for some reason an error code 7 will be returned, along with a (hopefully) helpful error message.

Customers and tags are given as a list of objects. Any enduser or tag that was previously imported, but not in this call will be marked as 'suspended'.

A customer should contain one or more of the following fields:

{
    "id": <string customer id (required)>,
    "name": <string customer name>,
    "address1": <string address line 1>,
    "address2": <string address line 2>,
    "address3": <string address line 3>,
    "zipcode": <string zipcode>,
    "tel": <string telephone number>,
    "mobile": <string mobile number>,
    "notes": <string free notes field>,
    "suspended": <boolean true if user is suspended>,
    "balances": <list of balances, where a balance is a list of [<product enum>, <product value>]>,
    "daily_limits": <list of balances, as balances, but the value may also be null>,
    "payment_type": <integer payment type enum> (see below)
    "driver_ids": <list of allowed driver ids>
}

Payment type enum:

PRE_PAY = 0
DAILY_LIMIT = 1

The following is an example value for balances, were water is 100 liters and ADBLUE is 300 liters:

[[1, 100], [6, 300]]

A tag should contain one or more of the following fields:

{
    "id": <string tag id (required)>,
    "customer": <string id of customer who has this tag>,
    "tag_type": <integer TAG=1, CARD=2, ODOM_REQ=3, UID_REQ=4, UID_ODOM_REQ=5 (required)>,
    "credit_type": <integer CASH=1, VOLUME=2>,
    "product_mask": <list of integers (see products enum below)>
    "pin": <string for PIN number, or null for no PIN>,
    "suspended": <boolean true if this card may not be used>,
    "daily_limits": <list of per-tag daily limits, given as a list of [<product enum>, <product value>] (value may be null to indicate no limit)>,
    "metered_product_daily_limit": <number for daily limit for volume tags with multiple products, or null>,
    "vehicle_reg": <user defined vehicle reg number>,
    "vehicle_model": <user defined vehicle model>,
    "vehicle_fleet_no": <user defined vehicle fleet number>
}

Product enum:

RESERVED_0 = 0
WATER = 1
DIESEL = 2
PREMIUM_UNLEADED = 3
UNLEADED = 4
LEADED = 5
ADBLUE = 6
OIL = 7
LPG = 8
KEROSENE = 9
AVGAS = 10
JETA1 = 11
CNG = 12
MPD = 13
RESERVED_1 = 14
RESERVED_2 = 15

network.remove_tag

Unassigns the tag from network

networks.get_networks

Get a list of networks.

Returned in the followed format:

[
    {
        "name": <Network name>,
        "key": <Company key>
    }
]

networks.get_product_types

Gets all product types as enum labels and values in a dict. If a session key is given, the product names will be returned for the associated network, otherwise global names will be returned.

pricezones.get_pricezone

Get price zone for a given network.

Returns the following:

{
    "key": <price zone key>,
    "name": <price zone name>,
    "prices": {
        "<product name>": "<price or empty string>"
    },
    "prices_enum": {
        "<product enum>": "<price or empty string>"
    },
}

Prices are encoded as a strings (to avoid floating point error). An empty string indicates a null price (i.e. no price set).

pricezones.get_pricezones

Get pricezones for a given network.

Returns a list of objects for each price zone, in the following format:

[
    {
        "key": <price zone uid>,
        "name": <price zone name>,
        "prices": {
            <product name>: <product price>
        },
        "prices_enum": {
            <product enum>: <product price>
        }
    }
]

Prices are encoded as a strings (to avoid floating point error). An empty string indicates a null price (i.e. no price set).

pricezones.set_pricezone

The price_data should be an object which maps the product on to the price.

The product should be an integer product enumeration. The price should be a string containing a price to three decimal places.

The product may also be string containing the product name, i.e. "diesel", but this is for backwards compatibility only.

Products not included in price_data will be left unchanged.

Return value is always True.

sites.get_site_groups

sites.get_site_objects

sites.get_sites

sites.get_sites_in_range

Get the sites within a given radius from a location.

Response is the same as get_sites with the following additions:

"distance" is the distance to the site in km

"tanks" is a list of tanks in the site, exposing "name", "key", "product", "last_sample_time", and "last_sample_level"

"devices" is a list of the devices in a site, exposing "name", "key" and "gps"

sites.get_sites_with_objects_gps

Gets a list of sites in a network, and the gps coords of the site, devices and tanks

sites.get_tank_samples

Get a range of tank dips for a given device from start to end. If start is omitted then the start will be from the first available sample, if end is omitted, samples up to the most recent will be returned.

Samples are returned as a list of tuples where each tuple contains the timestamp and volume.

sites.get_tanks_by_asset_tag

tanks.get_latest_samples

Get latest samples for all tanks the user has access to.

Return value is a mapping of tank key to a list of two values, containing sample time and sample level.

{
    <tank key>: [<sample time>, <sample level>],
    etc...
}

The sample pairs may also be [null, null] if the tank has never recorded a sample.

tanks.get_tank_groups

Gets the tank groups that the user has permission to see

tanks.get_tanks

Get tank objects for network and company