7. Reference Guide

7.1. Proxies

# =========================================================================== # Interface between the ION and Python. Provides Proxy object to connect # to ION. # # Author: Marc Sanchez Net # Date: 04/17/2019 # Copyright (c) 2019, California Institute of Technology (“Caltech”). # U.S. Government sponsorship acknowledged. # ===========================================================================

pyion.proxies.get_bp_proxy(node_nbr)

Returns a BpProxy for a given node number. If it already exists, it gives you the already instantiated copy.

Param:

Node number

Returns:

BpProxy object

pyion.proxies.get_cfdp_proxy(peer_entity_nbr)

Returns a CfdpProxy for a given peer entity number. If it already exists, it gives you the already instantiated copy.

Param:

Peer entity number

Returns:

CfdpProxy object

pyion.proxies.get_ltp_proxy(client_id)

Returns an LtpProxy for a given client application. If it already exists, it gives you the already instantiated copy.

Param:

Client id (number)

Returns:

LtpProxy object

pyion.proxies.get_psm_proxy(node_nbr)

Return a PsmProxy for a given client application. If it already exists, it gives you th ealready instantiated copy

Parameters:

node_nbr – Node number

Returns:

PsmProxy object

pyion.proxies.get_sdr_proxy(node_nbr)

Return an SdrProxy for a given client application. If it already exists, it gives you th ealready instantiated copy

Param:

Node number

Returns:

SdrProxy object

7.2. Bundle Protocol

7.3. Licklider Transmission Protocol

# =========================================================================== # Interface between the ION’s implementation of the CCSDS LTP and Python. # Internally, all classes call the C Extension _ltp. # # Author: Marc Sanchez Net # Date: 05/30/2019 # Copyright (c) 2019, California Institute of Technology (“Caltech”). # U.S. Government sponsorship acknowledged. # ===========================================================================

class pyion.ltp.AccessPoint(proxy, client_id, sap_addr)

Bases: object

Class to represent an LTP access point.

property is_open

Returns True if the access point is opened

ltp_interrupt()

Trigger LTP to be interrupted

ltp_receive()

Trigger LTP to receive data

ltp_send(dest_engine_nbr, data)

Trigger LTP to send data

Param:

Destination engine number

Param:

Data as str, bytes or bytearray

7.4. CCSDS File Delivery Protocol

# =========================================================================== # Interface between the ION’s implementation of the CCSDS CFDP and Python. # Internally, all classes call the C Extension _cfdp. # # Author: Marc Sanchez Net # Date: 04/17/2019 # Copyright (c) 2019, California Institute of Technology (“Caltech”). # U.S. Government sponsorship acknowledged. # ===========================================================================

class pyion.cfdp.Entity(proxy, peer_entity_nbr, param_addr, endpoint, mode, closure_latency, seg_metadata)

Bases: object

Class to represent a CFDP entity.

add_filestore_request(action, file1, file2=None)

Add a user message to all CFDP PDUs in the next transaction

Parameters:

• action – See pyion.CFDP_CREATE_FILE, etc.

• file1 – String or Path-object

• file2 – None, string or Path-object.

add_usr_message(msg)

Add a user message to all CFDP PDUs in the next transaction

Parameters:

str – User message to add

cfdp_cancel()

Cancel the current CFDP transaction

cfdp_report()

Request issuance on the transmission/reception progress of the current CFDP transaction.

cfdp_request(source_file, dest_file=None, mode=None, closure_lat=None, seg_metadata=None)

Request a file to be sent to this node using CFDP

Parameters:

• source_file – str or Path of file to request

• dest_file – str or Path. Name of file at this node once it is received. Defaults to source_file

• **kwargs –

  See proxy.cfdp_send

cfdp_resume()

Resume the current CFDP transaction

cfdp_send(source_file, dest_file=None, mode=None, closure_lat=None, seg_metadata=None)

Send a file using CFDP to the peer engine for this entity

Parameters:

• source_file – str or Path of file to send

• dest_file – str or Path. Name of file at receiving engine. It defaults to source_file

• **kwargs –

  See proxy.cfdp_send

cfdp_suspend()

Suspend the current CFDP transaction

property is_open

Returns True if entity is opened

register_event_handler(event, func)

Register and event handler for this entity

Parameters:

• event – See pyion.constants.CFDP_CREATE_FILE, etc.

• func – Function handle with the following signature def ev_handler(params), where params is a dictionary with contents that depend on the type of event (see CCSDS CFDP spec, section 3.5.6)

