4. Modules¶

4.1. Endpoint¶

An endpoint is an OMCI client or server.

Endpoints are modeled by instances of the Endpoint class. Examples:

client = Endpoint((address, port), is_server=False, cterm_name='foo',
                  onu_id_range=range(100))
message = ...
client.send(message)
response, address = client.recv()
client.process(response)

server = Endpoint((address, port), is_server=True, cterm_name='foo',
                  onu_id_range=range(100))
message, address = server.recv()
response = server.process(message)
if response:
    server.send(response, address)

class obbaa_onusim.endpoint.Endpoint(server_address, *, is_server=True, cterm_name=None, onu_id_range=None, tr451=True, timeout=10, dumpfd=None)¶

Bases: object

Models an OMCI client or server instance.

Note

There should probably be an Endpoint base class with Client and Server subclasses.

__init__(server_address, *, is_server=True, cterm_name=None, onu_id_range=None, tr451=True, timeout=10, dumpfd=None)¶

Create an OMCI endpoint instance.

Parameters

server_address (Tuple[str, int]) – Server address (and port). Clients send to this address; servers listen on it.
is_server (bool) – Whether or not this endpoint is a server.
cterm_name (Optional[str]) – Channel termination name. Clients include this name in all messages. Servers will process only messages that contain it.
onu_id_range (Optional[range]) – ONU id range, e.g. range(10) means ONU ids 0, 1, …9. Ignored by clients. Servers will process only messages that contain one of these ONU ids.
tr451 (bool) – Whether to process TR-451 (cterm_name, onu_id) headers.
timeout (int) – Clients will time out after this number of seconds. Ignored by servers.
dumpfd (Optional[IO[str]]) – File to which to send hex dumps of all sent and received messages (ignoring the TR-451 header).

recv(*, bufsize=2048)¶

Receive a buffer from the server socket and decode it as a message.

Parameters: bufsize (int) – Buffer size in bytes.
Return type: Tuple[Message, Tuple[str, int]]
Returns: Decoded message and the address from which it was received.

process(message)¶

Process a received message.

Parameters: message (Message) – Message to process.
Return type: Optional[Message]
Returns: None (if no response is requested) or the response.

Note

Messages that don’t have an expected cterm_name or onu_id will be ignored and no response will be sent. This is probably wrong.

send(message, address=None)¶

Send a message to the server or the specified address.

Parameters

message (Message) – Message to send.
address (Optional[Tuple[str, int]]) – Address to send the message to. Defaults to the server address.

Return type

None

property server_address¶

Server address.

Return type: Tuple[str, int]

property database¶

Database object.

Return type: Database

__str__()¶: Return str(self).

4.2. Messages and Actions¶

Message classes¶

OMCI messages are modeled by subclasses of the Message base class.

Message instances can be created in two ways:

Directly via Message.__init__: this is how clients create requests and servers create responses and notifications

By calling Message.decode to decode a received message: this is how servers decode requests and clients decode responses and notifications

Examples:

values = {'battery_backup': True}
message = Set(cterm_name='foo', onu_id=42, tci=42, extended=False,
              me_class=256, me_inst=0, values=values)

# common fields can be put in a dictionary and used like this
common = {'cterm_name': 'foo', 'onu_id': 42, 'tci': 42, 'extended': False}
message = Set(me_class=256, me_inst=0, values=values, **common)

buffer, address = sock.recvfrom(bufsize)
message = Message.decode(buffer)

# the __str__() method returns a user-friendly string representation
print(message)

class obbaa_onusim.message.Message(_no_validate=False, **fields)¶

Bases: object

Message base class.

The methods are documented in a logical order corresponding to a message’s life-cycle:

__init__ constructs the message from its field values
encode converts the message to an OMCI buffer
(the buffer is now presumably sent over the network)
decode converts an OMCI buffer back to a message
process processes the message, maybe constructing a response message

__init__(_no_validate=False, **fields)¶

Message base class constructor.

Subclasses will not usually need to provide their own constructors because they can supply their own fields via the base class constructor.

Parameters

_no_validate (bool) – This is for internal use only.
**fields –
Keyword arguments. There are several categories of field:
1. The TR-451 header fields (cterm_name, onu_id=42) must always be supplied
2. The OMCI message type fields (type_ar, type_ak, type_mt) are handled automatically and so must not be supplied
3. These OMCI header fields have defaults but can be overridden:
  - tci (Transaction Correlation Identifier); 0-65535; default 0
  - extended (whether to use extended messages); default False
4. These OMCI header fields do not have defaults and therefore must be supplied:
  - me_class (Managed Entity Class); 0-65535
  - me_inst (Managed Entity Instance); 0-65535
5. Any additional fields are message type specific

Note

Message base class instances can’t be instantiated. Only instances of subclasses, e.g. Set and Get, can be instantiated.

