brandonv101 / mmm-parcel Goto Github PK

Track deliveries . Supports 428 couriers worldwide based on aftership.com

View parcel tracking status, for display on Magic Mirror. Inspired by MMM-AfterShip by Mykle1.

Example with expected deliveries on a separate line. Expected delivery line is only shown when an ETA is known.

Example of the same in the compact view:

And in the very compact view (one-liner per shipment):

• Go into the ~/MagicMirror/modules directory and do git clone https://github.com/martinkooij/MMM-Parcel.

• Go into the MMM-Parcel directory and do npm install

• Get an account on aftership.com (Free account is OK if you track less than 100 parcels per month)

• Get your FREE API Key from https://www.aftership.com/ via settings -> API.

• You MUST add couriers to your account at aftership.com.

• Add your own trackings

• Tell me what you like, or any issues you have. It is difficult to test as I cannot control or test all variations from AfterShip.

Do a git pull in the MMM-Parcel module directory. Running a npm install again in the same directory is recommended and does no harm. In case supporting features need new packages, such as when you upgrade to a version with the automatic translations feature, the npm install is really needed.

To use this module, add it to the modules array in the config/config.js file:

{
module: 'MMM-Parcel',
position: 'top_right',	// This can be any of the regions. Best results in left or right regions.
header: 'My Parcels',   // This is optional
config: {
	apiKey: 'Your API KEY goes here', // Your free API Key from aftership.com
	maxNumber: 10, //maximum number of Parcels to show
	showCourier: true,
	autoHide: false, // hide module on mirror when there are no deliveries to be shown
	isSorted: true,  // sort on delivery Status (most important ones first)
	compactness: -1, // 0 = elaborate, 1 = compact display, 2 = very compact, one-liner per shipment, -1 = automatic
	hideExpired: true, // don't show expired parcels
	hideDelivered: 15, // Hide delivered parcels after 15 days. 
	updateInterval: 600000, // 10 minutes = 10 * 60 * 1000 milliseconds. 
	parcelStatusText: ["Exception", "Failed Attempt","In Delivery", "In Transit", 
	                   "Info Received", "Pending", "Delivered", "Expired"], // This is the default. Enter your own language text
	parcelIconColor: ["red", "red", "green", "green", "cornflowerblue", "cornflowerblue", "grey", "grey"], // This is the default. Change for other icon colors
	onlyDaysFormat: {
	  lastDay : '[Yesterday]',
	  sameDay : '[Today]',
	  nextDay : '[Tomorrow]',
	  lastWeek : '[Last] dddd',
	  nextWeek : 'dddd',
	  sameElse : 'L'
	  }, // formatting when only days are shown and time is unknown. 
	expectedDeliveryText: 'Delivery Expected: ',	 // This is the default. Changes time infoline. 
    noParcelText: 'No Shipment Data'	 // This is the default. Changes infoline in case of no trackings. 
	}
},

The above example is a bit long. If you are OK with English texts and you do like the default colors and settings provided by the module the following simple config suffices!

{
module: 'MMM-Parcel',
position: 'top_right',	// This can be any of the regions. Best results in left or right regions.
header: 'My Parcels',   // This is optional
config: {
	apiKey: 'Your API KEY goes here' // Your free API Key from aftership.com
	}
},

The following properties can be configured:

Many couriers enter checkpoint message in the language of the country of origin, sometimes aftership decides to translate to English, sometimes not. the MMM-Parcel module contains a translation feature of these information texts based on a free Google Translate API. This only works if autoTranslate is set to a valid language string (see https://cloud.google.com/translate/docs/languages). Translation services will not be called if autoTranslate is absent or set to false.

An example of a non-translated view on the mirror:

The infotexts can be automatically translated via Google translate API. Add for example autoTranslate : "en", in the config.js file in the MMM-Parcel descriptions. Restart the mirror and off you go! The translation API is only called when there is a change in the deliveries.

I adapted my mirror module to be a Dutch mirror by setting Dutch language settings and autoTranslate to "nl" in the config:

{
module: 'MMM-Parcel',
position: 'top_right',
header: 'Pakjes',   
config: {
	apiKey: 'XXXXXXXXXXXXXX', // API key of Aftership
	compactness: -1,
	autoTranslate: "nl",
	parcelStatusText: ["Fout", "Mislukte bezorging","In bezorging","Onderweg", "Ingevoerd", "Wachtend", "Afgeleverd", "Te oud"],
	onlyDaysFormat: 
		{lastDay : '[gisteren]',
		 sameDay : '[vandaag]',
		 nextDay : '[morgen]',
		 lastWeek : '[afgelopen] dddd',
		 nextWeek : 'dddd',
		 sameElse : 'L'},
	expectedDeliveryText: 'Bezorging verwacht: ',
	noParcelText: 'Geen Data'
	}
},

And Yo, see the Dutch mirror:

Advanced users: When you don't like certain automated translations you can put a forced translation JSON file in de MMM-Parcel module directory called force_trans.json Don't worry, the file, if it exists, is ignored by git pull so will not be overwritten by an update. The file is a JSON formatted text file (don't make any JSON syntax errors!) of translation pairs of original texts (in full) and translated texts. The translation translates complete message entries not word by word. Example:

{
"Departed" : "Vertrokken", 
"Processed Through Facility": "Verwerkt in sorteercentrum"
}

• [aftership] (installed via npm install)
• [google-translate-api] (installed via npm install)
• [moment] (already available)
• font-awesome 4.7.0 (already available)

• narrow layout added
• hideDelivered can take an integer.
• possibility to translate the info texts.

• version 1.3.0. Added Narrow layout, hideDelivered in days + editorials on Readme. Removed bug of showing "undefined" when the parcellist is empty.
• version 1.2.2. Bug fixed, code linting, now displays time of latest checkpoint when no expected delivery is (yet) known. Message line before clock line.
• version 1.2.1. Removed spurious debug info to log files
• version 1.2.0. Functional release (adding translations, autohide and automatic compactness)

• Aftership does a good job in collecting information from the courier but is not perfect. Use the mirror presentation as a hint.
• On full mirrors with many modules the google API translations (if set) sometimes arrive just after the visual update during start-up. No problem, in the next update cycle the translations are picked up. And a mirror is only booted up once a month or less no?