wait_for_transaction_end(timeout=None)

Blocks the calling thread until the transaction has finished or the timeout expires.

Parameters:

timeout – Time to wait in [seconds]

Returns:

True if transaction finished successfully

7.5. ION Memory/Storage Functions

# =========================================================================== # Defines proxies to ION’s SDR and PSM so that you can monitor them. # # Author: Marc Sanchez Net # Date: 08/12/2019 # Copyright (c) 2019, California Institute of Technology (“Caltech”). # U.S. Government sponsorship acknowledged. # ===========================================================================

class pyion.mem.PsmProxy(node_nbr)

Bases: MemoryProxy

Proxy object to ION’s PSM

Variables:

• wm_key (int) – See wmKey in ionconfig. Defaults to 65281 (i.e., ION’s default value)

• wm_size (int) – Unused

• partition_name (str) – Unused

dump()

Dump the current state of the PSM

Return Tuple[Dict]:

usage summary, small pool free block count, large pool free block count

class pyion.mem.SdrProxy(node_nbr)

Bases: MemoryProxy

Proxy object to ION’s SDR

Variables:

• int – Node number

• str – SDR name (see ionconfig, option sdrName)

dump()

Dump the current state of the SDR

Return Tuple[Dict]:

usage summary, small pool free block count, large pool free block count

7.6. ION Management Functions

# =========================================================================== # Defines management ION functions. # # Author: Marc Sanchez Net # Date: 08/21/2019 # Copyright (c) 2019, California Institute of Technology (“Caltech”). # U.S. Government sponsorship acknowledged. # ===========================================================================

pyion.mgmt.bp_add_endpoint(eid, discard=True)

Define a new endpoint in ION

Parameters:

• eid (str) – E.g., ipn:1.1. (ipn:x.0 not valid)

• discard (bool) – If True, bundles arriving to and endpoint that has not application attached to it will be discarded. Otherwise they will be enqueued for later delivery.

pyion.mgmt.bp_endpoint_exists(eid)

Check if an endpoint has been defined in ION.

Parameters:

eid (str) – E.g., ipn:1.1.

Return bool:

True if endpoint is defined in ION

pyion.mgmt.bp_list_endpoints()

List all endpoints defined in ION

pyion.mgmt.cgr_add_contact(orig, dest, tstart, tend, rate, region_nbr=1, confidence=1.0, announce=True)

Add a contact to ION’s contact plan

Parameters:

• orig (int) – Node number of the contact origin

• dest (int) – Node number of the contact destination

• tstart (str) – Contact start time. Format is yyyy/mm/dd-hh:MM:ss or +0

• tend (str) – Contact end time. Format is yyyy/mm/dd-hh:MM:ss or +0

• rate (float) – Contact data rate in [bits/sec].

• region_nbr (int) – Region index. Defaults to 1.

• confidence (float) – Contact confidence. Defaults to 1.

• announce (bool) – If True, the information of this contact will be multicasted to all nodes in the region. Default is True

Warning

The contact data rate gets transformed to bytes/sec and rounded internally

pyion.mgmt.cgr_add_range(orig, dest, tstart, tend, owlt=0.0, announce=True)

Add a range to ION’s contact plan

Parameters:

• orig (int) – Node number of the contact origin

• dest (int) – Node number of the contact destination

• tstart (str) – Contact start time. Format is yyyy/mm/dd-hh:MM:ss

• tend (str) – Contact end time. Format is yyyy/mm/dd-hh:MM:ss

• owlt (float) – Range in light seconds.

• announce (bool) – If True, the information of this contact will be multicasted to all nodes in the region. Default is True

Warning

The owlt gets rounded internally

pyion.mgmt.cgr_delete_contact(orig, dest, tstart=None, region_nbr=1, announce=True)

Delete a contact from ION’s contact plan

Parameters:

• orig (int) – Node number of the contact origin

• dest (int) – Node number of the contact destination.

• tstart (str) – Contact start time. If None, all contacts between orig and dest are deleted. Format is yyyy/mm/dd-hh:MM:ss

• region_nbr (int) – Region number for this node. Defaults to 1

• announce (bool) – If True, the information of this contact will be multicasted to all nodes in the region. Default is True

pyion.mgmt.cgr_delete_range(orig, dest, tstart=None)

Delete a range from ION’s contact plan

Parameters:

• orig (int) – Node number of the contact origin

• dest (int) – Node number of the contact destination

