Skip to content

Instantly share code, notes, and snippets.

What would you like to do?
Reverse Engineering eSCL / Apple AirScan
Reverse Engineering the Apple Airscan / eSCL Protocol
I am not certain of the origins, one person involved in IPP printing claimed it was proprietary of HP , but then again they have their own protocol. AirScan/eSCL is used by other manufacturers too like Xerox, Kyocera, Canon and more. Mopria also seems to claim some responsibility for it but then again it seems not completely. In any case it seems shrouded in such secrecy that to date several years after its implementation, unless someone wants to take it all apart.
I offer this as my contribution. It is not perfect but almost there.
As I began looking for information to make a scanner more compatible, I could only find fragments of information. Even Apple Developer Forums offered zero help.
Server/Client in eSCL / AirScan:
There is a “server”and a “client” the client can be a desktop computer or mobile device. The server is a scanner or another device configured to emulate a hardware scanner, even a desktop computer. In my case I did this on Linux, so Linux is discussed here. Examples of clients are Mopria Android Client, Apple Airscan (OSX and iOS), VueScan also runs on Mac Linux or Windows and seems to have some level of eSCL built in. It seems to be the “easiest client to please”
How does eSCL/Airscan work?
The basics:
Avahi / Bonjour Discovery (typical dscovery _uscan._tcp
Client GET ScannerStatus
Server responds with HTML/XML
GET ScannerCapabilities
Server responds with HTML/XML
(GET ScannerStatus) again optional before a scan
(Server responds with HTML/XML)
POST to ScanJobs an xml file that conforms to available options in ScannerStatus received earlier.
Server replies to POST with 201 Created and Location: /path/to/file.
(GET ScannerStatus) again optional after a scan
(Server responds with HTML/XML "Processing")
(GET ScannerStatus) again optional after a scan
(Server responds with HTML/XML "Processing")
GET ScannerStatus so we can tell when the scan is ready
Server responds with HTML/XML JOB URI
Job downloaded from URI
More detail:
Of curse the first step in the process in a Bonjour advertisement. On Linux, we do this with avahi daemon. Later we will get to formatting a file for that purpose.
After the client queries Bonjour/Avahi devices a text record like the following is received. I am showing only IPV4 responses but IP v6 is identical , except for the address.
+ wlan2 IPv4 AirScanning@hostname _uscan._tcp local
This provides basic information that there are scanning service (_uscan._tcp) at the server hostname
With Linux and Avahi when we use the –resolve option we see more information including the following.
= wlan2 IPv4 AirScanning@HDTVStreamersIn _uscan._tcp local
hostname = [HDTVStreamersIn.local]
address = []
port = [80]
txt = ["txtvers=1" "ty=AirScanning" "pdl=application/octet-stream,image/jpeg,application/pdf" "note=AirScanning" "adminurl=http://HDTVStreamersIn.local/airscan.php" "vers=2.5" "representation=http://HDTVStreamersIn.local./images/AirScanIcon2.png" "rs=eSCL" "cs=grayscale,color" "is=platen,adf" "duplex=F"]
The above is important for a few reasons. It tells us the next place to query . The “rs” (resource?) text entry is eSCL, which means that our base URL is
We could also theoretically have more than one scanner at an IP each with its own Avahi/Bonjour advertisement and nique root URI defined in “rs”
The “:80” is not required in the above example unless it is a port other than port 80. Also I have yet to see how an https advertisement looks, but imagine it has a flag indicating “https” somewhere..
From that basename we add “/ScannerStatus” giving us
If the scanner is not busy we will get something like :
<?xml version="1.0" encoding="UTF-8"?>
<scan:ScannerStatus xmlns:xsi="" xmlns:scan="" xmlns:pwg="" xsi:schemaLocation=" eSCL.xsd">
Now when we make a GET request to the above URL to see what the scanner is capable of, and we see something like:
<?xml version="1.0" encoding="UTF-8"?>
<scan:ScannerCapabilities xmlns:xsi="" xmlns:scan="" xmlns:pwg="" xsi:schemaLocation=" eSCL.xsd">
<pwg:MakeAndModel>AirScanning on DeviceName</pwg:MakeAndModel>
This tells us the information that should be contained in our request.
We can then generate a simple scan request to POST with minimal information.
Please note. In SOME cases there may be multiple ways to define the same capability. One example is
<pwg:DocumentFormat> or <scan:DocumentFormatExt>
</scan:MaxWidth> or <pwg:Width>
</scan:MaxHeight> or <pwg:Height>
The above xml sections may or may not both be present in ScannerStatus, but it appears that some clients use them without regard to which is in ScannerStatus. If you are working on a client you should respect what is in Scanner Status. If you are working on a server you should prepare to accept these options even if different from this ScannerCapabilites offered. I suspect that there are other such options like color mode but as yet have not seen it happen.
What the Scanner Status XML means:
The ScannerCapabilities xml above indicates nothing of ADF or Feeder, so it is flatbed only
Supported resolutions afe 300x300 and 600x600 DPI
Supported formats are JPG, PDF and oclet-stream (this last one is apparently required for Apple compatibility)
We can scan with the following intentions; Preview, Text and Graphic, Photo and Document. On some scanners , scanning with Document intent for instance may initiate a Black and white scan.
We have color modes Grayscale8 and RGB24 available
MaxWidth/Height defines the maximum scan area at 300 DPI.
MinWidth/Height defines the minimum scan area at 300 DPI.
This xml example does not have<pwg:ContentRegionUnits>escl:ThreeHundredthsOfInches</pwg:ContentRegionUnits>, which I suspect may affect the measurenet unit of Min and max height and width
Because this is a flatbed scanner some apps like Image Capture in OSX will start with a preview image, so once the scanner is selected it is already acquiring this preview. This allows us to select a limited part of the platen if for instance we have a small photo. This ScannerCapabilities xml file tells us we can select a single scan region so we can not put 2 photos on the platen and scan themas separate files. When we select that scan region we pass those coordinates on to out ScanJob xml POST request.
Now we can POST our XML which is derived from ScannerCapabilities, but we make adjustments for height , witdth and select the resolution from those offered in ScannerStatus, etc.
<?xml version="1.0" encoding="UTF-8"?>
<scan:ScanSettings xmlns:scan="" xmlns:pwg="">
Because we selected the scan area and our image is pushed to the upper left of the platen X=0 and Y=0 we will be doing some cropping from that point rather than scanning the entire platen. Doing the math in the xml above our image should scan to 4100px H x 3000px W, as max width/height is expressed iat 300 DPI and we are scanning at 600 DPI .
Once the above is POSTed from client to server we then we get a response 201Created back as well as Location /escl/Scans/UNIQUE_ID.
Now we need to start checking ScannerStatus and might well see something like:
<?xml version="1.0" encoding="UTF-8"?>
<scan:ScannerStatus xmlns:xsi="" xmlns:scan="" xmlns:pwg="" xsi:schemaLocation=" eSCL.xsd">
(here is where things get a little fuzzy and we have trouble keeping ALL clients happy! If you know the missing sauce from this point on please open a ticket. )
once the xml changes to something like
<?xml version="1.0" encoding="UTF-8"?>
<scan:ScannerStatus xmlns:xsi="" xmlns:scan="" xmlns:pwg="" xsi:schemaLocation=" eSCL.xsd">
Now the client SHOULD(!?) go and download the file from the URL and display & save it.
Some clients send a “DELETE” command after downloading but PWG claims a scanned document should be kept available for 300 seconds after scan completion
Resources (not all is completely relevant):
Here is the uscan.service file i use in /etc/avahi/services and some explanation. The <txt-record>representation causes an icon to show in Mopria and a somewhat greyed out icon in OSX Image Capture. Because Ihave tested on a customized version of Apache with PHP I use port 80, but use what you want. I set the adminurl to the web GUI.
<?xml version="1.0" standalone='no'?><!--*-nxml-*-->
<!DOCTYPE service-group SYSTEM "avahi-service.dtd">
<name replace-wildcards="yes">AirScanning@%h</name>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.