validate()¶

Validate a message, returning a dictionary of modified fields.

This is primarily intended for when an application calls the constructor directly and therefore have supplied some invalid fields.

If this method detects an unrecoverable error, it should raise an exception.

The base class implementation just returns an empty dictionary. Subclasses should override this method.

Return type: Dict[str, Union[bytes, int, str, dict, list]]
Returns: Dictionary mapping field names to field values. The instance will be updated with these fields.

encode(*, tr451=True)¶

Encode this message into a buffer.

Parameters: tr451 (bool) – Whether to add a TR-451 header to the buffer.
Return type: bytearray
Returns: The encoded buffer.

encode_contents()¶

Encode this message’s contents, i.e. its type-specific payload.

The base class implementation just returns an empty buffer. Subclasses should override this method.

Return type: bytearray
Returns: Encoded buffer.

classmethod decode(buffer, *, tr451=True)¶

Decode a buffer, returning a Message instance of the appropriate type.

Parameters

buffer (Union[bytes, bytearray]) – Buffer, e.g. just received from a socket.
tr451 (bool) – Whether the buffer has a TR-451 header.

Return type

Message

Returns

Message instance of the appropriate type.

decode_contents(contents)¶

Decode this message’s contents, i.e. its type-specific payload.

Parameters: contents (bytearray) – The contents part of the buffer.
Return type: Dict[str, Union[bytes, int, str, dict, list]]
Returns: Dictionary mapping field names to field values. The instance will be updated with these fields.

process(endpoint)¶

Pass this message to the endpoint for processing, and return the response (if any).

Parameters: endpoint (object) – Endpoint to which to pass the message for processing.
Return type: Optional[Message]
Returns: The response, or None if there is no response.

get(name, default=None)¶

Get the value of the named field.

Parameters

name (str) – Field name.
default (Union[bytes, int, str, dict, list, None]) – Value to return if the field doesn’t exist.

Return type

Union[bytes, int, str, dict, list]

Returns

Field value.

Note

It will usually be more convenient to rely on the fact that __getattr__ has been defined to return field values directly. Assuming that field foo exists, these are the same:

self.get('foo')
self.foo

As with dictionaries, if you’re not sure whether the field exists, it’s safer to use get().

set(name, value)¶

Set the value of the named field.

Parameters

name (str) – Field name.
value (Union[bytes, int, str, dict, list]) – Field value.

Note

The field name isn’t checked, so it’s possible to inadvertently create new fields using this method.

Return type: None

__str__()¶

Return a user-friendly representation of a message.

Example:

values = {'battery_backup': True}
message = Set(cterm_name='foo', onu_id=42, tci=84, me_class=256,
              me_inst=0, values=values)
print(message)

->

Set(attr_mask=0x400, cterm_name='foo', extended=False,
    me_class=256, me_inst=0, onu_id=42, tci=84,
    values={'battery_backup': 1})

Note

Oops. This example shows that value conversion between user and raw units isn’t yet complete.

Return type: str

Action classes¶

An action is an operation, typically involving a command/response message round-trip.

class obbaa_onusim.action.Action(number, name, description=None, request=None, response=None)¶

Bases: obbaa_onusim.types.NumberName, obbaa_onusim.types.AutoGetter

Action class.

__init__(number, name, description=None, request=None, response=None)¶

Action constructor.

Parameters

number (int) – Action number. This is the OMCI message type ( type_mt) for the action’s request and response messages.
name (str) – Action name. This is only used for documentation purposes.
description (Optional[str]) – Action description. This is only used for documentation purposes.
request (Optional[Type[Message]]) – Request message class.
response (Optional[Type[Message]]) – Response message class. If None no response is expected.

class obbaa_onusim.action.Arg(number, name, description=None, data=None, cond=None)¶

Bases: obbaa_onusim.types.NumberName, obbaa_onusim.types.AutoGetter

__init__(number, name, description=None, data=None, cond=None)¶: Initialize self. See help(type(self)) for accurate signature.

Set action¶

The Set action’s messages are defined in G.988 A.2.5-6 (extended) and A.3.5-6 (baseline).

The relevant classes and instances are:

Set: Set command message class
SetResponse: Set response message class
set_action: Set action instance

class obbaa_onusim.actions.set.Set(_no_validate=False, **fields)¶

Bases: obbaa_onusim.message.Message

Set command message.

validate()¶

Validate the values field (a dictionary), returning new values for the attr_mask and values fields.

For each item in the values dictionary:

Check it’s a valid attribute name or number

Check it’s a writable attribute

If any of the checks fail, output a warning and ignore the attribute.

Return type

Dict[str, Union[bytes, int, str, dict, list]]

Returns

Dictionary with the following items.

