# microSCHC
## In a nutshell
Implementation in microPython of SCHC as specified in RFC 8724 [1].
## License
MIT License, Copyright (c) 2022-2025 Orange, by Quentin Lampin
## Installing microSCHC
Releases of microSCHC are available on PyPI. To install microSCHC, run
```bash
pip install microschc[extras]
```
Note: you can also install microschc with support of PCAPng capture files in case you don't need it
```bash
pip install microschc
```
Latest (pre-release) microSCHC versions can be built from source using `hatch` and installed using the wheel (.whl) file generated in the `dist/` folder.
**build**:
```bash
hatch build -t wheel
```
**installation**:
```bash
pip install dist/microschc-<version>-py3-none-any.whl
```
## Quickstart Example
Here's a quick example of how to use microSCHC to compress IPv6/UDP/CoAP headers:
```python
ffrom microschc import ContextManager, Context, Stack, RuleDescriptor, RuleNature, Buffer
from microschc.protocol.ipv6 import ipv6_base_header_template
from microschc.protocol.udp import udp_header_template
from microschc.protocol.coap import CoAPFields, coap_base_header_template, coap_option_template
from microschc.rfc8724 import RuleFieldDescriptor, CDA, MO
from microschc.tools.targetvalue import create_target_value
# Packet example to compress
packet: Buffer = Buffer(content= b"\x60\x0f\xf8\x5f" # IPv6 Version + Traffic Class + Flow Label
b"\x00\x1c" # Payload Length
b"\x11" # Next Header
b"\x40" # Hop Limit
b"\x20\x01\x0d\xb8\x00\x0a\x00\x00" # Source Address
b"\x00\x00\x00\x00\x00\x00\x00\x03" # |
b"\x20\x01\x0d\xb8\x00\x0a\x00\x00" # Destination Address
b"\x00\x00\x00\x00\x00\x00\x00\x20" # |
b"\x90\xa0" # UDP Source Port
b"\x16\x33" # Destination Port
b"\x00\x1c" # Length
b"\x29\x23" # Checksum
b"\x52" # CoAP Version + Type + Token Length
b"\x45" # Code
b"\x14\xb5" # Message ID
b"\x37\x09" # Token
b"\x61" # Option Delta 1 + Option Length 1
b"\x76" # Option Value 1
b"\x61" # Option Delta 2 + Option Length 2
b"\x3c" # Option Value 2
b"\xff" # Payload Marker
b"\xfb\x40\x31\x66\x66\x66\x66\x66\x66" # App Payload
)
# Create field descriptors for IPv6 header
ipv6_field_descriptors = ipv6_base_header_template(
flow_label=b'\x0f\xf8\x5f',
src_address=b'\x20\x01\x0d\xb8\x00\x0a\x00\x00\x00\x00\x00\x00\x00\x00\x00\x03',
dst_address=b'\x20\x01\x0d\xb8\x00\x0a\x00\x00\x00\x00\x00\x00\x00\x00\x00\x20',
next_header=17,
hop_limit=64
)
# Create field descriptors for UDP header
udp_field_descriptors = udp_header_template(
source_port=b'\x90\xa0',
destination_port=b'\x16\x33'
)
# Create field descriptors for CoAP header
coap_base_header_field_descriptors = coap_base_header_template(
type=b'\x01',
code=0b01000101,
token=[b'\xd1\x59', b'\x21\x50', b'\x37\x09', b'\x1f\x0a', b'\xb7\x25', b'\x8d\x43']
)
# Create field descriptors for CoAP options
coap_option_1_field_descriptors = coap_option_template(
option_delta=b'\x06',
option_length=[1, 2],
option_value=None
)
coap_option_2_field_descriptors = coap_option_template(
option_delta=6,
option_length=[1,2],
option_value=[b"\x2d\x16", b"\x3c"]
)
coap_payload_maker_field_descriptor = RuleFieldDescriptor(
id=CoAPFields.PAYLOAD_MARKER,
length=8,
target_value=create_target_value(b"\xff"),
matching_operator=MO.EQUAL,
compression_decompression_action=CDA.NOT_SENT
)
# Combine all field descriptors
field_descriptors = (
ipv6_field_descriptors
+ udp_field_descriptors
+ coap_base_header_field_descriptors
+ coap_option_1_field_descriptors
+ coap_option_2_field_descriptors
+ [coap_payload_maker_field_descriptor]
)
# Create a rule descriptor
rule_descriptor = RuleDescriptor(
id=Buffer(b'\x00', length=8),
nature=RuleNature.COMPRESSION,
field_descriptors=field_descriptors,
)
# Create a context with the rule
context = Context(
id="quickstart-context",
description="Context for IoT device communication",
interface_id="default",
parser_id=Stack.IPV6_UDP_COAP,
ruleset=[rule_descriptor],
)
# Create a context manager
context_manager = ContextManager(context=context)
# Use the context manager to compress packets
compressed_packet = context_manager.compress(packet)
```
## microSCHC, developpement plan
microSCHC aims at implementing the SCHC Compression/Decompression (C/D) routines described in RFC 8724 [1].
Currently, microSCHC provides parsers for IPv4[2] IPv6[3], UDP[4], CoAP[5] and SCTP[6].
Beyond implementing the core SCHC specification, microSCHC also aims to support the IETF WG SCHC in its ongoing work.
For example, it implements and evaluates different approaches for CoAP parsing, including both syntactic and semantic approaches, to help inform the WG's decisions on best practices for CoAP compression in constrained networks.
Current features:
1. Parsers
- [x] IPv4
- [x] IPv6
- [x] UDP
- [x] SCTP
- [x] CoAP (syntactic and semantic approaches)
- [x] CoAP over UDP over IPv6 stack parser
2. Matching Operators (MO)
- [x] equal
- [x] ignore
- [x] MSB(x)
- [x] match-mapping
3. Compression/Decompression Actions (CDA)
1. Compression
- [x] not-sent
- [x] value-sent
- [x] mapping-sent
- [x] LSB
- [x] compute-* (e.g. UDP-checksum)
2. Decompression counterparts
- [x] not-sent
- [x] value-sent
- [x] mapping-sent
- [x] LSB
- [-] compute-* (e.g. UDP-checksum)
- [x] UDP Checksum
- [x] UDP Length
- [x] IPv6 Payload Length
- [x] IPv4 Payload Length
4. Rules
- [x] rule data model
- [x] rule matching algorithm
- [ ] YANG model interpreter
5. Compression
- [x] field (left-)packet
- [x] field residues concatenation
- [x] length of variable length field encoding
- [x] packet compression
6. Context Management
- [x] Definition & implementation of custom SCHC Context (not specified in RFCs)
- [1] "RFC 8724 SCHC: Generic Framework for Static Context Header Compression and Fragmentation" , A. Minaburo et al.
- [2] "RFC 791 INTERNET PROTOCOL. J.Postel et al."
- [3] "RFC 8200 Internet Protocol, Version 6 (IPv6) Specification, S. Deering et al."
- [4] "RFC 768 User Datagram Protocol, J. Postel"
- [5] "RFC 7252 The Constrained Application Protocol (CoAP), Z. Shelby et al."
- [6] "RFC 4960 Stream Control Transmission Protocol, R. Stewart et al."
Raw data
{
"_id": null,
"home_page": null,
"name": "microschc",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Quentin Lampin <quentin.lampin@orange.com>",
"keywords": "compression, iot, lpwan, schc",
"author": null,
"author_email": "Quentin Lampin <quentin.lampin@orange.com>",
"download_url": null,
"platform": null,
"description": "# microSCHC\n\n## In a nutshell\n\nImplementation in microPython of SCHC as specified in RFC 8724 [1].\n\n## License\n\nMIT License, Copyright (c) 2022-2025 Orange, by Quentin Lampin\n\n## Installing microSCHC\n\nReleases of microSCHC are available on PyPI. To install microSCHC, run\n\n```bash\npip install microschc[extras]\n```\n\nNote: you can also install microschc with support of PCAPng capture files in case you don't need it\n\n```bash\npip install microschc\n```\n\n\nLatest (pre-release) microSCHC versions can be built from source using `hatch` and installed using the wheel (.whl) file generated in the `dist/` folder.\n\n**build**:\n\n```bash\nhatch build -t wheel\n```\n\n**installation**:\n\n```bash\npip install dist/microschc-<version>-py3-none-any.whl\n```\n\n## Quickstart Example\n\nHere's a quick example of how to use microSCHC to compress IPv6/UDP/CoAP headers:\n\n```python\nffrom microschc import ContextManager, Context, Stack, RuleDescriptor, RuleNature, Buffer\nfrom microschc.protocol.ipv6 import ipv6_base_header_template\nfrom microschc.protocol.udp import udp_header_template\nfrom microschc.protocol.coap import CoAPFields, coap_base_header_template, coap_option_template\nfrom microschc.rfc8724 import RuleFieldDescriptor, CDA, MO\nfrom microschc.tools.targetvalue import create_target_value\n\n# Packet example to compress\npacket: Buffer = Buffer(content= b\"\\x60\\x0f\\xf8\\x5f\" # IPv6 Version + Traffic Class + Flow Label\n b\"\\x00\\x1c\" # Payload Length\n b\"\\x11\" # Next Header \n b\"\\x40\" # Hop Limit\n b\"\\x20\\x01\\x0d\\xb8\\x00\\x0a\\x00\\x00\" # Source Address\n b\"\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x03\" # |\n b\"\\x20\\x01\\x0d\\xb8\\x00\\x0a\\x00\\x00\" # Destination Address\n b\"\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x20\" # |\n b\"\\x90\\xa0\" # UDP Source Port\n b\"\\x16\\x33\" # Destination Port\n b\"\\x00\\x1c\" # Length\n b\"\\x29\\x23\" # Checksum\n b\"\\x52\" # CoAP Version + Type + Token Length\n b\"\\x45\" # Code\n b\"\\x14\\xb5\" # Message ID\n b\"\\x37\\x09\" # Token\n b\"\\x61\" # Option Delta 1 + Option Length 1\n b\"\\x76\" # Option Value 1\n b\"\\x61\" # Option Delta 2 + Option Length 2\n b\"\\x3c\" # Option Value 2\n b\"\\xff\" # Payload Marker\n b\"\\xfb\\x40\\x31\\x66\\x66\\x66\\x66\\x66\\x66\" # App Payload\n\n)\n\n# Create field descriptors for IPv6 header\nipv6_field_descriptors = ipv6_base_header_template(\n flow_label=b'\\x0f\\xf8\\x5f',\n src_address=b'\\x20\\x01\\x0d\\xb8\\x00\\x0a\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x03',\n dst_address=b'\\x20\\x01\\x0d\\xb8\\x00\\x0a\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x00\\x20',\n next_header=17,\n hop_limit=64\n)\n\n# Create field descriptors for UDP header\nudp_field_descriptors = udp_header_template(\n source_port=b'\\x90\\xa0',\n destination_port=b'\\x16\\x33'\n)\n\n# Create field descriptors for CoAP header\ncoap_base_header_field_descriptors = coap_base_header_template(\n type=b'\\x01',\n code=0b01000101,\n token=[b'\\xd1\\x59', b'\\x21\\x50', b'\\x37\\x09', b'\\x1f\\x0a', b'\\xb7\\x25', b'\\x8d\\x43']\n)\n\n# Create field descriptors for CoAP options\ncoap_option_1_field_descriptors = coap_option_template(\n option_delta=b'\\x06',\n option_length=[1, 2],\n option_value=None\n)\n\ncoap_option_2_field_descriptors = coap_option_template(\n option_delta=6,\n option_length=[1,2],\n option_value=[b\"\\x2d\\x16\", b\"\\x3c\"]\n)\n\ncoap_payload_maker_field_descriptor = RuleFieldDescriptor(\n id=CoAPFields.PAYLOAD_MARKER,\n length=8,\n target_value=create_target_value(b\"\\xff\"),\n matching_operator=MO.EQUAL,\n compression_decompression_action=CDA.NOT_SENT\n)\n\n# Combine all field descriptors\nfield_descriptors = (\n ipv6_field_descriptors\n + udp_field_descriptors \n + coap_base_header_field_descriptors \n + coap_option_1_field_descriptors \n + coap_option_2_field_descriptors\n + [coap_payload_maker_field_descriptor]\n)\n\n# Create a rule descriptor\nrule_descriptor = RuleDescriptor(\n id=Buffer(b'\\x00', length=8),\n nature=RuleNature.COMPRESSION,\n field_descriptors=field_descriptors,\n)\n\n# Create a context with the rule\ncontext = Context(\n id=\"quickstart-context\",\n description=\"Context for IoT device communication\",\n interface_id=\"default\",\n parser_id=Stack.IPV6_UDP_COAP,\n ruleset=[rule_descriptor],\n)\n\n# Create a context manager\ncontext_manager = ContextManager(context=context)\n\n# Use the context manager to compress packets\ncompressed_packet = context_manager.compress(packet)\n```\n\n## microSCHC, developpement plan\n\nmicroSCHC aims at implementing the SCHC Compression/Decompression (C/D) routines described in RFC 8724 [1].\n\nCurrently, microSCHC provides parsers for IPv4[2] IPv6[3], UDP[4], CoAP[5] and SCTP[6].\n\nBeyond implementing the core SCHC specification, microSCHC also aims to support the IETF WG SCHC in its ongoing work. \nFor example, it implements and evaluates different approaches for CoAP parsing, including both syntactic and semantic approaches, to help inform the WG's decisions on best practices for CoAP compression in constrained networks.\n\nCurrent features:\n\n1. Parsers\n - [x] IPv4\n - [x] IPv6\n - [x] UDP\n - [x] SCTP\n - [x] CoAP (syntactic and semantic approaches)\n - [x] CoAP over UDP over IPv6 stack parser\n \n2. Matching Operators (MO)\n - [x] equal\n - [x] ignore\n - [x] MSB(x)\n - [x] match-mapping\n\n3. Compression/Decompression Actions (CDA)\n 1. Compression\n - [x] not-sent\n - [x] value-sent\n - [x] mapping-sent\n - [x] LSB\n - [x] compute-* (e.g. UDP-checksum)\n \n 2. Decompression counterparts\n - [x] not-sent\n - [x] value-sent\n - [x] mapping-sent\n - [x] LSB\n - [-] compute-* (e.g. UDP-checksum)\n - [x] UDP Checksum\n - [x] UDP Length\n - [x] IPv6 Payload Length\n - [x] IPv4 Payload Length\n \n4. Rules\n - [x] rule data model\n - [x] rule matching algorithm\n - [ ] YANG model interpreter\n5. Compression\n - [x] field (left-)packet\n - [x] field residues concatenation\n - [x] length of variable length field encoding\n - [x] packet compression\n6. Context Management\n - [x] Definition & implementation of custom SCHC Context (not specified in RFCs)\n\n- [1] \"RFC 8724 SCHC: Generic Framework for Static Context Header Compression and Fragmentation\" , A. Minaburo et al.\n- [2] \"RFC 791 INTERNET PROTOCOL. J.Postel et al.\"\n- [3] \"RFC 8200 Internet Protocol, Version 6 (IPv6) Specification, S. Deering et al.\"\n- [4] \"RFC 768 User Datagram Protocol, J. Postel\"\n- [5] \"RFC 7252 The Constrained Application Protocol (CoAP), Z. Shelby et al.\"\n- [6] \"RFC 4960 Stream Control Transmission Protocol, R. Stewart et al.\"",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python implementation of the Static Context Header Compression (SCHC) protocol",
"version": "0.21.0",
"project_urls": {
"Bug Tracker": "https://github.com/quentinlampin/microschc/issues",
"Homepage": "https://github.com/quentinlampin/microschc/"
},
"split_keywords": [
"compression",
" iot",
" lpwan",
" schc"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "f84c0d1a6d2120f6a15f98c1b11c2abe0f39e7ef6835be5fa8bc38a42352ed87",
"md5": "497ae63b7c8a7917d48f7c8994888e10",
"sha256": "e90b2a1d184e736f67cffaff559b0fcb97062a73ec6ca4a08c489d8fcaa53ac2"
},
"downloads": -1,
"filename": "microschc-0.21.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "497ae63b7c8a7917d48f7c8994888e10",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 71980,
"upload_time": "2025-07-25T13:40:37",
"upload_time_iso_8601": "2025-07-25T13:40:37.359225Z",
"url": "https://files.pythonhosted.org/packages/f8/4c/0d1a6d2120f6a15f98c1b11c2abe0f39e7ef6835be5fa8bc38a42352ed87/microschc-0.21.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-25 13:40:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "quentinlampin",
"github_project": "microschc",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "backports.strenum",
"specs": []
}
],
"lcname": "microschc"
}
JSON
