WINC functions¶

pywinc utility entry point¶

Main pywinc tool functions

iotprovision.winc.pywinc_main.build_client_certs(files, decode_print=False, outfile=None)¶

Build a client certificate storage object

Parameters:

files (Array with file or directory names) – Certificates to include in the storage object.
decode_print (bool, optional) – Print storage object in a readable format, defaults to False
outfile (String, optional) – File name of the file where the storage object should be stored, defaults to None

Returns:

0 for success and 1 for failure

Return type:

Int

iotprovision.winc.pywinc_main.build_root_certs(files, decode_print=False, outfile=None)¶

Build a root certificate storage object

Parameters:

files (Array with file or directory names) – Certificates to include in the storage object.
decode_print (bool, optional) – Print storage object in a readable format, defaults to False
outfile (String, optional) – File name of the file where the storage object should be stored, defaults to None

Returns:

0 for success and 1 for failure

Return type:

Int

iotprovision.winc.pywinc_main.decode_client_certs_storage(file)¶

Decode and print a client storage object

Parameters:: files (String) – Storage object file name
Returns:: 0 for success and 1 for failure
Return type:: Int

iotprovision.winc.pywinc_main.decode_root_certs_storage(file)¶

Decode and print a root storage object

Parameters:: file (String) – Storage file name
Returns:: 0 for success and 1 for failure
Return type:: Int

iotprovision.winc.pywinc_main.pywinc(args, logging_level)¶

WINC tool CLI commands handler

Parameters:

args (object) – Command line arguments (argparse output)
logging_level (Int) – Logging level from logger module e.g. logging.INFO

Returns:

Status. STATUS_SUCCESS=0 or STATUS_ERROR=1

Return type:

Int

iotprovision.winc.pywinc_main.read_client_certs(port, decode_print=False, outfile=None)¶

Read client storage from WINC

Parameters:

port (String) – Serial port to use for the operation e.g. COM5
decode_print (bool, optional) – Print storage object in a readable format, defaults to False
outfile (String, optional) – File in which the storage object should be stored, defaults to None

Returns:

0 for success and 1 for failure

Return type:

Int

iotprovision.winc.pywinc_main.read_root_certs(port, decode_print=False, outfile=None)¶

Read root certificate storage from WINC

Parameters:

port (String) – Serial port to use for the operation e.g. COM5
decode_print (bool, optional) – Print the storage object in a readable format, defaults to False
outfile (String, optional) – File in which the storage object should be stored, defaults to None

Returns:

0 for success and 1 for failure

Return type:

Int

iotprovision.winc.pywinc_main.winc_fw_upgrade(port, file)¶

Upgrade WINC FW

Parameters:

port (String) – Serial port to use for the operation e.g. COM5
file (String) – WINC FW image file name

Returns:

0 for success and 1 for failure

Return type:

Int

iotprovision.winc.pywinc_main.write_client_certs_storage(port, file)¶

Write a client certificate storage object to WINC

Parameters:

port (String) – Serial port to use for the operation e.g. COM5
file (String) – Storage object file name

Returns:

0 for success and 1 for failure

Return type:

Int

iotprovision.winc.pywinc_main.write_root_certs_storage(port, file)¶

Write a root certificate storage object to WINC

Parameters:

port (String) – Serial port to use for the operation e.g. COM5
file (String) – Storage object file name

Returns:

0 for success and 1 for failure

Return type:

Int

WINC certificates¶

This module handles the WINC FW and certificate upgrade.

Features:

Update the WINC FW
Build root certificate storage and upgrade WINC with it
Build client file storage and upgrade WINC with it
Read root certificate storage from WINC
Read client file storage from WINC

class iotprovision.winc.winc_certs.ClientCert(data=None, data_type='certificate', offset=None)¶

Bases: object

WINC client certificate storage file object.

Represents one file entry in WINC client certificate storage.

File name is: crt _ + serial number in certificate (16 bytes) = total 20 bytes (21 with string termination)

FILE_ADDRESS_SIZE = 4¶

FILE_ENTRY_SIZE = 56¶

FILE_NAME_SIZE = 48¶

FILE_SIZE = 4¶

build_entry(file_offset)¶

file_blob_addr = 0¶

file_data¶: alias of object

file_flash_addr = 0¶

file_name = ''¶

file_size = 0¶

load_from_certificate(certificate)¶

load_from_ecdsa_list(ecdsa_list)¶

load_from_file_entry_blob(blob)¶

Decode a file entry from the client certificate store

A file entry is stored like this in WINC:

Bytes | C Type                 | Description
--------------------------------------------------------
48    | char                   | File name
4     | uint32_t little endian | File size
4     | uint32_t little endian | Start address of the certificate (not aligned on a 32-bit word boundary, at least what we read out was not)

Parameters:: blob (bytes/bytearray) – Raw bytes of the file entry

class iotprovision.winc.winc_certs.ClientCertStorage¶

Bases: object