attr_mask: attribute mask containing bits for valid attributes from the supplied values
values: dictionary containing valid attributes from the supplied values, and with raw attribute values

encode_contents()¶

Encode this message’s contents, i.e. its type-specific payload.

The base class implementation just returns an empty buffer. Subclasses should override this method.

Return type: bytearray
Returns: Encoded buffer.

decode_contents(contents)¶

Decode this message’s contents, i.e. its type-specific payload.

Return type

Dict[str, Union[bytes, int, str, dict, list]]

Returns

Dictionary with the following items.

attr_mask: attribute mask; 0-65535
values: MIB-specific attribute names and values as specified by the attribute mask

Note

Set and GetResponse are inconsistent: here the dictionary contains a values item, but GetResponse places the attributes directly in the object. This inconsistency will be resolved.

process(server)¶

Pass this message to the endpoint for processing, and return the response (if any).

Parameters: endpoint – Endpoint to which to pass the message for processing.
Return type: SetResponse
Returns: The response, or None if there is no response.

class obbaa_onusim.actions.set.SetResponse(_no_validate=False, **fields)¶

Bases: obbaa_onusim.message.Message

Set response message.

encode_contents()¶

Encode this message’s contents, i.e. its type-specific payload.

The base class implementation just returns an empty buffer. Subclasses should override this method.

Return type: bytearray
Returns: Encoded buffer.

decode_contents(contents)¶

Decode this message’s contents, i.e. its type-specific payload.

Return type

Dict[str, Union[bytes, int, str, dict, list]]

Returns

Dictionary with the following items.

reason: result, reason; 0-255
attr_mask: attribute mask; 0-65535
If reason is 0b1001 (9): * opt_attr_mask: optional-attribute mask; 0-65535 * opt_exec_mask: attribute execution mask; 0-65535

obbaa_onusim.actions.set.set_action = Action(number=8, name='set', description='Set action')¶

Set Action.

This specifies the message type and provides a link between the action’s command and response messages.

Get action¶

The Get action’s messages are defined in G.988 A.2.7-8 (extended) and A.3.7-8 (baseline).

The relevant classes and instances are:

Get: Get command message class
GetResponse: Get response message class
get_action: Get action instance.

class obbaa_onusim.actions.get.Get(_no_validate=False, **fields)¶

Bases: obbaa_onusim.message.Message

Get command message.

encode_contents()¶

Encode this message’s contents, i.e. its type-specific payload.

The base class implementation just returns an empty buffer. Subclasses should override this method.

Return type: bytearray
Returns: Encoded buffer.

decode_contents(contents)¶

Decode this message’s contents, i.e. its type-specific payload.

Return type

Dict[str, Union[bytes, int, str, dict, list]]

Returns

Dictionary with the following items.

attr_mask: attribute mask; 0-65535

process(server)¶

Pass this message to the endpoint for processing, and return the response (if any).

Parameters: endpoint – Endpoint to which to pass the message for processing.
Return type: GetResponse
Returns: The response, or None if there is no response.

class obbaa_onusim.actions.get.GetResponse(_no_validate=False, **fields)¶

Bases: obbaa_onusim.message.Message

Get response message.

encode_contents()¶

Encode this message’s contents, i.e. its type-specific payload.

The base class implementation just returns an empty buffer. Subclasses should override this method.

Return type: bytearray
Returns: Encoded buffer.

decode_contents(contents)¶

Decode this message’s contents, i.e. its type-specific payload.

Return type

Dict[str, Union[bytes, int, str, dict, list]]

Returns

Dictionary with the following items.

reason: result, reason; 0-255
attr_mask: attribute mask; 0-65535
opt_attr_mask: optional-attribute mask; 0-65535
opt_exec_mask: attribute execution mask; 0-65535
other: MIB-specific attributes as specified by the attribute mask

obbaa_onusim.actions.get.get_action = Action(number=9, name='get', description='Get action')¶

Get Action.

This specifies the message type and provides a link between the action’s command and response messages.

MIB upload and MIB upload next actions¶

The MIB upload and MIB upload next actions’ messages are defined in G.988 A.2.13-16 (extended) and A.3.13-16 (baseline).

The relevant classes and instances are:

MibUpload and MibUploadNext: MIB upload and MIB upload next command message classes
MibUploadResponse and MibUploadNextResponse: MIB upload and MIB upload next response message classes
mib_upload_action and mib_upload_next_action: MIB upload and MIB upload next action instances.

class obbaa_onusim.actions.upload.MibUpload(_no_validate=False, **fields)¶

Bases: obbaa_onusim.message.Message

MIB upload command message.

process(server)¶

Pass this message to the endpoint for processing, and return the response (if any).

Parameters: endpoint – Endpoint to which to pass the message for processing.
Return type: MibUploadResponse
Returns: The response, or None if there is no response.