• tstart (str) – Range start time. If None, all ranges between orig and dest are deleted. Format is yyyy/mm/dd-hh:MM:ss

pyion.mgmt.cgr_list_contacts()

List all contacts in ION’s contact plan.

Return List[Dict]:

Each dict is a contact defined as: {orig:, dest:, tstart:, tend:, rate:, confidence:, }

Tip

The data rate is returned in [bits/sec]

pyion.mgmt.cgr_list_ranges()

List all ranges in ION’s contact_plan

Return List[Dict]:

Each dict is a range defined as: {orig:, dest:, tstart:, tend:, owlt:}

pyion.mgmt.cgr_list_regions()

List all the regions defined in this ION node

Return List[int]:

List of region numbers

pyion.mgmt.ltp_span_exists(engine_nbr)

Determines if an LTP span is defined within ION.

Parameters:

engine_nbr (int) – Peer engine number.

Return bool:

True if span exists.

7.7. Constants

# =========================================================================== # This file constains all the constants used in pyion # # Author: Marc Sanchez Net # Date: 04/17/2019 # Copyright (c) 2019, California Institute of Technology (“Caltech”). # U.S. Government sponsorship acknowledged. # ===========================================================================

class pyion.constants.BpAckReqEnum(value)

Bases: IntEnum

BP application acknowledgement enumeration. See help(BpAckReqEnum)

class pyion.constants.BpCustodyEnum(value)

Bases: IntEnum

BP custody switch enumeration. See help(CustodyEnum)

class pyion.constants.BpEcsEnumeration(value)

Bases: IntEnum

BP extended class-of-service enumeration. See help(BpEcsEnumeration)

• BP_MINIMUM_LATENCY: Forward bundle on all routes

• BP_BEST_EFFORT: Send using an unreliable convergence layer

• BP_RELIABLE: Send using a reliable convergence layer

• BP_RELIABLE_STREAMING: BP_BEST_EFFORT | BP_RELIABLE

class pyion.constants.BpPriorityEnum(value)

Bases: IntEnum

BP priority enumeration. See help(BpPriorityEnum)

class pyion.constants.BpReportsEnum(value)

Bases: IntEnum

BP reports enumeration. See help(BpReportsEnum)

class pyion.constants.CfdpClosure(value)

Bases: IntEnum

Length of time following transmission of the EOF PDU within which a responding Transaction Finish PDU is expected. If no Finish PDU is requested, this parameter value should be zero.

Tip

If you need a number of seconds not specified as an option in this enumeration, simply pass it directly.

class pyion.constants.CfdpConditionEnum(value)

Bases: IntEnum

CFDP condition types. See help(CfdpConditionEnum)

class pyion.constants.CfdpDeliverCodeEnum(value)

Bases: IntEnum

CFDP delivery code enumeration. See help(CfdpDeliverCodeEnum)

class pyion.constants.CfdpEventEnum(value)

Bases: IntEnum

CFDP event types. See help(CfdpEventEnum) and Section 3.5.6 of CCSDS CFDP

class pyion.constants.CfdpFileStatusEnum(value)

Bases: IntEnum

CFDP file status enumeration. See help(CfdpFileStatusEnum)

class pyion.constants.CfdpFileStoreEnum(value)

Bases: IntEnum

CFDP file store actions. See help(CfdpFileStoreEnum)

class pyion.constants.CfdpMetadataEnum(value)

Bases: IntEnum

CFDP segment metadata options. See help(CfdpMetadataEnum)

• CFDP_NO_SEG_METADATA: No metadata added

• CFDP_SEG_METADATA: Adds current time as string to all PDUs

class pyion.constants.CfdpMode(value)

Bases: IntEnum

CFDP mode enumeration. See help(CfdpMode)

• CFDP_CL_RELIABLE: Reliability provided by the convergence layer

• CFDP_UNRELIABLE: No reliability provided

• CFDP_BP_RELIABLE: Reliability provided by BP custody transfer

7.8. Utilities

# =========================================================================== # Module with utility functions and classes for pyion # # Author: Marc Sanchez Net # Date: 04/17/2019 # Copyright (c) 2019, California Institute of Technology (“Caltech”). # U.S. Government sponsorship acknowledged. # ===========================================================================

pyion.utils.check_ion_env_vars(ION_NODE_LIST_DIR)

Check the ION environment variables to ensure they are consistent (e.g., the paths set are valid and exist in the host).

Host environment variables are only utilized if the module variables pyion.ION_PWD and pyion.ION_NODE_LIST_DIR are None.