Client certificate storage object

CRC32_OFFSET = 464¶

CRC32_SIZE = 4¶

FILE_COUNT_OFFSET = 8¶

FILE_COUNT_SIZE = 4¶

FILE_ENTRIES_OFFSET = 16¶

FILE_ENTRIES_SIZE = 448¶

FILE_STORAGE_OFFSET = 468¶

MAX_FILE_ENTRIES = 8¶

MAX_NUMBER_OF_FILES = 8¶

NEXT_FILE_OFFSET = 12¶

NEXT_FILE_SIZE = 4¶

START_PATTERN = b'\xab\xfe\x18[p\xc3F\x92'¶

START_PATTERN_SIZE = 8¶

add_certificate(certificate_file)¶

Add a certificate from named file to the store

The certificate can be in DER or PEM format.

Parameters:: certificate_file (String) – Certificate file name

add_certificate_blob(certificate)¶

Add a certificate memory blob to the store

The certificate can be in DER or PEM format.

Parameters:: certificate (bytes) – Certificate blob

add_certificates(certificates)¶

Add certificates to the store

Certificates can be in DER or PEM format.

Parameters:: certificates (List or array) – List of certificate file names

add_ecdsa_list()¶: Build the ECDSA file list and append to the store

build()¶

Build the storage object

Returns:: Storage object
Return type:: Bytearray

calculate_storage_size()¶

Calculate the size of the storage

Calculate the size of the current storage based on items that are currently added.

Returns:: Size in bytes
Return type:: Integer

decode(blob)¶

Decode a storage object

TLS client files storage header:

Bytes | C Type                 | Description
----------------------------------------------------------------------
8     | uint8_t                | TLS client files start pattern is {0xAB, 0xFE, 0x18, 0x5B, 0x70, 0xC3, 0x46, 0x92}
4     | uint32_t little endian | Number of files in the blob
4     | uint32_t little endian | Next write address relative to blob start or flash start? when adding a new file. This is the end of the blob aligned on a 32-bit word address.
...   | struct                 | File entries. Max 8 files are allowed by WINC
4     | uint32_t little endian | CRC32 of the whole blob
...   | uint8_t                | Files (Certificates should be in DER format)

Parameters:: blob (bytes/bytearray) – TLS client storage bytes

storage_space_left()¶

Calculate space left in WINC flash when current storage is programmed

Returns:: Space left in WINC in bytes
Return type:: Integer

class iotprovision.winc.winc_certs.RootCert(certificate=None)¶

Bases: object

Root certificate entry.

Returns:: Root certificate instance
Return type:: object

CERT_SIZE = 44¶

KEY_TYPE_MAP = {'EC': 2, 'RSA': 1}¶

SHA1_SIZE = 20¶

TIME_SIZE = 8¶

build()¶

Build the root certificate entry.

Returns:: Binary blob of the root certificate entry
Return type:: bytearray

decode(blob, count, certs)¶

Decodes root certificate entries

Each root CA entry in the storage blob is built up like this:

Bytes  | C Type   | Description
-      -          -
20     | uint8_t  | SHA1 of certificate issuer name
Certificate issue date
2      | uint16_t | Year
1      | uint8_t  | Month
1      | uint8_t  | Day
1      | uint8_t  | Hour
1      | uint8_t  | Minute
1      | uint8_t  | Second
1      | uint8_t  | Padding byte to align on 32-bit word boundary
Certificat expiry date
2      | uint16_t | Year
1      | uint8_t  | Month
1      | uint8_t  | Day
1      | uint8_t  | Hour
1      | uint8_t  | Minute
1      | uint8_t  | Second
1      | uint8_t  | Padding byte to align on 32-bit word boundary
Key information
4      | uint32_t | Key info type (1=RSA, 2=ECC)
2      | uint16_t | ECC curve ID / RSA modulo size
2      | uint16_t | ECC EC coordinate size / RSA exponent size
Key
[..]   | uint8_t  | ECC x = 2 * EC coordinate size; RSA x = modulo size + exponent size
[..]   | uint8_t  | Padding bytes to align on 32-bit word boundary

Parameters:

blob (bytearray()) – Binary data containing the root CA entries
count (integer) – Number of entries to decode in blob
certs (array) – An array of RootCert objects will be returned here after decoding

length()¶

Calculates the length of the root certificate entry

Returns:: Length of the entry
Return type:: integer

load_from_certificate(certificate)¶

Build the root certificate storage entry from a certificate

Parameters:: certificate (x509.certificate from cryptography package) – Certificate

class iotprovision.winc.winc_certs.RootCertStorage¶

Bases: object

Root certificates storage object.

The root certificate store is built up like this:

Bytes      | C Type   | Description
-          -          -
16         | uint8_t  | Start pattern
4          | uint32_t | Number of certificates in the store
xx         | struct   | Root certificate entry
..
xx         | sturct   | Root certificate entry