class obbaa_onusim.actions.upload.MibUploadResponse(_no_validate=False, **fields)¶

Bases: obbaa_onusim.message.Message

MIB upload response message.

encode_contents()¶

Encode this message’s contents, i.e. its type-specific payload.

The base class implementation just returns an empty buffer. Subclasses should override this method.

Return type: bytearray
Returns: Encoded buffer.

decode_contents(contents)¶

Decode this message’s contents, i.e. its type-specific payload.

Return type

Dict[str, Union[bytes, int, str, dict, list]]

Returns

Dictionary with the following items.

num_upload_nexts: number of MibUploadNext commands required; 0-65535

class obbaa_onusim.actions.upload.MibUploadNext(_no_validate=False, **fields)¶

Bases: obbaa_onusim.message.Message

MIB upload next command message.

encode_contents()¶

Encode this message’s contents, i.e. its type-specific payload.

The base class implementation just returns an empty buffer. Subclasses should override this method.

Return type: bytearray
Returns: Encoded buffer.

decode_contents(contents)¶

Decode this message’s contents, i.e. its type-specific payload.

Return type

Dict[str, Union[bytes, int, str, dict, list]]

Returns

Dictionary with the following items.

seq_num: command sequence number; 0-65535

process(server)¶

Pass this message to the endpoint for processing, and return the response (if any).

Parameters: endpoint – Endpoint to which to pass the message for processing.
Return type: MibUploadNextResponse
Returns: The response, or None if there is no response.

class obbaa_onusim.actions.upload.MibUploadNextResponse(_no_validate=False, **fields)¶

Bases: obbaa_onusim.message.Message

MIB upload next response message.

encode_contents()¶

Encode this message’s contents, i.e. its type-specific payload.

The base class implementation just returns an empty buffer. Subclasses should override this method.

Return type: bytearray
Returns: Encoded buffer.

decode_contents(contents)¶

Decode this message’s contents, i.e. its type-specific payload.

Return type

Dict[str, Union[bytes, int, str, dict, list]]

Returns

Dictionary with the following items.

me_class.me_inst.attr_name: the item name is the
dot-separated ME class (MIB number), ME instance, and attribute name.

obbaa_onusim.actions.upload.mib_upload_action = Action(number=13, name='mib-upload', description='MIB upload action')¶

MIB upload Action.

This specifies the message type and provides a link between the action’s command and response messages.

obbaa_onusim.actions.upload.mib_upload_next_action = Action(number=14, name='mib-upload-next', description='MIB upload next action')¶

MIB upload next Action.

This specifies the message type and provides a link between the action’s command and response messages.

MIB reset action¶

The MIB reset action’s messages are defined in G.988 A.2.17-18 ( extended) and A.3.17-18 (baseline).

The relevant classes and instances are:

MibReset: MIB reset command message class
MibResetResponse: MIB reset response message class
mib_reset_action: MIB reset action instance.

class obbaa_onusim.actions.reset.MibReset(_no_validate=False, **fields)¶

Bases: obbaa_onusim.message.Message

MIB reset command message.

process(server)¶

Pass this message to the server database for processing, and return the response.

Return type: MibResetResponse

class obbaa_onusim.actions.reset.MibResetResponse(_no_validate=False, **fields)¶

Bases: obbaa_onusim.message.Message

MIB reset response message.

encode_contents()¶

Encode this message’s contents, i.e. its type-specific payload.

The base class implementation just returns an empty buffer. Subclasses should override this method.

Return type: bytearray
Returns: Encoded buffer.

decode_contents(contents)¶

Decode this message’s contents, i.e. its type-specific payload.

Return type

Dict[str, Union[bytes, int, str, dict, list]]

Returns

Dictionary with the following items.

reason: result, reason; 0-255

obbaa_onusim.actions.reset.mib_reset_action = Action(number=15, name='mib-reset', description='MIB reset action')¶

MIB reset Action.

This specifies the message type and provides a link between the action’s command and response messages.

4.3. MIBs¶

MIB classes¶

A MIB (Management Information Base), also referred to as an ME (Managed Entity), is defined via a MIB instance.

A MIB definition describes its Attrs (attributes), Actions, Notifications, Changes and Alarms.

Example:

onu_data_mib = MIB(2, 'ONU_DATA', 'Models the MIB itself', attrs=(
  Attr(0, 'me_inst', 'Managed entity instance', R, M, Number(2, fixed=0)),
  Attr(1, 'mib_data_sync', 'MIB data sync', RW, M, Number(1))
), actions= (
  get_action, set_action, get_all_alarms_action,
  get_all_alarms_next_action, mib_reset_action, mib_upload_action,
  mib_upload_next_action
))

obbaa_onusim.mib.mibs = {mib.number: mib for mib in all-MIB-instances}¶: All instantiated MIBs.

class obbaa_onusim.mib.MIB(number, name, description=None, *, attrs=None, actions=None, notifications=None, changes=None, alarms=None)¶

Bases: obbaa_onusim.types.NumberName, obbaa_onusim.types.AutoGetter

MIB definition class.

__init__(number, name, description=None, *, attrs=None, actions=None, notifications=None, changes=None, alarms=None)¶

MIB class constructor.

The constructor adds new MIB instances to the mibs dictionary.

Parameters

number (int) – MIB number; MUST be unique across all MIB instances; 0-65535.
name (str) – MIB name; MUST be unique across all MIB instances.
description (Optional[str]) – MIB description; used only for documentation purposes.
attrs (Optional[Tuple[Attr, …]]) – MIB attributes. They’re defined as a tuple but each has a number, so order doesn’t matter.
actions (Optional[Tuple[Action, …]]) – Actions valid for use with this MIB.
notifications (Optional[Tuple[Notification, …]]) – Notifications generated by this MIB.
changes (Optional[Tuple[Change, …]]) – Changes generated by this MIB.
alarms (Optional[Tuple[Alarm, …]]) – Alarms generated by this MIB.

attr(number_or_name)¶

Find a MIB attribute by number or name, returning the attribute or None.

Parameters: number_or_name (Union[int, str]) – MIB attribute number or name.
Return type: Optional[Attr]
Returns: Attr instance or None if not found.

attr_names(access=None)¶

Return a (string representation of) a list of all attribute names, optionally restricted to those with a specified access level.

Parameters: access (Optional[Access]) – Desired access level, or None to return all attributes.
Return type: str
Returns: String of the form name1, name2, name3.

Note

Attribute 0 is me_inst (the ME instance number) and is not returned.

class obbaa_onusim.mib.Attr(number, name, description=None, access=None, requirement=None, data=None)¶

Bases: obbaa_onusim.types.NumberName, obbaa_onusim.types.AutoGetter

MIB attribute class.

__init__(number, name, description=None, access=None, requirement=None, data=None)¶

MIB attribute constructor.

Parameters

number (int) – attribute number; MUST be unique within its MIB; 0-16.
name (str) – attribute name; MUST be unique within its MIB.
description (Optional[str]) – attribute description; used only for documentation purposes.
access (Optional[Access]) – attribute access level.
requirement (Optional[Requirement]) – attribute support requirement
data (Union[Datum, Tuple[Datum, …], None]) – attribute data specification.

decode(content, offset)¶

Decode a MIB attribute value.

Parameters

content (bytearray) – buffer from which to decode the value.
offset (int) – byte offset within buffer at which to start decoding.

Return type

Tuple[Union[bytearray, int, str, Tuple[Union[bytearray, int, str], …]], int]

Returns

Decoded values and updated offset.

The decoded values are returned as a tuple (if there’s more than one value), a single value, or None
The offset is ready to be passed to the next decode invocation

encode(values=None)¶

Encode a MIB attribute value.

Parameters: values (Union[bytearray, int, str, Tuple[Union[bytearray, int, str], …], None]) – tuple, single value or None.
Return type: bytearray
Returns: Encoded buffer. If None was supplied, an empty buffer is returned.

resolve(values=None)¶

Resolve a MIB attribute value by invoking any callable values.

Any callable values are invoked (with no arguments) and are replaced with the returned value. See Database for an example.

Parameters: values (Union[bytearray, int, str, Tuple[Union[bytearray, int, str], …], None]) – tuple, single value or None.
Return type: Union[bytearray, int, str, Tuple[Union[bytearray, int, str], …]]
Returns: Resolved values. If None was supplied, then None is returned.

property mask¶: Get this attribute’s mask, e.g. the value to use when forming the Get command’s attr_mask field.

Note

Don’t call this on attribute 0 (me_inst). You’ll get an assertion failure.

property size¶: Get this attribute’s value size in bytes.

class obbaa_onusim.mib.Access(name)¶

Bases: obbaa_onusim.types.Name, obbaa_onusim.types.AutoGetter

Attribute access class (G.988 Section 9).

__init__(name)¶: Initialize self. See help(type(self)) for accurate signature.

obbaa_onusim.mib.R = Access(name='R')¶: Read-only access.

obbaa_onusim.mib.W = Access(name='W')¶: Write-only access.

obbaa_onusim.mib.RW = Access(name='RW')¶: Read-Write access.

obbaa_onusim.mib.RC = Access(name='RC')¶: Read and set-by-Create access.

obbaa_onusim.mib.RWC = Access(name='RWC')¶: Read-Write and set-by-Create access.

class obbaa_onusim.mib.Requirement(name)¶

Bases: obbaa_onusim.types.Name, obbaa_onusim.types.AutoGetter

Attribute requirement class.