Returns:: Root certificate storage object
Return type:: RootCertStorage instance

CERT_NUMBER_SIZE = 4¶

START_PATTERN = b'\x11\xf1\x12\xf2\x13\xf3\x14\xf4\x15\xf5\x16\xf6\x17\xf7\x18\xf8'¶

START_PATTERN_SIZE = 16¶

add_certificate(certificate_file)¶

Add a certificate to the store

The certificate can be in DER or PEM format.

Parameters:: certificate_file – File name of the certificate

add_certificate_blob(certificate)¶

Add a certificate memory blob to the store

The certificate can be in DER or PEM format.

Parameters:: certificate (bytes) – Certificate blob

add_certificates(clist)¶

Add a root certificates to the store

Parameters:: clist (list) – List of root certificate file names that should be added

build()¶

Build a root certificate binary blob

Returns:: Root certificate storage image
Return type:: bytearray

decode(blob)¶

Decode a root certificate store.

Parameters:: blob (bytes or bytearray) – Root certificate binary blob

WINC flash memory map¶

class iotprovision.winc.winc_flash_map.FlashMap¶

Bases: object

aws_endpoint_offset = 28160¶

block_size = 32768¶

boot_fw_offset = 0¶

boot_fw_size = 4096¶

cached_conns_offset = 36864¶

cached_conns_size = 4096¶

control_section_offset = 4096¶

control_section_size = 8192¶

firmware_offset = 40960¶

firmware_size = 241664¶

gain_offset = 13312¶

gain_size = 3072¶

http_mem_offset = 28672¶

http_mem_size = 8192¶

ota_fw_offset = 282624¶

ota_fw_size = 241664¶

page_size = 256¶

pll_offset = 12288¶

pll_size = 1024¶

sector_size = 4096¶

start_addr = 0¶

thing_name_offset = 28416¶

thing_name_size = 42¶

tls_root_cert_offset = 16384¶

tls_root_cert_size = 4096¶

tls_server_offset = 20480¶

tls_server_size = 8192¶

total_flash_size = 1048576¶

iotprovision.winc.winc_flash_map.print_flash_map()¶

WINC upgrade¶

class iotprovision.winc.wincupgrade.ProgressLogger(logger, start, end, step_percents=10, msg='')¶

Bases: object

Simple progress logger

Logs progress using logging module. The ProgressLogger will log a message every step_percents until current_value reaches range Example: Progress logger for a function writing to a memory with 256 pages, logging a message for every 10%

progresslogger = ProgressLogger(256, 10, "written")
for page_index in range(256):
    writePage()
    progresslogger.log(page_index)

Parameters:

logger (logging.Logger object) – logger object, typically fetched using logging.getLogger()
start (int of float) – start value
end (int or float) – end value
step_percents (int, optional) – step size for logging, i.e. logging will only happen every step_percents, defaults to 10
msg (str, optional) – progress message to be appended after the percentage output, defaults to “”

log(absolute_progress)¶

Log current progress

Parameters:: absolute_progress (int or float) – current progress

class iotprovision.winc.wincupgrade.WincUpgrade(serial, loglevel=logging.INFO)¶

Bases: object

check_bridge()¶

erase_flash()¶

erase_sector(sector_offset)¶

read_firmware_version()¶

read_flash(numbytes=None)¶

read_sector(sector_offset)¶

reset()¶

upgrade_full_image(data)¶: Do the upgrade by erasing and writing

verify_flash(reference_data)¶

write_flash(data)¶

write_sector(sector_offset, data)¶

write_tls_root_certificate_sector(data)¶

class iotprovision.winc.wincupgrade.WincUpgradeBridgeCmdRsp(serial)¶

Bases: object

Command/response generator for WINC upgrade bridge

send_receive_read(cmd, rsp_size)¶

Send a READ command and receive the response

Parameters:: cmd – read request to send
Returns:: response received

send_receive_write(cmd)¶

Send a WRITE command and receive the response

Parameters:: cmd – write request to send

class iotprovision.winc.wincupgrade.WincUpgradeBridgeLink(serial)¶

Bases: object

Read / write link driver for Winc1500

ERASE_SECTOR = 5¶

READ_FW_VER = 0¶

READ_PAGE = 1¶

READ_SECTOR = 2¶

WINC_RESET = 6¶

WRITE_PAGE = 3¶

WRITE_SECTOR = 4¶

erase_sector(offset)¶

read_command(command_id, offset)¶

read_firmware_version()¶

read_page(offset)¶

read_sector(offset)¶

reset()¶

write_command(command_id, payload_size, offset, data)¶

write_page(offset, data)¶

write_sector(offset, data)¶

exception iotprovision.winc.wincupgrade.WincUpgradeError(msg=None, code=0)¶

Bases: Exception

WINC upgrade specific exception

Table of Contents

Previous topic

This Page

WINC functions¶

pywinc utility entry point¶

WINC certificates¶

WINC flash memory map¶

WINC upgrade¶