__init__(name)¶: Initialize self. See help(type(self)) for accurate signature.

obbaa_onusim.mib.M = Requirement(name='M')¶: Mandatory

obbaa_onusim.mib.O = Requirement(name='O')¶: Optional

class obbaa_onusim.mib.Notification(name, description=None, *, names=None)¶

Bases: obbaa_onusim.types.Name, obbaa_onusim.types.AutoGetter

Attribute notification class.

obbaa_onusim.mib.test_result_notification = Notification(name='test_result')¶: Test result notification.

class obbaa_onusim.mib.Change(number, name, description=None, *, names=None)¶

Bases: obbaa_onusim.types.NumberName

Attribute change class.

class obbaa_onusim.mib.Alarm(number, name, description=None, *, names=None)¶

Bases: obbaa_onusim.types.NumberName

Attribute alarm class.

ONU-G MIB¶

ONU-G MIB (G.988 9.1.1).

obbaa_onusim.mibs.onu_g.onu_g_mib = MIB(number=256, name='ONU-G', description='Represents the ONU as equipment')¶: Instantiated MIB.

ONU2-G MIB¶

ONU2-G MIB (G.988 9.1.2).

obbaa_onusim.mibs.onu2_g.onu2_g_mib = MIB(number=257, name='ONU2-G', description='Contains additional attributes associated with a PON ONU')¶: Instantiated MIB.

ONU data MIB¶

ONU data MIB (G.988 9.1.3).

obbaa_onusim.mibs.onu_data.onu_data_mib = MIB(number=2, name='ONU data', description='Models the MIB itself')¶: Instantiated MIB.

Software image MIB¶

Software image MIB (G.988 9.1.4).

obbaa_onusim.mibs.software_image.software_image_mib = MIB(number=7, name='Software image', description='Models an executable software image')¶: Instantiated MIB.

4.4. Database¶

MIB database access.

This will currently only really work on the server side, but it makes sense also to have a client-side database, populated via get and MIB upload actions.

obbaa_onusim.database.specs = ((MIB(number=256, name='ONU-G', description='Represents the ONU as equipment'), ({'me_inst': 0, 'vendor_id': 1234, 'version': 'v2', 'serial_number': ('abcdefgh', 5678)},)), (MIB(number=257, name='ONU2-G', description='Contains additional attributes associated with a PON ONU'), ({'me_inst': 0, 'omcc_version': 180, 'sys_up_time': <function <lambda>>},)), (MIB(number=2, name='ONU data', description='Models the MIB itself'), ({'me_inst': 0, 'mib_data_sync': 0},)), (MIB(number=7, name='Software image', description='Models an executable software image'), ({'me_inst': 0}, {'me_inst': 1}, {'me_inst': 256}, {'me_inst': 257})))¶: MIB instance specs (these are instantiated on all ONUs).

Note

These specs should be read from JSON/YAML files.

obbaa_onusim.database.mibs = {2: MIB(number=2, name='ONU data', description='Models the MIB itself'), 7: MIB(number=7, name='Software image', description='Models an executable software image'), 256: MIB(number=256, name='ONU-G', description='Represents the ONU as equipment'), 257: MIB(number=257, name='ONU2-G', description='Contains additional attributes associated with a PON ONU')}¶: Implemented MIBs, i.e. the MIBs referenced by the MIB instance specs.

class obbaa_onusim.database.Results¶

Bases: object

Database results class (used for all database operations).

__init__()¶: Database results constructor.

reason: int¶: Reason, result (used by all operations).

attr_mask: int¶: Attribute mask (used by most operations).

opt_attr_mask: int¶: Optional-attribute mask (used with reason 0b1001).

attr_exec_mask: int¶: Attribute-execution mask (used with reason 0b1001).

attrs: List[Tuple[Attr, AttrDataValues]]¶: Attributes and their values (used by Database.get).

num_upload_nexts: int¶: Number of upload-nexts (used by Database.upload).

body: List[int, List[Snapshot]]¶: Next message body (used by Database.upload_next).

__str__()¶: Return str(self).

class obbaa_onusim.database.Database(onu_id_range)¶

Bases: object

MIB database class.

__init__(onu_id_range)¶

MIB database constructor.

Parameters: onu_id_range (range) – ONU id range, e.g. range(10) means ONU ids 0, 1, …9. An identical database is instantiated for each of these ONU ids.

set(onu_id, me_class, me_inst, attr_mask, values, *, extended=False)¶

Set the specified attribute values.

Parameters

onu_id – ONU id.
me_class – MIB class.
me_inst – MIB instance.
attr_mask – attributes to set.
values – values to which attributes will be set.
extended – whether an extended message has been requested.

Return type

Results

Returns

Results object, including reason and opt_attr_mask.

get(onu_id, me_class, me_inst, attr_mask, *, extended=False)¶

Get the specified attribute values.

Parameters

onu_id (int) – ONU id.
me_class (int) – MIB class.
me_inst (int) – MIB instance.
attr_mask (int) – requested attributes.
extended (bool) – whether an extended message has been requested.

Return type

Results

Returns

Results object, including reason, attr_mask and opt_attr_mask and attrs.

upload(onu_id, me_class, me_inst, *, extended=False)¶

Prepare for uploading MIBs.

This involves taking a snapshot and calculating how many subsequent Database.upload_next operations will be needed.

Parameters

onu_id – ONU id.
me_class – MIB class (MUST be the ONU Data MIB class, i.e. 2).
me_inst – MIB instance (MUST be the ONU Data MIB instance, i.e. 0).
extended – whether an extended message has been requested (if so, the subsequent Database.upload_next operations MUST also request extended messages).

Return type

Results

Returns

Results object, including reason and num_upload_nexts.

upload_next(onu_id, me_class, me_inst, seq_num, *, extended=False)¶

Upload the next part of a snapshot that was previously saved via Database.upload.

Parameters

onu_id – ONU id.
me_class – MIB class (MUST be the ONU Data MIB class, i.e. 2).
me_inst – MIB instance (MUST be the ONU Data MIB instance, i.e. 0).
extended – whether an extended message has been requested (if so, the earlier Database.upload operation MUST have also requested extended messages).

Return type

Results

Returns

Results object, including reason and body.

reset(onu_id, me_class, me_inst, *, extended=False)¶

Reset the specified MIB instance.

Parameters

onu_id – ONU id.
me_class – MIB class.
me_inst – MIB instance.
extended – whether an extended message has been requested.

Return type

Results

Returns

Results object, including reason.

4.5. Support¶

Types¶

Various common data types.

class obbaa_onusim.types.Name(name, description=None, *, names=None)¶

Bases: object

Name (and description) mixin class.

__init__(name, description=None, *, names=None)¶: Initialize self. See help(type(self)) for accurate signature.

__str__()¶

Return str(self).

Return type: str

class obbaa_onusim.types.NumberName(number, name, description=None, *, names=None)¶

Bases: obbaa_onusim.types.Name

Number, name (and description) mixin class.

__init__(number, name, description=None, *, names=None)¶: Initialize self. See help(type(self)) for accurate signature.

__str__()¶

Return str(self).

Return type: str

class obbaa_onusim.types.AutoGetter¶

Bases: object

Auto-getter mixin class.

Allows instance._attr to be accessed (only for read access) as instance.attr.

class obbaa_onusim.types.Datum(size, default=None, fixed=None)¶

Bases: obbaa_onusim.types.AutoGetter

Single data item class.

Defines a single data item of a given type, with support for default and fixed values, for encoding and decoding values, and for converting between user and raw values.

__init__(size, default=None, fixed=None)¶

Data item constructor.

Parameters

size (int) – size of data item in bytes.
default (Union[bytearray, int, str, None]) – default value of data item (used if no value is specified).
fixed (Union[bytearray, int, str, None]) – fixed value of data item (takes precedence over the default; any attempt to define a data item instance with a different value is an error).

Note

A default MUST currently be provided (it determines the type); this is wrong: the type should come from the subclass.

decode(buffer, offset)¶

Decode data item value.

Parameters

buffer (bytearray) – buffer from which to decode the value
offset (int) – byte offset within buffer at which to start decoding

Return type

Tuple[Union[bytearray, int, str], int]

Returns

Decoded value and updated offset.

If there isn’t sufficient data in the buffer, the default value is returned
The returned value is a user value (it’s converted from the raw value)
The offset is ready to be passed to the next decode invocation

encode(value=None)¶

Encode data item value.

Parameters

value (Union[bytearray, int, str, None]) – the value to be encoded

Return type

bytearray

Returns

Encoded buffer.

If value is None, the default value is encoded
The value is converted to a raw value before encoding

raw_value(value)¶

Convert data item user value to raw value.

Return type: Union[bytearray, int, str]

value(raw_value)¶

Convert data item raw value to user value.

Return type: Union[bytearray, int, str]

__str__()¶

Return str(self).

Return type: str

class obbaa_onusim.types.Bool(size, default=None, fixed=None)¶

Bases: obbaa_onusim.types.Datum

Boolean data item class.

__init__(size, default=None, fixed=None)¶: The default defaults to false.

raw_value(value)¶

Convert data item user value to raw value.

Return type: int

value(raw_value)¶

Convert data item raw value to user value.

Return type: bool

class obbaa_onusim.types.Enum(size, values=None, default=None, fixed=None)¶

Bases: obbaa_onusim.types.Datum

Enumeration data item class.

__init__(size, values=None, default=None, fixed=None)¶

Data item constructor.

Parameters

size (int) – size of data item in bytes.
default (Optional[str]) – default value of data item (used if no value is specified).
fixed (Optional[str]) – fixed value of data item (takes precedence over the default; any attempt to define a data item instance with a different value is an error).

Note

A default MUST currently be provided (it determines the type); this is wrong: the type should come from the subclass.

raw_value(value)¶

Convert data item user value to raw value.

Return type: int

value(raw_value)¶

Convert data item raw value to user value.

Return type: str

__str__()¶

Return str(self).

Return type: str

class obbaa_onusim.types.Bits(size, values=None, default=None, fixed=None)¶

Bases: obbaa_onusim.types.Enum

Bits data item class.

class obbaa_onusim.types.Number(size, default=None, fixed=None, units=None)¶

Bases: obbaa_onusim.types.Datum

Number data item class.

__init__(size, default=None, fixed=None, units=None)¶

Data item constructor.

Parameters

size (int) – size of data item in bytes.
default (Optional[int]) – default value of data item (used if no value is specified).
fixed (Optional[int]) – fixed value of data item (takes precedence over the default; any attempt to define a data item instance with a different value is an error).

Note

A default MUST currently be provided (it determines the type); this is wrong: the type should come from the subclass.

raw_value(value)¶

Convert data item user value to raw value.

Return type: int

value(raw_value)¶

Convert data item raw value to user value.

Return type: int

class obbaa_onusim.types.String(size, default=None, fixed=None)¶

Bases: obbaa_onusim.types.Datum

String data item class.

__init__(size, default=None, fixed=None)¶

Data item constructor.

Parameters

size (int) – size of data item in bytes.
default (Optional[str]) – default value of data item (used if no value is specified).
fixed (Optional[str]) – fixed value of data item (takes precedence over the default; any attempt to define a data item instance with a different value is an error).

Note

A default MUST currently be provided (it determines the type); this is wrong: the type should come from the subclass.

raw_value(value)¶

Convert data item user value to raw value.

Return type: bytes

value(raw_value)¶

Convert data item raw value to user value.

Return type: str

class obbaa_onusim.types.Bytes(size, default=None, fixed=None)¶

Bases: obbaa_onusim.types.Datum

Bytes data item class.

__init__(size, default=None, fixed=None)¶

Data item constructor.

Parameters

size (int) – size of data item in bytes.
default (Optional[bytes]) – default value of data item (used if no value is specified).
fixed (Optional[bytes]) – fixed value of data item (takes precedence over the default; any attempt to define a data item instance with a different value is an error).

Note

A default MUST currently be provided (it determines the type); this is wrong: the type should come from the subclass.

raw_value(value)¶

Convert data item user value to raw value.

Return type: bytes

value(raw_value)¶

Convert data item raw value to user value.

Return type: bytes

Utilities¶

Various utility functions.

obbaa_onusim.util.argparser(prog, description, **kwargs)¶

Argument parser helper.

Parameters

prog (str) – program name, typically from sys.argv[0].
description (str) – program description, typically from __doc__.
**kwargs – additional arguments; currently supported keys are default_xxx for argument xxx, e.g. default_address.

Return type

ArgumentParser

Returns

Argument parser, with common options added.

obbaa_onusim.util.cleandoc(docstring)¶

Clean documentation string (docstring) per PEP 257 rules.

Parameters: docstring – supplied docstring.
Returns: Clean docstring.

Note

This is just a wrapper around inspect.cleandoc.

obbaa_onusim.util.indices(mask)¶

Attribute indices helper.

Parameters: mask (int) – the attribute mask for which to return the indices.
Return type: Tuple[Tuple[int, int], …]
Returns: Tuple of (index, index_mask) tuples, where index is in the range 1 through 16 (inclusive).

obbaa_onusim.util.openfile(spec)¶

Open file helper.

Parameters

spec (Optional[str]) –

file/mode spec; for example:

file uses mode w
file+ uses mode a
file+r uses mode r

Return type

Optional[IO[str]]

Returns

File object, or None if spec is None.

obbaa_onusim.util.toint(x)¶

String to integer conversion helper.

Supports bases 2, 8, 10 and 16.

Parameters: x (Any) – value to convert
Returns: Integer.

Note

It’ll throw an exception if given an invalid string.

4. Modules¶

4.1. Endpoint¶

4.2. Messages and Actions¶

Message classes¶

Action classes¶

Set action¶

Get action¶

MIB upload and MIB upload next actions¶

MIB reset action¶

4.3. MIBs¶

MIB classes¶

ONU-G MIB¶

ONU2-G MIB¶

ONU data MIB¶

Software image MIB¶

4.4. Database¶

4.5. Support¶

Types¶

Utilities¶

Table of Contents

Previous topic

Next topic

This Page